Module: Arachni::Framework::Parts::State

Included in:
Arachni::Framework
Defined in:
lib/arachni/framework/parts/state.rb

Overview

Provides access to State::Framework and helpers.

Author:

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



18
19
20
 
# File 'lib/arachni/framework/parts/state.rb', line 18

def self.included( base )
    base.extend ClassMethods
end

Instance Method Details

#abort(wait = true) ⇒ Object

Aborts the framework #run on a best effort basis.

Parameters:

  • wait (Bool) (defaults to: true) —

    Wait until the system has been aborted.



294
295
296
 
# File 'lib/arachni/framework/parts/state.rb', line 294

def abort( wait = true )
    state.abort wait
end

#abort? ⇒ Bool

Returns ‘true` if the framework has been instructed to abort (i.e. is in the process of being aborted or has been aborted), `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework has been instructed to abort (i.e. is in the process of being aborted or has been aborted), `false` otherwise.



280
281
282
 
# File 'lib/arachni/framework/parts/state.rb', line 280

def abort?
    state.abort?
end

#aborted? ⇒ Bool

Returns ‘true` if the framework #run has been aborted, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework #run has been aborted, `false` otherwise.



273
274
275
 
# File 'lib/arachni/framework/parts/state.rb', line 273

def aborted?
    state.aborted?
end

#aborting? ⇒ Bool

Returns ‘true` if the framework is in the process of aborting, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework is in the process of aborting, `false` otherwise.



286
287
288
 
# File 'lib/arachni/framework/parts/state.rb', line 286

def aborting?
    state.aborting?
end

#clean_up(shutdown_browsers = true) ⇒ Object

Cleans up the framework; should be called after running the audit or after canceling a running scan.

It stops the clock and waits for the plugins to finish up.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/arachni/framework/parts/state.rb', line 103

def clean_up( shutdown_browsers = true )
    return if @cleaned_up
    @cleaned_up = true

    state.force_resume

    state.status = :cleanup

    sitemap.merge!( browser_sitemap )

    if shutdown_browsers
        state.set_status_message :browser_cluster_shutdown
        shutdown_browser_cluster
    end

    state.set_status_message :clearing_queues
    page_queue.clear
    url_queue.clear

    @finish_datetime  = Time.now
    @start_datetime ||= Time.now

    # Make sure this is disabled or it'll break reporter output.
    disable_only_positives

    state.running = false

    state.set_status_message :waiting_for_plugins
    @plugins.block

    # Plugins may need the session right till the very end so save it for last.
    @session.clean_up
    @session = nil

    true
end

#done? ⇒ Bool

Returns ‘true` if the system has completed successfully, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the system has completed successfully, `false` otherwise.



250
251
252
 
# File 'lib/arachni/framework/parts/state.rb', line 250

def done?
    state.done?
end

#initialize ⇒ Object 



65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/arachni/framework/parts/state.rb', line 65

def initialize
    super

    Element::Capabilities::Auditable.skip_like do |element|
        if pause?
            print_debug "Blocking on element audit: #{element.audit_id}"
        end

        wait_if_paused
    end

    state.status = :ready
end

#pause(wait = true) ⇒ Integer

Note:

Each call from a unique caller is counted as a pause request and in order for the system to resume all pause callers need to #resume it.

Pauses the framework on a best effort basis.

Parameters:

  • wait (Bool) (defaults to: true) —

    Wait until the system has been paused.

Returns:

  • (Integer) —

    ID identifying this pause request.



265
266
267
268
269
 
# File 'lib/arachni/framework/parts/state.rb', line 265

def pause( wait = true )
    id = generate_token.hash
    state.pause id, wait
    id
end

#pause? ⇒ Bool

Returns ‘true` if the framework has been instructed to pause (i.e. is in the process of being paused or has been paused), `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework has been instructed to pause (i.e. is in the process of being paused or has been paused), `false` otherwise.



239
240
241
 
# File 'lib/arachni/framework/parts/state.rb', line 239

def pause?
    state.pause?
end

#paused? ⇒ Bool

Returns ‘true` if the framework is paused, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework is paused, `false` otherwise.



232
233
234
 
# File 'lib/arachni/framework/parts/state.rb', line 232

def paused?
    state.paused?
end

#pausing? ⇒ Bool

Returns ‘true` if the framework is in the process of pausing, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the framework is in the process of pausing, `false` otherwise.



245
246
247
 
# File 'lib/arachni/framework/parts/state.rb', line 245

def pausing?
    state.pausing?
end

#reset ⇒ Object

Note:

Prefer this from #reset if you already have an instance.

Note:

You should first reset Options.

Resets everything and allows the framework to be re-used.



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/arachni/framework/parts/state.rb', line 149

def reset
    @cleaned_up  = false
    @browser_job = nil

    @failures.clear
    @retries.clear

    # This needs to happen before resetting the other components so they
    # will be able to put in their hooks.
    self.class.reset

    clear_observers
    reset_trainer
    reset_session

    @checks.clear
    @reporters.clear
    @plugins.clear
end

#reset_trainer ⇒ Object 



141
142
143
 
# File 'lib/arachni/framework/parts/state.rb', line 141

def reset_trainer
    @trainer = Trainer.new( self )
end

#restore(afs) ⇒ Framework

Returns Restored instance.

Parameters:

  • afs (String) —

    Path to an ‘.afs.` (Arachni Framework Snapshot) file created by #suspend.

