Module: Arachni::Element::Capabilities::Analyzable::Timeout

Included in:
Arachni::Element::Capabilities::Analyzable
Defined in:
lib/arachni/element/capabilities/analyzable/timeout.rb

Overview

Evaluates whether or not the injection of specific data affects the response time of the web application.

It takes into account unstable network conditions and server-side failures and verifies the results before logging.

# Methodology

Here’s how it works:

  • Phase 1 (#timeout_analysis) – We’re picking the low hanging fruit here so we can run this in larger concurrent bursts which cause lots of noise.

    • Initial probing for candidates, if element submission

      times-out it is added to the Phase 2 queue.

  • Phase 2 (Timeout.analysis_phase_2) – Verifies the candidates. This is much more delicate so the concurrent requests are lowered to pairs.

    • Control check – Ensures that the webapp is alive and not just timing-out

      by default.

    • Verification using an increased timeout delay –

      Any elements that time out again are logged.

    • Stabilization (#ensure_responsiveness).

  • Phase 3 (Timeout.analysis_phase_3) – Same as phase 2 but with a higher delay to ensure that false-positives are truly weeded out.

Ideally, all requests involved with timing attacks would be run in sync mode but the performance penalties are too high, thus we compromise and make the best of it by running as little an amount of blocking requests as possible for any given phase.

# Usage

  • Call #timeout_analysis to schedule requests for Phase 1.

  • Call HTTP::Client#run to run the Phase 1 requests which will populate the Phase 2 queue with candidates – if there are any.

  • Call Timeout.run to filter the candidates through Phases 2 and 3 to ensure that false-positives are weeded out.

Be sure to call Timeout.run as soon as possible after Phase 1, as the candidate elements keep a reference to their auditor which will prevent it from being garbage collected.

This deviates from the normal framework structure because it is preferable to run timeout audits separately in order to avoid interference by other audit operations.

Author:

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add_phase_2_candidate(elem) ⇒ Object 



106
107
108
109
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 106

def add_phase_2_candidate( elem )
    @phase_2_candidate_ids << elem
    @candidates_phase_2    << elem
end

.candidates_include?(candidate) ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 102

def candidates_include?( candidate )
    @phase_2_candidate_ids.include? candidate
end

.deduplicate ⇒ Object 



89
90
91
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 89

def deduplicate
    @deduplicate = true
end

.deduplicate? ⇒ Boolean

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 85

def deduplicate?
    @deduplicate
end

.do_not_deduplicate ⇒ Object

Used just for specs of timing-attack checks.



94
95
96
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 94

def do_not_deduplicate
    @deduplicate = false
end

.has_candidates? ⇒ Boolean

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 98

def has_candidates?
    @candidates_phase_2.any?
end

.payload_delay_from_options(options) ⇒ Object 



133
134
135
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 133

def payload_delay_from_options( options )
    (options[:delay] / options[:timeout_divider]).to_s
end

.reset ⇒ Object 



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 64

def reset

    # We can track out own candidate state here, without registering it
    # with the global system State, because everything that happens
    # here is green-lit by #timing_attack_probe, which does register
    # its state as it uses #audit.
    #
    # Also, candidates will be consumed prior to a suspension, so when
    # we suspend and restore scans there will be no issue.

    @candidates_phase_2    = []
    @phase_2_candidate_ids = Support::LookUp::HashSet.new( hasher: :timeout_id )

    @candidates_phase_3    = []
    @phase_3_candidate_ids = Support::LookUp::HashSet.new( hasher: :timeout_id )

    @logged = Support::LookUp::HashSet.new( hasher: :audit_id )

    deduplicate
end

.run ⇒ Object

Verifies and logs candidate elements.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 112

def run
    while !@candidates_phase_2.empty?
        analysis_phase_2( @candidates_phase_2.pop )
    end

    while (candidate = @candidates_phase_3.pop)

        # We've allowed multiple variations of the same element in
        # previous operations because, during the audit, the payload
        # that hit could have made the server unresponsive and fooled us
        # into thinking that other valid variations exist too.
        #
        # That's why Phase 3 is here, to shift through these possible
        # issues and verify them once again, however, if a variation
        # is logged, it's game over for that input vector.
        next if Timeout.deduplicate? && logged?( candidate )

        analysis_phase_3( candidate )
    end
end

.timeout_from_options(options) ⇒ Object 



137
138
139
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 137

def timeout_from_options( options )
    options[:delay] + options[:add]
end

Instance Method Details

#ensure_responsiveness(limit = 120_000, prepend = '* ') ⇒ Bool

Submits self with a high timeout value and blocks until it gets a response.

This is to make sure that responsiveness has been restored before progressing further in the timeout analysis.

Parameters:

  • limit (Integer) (defaults to: 120_000) —

    How many milliseconds to afford the server to respond.

Returns:

  • (Bool) —

    ‘true` if server responds within the given time limit, `false` otherwise.



265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 265

def ensure_responsiveness( limit = 120_000, prepend = '* ' )
    options = {
        timeout:           limit,
        mode:              :sync,
        response_max_size: 0
    }

    print_info "#{prepend}Waiting for the effects of the timing attack to " <<
        'wear off, this may take a while (max waiting time is ' <<
         "#{options[:timeout] / 1000.0} seconds)."

    if (response = timeout_control.submit( options )).timed_out?
        print_bad "#{prepend}Max waiting time exceeded."
        false
    else
        print_info "#{prepend}OK, got a response after #{response.time} seconds."
        true
    end
end

#timeout_analysis(payloads, opts) ⇒ Bool

Performs timeout/time-delay analysis and logs an issue should there be one.

Parameters:

  • payloads (String, Array<String>, Hash{Symbol => <String, Array<String>>}) —

    Payloads to inject, if given:

    • String – Will inject the single payload.

    • Array – Will iterate over all payloads and inject them.

    • Hash – Expects Platform (as ‘Symbol`s ) for keys and Array of

      `payloads` for values. The applicable `payloads` will be
{Platform::Manager#pick picked} from the hash based on
{Element::Capabilities::Submittable#platforms applicable platforms}
for the {Element::Capabilities::Submittable#action resource} to be audited.

    Delay stub ‘__TIME__` will be substituted with `timeout / timeout_divider`.

  • opts (Hash) —

    Options as described in Mutable::MUTATION_OPTIONS with the specified extras.

Options Hash (opts):

  • :timeout (Integer) —

    Milliseconds to wait for the request to complete.

  • :timeout_divider (Integer) — default: 1 —

    ‘__TIME__ = timeout / timeout_divider`

  • :add (Integer) — default: 0 —

    Add this integer to the expected time the request is supposed to take, in milliseconds.

Returns:

  • (Bool) —

    ‘true` if the audit was scheduled successfully, `false` otherwise (like if the resource is out of scope).



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 228

def timeout_analysis( payloads, opts )
    return false if self.inputs.empty?

    if scope.out?
        print_debug 'Timeout analysis: Element is out of scope,' <<
                        " skipping: #{audit_id}"
        return false
    end

    timing_attack_probe( payloads, opts ) do |elem|
        next if Timeout.deduplicate? && Timeout.candidates_include?( elem )

        print_info 'Found a candidate for Phase 2 -- ' <<
            "#{elem.type.capitalize} input '#{elem.affected_input_name}' " <<
            "pointing to: #{elem.action}"
        print_verbose "Using: #{elem.affected_input_value.inspect}"

        Timeout.add_phase_2_candidate( elem )
    end

    true
end

#timeout_id ⇒ Object 



251
252
253
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 251

def timeout_id
    "#{audit_id( self.affected_input_value )}:#{self.affected_input_name}"
end

#timing_attack_probe(payloads, options, &block) ⇒ Object

Performs a simple probe for elements whose submission results in a response time that matches the delay criteria in ‘options`.

Parameters:

  • payloads (String, Array<String>, Hash{Symbol => <String, Array<String>>}) —

    Payloads to inject, if given:

    • String – Will inject the single payload.

    • Array – Will iterate over all payloads and inject them.

    • Hash – Expects Platform (as ‘Symbol`s ) for keys and Array of

      `payloads` for values. The applicable `payloads` will be
{Platform::Manager#pick picked} from the hash based on
{Element::Capabilities::Submittable#platforms applicable platforms}
for the {Element::Capabilities::Submittable#action resource} to be audited.

    Delay stub ‘__TIME__` will be substituted with `timeout / timeout_divider`.

  • opts (Hash) —

    Options as described in Mutable::MUTATION_OPTIONS with the specified extras.



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 289

def timing_attack_probe( payloads, options, &block )
    fail ArgumentError, 'Missing block' if !block_given?

    options                     = options.dup
    options[:delay]             = options.delete(:timeout)
    options[:timeout_divider] ||= 1
    options[:add]             ||= 0

    options.merge!(
        # Don't submit the form with its original values, we don't want
        # any interference during timing attacks.
        skip_original:     true,

        # Intercept each element mutation prior to it being submitted and
        # replace the '__TIME__' stub with the actual delay value.
        each_mutation:     proc do |mutation|
            injected = mutation.affected_input_value

            # Preserve the placeholder (__TIME__) payload because it's going to
            # be needed for the verification phases...
            mutation.audit_options[:timing_string] = injected

            # ...but update it to use a real payload for this audit.
            mutation.affected_input_value = injected.
                gsub( '__TIME__', payload_delay_from_options( options ) )
        end
    )

    # Ignore response bodies to preserve bandwidth since we don't care
    # about them anyways.
    options[:submit] = {
        response_max_size: 0,
        timeout:           timeout_from_options( options ),
    }

    if debug_level_2?
        print_debug_level_2 "#{__method__}: #{options}"
    end

    audit( payloads, options ) do |response, mutation|
        next if !response.timed_out?
        block.call( mutation, response )
    end
end

#timing_attack_verify(delay, &block) ⇒ Object

Verifies that response times are controllable for elements picked by #timing_attack_probe.

  • Liveness check: Element is submitted as is with a very high timeout value, to make sure that (or wait until) the server is alive to #ensure_responsiveness.

  • Control check: Element is, again, submitted as is, although this time with a timeout value of ‘delay` to ensure that the server is stable enough to be checked.

    • If this fails the check is aborted.

  • Verification: Element is submitted with an increased delay to verify the vulnerability.

    • If verification succeeds the ‘block` is called.

  • Stabilize responsiveness: Wait for the effects of the timing attack to wear off by calling #ensure_responsiveness.

Parameters:

  • delay (Integer)
  • block (Block) 


352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/arachni/element/capabilities/analyzable/timeout.rb', line 352

def timing_attack_verify( delay, &block )
    fail ArgumentError, 'Missing block' if !block_given?

    options         = self.audit_options
    options[:delay] = delay

    # Actual value to use for the server-side delay operation.
    payload_delay = payload_delay_from_options( options )

    # Prepared payload, which will hopefully introduce a server-side delay.
    payload = options[:timing_string].gsub( '__TIME__', payload_delay )

    # Timeout value (in milliseconds) for the HTTP request.
    timeout = timeout_from_options( options )

    # Make sure we're starting off with a clean slate.
    ensure_responsiveness

    # This is the control; submits the element with its default (or sample,
    # if its defaults are empty) values and ensures that element submission
    # doesn't time out by default.
    #
    # If it does, then there's no way for us to test it reliably.
    if_timeout_control_check_ok timeout do

        # Update our candidate mutation's affected input with the new payload.
        self.affected_input_value = payload

        print_verbose "  * Payload delay:   #{payload_delay}"
        print_verbose "  * Request timeout: #{timeout}"
        print_verbose "  * Payload:         #{payload.inspect}"

        submit( response_max_size: 0, timeout: timeout ) do |response|
            if !response.timed_out?
                print_info '* Verification failed.'
                print_verbose "  * Server responded in #{response.time} seconds."
                next
            end

            block.call( response )

            ensure_responsiveness
        end
    end

    http.run
end