Returns:



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/arachni/framework/parts/state.rb', line 179

def restore( afs )
    Snapshot.load afs

    browser_job_update_skip_states state.browser_skip_states

    checks.load  Options.checks
    plugins.load Options.plugins.keys

    nil
end

#resume(id) ⇒ Object

Note:

Each call from a unique caller is counted as a pause request and in order for the system to resume all pause callers need to #resume it.

Removes a #pause request for the current caller.

Parameters:

  • id (Integer) —

    ID of the #pause request.



306
307
308
 
# File 'lib/arachni/framework/parts/state.rb', line 306

def resume( id )
    state.resume id
end

#running? ⇒ Bool

Returns ‘true` if the framework is running, `false` otherwise. This is `true` even if the scan is #paused?.

Returns:

  • (Bool) —

    ‘true` if the framework is running, `false` otherwise. This is `true` even if the scan is #paused?.



220
221
222
 
# File 'lib/arachni/framework/parts/state.rb', line 220

def running?
    state.running?
end

#scanning? ⇒ Bool

Returns ‘true` if the system is scanning, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the system is scanning, `false` otherwise.



226
227
228
 
# File 'lib/arachni/framework/parts/state.rb', line 226

def scanning?
    state.scanning?
end

#snapshot_path ⇒ String

Returns Provisioned #suspend dump file for this instance.

Returns:



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/arachni/framework/parts/state.rb', line 81

def snapshot_path
    return @state_archive if @state_archive

    default_filename =
        "#{URI(options.url).host} #{Time.now.to_s.gsub( ':', '_' )} " <<
            "#{generate_token}.afs"

    location = options.snapshot.save_path

    if !location
        location = default_filename
    elsif File.directory? location
        location += "/#{default_filename}"
    end

    @state_archive ||= File.expand_path( location )
end

#state ⇒ State::Framework

Returns:



170
171
172
 
# File 'lib/arachni/framework/parts/state.rb', line 170

def state
    Arachni::State.framework
end

#status ⇒ Symbol

Returns Status of the instance, possible values are (in order):

  • ‘:ready` – Initialised and waiting for instructions.

  • ‘:preparing` – Getting ready to start (i.e. initializing plugins etc.).

  • ‘:scanning` – The instance is currently auditing the webapp.

  • ‘:pausing` – The instance is being paused (if applicable).

  • ‘:paused` – The instance has been paused (if applicable).

  • ‘:suspending` – The instance is being suspended (if applicable).

  • ‘:suspended` – The instance has being suspended (if applicable).

  • ‘:cleanup` – The scan has completed and the instance is

    {Framework::Parts::State#clean_up cleaning up} after itself (i.e. waiting for
plugins to finish etc.).

  • ‘:aborted` – The scan has been #abort, you can grab the

    report and shutdown.

  • ‘:done` – The scan has completed, you can grab the report and shutdown.

Returns:

  • (Symbol) —

    Status of the instance, possible values are (in order):

    • ‘:ready` – Initialised and waiting for instructions.

    • ‘:preparing` – Getting ready to start (i.e. initializing plugins etc.).

    • ‘:scanning` – The instance is currently auditing the webapp.

    • ‘:pausing` – The instance is being paused (if applicable).

    • ‘:paused` – The instance has been paused (if applicable).

    • ‘:suspending` – The instance is being suspended (if applicable).

    • ‘:suspended` – The instance has being suspended (if applicable).

    • ‘:cleanup` – The scan has completed and the instance is

      {Framework::Parts::State#clean_up cleaning up} after itself (i.e. waiting for
plugins to finish etc.).

    • ‘:aborted` – The scan has been #abort, you can grab the

      report and shutdown.

    • ‘:done` – The scan has completed, you can grab the report and shutdown.



213
214
215
 
# File 'lib/arachni/framework/parts/state.rb', line 213

def status
    state.status
end

#status_messages ⇒ Array<String>

Returns Messages providing more information about the current #status of the framework.

Returns:

  • (Array<String>) —

    Messages providing more information about the current #status of the framework.



193
194
195
 
# File 'lib/arachni/framework/parts/state.rb', line 193

def status_messages
    state.status_messages
end

#suspend(wait = true) ⇒ String?

Writes a Snapshot.dump to disk and aborts the scan.

Parameters:

  • wait (Bool) (defaults to: true) —

    Wait for the system to write it state to disk.

Returns:

  • (String, nil) —

    Path to the state file ‘wait` is `true`, `nil` otherwise.



317
318
319
320
321
 
# File 'lib/arachni/framework/parts/state.rb', line 317

def suspend( wait = true )
    state.suspend( wait )
    return snapshot_path if wait
    nil
end

#suspend? ⇒ Bool

Returns ‘true` if the system is in the process of being suspended, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the system is in the process of being suspended, `false` otherwise.



326
327
328
 
# File 'lib/arachni/framework/parts/state.rb', line 326

def suspend?
    state.suspend?
end

#suspended? ⇒ Bool

Returns ‘true` if the system has been suspended, `false` otherwise.

Returns:

  • (Bool) —

    ‘true` if the system has been suspended, `false` otherwise.



332
333
334
 
# File 'lib/arachni/framework/parts/state.rb', line 332

def suspended?
    state.suspended?
end