Class: Buby

Inherits:
Object show all
Defined in:
lib/buby.rb,
lib/buby/tab.rb,
lib/buby/cookie.rb,
lib/buby/version.rb,
lib/buby/extender.rb,
lib/buby/implants.rb,
lib/buby/parameter.rb,
lib/buby/scan_issue.rb,
lib/buby/http_listener.rb,
lib/buby/parameter/url.rb,
lib/buby/scanner_check.rb,
lib/buby/implants/jruby.rb,
lib/buby/parameter/base.rb,
lib/buby/parameter/body.rb,
lib/buby/proxy_listener.rb,
lib/buby/implants/cookie.rb,
lib/buby/parameter/cookie.rb,
lib/buby/scanner_listener.rb,
lib/buby/implants/parameter.rb,
lib/buby/implants/temp_file.rb,
lib/buby/message_editor_tab.rb,
lib/buby/implants/scan_issue.rb,
lib/buby/context_menu_factory.rb,
lib/buby/implants/text_editor.rb,
lib/buby/implants/request_info.rb,
lib/buby/scope_change_listener.rb,
lib/buby/implants/response_info.rb,
lib/buby/implants/message_editor.rb,
lib/buby/scanner_insertion_point.rb,
lib/buby/session_handling_action.rb,
lib/buby/implants/intruder_attack.rb,
lib/buby/implants/scan_queue_item.rb,
lib/buby/message_editor_controller.rb,
lib/buby/implants/extension_helpers.rb,
lib/buby/intruder_payload_generator.rb,
lib/buby/intruder_payload_processor.rb,
lib/buby/message_editor_tab_factory.rb,
lib/buby/implants/buby_array_wrapper.rb,
lib/buby/implants/http_request_response.rb,
lib/buby/implants/context_menu_invocation.rb,
lib/buby/implants/scanner_insertion_point.rb,
lib/buby/scanner_insertion_point_provider.rb,
lib/buby/implants/intercepted_proxy_message.rb,
lib/buby/implants/message_editor_controller.rb,
lib/buby/intruder_payload_generator_factory.rb

Overview

TODO:

move more to BurpExtender side

Buby is a mash-up of the commercial security testing web proxy PortSwigger Burp Suite(tm) allowing you to add scripting to Burp. Burp is driven from and tied to JRuby with a Java extension using the BurpExtender API.

The Buby class is an abstract implementation of a BurpExtender ruby handler. Included are several abstract event handlers used from the BurpExtender java implementation:

  • evt_extender_init

  • evt_proxy_message

  • evt_command_line_args (removed in 1.5.01)

  • evt_register_callbacks

  • evt_application_closing (deprecated)

  • evt_extension_unloaded

Buby also supports the newer event handlers available in Burp 1.2.09 and up:

  • evt_http_message

  • evt_scan_issue

This class also exposes several methods to access Burp functionality and user interfaces through the IBurpExtenderCallbacks interface (note, several abbreviated aliases also exist for each):

  • doActiveScan

  • doPassiveScan

  • excludeFromScope

  • includeInScope

  • isInScope

  • issueAlert

  • makeHttpRequest

  • sendToIntruder

  • sendToRepeater

  • sendToSpider

Buby also provides front-end ruby methods for the various callback methods supported by Burp. New callbacks have been cropping up in newer Burp versions frequently.

Available since Burp 1.2.09:

  • getProxyHistory

  • getSiteMap

  • restoreState

  • saveState

  • getParameters

  • getHeaders

Available since Burp 1.2.15:

  • getScanIssues

Available since Burp 1.2.17:

  • exitSuite

If you wish to access any of the IBurpExtenderCallbacks methods directly. You can use 'burp_callbacks' to obtain a reference.

CREDIT:

Burp and Burp Suite are trademarks of PortSwigger(ltd)

Copyright 2013 PortSwigger Ltd. All rights reserved.
See http://portswigger.net for license terms.

This JRuby library and the accompanying Java and JRuby BurpExtender implementations were written by Timur Duehr @ Matasano Security. The original version of this library and BurpExtender.java implementation was written by Eric Monti @ Matasano Security. Matasano Security claims no professional or legal affiliation with PortSwigger LTD.

However, the authors would like to express their personal and professional respect and admiration to Burp's authors and appreciation to PortSwigger for the availability of the IBurpExtender extension API and its continued improvement. The availability of this interface goes a long way to helping make Burp Suite a truly first-class application.

Defined Under Namespace

Modules: Extender, HttpRequestResponseHelper, Implants, Parameter, ScanIssueHelper, Version Classes: BubyArrayWrapper, ContextMenuFactory, Cookie, HttpListener, HttpRequestResponseList, IntruderPayloadGenerator, IntruderPayloadGeneratorFactory, IntruderPayloadProcessor, MessageEditorController, MessageEditorTab, MessageEditorTabFactory, ProxyListener, ScanIssue, ScanIssuesList, ScannerCheck, ScannerInsertionPoint, ScannerInsertionPointProvider, ScannerListener, ScopeChangeListener, SessionHandlingAction, Tab

Constant Summary collapse

VERSION =
Deprecated.

moving to proper version module

Buby::Version::STRING
COMPAT_VERSION =

latest tested version of burp

'1.5.17'
LIBPATH =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Deprecated.

to be removed next version

:stopdoc:

::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
PATH =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Deprecated.

to be removed next version

::File.dirname(LIBPATH) + ::File::SEPARATOR
ACTION_FOLLOW_RULES =
Java::Burp::IInterceptedProxyMessage::ACTION_FOLLOW_RULES
ACTION_DO_INTERCEPT =
Java::Burp::IInterceptedProxyMessage::ACTION_DO_INTERCEPT
ACTION_DONT_INTERCEPT =
Java::Burp::IInterceptedProxyMessage::ACTION_DONT_INTERCEPT
ACTION_DROP =
Java::Burp::IInterceptedProxyMessage::ACTION_DROP
ACTION_FOLLOW_RULES_AND_REHOOK =
Java::Burp::IInterceptedProxyMessage::ACTION_FOLLOW_RULES_AND_REHOOK
ACTION_DO_INTERCEPT_AND_REHOOK =
Java::Burp::IInterceptedProxyMessage::ACTION_DO_INTERCEPT_AND_REHOOK
ACTION_DONT_INTERCEPT_AND_REHOOK =
Java::Burp::IInterceptedProxyMessage::ACTION_DONT_INTERCEPT_AND_REHOOK
TOOL_SUITE =

Flag used to identify Burp Suite as a whole.

Java::Burp::IBurpExtenderCallbacks::TOOL_SUITE
TOOL_TARGET =

Flag used to identify the Burp Target tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_TARGET
TOOL_PROXY =

Flag used to identify the Burp Proxy tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_PROXY
TOOL_SPIDER =

Flag used to identify the Burp Spider tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_SPIDER
TOOL_SCANNER =

Flag used to identify the Burp Scanner tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_SCANNER
TOOL_INTRUDER =

Flag used to identify the Burp Intruder tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_INTRUDER
TOOL_REPEATER =

Flag used to identify the Burp Repeater tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_REPEATER
TOOL_SEQUENCER =

Flag used to identify the Burp Sequencer tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_SEQUENCER
TOOL_DECODER =

Flag used to identify the Burp Decoder tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_DECODER
TOOL_COMPARER =

Flag used to identify the Burp Comparer tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_COMPARER
TOOL_EXTENDER =

Flag used to identify the Burp Extender tool.

Java::Burp::IBurpExtenderCallbacks::TOOL_EXTENDER

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(other = nil) ⇒ Buby

:startdoc:


122
123
124
125
126
127
128
# File 'lib/buby.rb', line 122

def initialize(other=nil)
  if other
    raise TypeError, "argument must be another kind of Buby, got #{other.class}" unless other.is_a? Buby
    @burp_extender = other.burp_extender
    @burp_callbacks = other.burp_callbacks
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args, &block) ⇒ Object

so things will JustWork(tm) for most new interface additions.


2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
# File 'lib/buby.rb', line 2145

def method_missing(meth, *args, &block)
  if _check_cb.respond_to?(meth)
    warn 'this method may not be implemented fully'
    self.class.class_exec(meth) do |meth|
      define_method(meth) do |*argv, &blck|
        _check_and_callback(meth, *argv, &blck)
      end
    end
    __send__ meth, *args, &block
  else
    super
  end
end

Class Method Details

.burp_loaded?Boolean

Checks the Java namespace to see if Burp has been loaded.

Returns:

  • (Boolean)

2304
2305
2306
2307
2308
2309
2310
2311
# File 'lib/buby.rb', line 2304

def self.burp_loaded?
  @burp_loaded ||= begin
    Java.burp.StartBurp
    true
  rescue NameError
    false
  end
end

.legacy_mode?Class?

determines if we're running in legacy mode

Returns:

  • (Class, nil)

2315
2316
2317
2318
2319
2320
2321
2322
# File 'lib/buby.rb', line 2315

def self.legacy_mode?
  @legacy ||= begin
    Java.burp.BurpExtender
  rescue NameError
    false
  end
  @legacy
end

.libpath(*args) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Returns the library path for the module. If any arguments are given, they will be joined to the end of the libray path using File.join.


2336
2337
2338
# File 'lib/buby.rb', line 2336

def self.libpath( *args )
  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
end

.load_burp(jar_path) ⇒ Object

Attempts to load burp with require and confirm it provides the required class in the Java namespace.

Returns: true/false depending on whether the required jar provides us the required class

Raises: may raise the usual require exceptions if jar_path is bad.


2298
2299
2300
2301
# File 'lib/buby.rb', line 2298

def self.load_burp(jar_path)
  require jar_path
  return burp_loaded?
end

.path(*args) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Returns the lpath for the module. If any arguments are given, they will be joined to the end of the path using File.join.


2346
2347
2348
# File 'lib/buby.rb', line 2346

def self.path( *args )
  args.empty? ? PATH : ::File.join(PATH, args.flatten)
end

.require_all_libs_relative_to(fname, dir = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Utility method used to require all files ending in .rb that lie in the directory below this file that has the same name as the filename passed in. Optionally, a specific directory name can be passed in such that the filename does not have to be equivalent to the directory.


2357
2358
2359
2360
2361
2362
2363
# File 'lib/buby.rb', line 2357

def self.require_all_libs_relative_to( fname, dir = nil )
  dir ||= ::File.basename(fname, '.*')
  search_me = ::File.expand_path(
      ::File.join(::File.dirname(fname), dir, '**', '*.rb'))

  Dir.glob(search_me).sort.each {|rb| require rb}
end

.start(extender = nil, h_class = nil, init_args = nil, args = nil) ⇒ Object

Starts burp using a supplied handler class

Parameters:

  • extender (defaults to: nil)

    Buby BurpExtender to use for callbacks

  • h_class (Class) (defaults to: nil)

    Buby or a derived class. instance of which will become handler.

  • args (Array<String>) (defaults to: nil)

    arguments to Burp

  • init_args (defaults to: nil)

    arguments to the handler constructor

    @return Buby handler instance


2278
2279
2280
2281
2282
2283
# File 'lib/buby.rb', line 2278

def self.start(extender = nil, h_class=nil, init_args=nil, args=nil)
  h_class ||= self
  init_args ||= []
  args ||= []
  h_class.new(*init_args).start_burp(extender, args)
end

.start_burp(extender = nil, h_class = nil, init_args = nil, args = nil) ⇒ Object

Deprecated.

Use Buby.start instead

See Also:


2287
2288
2289
# File 'lib/buby.rb', line 2287

def self.start_burp(extender = nil, h_class = nil, init_args = nil, args = nil)
  self.start(extender, h_class, init_args, args)
end

Instance Method Details

#_check_and_callback(meth, *args, &block) ⇒ Object

This method is a __send__ callback gate for the IBurpExtenderCallbacks reference. It first checks to see if a method is available before calling with the specified arguments, and raises an exception if it is unavailable.

  • meth = string or symbol name of method

  • args = variable length array of arguments to pass to meth


676
677
678
679
680
681
682
# File 'lib/buby.rb', line 676

def _check_and_callback(meth, *args, &block)
  begin
    _check_cb.__send__ meth, *args, &block
  rescue NoMethodError
    raise "#{meth} is not available in your version of Burp"
  end
end

#_check_cbObject

Internal method to check for the existence of the burp_callbacks reference before doing anything with it.


149
150
151
# File 'lib/buby.rb', line 149

def _check_cb
  @burp_callbacks or raise "Burp callbacks have not been set"
end

#activate!(extender) ⇒ Object

Makes this handler the active Ruby handler object for the BurpExtender Java runtime. (there can be only one!)

Parameters:

  • extender

    Buby's BurpExtender interface


133
134
135
# File 'lib/buby.rb', line 133

def activate!(extender)
  extender.handler = self
end

#addScanIssue(issue) ⇒ Object Also known as: add_scan_issue

Note:

Wherever possible, extensions should implement custom Scanner checks using IScannerCheck and report issues via those checks, so as to integrate with Burp's user-driven workflow, and ensure proper consolidation of duplicate reported issues. This method is only designed for tasks outside of the normal testing workflow, such as importing results from other scanning tools.

This method is used to register a new Scanner issue.

Parameters:

  • issue (IScanIssue)

    An issue to be added to the scan results.


1685
1686
1687
# File 'lib/buby.rb', line 1685

def addScanIssue(issue)
  _check_and_callback(:addScanIssue, issue)
end

#addSuiteTab(tab) ⇒ Object Also known as: add_suite_tab

This method is used to add a custom tab to the main Burp Suite window.

Parameters:

  • tab (ITab)

    A tab to be added to the suite's user interface.


1490
1491
1492
# File 'lib/buby.rb', line 1490

def addSuiteTab(tab)
  _check_and_callback(:addSuiteTab, tab)
end

#addToSiteMap(item) ⇒ Object Also known as: add_to_site_map

This method can be used to add an item to Burp's site map with the specified request/response details. This will overwrite the details of any existing matching item in the site map.

This method is only available with Burp 1.3.09+

Parameters:

  • item (IHttpRequestResponse)

    Details of the item to be added to the site map


830
831
832
# File 'lib/buby.rb', line 830

def addToSiteMap(item)
  _check_and_callback(:addToSiteMap, item)
end

#application_closingObject

This method is called by BurpExtender right before closing the application. Implementations can use this method to perform cleanup tasks such as closing files or databases before exit.


2072
2073
2074
# File 'lib/buby.rb', line 2072

def application_closing
  pp([:got_app_close]) if $DEBUG
end

#applyMarkers(httpRequestResponse, requestMarkers, responseMarkers) ⇒ IHttpRequestResponseWithMarkers Also known as: apply_markers

TODO:

Bring IHttpRequestResponse helper up to date

This method is used to apply markers to an HTTP request or response, at offsets into the message that are relevant for some particular purpose. Markers are used in various situations, such as specifying Intruder payload positions, Scanner insertion points, and highlights in Scanner issues.

Parameters:

  • httpRequestResponse (IHttpRequestResponse)

    The object to which the markers should be applied.

  • requestMarkers (Array<Array<Fixnum>>)

    A list of index pairs representing the offsets of markers to be applied to the request message. Each item in the list must be an int array containing the start and end offsets for the marker. The markers in the list should be in sequence and not overlapping. This parameter is optional and may be nil if no response markers are required.

  • responseMarkers (Array<Array<Fixnum>>)

    A list of index pairs representing the offsets of markers to be applied to the response message. Each item in the list must be an int array containing the start and end offsets for the marker. The markers in the list should be in sequence and not overlapping. This parameter is optional and may be nil if no response markers are required.

Returns:

  • (IHttpRequestResponseWithMarkers)

    A marked request/response pair.


1658
1659
1660
# File 'lib/buby.rb', line 1658

def applyMarkers(httpRequestResponse, requestMarkers, responseMarkers)
  _check_and_callback(:applyMarkers, httpRequestResponse, requestMarkers, responseMarkers).tap{|obj| Buby::HttpRequestResponseHelper.implant(obj)}
end

#burp_callbacksObject

Returns the internal reference to the IBupExtenderCallbacks instance. This reference gets set from Java through the evt_register_callbacks method. It is exposed to allow you to access the IBurpExtenderCallbacks instance directly if you so choose.


145
# File 'lib/buby.rb', line 145

def burp_callbacks; @burp_callbacks; end

#burp_extenderObject

Returns the internal reference to the BurpExtender instance. This reference gets set from Java through the evt_extender_init method.


139
# File 'lib/buby.rb', line 139

def burp_extender; @burp_extender; end

#createMessageEditor(controller = nil, editable = true) ⇒ IMessageEditor Also known as: create_message_editor

This method is used to create a new instance of Burp's HTTP message editor, for the extension to use in its own UI.

Parameters:

  • controller (defaults to: nil)

    An object created by the extension that implements the IMessageEditorController interface. This parameter is optional and defaults to nil. If it is provided, then the message editor will query the controller when required to obtain details about the currently displayed message, including the IHttpService for the message, and the associated request or response message. If a controller is not provided, then the message editor will not support context menu actions, such as sending requests to other Burp tools.

  • editable (Boolean) (defaults to: true)

    Indicates whether the editor created should be editable, or used only for message viewing.

Returns:

  • (IMessageEditor)

    An object which the extension can use in its own UI.


1531
1532
1533
# File 'lib/buby.rb', line 1531

def createMessageEditor(controller = nil, editable = true)
  Buby::Implants::MessageEditor.implant _check_and_callback(:createMessageEditor, controller, editable)
end

#createTextEditorITextEditor Also known as: create_text_editor

This method is used to create a new instance of Burp's plain text editor, for the extension to use in its own UI.

Returns:

  • (ITextEditor)

    A new text editor the extension can use in its own UI.


1566
1567
1568
# File 'lib/buby.rb', line 1566

def createTextEditor
  Buby::Implants::TextEditor.implant _check_and_callback(:createTextEditor)
end

#customizeUiComponent(component) ⇒ Object Also known as: customize_ui_component

This method is used to customize UI components in line with Burp's UI style, including font size, colors, table line spacing, etc.

Parameters:

  • component (Component)

    The UI component to be customized.


1510
1511
1512
# File 'lib/buby.rb', line 1510

def customizeUiComponent(component)
  _check_and_callback(:customizeUiComponent, component)
end

#doActiveScan(host, port, useHttps, request, insertionPointOffsets = nil) ⇒ IScanQueueItem #doActiveScan(request, insertionPointOffsets = nil) ⇒ IScanQueueItem #doActiveScan(service, request, insertionPointOffsets = nil) ⇒ IScanQueueItem #doActiveScan(url, insertionPointOffsets = nil) ⇒ IScanQueueItem Also known as: do_active_scan, active_scan

This method can be used to send an HTTP request to the Burp Scanner tool to perform an active vulnerability scan. If the request is not within the current active scanning scope, the user will be asked if they wish to proceed with the scan.

Overloads:

  • #doActiveScan(host, port, useHttps, request, insertionPointOffsets = nil) ⇒ IScanQueueItem

    Parameters:

    • host (String, java.net.URL, URI)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • useHttps (Boolean)

      Flags whether the protocol is HTTPS or HTTP.

    • request (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request.

    • insertionPointOffsets (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

  • #doActiveScan(request, insertionPointOffsets = nil) ⇒ IScanQueueItem

    Parameters:

    • request (IHttpRequestResponse)

      Request object containing details about the request to scan.

    • insertionPointOffsets (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

  • #doActiveScan(service, request, insertionPointOffsets = nil) ⇒ IScanQueueItem

    Parameters:

    • service (IHttpService)

      Object describing host, port and protocol for scan.

    • request (IHttpRequestResponse, String, Array<byte>)

      Request object containing details about the request to scan.

    • insertionPointOffsets (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

  • #doActiveScan(url, insertionPointOffsets = nil) ⇒ IScanQueueItem

    Parameters:

    • url (String, URI, java.net.URL)

      Build a GET request and scan url.

    • insertionPointOffsets (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

Returns:

  • (IScanQueueItem)

    The resulting scan queue item.

Raises:

  • (ArgumentError)

193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
# File 'lib/buby.rb', line 193

def doActiveScan(*args)
  raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless (1..5).include?(args.size)
  host, port, https, req, ip_off = *args
  if args.size < 4
    case args.first
    when Java::Burp::IHttpRequestResponse
      raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless args.size < 3
      req, ip_off = *args
      host = req.host
      port = req.port
      https = req.protocol
    when Java::Burp::IHttpService
      raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless args.size
      serv, req, ip_off = *args
      https = serv.getProtocol
      host = serv.getHost
      port = serv.getPort
      req = req.request
    else
      url = (req.kind_of?(URI) || req.kind_of?(Java::JavaNet::URL)) ? req : Java::JavaNet::URL.new(req.to_s)
      req = helpers.buildHttpRequest req
      host = url.host
      port = url.port
      https = url.respond_to? :scheme ? url.scheme : url.protocol
    end
  end

  https = case https.to_s.downcase
  when 'https'
    true
  when 'http'
    false
  else
    !!https
  end

  port ||= https ? 443 : 80
  port = https ? 443 : 80 if port < 0
  host = host.host if host.respond_to? :host

  req = req.request if req.respond_to? :request
  req = req.to_java_bytes if req.respond_to? :to_java_bytes
  scanq = if getBurpVersion
    _check_and_callback :doActiveScan, host, port, https, req, ip_off
  else
    _check_and_callback :doActiveScan, host, port, https, req
  end
  Buby::Implants::ScanQueueItem.implant scanq
end

#doPassiveScan(host, port, useHttps, request, response) ⇒ IScanQueueItem #doPassiveScan(host, port, useHttps, request_response) ⇒ IScanQueueItem #doPassiveScan(service, request, response) ⇒ IScanQueueItem #doPassiveScan(service, request_response) ⇒ IScanQueueItem #doPassiveScan(request) ⇒ IScanQueueItem Also known as: do_passive_scan, passive_scan

Send an HTTP request and response to the Burp Scanner tool to perform a passive vulnerability scan.

Overloads:

  • #doPassiveScan(host, port, useHttps, request, response) ⇒ IScanQueueItem

    Parameters:

    • host (String, java.net.URL, URI)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • useHttps (Boolean)

      Flags whether the protocol is HTTPS or HTTP.

    • request (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request.

    • response (String, Array<byte>, IHttpRequestResponse)

      The full HTTP response.

  • #doPassiveScan(host, port, useHttps, request_response) ⇒ IScanQueueItem

    Parameters:

    • host (String, java.net.URL, URI)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • useHttps (Boolean)

      Flags whether the protocol is HTTPS or HTTP.

    • request (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request and response.

  • #doPassiveScan(service, request, response) ⇒ IScanQueueItem

    Parameters:

    • service (IHttpService)

      Object describing host, port and protocol for scan.

    • request (IHttpRequestResponse, String, Array<byte>)

      Request object containing details about the request to scan.

    • request (IHttpRequestResponse, String, Array<byte>)

      Request object containing details about the response to scan.

  • #doPassiveScan(service, request_response) ⇒ IScanQueueItem

    Parameters:

    • service (IHttpService)

      Object describing host, port and protocol for scan.

    • request (IHttpRequestResponse, String, Array<byte>)

      Request object containing details about the request to scan.

  • #doPassiveScan(request) ⇒ IScanQueueItem

    Parameters:

    • request (IHttpRequestResponse)

      Request object containing details about the request to scan.

Returns:

  • (IScanQueueItem)

    The resulting scan queue item.

Raises:

  • (ArgumentError)

277
278
279
280
281
282
283
284
285
286
287
288
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
# File 'lib/buby.rb', line 277

def doPassiveScan(*args)
  raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1..4)" unless (1..4).include?(args.size)
  host, port, https, req, resp = *args
  case args.size
  when 1
    req = args.first
    host = req.getHost
    port = req.getPort
    https = req.getProtocol
    resp = req.getResponse
  when 2, 3
    serv, req = *args
    host = serv.getHost
    port = serv.getPort
    https = req.getProtocol
    resp = (resp && resp.getResponse) || req.getResponse
  when 4
    resp = req.response
  else
    # nop
  end

  https = case https.to_s.downcase
  when 'https'
    true
  when 'http'
    false
  else
    !!https
  end

  port ||= https ? 443 : 80
  port = https ? 443 : 80 if port < 0
  host = host.host if host.respond_to? :host

  req = req.request if req.respond_to? :request
  req = req.to_java_bytes if req.respond_to? :to_java_bytes

  resp = resp.response if resp.respond_to? :response
  resp = resp.to_java_bytes if resp.respond_to? :to_java_bytes

  Buby::Implants::ScanQueueItem.implant(_check_and_callback(:doPassiveScan, host, port, https, req, resp))
end

#evt_application_closingObject

Deprecated.

This method is called by BurpExtender right before closing the application. Implementations can use this method to perform cleanup tasks such as closing files or databases before exit.


2065
2066
2067
# File 'lib/buby.rb', line 2065

def evt_application_closing
  pp([:got_app_close]) if $DEBUG
end

#evt_command_line_args(args) ⇒ Object

Deprecated.
  • nothing calls this anymore

This method is called by the BurpExtender implementation Burp startup. The args parameter contains main()'s argv command-line arguments array.

Note: This maps to the 'setCommandLineArgs' method in the java implementation of BurpExtender.

The return value is ignored.


1726
1727
1728
# File 'lib/buby.rb', line 1726

def evt_command_line_args args
  pp([:got_args, args]) if $DEBUG
end

#evt_extender_init(ext) ⇒ Object

Deprecated.

This method is called by the BurpExtender java implementation upon initialization of the BurpExtender instance for Burp. The args parameter is passed with a instance of the newly initialized BurpExtender instance so that implementations can access and extend its public interfaces.

The return value is ignored.


1700
1701
1702
1703
# File 'lib/buby.rb', line 1700

def evt_extender_init ext
  @burp_extender = ext
  pp([:got_extender, ext]) if $DEBUG
end

#evt_http_message(tool_name, is_request, message_info) ⇒ Object

Deprecated.

This is the called by the legacy interface, use #process_http_message instead

TODO:

Bring IHttpRequestResponse helper up to date

Note:

Changed in Burp 1.5.01+

This method is invoked whenever any of Burp's tools makes an HTTP request or receives a response. This is effectively a generalised version of the pre-existing evt_proxy_message method, and can be used to intercept and modify the HTTP traffic of all Burp tools.

IMPORTANT: This event handler is only used in Burp version 1.2.09 and higher.

Note: this method maps to the processHttpMessage BurpExtender Java method.

This method should be overridden if you wish to implement functionality relating to generalized requests and responses from any BurpSuite tool.

You may want to use evt_proxy_message if you only intend to work on proxied messages. Note, however, the IHttpRequestResponse Java object is not used in evt_proxy_message and gives evt_http_message a somewhat nicer interface to work with.

Parameters:

  • tool_name = a string name of the tool that generated the message

  • is_request = boolean true = request / false = response

  • message_info = an instance of the IHttpRequestResponse Java class with methods for accessing and manipulating various attributes of the message.


2000
2001
2002
2003
# File 'lib/buby.rb', line 2000

def evt_http_message(tool_name, is_request, message_info)
  HttpRequestResponseHelper.implant(message_info)
  pp([:got_evt_http_message, tool_name, is_request, message_info]) if $DEBUG
end

#evt_proxy_message(msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action) ⇒ Object

Deprecated.

This method is called by BurpExtender while proxying HTTP messages and before passing them through the Burp proxy. Implementations can use this method to implement arbitrary processing upon HTTP requests and responses such as interception, logging, modification, and so on.

The 'is_req' parameter indicates whether it is a response or request.

Note: This method maps to the 'processProxyMessage' method in the java implementation of BurpExtender.

See also, evt_proxy_message_raw which is actually called before this in the BurpExtender processProxyMessage handler.

Below are the parameters descriptions based on the IBurpExtender javadoc. Where applicable, decriptions have been modified for local parameter naming and other ruby-specific details added.

  • msg_ref: An identifier which is unique to a single request/response pair. This can be used to correlate details of requests and responses and perform processing on the response message accordingly. This number also corresponds to the Burp UI's proxy “history” # column.

  • is_req: (true/false) Flags whether the message is a client request or a server response.

  • rhost: The hostname of the remote HTTP server.

  • rport: The port of the remote HTTP server.

  • is_https: Flags whether the protocol is HTTPS or HTTP.

  • http_meth: The method verb used in the client request.

  • url: The requested URL. Set in both the request and response.

  • resourceType: The filetype of the requested resource, or nil if the resource has no filetype.

  • status: The HTTP status code returned by the server. This value is nil for request messages.

  • req_content_type: The content-type string returned by the server. This value is nil for request messages.

  • message: The full HTTP message. **Ruby note:

    For convenience, the message is received and returned as a ruby
    String object. Internally within Burp it is handled as a java byte[]
    array. See also the notes about the return object below.
    
  • action: An array containing a single integer, allowing the implementation to communicate back to Burp Proxy a non-default interception action for the message. The default value is ACTION_FOLLOW_RULES (or 0). Possible values include:

    ACTION_FOLLOW_RULES = 0
    ACTION_DO_INTERCEPT = 1
    ACTION_DONT_INTERCEPT = 2
    ACTION_DROP = 3
    

    Refer to the BurpExtender.java source comments for more details.

Return Value:

Implementations should return either (a) the same object received
in the message paramater, or (b) a different object containing a
modified message.

**IMPORTANT RUBY NOTE: Always be sure to return a new object if making modifications to messages.

Explanation: The (a) and (b) convention above is followed rather literally during type conversion on the return value back into the java BurpExtender.

When determining whether a change has been made in the message or not, the decision is made based on whether the object returned is the same as the object submitted in the call to evt_proxy_message.

So, for example, using in-place modification of the message using range substring assignments or destructive method variations like String.sub!() and String.gsub! alone won't work because the same object gets returned to BurpExtender.

In short, this means that if you want modifications to be made, be sure to return a different String than the one you got in your handler.

So for example this code won't do anything at all:

...
message.sub!(/^GET /, "HEAD ")
return message

Nor this:

message[0..4] = "HEAD "
return message

But this will

...
return message.sub(/^GET /, "HEAD ")

And so will this

...
message[0..4] = "HEAD "
return message.dup

1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
# File 'lib/buby.rb', line 1936

def evt_proxy_message msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action
  pp([ (is_req)? :got_proxy_request : :got_proxy_response,
       [:msg_ref, msg_ref],
       [:is_req, is_req],
       [:rhost, rhost],
       [:rport, rport],
       [:is_https, is_https],
       [:http_meth, http_meth],
       [:url, url],
       [:resourceType, resourceType],
       [:status, status],
       [:req_content_type, req_content_type],
       [:message, message],
       [:action, action[0]] ]) if $DEBUG

  return message
end

#evt_proxy_message_raw(msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action) ⇒ Object

Deprecated.

Seems we need to specifically render our 'message' to a string here in ruby. Otherwise there's flakiness when converting certain binary non-ascii sequences. As long as we do it here, it should be fine.

Note: This method maps to the 'processProxyMessage' method in the java implementation of BurpExtender.

This method just handles the conversion to and from evt_proxy_message which expects a message string


1804
1805
1806
1807
1808
1809
1810
1811
1812
# File 'lib/buby.rb', line 1804

def evt_proxy_message_raw msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action
  pp [:evt_proxy_message_raw_hit, msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, message, action ] if $DEBUG

  str_msg = String.from_java_bytes(message)
  ret = evt_proxy_message(msg_ref, is_req, rhost, rport, is_https, http_meth, url, resourceType, status, req_content_type, str_msg, action)

  message = ret.to_java_bytes if ret.object_id != str_msg.object_id
  return message
end

#evt_register_callbacks(cb, alert = true) ⇒ IBurpExtenderCallbacks

Deprecated.

This method is called by BurpExtender on startup to register Burp's IBurpExtenderCallbacks interface object.

This maps to the 'registerExtenderCallbacks' method in the Java implementation of BurpExtender.

The return value is ignored.

Parameters:

  • cb (IBurpExtenderCallbacks)

    callbacks presented by burp

  • alert (Boolean) (defaults to: true)

Returns:

  • (IBurpExtenderCallbacks)

    cb


1741
1742
1743
1744
1745
# File 'lib/buby.rb', line 1741

def evt_register_callbacks cb, alert = true
  cb.issueAlert("[JRuby::#{self.class}] registered callback") if alert
  pp([:got_evt_register_callbacks, cb]) if $DEBUG
  @burp_callbacks = cb
end

#evt_scan_issue(issue) ⇒ Object

Deprecated.
TODO:

move implant to new way…

This method is invoked whenever Burp Scanner discovers a new, unique issue, and can be used to perform customised reporting or logging of detected issues.

IMPORTANT: This event handler is only used in Burp version 1.2.09 and higher.

Note: this method maps to the BurpExtender Java method.

Parameters:

  • issue = an instance of the IScanIssue Java class with methods for viewing information on the scan issue that was generated.


2039
2040
2041
2042
# File 'lib/buby.rb', line 2039

def evt_scan_issue(issue)
  ScanIssueHelper.implant(issue)
  pp([:got_scan_issue, issue]) if $DEBUG
end

#excludeFromScope(url) ⇒ void #excludeFromScope(req) ⇒ void #excludeFromScope(req_info) ⇒ void #excludeFromScope(serv, req) ⇒ void Also known as: exclude_from_scope, exclude_scope

This method returns an undefined value.

Exclude the specified URL from the Suite-wide scope.

Overloads:

  • #excludeFromScope(url) ⇒ void

    Parameters:

    • url (java.net.URL, URI, String)

      The URL to exclude from the Suite-wide scope.

  • #excludeFromScope(req) ⇒ void

    Parameters:

    • req (IHttpRequestResponse)

      The request to exclude from the Suite-wide scope.

  • #excludeFromScope(req_info) ⇒ void

    Parameters:

    • req_info (IRequestInfo)

      The request information to exclude from the Suite-wide scope.

  • #excludeFromScope(serv, req) ⇒ void

    Parameters:

    • serv (IHttpService)

      The HTTP service to exclude from the Suite-wide scope.

    • req (Array<byte>, String)

      The request to exclude


339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
# File 'lib/buby.rb', line 339

def excludeFromScope(*args)
  url, req = args
  case args.size
  when 1
    case url
    when Java::Burp::IHttpRequestResponse,  Java::Burp::IRequestInfo
      url = url.getUrl
    else
      url = Java::JavaNet::URL.new(url.to_s) unless url.is_a? Java::JavaNet::URL
    end
  when 2
    url = getHelpers.__analyzeRequest(url, req).getUrl
  else
    raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1,2)"
  end
  _check_and_callback :excludeFromScope, url
end

#exitSuite(prompt_user = false) ⇒ void Also known as: exit_suite, close

This method returns an undefined value.

Shuts down Burp programatically. If the method returns the user cancelled the shutdown prompt.

Parameters:

  • prompt_user (Boolean) (defaults to: false)

    Display a dialog to confirm shutdown


793
794
795
# File 'lib/buby.rb', line 793

def exitSuite(prompt_user=false)
  _check_and_callback(:exitSuite, prompt_user)
end

#extender_initialize(ext) ⇒ void

This method returns an undefined value.

This method is called by the BurpExtender implementations upon initialization of the BurpExtender instance for Burp. The args parameter is passed with a instance of the newly initialized BurpExtender instance so that implementations can access and extend its public interfaces.

Parameters:

  • ext (IBurpExtender)

1712
1713
1714
1715
1716
# File 'lib/buby.rb', line 1712

def extender_initialize ext
  @burp_extender = ext
  @tool_names = {}
  pp([:got_extender, ext]) if $DEBUG
end

#extension_unloadedObject

This method is called by BurpExtender right before unloading the extension. Implementations can use this method to perform cleanup tasks such as closing files or databases before exit.


2079
2080
2081
# File 'lib/buby.rb', line 2079

def extension_unloaded
  pp([:got_extension_unloaded]) if $DEBUG
end

#generateScanReport(format, issues, file) ⇒ void Also known as: generate_scan_report

This method returns an undefined value.

This method is used to generate a report for the specified Scanner issues. The report format can be specified. For all other reporting options, the default settings that appear in the reporting UI wizard are used.

Parameters:

  • format (String)

    The format to be used in the report. Accepted values are HTML and XML.

  • issues (Array<IScanIssue>)

    The Scanner issues to be reported.

  • file (String, java.io.File)

    The file to which the report will be saved.


2112
2113
2114
2115
# File 'lib/buby.rb', line 2112

def generateScanReport(format, issues, file)
  file = Java::JavaIo::File.new file if file.kind_of?(String)
  _check_and_callback(:generateScanReport, format, issues, file)
end

#getBurpVersionArray<String> Also known as: burp_version, get_burp_version

This method can be used to determine the version of the loaded burp at runtime.

Returns:

  • (Array<String>)

    the product name, major version, and minor version.


883
884
885
886
887
888
889
# File 'lib/buby.rb', line 883

def getBurpVersion
  begin
    _check_and_callback(:getBurpVersion)
  rescue
    nil
  end
end

#getCommandLineArgumentsArray<String> Also known as: get_command_line_arguments, command_line_arguments

This method returns the command line arguments that were passed to Burp on startup.

Returns:

  • (Array<String>)

    The command line arguments that were passed to Burp on startup.


2095
2096
2097
# File 'lib/buby.rb', line 2095

def getCommandLineArguments
  _check_and_callback(:getCommandLineArguments)
end

#getContextMenuFactoriesArray<IContextMenuFactory> Also known as: get_context_menu_factories, context_menu_factories

This method is used to retrieve the context menu factories that are registered by the extension.

Returns:

  • (Array<IContextMenuFactory>)

    A list of context menu factories that are currently registered by this extension.


1214
1215
1216
# File 'lib/buby.rb', line 1214

def getContextMenuFactories
  _check_and_callback(:getContextMenuFactories)
end

#getCookieJarContentsArray<ICookie> Also known as: get_cookie_jar_contents, cookie_jar_contents

This method is used to retrieve the contents of Burp's session handling cookie jar. Extensions that provide an ISessionHandlingAction can query and update the cookie jar in order to handle unusual session handling mechanisms.

Returns:

  • (Array<ICookie>)

    An array of the cookies representing the contents of Burp's session handling cookie jar.


1579
1580
1581
# File 'lib/buby.rb', line 1579

def getCookieJarContents
  _check_and_callback(:getCookieJarContents).tap{|arr| Buby::Implants::Cookie.implant(arr.first)}
end

#getExtensionFilenameString Also known as: get_extension_filename, extension_filename

This method retrieves the absolute path name of the file from which the current extension was loaded.

Returns:

  • (String)

    The absolute path name of the file from which the current extension was loaded.


2124
2125
2126
# File 'lib/buby.rb', line 2124

def getExtensionFilename
  _check_and_callback(:getExtensionFilename)
end

#getExtensionStateListenersArray<IExtensionStateListener> Also known as: get_extension_state_listeners, extension_state_listeners

This method is used to retrieve the extension state listeners that are registered by the extension.

Returns:

  • (Array<IExtensionStateListener>)

    A list of extension state listeners that are currently registered by this extension.


996
997
998
# File 'lib/buby.rb', line 996

def getExtensionStateListeners
  _check_and_callback(:getExtensionStateListeners)
end

#getHeaders(message) ⇒ Array<Array<String>> Also known as: headers, get_headers

Deprecated.

Use IExtensionHelpers.analyzeRequest or IExtensionHelpers.analyzeResponse() instead.

Note:

This method is only available with Burp 1.2.09+ and is deprecated in 1.5.01+

Parses a raw HTTP message (request or response ) and returns an associative array containing the headers as they are structured in the 'Headers' tab in the Burp request/response viewer UI.

This method parses the specified request and returns details of each HTTP header.

Parameters:

  • message (Array<byte>, String)

    The request to be parsed.

Returns:

  • (Array<Array<String>>)

    An array of HTTP headers.


782
783
784
785
# File 'lib/buby.rb', line 782

def getHeaders(message)
  message = message.to_java_bytes if message.is_a? String
  _check_and_callback(:getHeaders, message)
end

#getHelpersObject Also known as: helpers, get_helpers

This method is used to obtain an IExtensionHelpers object, which can be used by the extension to perform numerous useful tasks.

building and analyzing HTTP requests.

Returns:

  • An object containing numerous helper methods, for tasks such as


912
913
914
# File 'lib/buby.rb', line 912

def getHelpers
  @helpers ||= Buby::Implants::ExtensionHelpers.implant(_check_and_callback(:getHelpers))
end

#getHttpListenersArray<IHttpListener> Also known as: get_http_listeners, http_listeners

This method is used to retrieve the HTTP listeners that are registered by the extension.

Returns:

  • (Array<IHttpListener>)

    A list of HTTP listeners that are currently registered by this extension.


1040
1041
1042
# File 'lib/buby.rb', line 1040

def getHttpListeners
  _check_and_callback(:getHttpListeners)
end

#getIntruderPayloadGeneratorFactoriesArray<IIntruderPayloadGeneratorFactory> Also known as: get_intruder_payload_generator_factories, intruder_payload_generator_factories

This method is used to retrieve the Intruder payload generator factories that are registered by the extension.

Returns:

  • (Array<IIntruderPayloadGeneratorFactory>)

    A list of Intruder payload generator factories that are currently registered by this extension.


1388
1389
1390
# File 'lib/buby.rb', line 1388

def getIntruderPayloadGeneratorFactories
  _check_and_callback(:getIntruderPayloadGeneratorFactories)
end

#getIntruderPayloadProcessorsArray<IIntruderPayloadProcessor> Also known as: get_intruder_payload_processors, intruder_payload_processors

This method is used to retrieve the Intruder payload processors that are registered by the extension.

Returns:

  • (Array<IIntruderPayloadProcessor>)

    A list of Intruder payload processors that are currently registered by this extension.


1428
1429
1430
# File 'lib/buby.rb', line 1428

def getIntruderPayloadProcessors
  _check_and_callback(:getIntruderPayloadProcessors)
end

#getMessageEditorTabFactoriesArray<IMessageEditorTabFactory> Also known as: get_message_editor_tab_factories, message_editor_tab_factories

This method is used to retrieve the message editor tab factories that are registered by the extension.

Returns:

  • (Array<IMessageEditorTabFactory>)

    A list of message editor tab factories that are currently registered by this extension.


1262
1263
1264
# File 'lib/buby.rb', line 1262

def getMessageEditorTabFactories
  _check_and_callback(:getMessageEditorTabFactories)
end

#getParameters(request) ⇒ Array<Array<String{ name, value, type }>> Also known as: parameters, get_parameters

Deprecated.

Use IExtensionHelpers.analyzeRequest() instead.

Note:

This method is only available with Burp 1.2.09+ and is deprecated in 1.5.01+

Parses a raw HTTP request message and returns an associative array containing parameters as they are structured in the 'Parameters' tab in the Burp request UI.

This method parses the specified request and returns details of each request parameter.

Parameters:

  • request (Array<btye>, String)

    The request to be parsed.

Returns:

  • (Array<Array<String{ name, value, type }>>)

    details of the parameters contained within the request.


761
762
763
764
# File 'lib/buby.rb', line 761

def getParameters(request)
  request = request.to_java_bytes if request.is_a? String
  _check_and_callback(:getParameters, request)
end

#getProxyHistoryHttpRequestResponseList Also known as: proxy_history, get_proxy_history

TODO:

Bring IHttpRequestResponse helper up to date

Returns a Java array of IHttpRequestResponse objects pulled directly from the Burp proxy history.


689
690
691
# File 'lib/buby.rb', line 689

def getProxyHistory
  HttpRequestResponseList.new(_check_and_callback(:getProxyHistory))
end

#getProxyListenersArray<IProxyListener> Also known as: get_proxy_listeners, proxy_listeners

This method is used to retrieve the Proxy listeners that are registered by the extension.

Returns:

  • (Array<IProxyListener>)

    A list of Proxy listeners that are currently registered by this extension.


1083
1084
1085
# File 'lib/buby.rb', line 1083

def getProxyListeners
  _check_and_callback(:getProxyListeners)
end

#getScanIssues(urlprefix = nil) ⇒ ScanIssuesList Also known as: scan_issues, get_scan_issues

This method returns all of the current scan issues for URLs matching the specified literal prefix. The prefix can be nil to match all issues.

Parameters:

  • urlprefix (String, java.net.URL, URI, nil) (defaults to: nil)

Returns:


714
715
716
# File 'lib/buby.rb', line 714

def getScanIssues(urlprefix=nil)
  ScanIssuesList.new( _check_and_callback(:getScanIssues, urlprefix && urlprefix.to_s) )
end

#getScannerChecksArray<IScannerCheck> Also known as: get_scanner_checks, scanner_checks

This method is used to retrieve the Scanner checks that are registered by the extension.

Returns:

  • (Array<IScannerCheck>)

    A list of Scanner checks that are currently registered by this extension.


1345
1346
1347
# File 'lib/buby.rb', line 1345

def getScannerChecks
  _check_and_callback(:getScannerChecks)
end

#getScannerInsertionPointProvidersArray<IScannerInsertionPointProvider> Also known as: get_scanner_insertion_point_providers, scanner_insertion_point_providers

This method is used to retrieve the Scanner insertion point providers that are registered by the extension.

Returns:

  • (Array<IScannerInsertionPointProvider>)

    A list of Scanner insertion point providers that are currently registered by this extension.


1307
1308
1309
# File 'lib/buby.rb', line 1307

def getScannerInsertionPointProviders
  _check_and_callback(:getScannerInsertionPointProviders)
end

#getScannerListenersArray<IScannerListener> Also known as: get_scanner_listeners

This method is used to retrieve the Scanner listeners that are registered by the extension.

Returns:

  • (Array<IScannerListener>)

    A list of Scanner listeners that are currently registered by this extension.


1126
1127
1128
# File 'lib/buby.rb', line 1126

def getScannerListeners
  _check_and_callback(:getScannerListeners)
end

#getScopeChangeListenersArray<IScopeChangeListener> Also known as: get_scope_change_listeners, scope_change_listeners

This method is used to retrieve the scope change listeners that are registered by the extension.

Returns:

  • (Array<IScopeChangeListener>)

    A list of scope change listeners that are currently registered by this extension.


1166
1167
1168
# File 'lib/buby.rb', line 1166

def getScopeChangeListeners
  _check_and_callback(:getScopeChangeListeners)
end

#getSessionHandlingActionsArray<ISessionHandlingAction> Also known as: get_session_handling_actions, session_handling_actions

This method is used to retrieve the session handling actions that are registered by the extension.

Returns:

  • (Array<ISessionHandlingAction>)

    A list of session handling actions that are currently registered by this extension.


1469
1470
1471
# File 'lib/buby.rb', line 1469

def getSessionHandlingActions
  _check_and_callback(:getSessionHandlingActions)
end

#getSiteMap(urlprefix = nil) ⇒ HttpRequestResponseList Also known as: site_map, get_site_map

TODO:

Bring IHttpRequestResponse helper up to date

Returns a Java array of IHttpRequestResponse objects pulled directly from the Burp site map for all urls matching the specified literal prefix. The prefix can be nil to return all objects.

Parameters:

  • urlprefix (String, java.net.URL, URI, nil) (defaults to: nil)

Returns:


702
703
704
# File 'lib/buby.rb', line 702

def getSiteMap(urlprefix=nil)
  HttpRequestResponseList.new(_check_and_callback(:getSiteMap, urlprefix && urlprefix.to_s))
end

#getStderrOutputStream Also known as: stderr, get_stderr

This method is used to obtain the current extension's standard error stream. Extensions should write all error messages to this stream, allowing the Burp user to configure how that output is handled from within the UI.

Returns:

  • (OutputStream)

    The extension's standard error stream.


938
939
940
# File 'lib/buby.rb', line 938

def getStderr
  @stderr ||= _check_and_callback(:getStderr)
end

#getStdoutOutputStream Also known as: stdout, get_stdout

TODO:

double check

This method is used to obtain the current extension's standard output stream. Extensions should write all output to this stream, allowing the Burp user to configure how that output is handled from within the UI.

Returns:

  • (OutputStream)

    The extension's standard output stream.


925
926
927
# File 'lib/buby.rb', line 925

def getStdout
  @stdout ||= _check_and_callback(:getStdout)
end

#getToolName(toolFlag) ⇒ String Also known as: get_tool_name

This method is used to obtain the descriptive name for the Burp tool identified by the tool flag provided.

Parameters:

  • toolFlag (Fixnum)

    A flag identifying a Burp tool (TOOL_PROXY, TOOL_SCANNER, etc.). Tool flags are defined within this interface.

Returns:

  • (String)

    The descriptive name for the specified tool.


1670
1671
1672
# File 'lib/buby.rb', line 1670

def getToolName(toolFlag)
  @tool_names[toolFlag] ||= _check_and_callback(:getToolName, toolFlag)
end

#harvest_cookies_from_history(cookie = nil, urlrx = nil, statefile = nil) ⇒ Object

Harvest cookies from a session's proxy history.

Params:

cookie    = optional: name of cookie to harvest
urlrx     = optional: regular expression to match urls against
statefile = optional: filename for a burp session file to temporarily load
            and harvest from.

Takes an optional block as additional 'select' criteria for cookies. The block return value of true/false will determine whether a cookie string is selected.


2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
# File 'lib/buby.rb', line 2241

def harvest_cookies_from_history(cookie=nil, urlrx=nil, statefile=nil)
  ret = []
  search_proxy_history(statefile, urlrx) do |hrr|
    if (resp = hrr.response)
      ret += helpers.analyzeResponse(resp).getCookies.select do |c|
        (cookie.nil? or c.match(cookie)) && (not block_given? or yield(c))
      end
    end
  end
  return ret
end

#includeInScope(url) ⇒ void #includeInScope(req) ⇒ void #includeInScope(req_info) ⇒ void #includeInScope(serv, req) ⇒ void Also known as: include_in_scope, include_scope

This method returns an undefined value.

Include the specified URL in the Suite-wide scope.

Overloads:

  • #includeInScope(url) ⇒ void

    Parameters:

    • url (java.net.URL, URI, String)

      The URL to include in the Suite-wide scope.

  • #includeInScope(req) ⇒ void

    Parameters:

    • req (IHttpRequestResponse)

      The request to include in the Suite-wide scope.

  • #includeInScope(req_info) ⇒ void

    Parameters:

    • req_info (IRequestInfo)

      The request information to include in the Suite-wide scope.

  • #includeInScope(serv, req) ⇒ void

    Parameters:

    • serv (IHttpService)

      The HTTP service to include in the Suite-wide scope.

    • req (Array<byte>, String)

      The request to include


375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
# File 'lib/buby.rb', line 375

def includeInScope(*args)
  url, req = args
  case args.size
  when 1
    case url
    when Java::Burp::IHttpRequestResponse,  Java::Burp::IRequestInfo
      url = url.getUrl
    else
      url = Java::JavaNet::URL.new(url.to_s) unless url.is_a? Java::JavaNet::URL
    end
  when 2
    url = getHelpers.__analyzeRequest(url, req).getUrl
  else
    raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1,2)"
  end
  _check_and_callback :includeInScope, url
end

#isExtensionBappboolean Also known as: is_extension_bapp, extension_bapp?, bapp?

This method determines whether the current extension was loaded as a BApp (a Burp App from the BApp Store).

Returns:

  • (boolean)

    Returns true if the current extension was loaded as a BApp.


2135
2136
2137
# File 'lib/buby.rb', line 2135

def isExtensionBapp
  _check_and_callback(:isExtensionBapp)
end

#isInScope(url) ⇒ Boolean #isInScope(req) ⇒ Boolean #isInScope(req_info) ⇒ Boolean #isInScope(serv, req) ⇒ Boolean Also known as: is_in_scope, in_scope?

Query whether a specified URL is within the current Suite-wide scope.

Overloads:

  • #isInScope(url) ⇒ Boolean

    Parameters:

    • url (java.net.URL, URI, String)

      The URL to query

  • #isInScope(req) ⇒ Boolean

    Parameters:

    • req (IHttpRequestResponse)

      The request to query

  • #isInScope(req_info) ⇒ Boolean

    Parameters:

    • req_info (IRequestInfo)

      The request info to query

  • #isInScope(serv, req) ⇒ Boolean

    Parameters:

    • serv (IHttpService)

      The HTTP service to query

    • req (Array<byte>, String)

      The request to query

Returns:

  • (Boolean)

407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
# File 'lib/buby.rb', line 407

def isInScope(*args)
  url, req = args
  case args.size
  when 1
    case url
    when Java::Burp::IHttpRequestResponse,  Java::Burp::IRequestInfo
      url = url.getUrl
    else
      url = Java::JavaNet::URL.new(url.to_s) unless url.is_a? Java::JavaNet::URL
    end
  when 2
    url = getHelpers.__analyzeRequest(url, req).getUrl
  else
    raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1,2)"
  end
  _check_and_callback :isInScope, url
end

#issueAlert(msg) ⇒ void Also known as: issue_alert, alert

This method returns an undefined value.

Display a message in the Burp Suite alerts tab.

Parameters:

  • msg (#to_s)

    The alert message to display.


430
431
432
# File 'lib/buby.rb', line 430

def issueAlert(msg)
  _check_and_callback :issueAlert, msg.to_s
end

#legacy_mode?Boolean

Returns:

  • (Boolean)

2324
2325
2326
# File 'lib/buby.rb', line 2324

def legacy_mode?
  self.class.legacy_mode?
end

#loadConfig(config) ⇒ void Also known as: load_config, config=

TODO:

updateConfig

This method returns an undefined value.

This method causes Burp to load a new configuration from the Map of name/value Strings provided. Any settings not specified in the Map will be restored to their default values. To selectively update only some settings and leave the rest unchanged, you should first call saveConfig to obtain Burp's current configuration, modify the relevant items in the Map, and then call loadConfig with the same Map.

This method is only available with Burp 1.3.09+

Parameters:

  • config (Hash, java.util.Map)

    A map of name/value Strings to use as Burp's new configuration.


861
862
863
# File 'lib/buby.rb', line 861

def loadConfig(config)
  _check_and_callback(:loadConfig, config)
end

#loadExtensionSetting(name) ⇒ String Also known as: load_extension_setting

This method is used to load configuration settings for the extension that were saved using the method saveExtensionSetting().

Parameters:

  • name (String)

    The name of the setting.

Returns:

  • (String)

    The value of the setting, or nil if no value is set.


1556
1557
1558
# File 'lib/buby.rb', line 1556

def loadExtensionSetting(name)
  _check_and_callback(:loadExtensionSetting, name)
end

#makeHttpRequest(host, port, https, request) ⇒ IHttpRequestResponse #makeHttpRequest(request) ⇒ IHttpRequestResponse #makeHttpRequest(url) ⇒ IHttpRequestResponse #makeHttpRequest(service, request) ⇒ IHttpRequestResponse Also known as: make_http_request, make_request

Issue an arbitrary HTTP request and retrieve its response

Overloads:

  • #makeHttpRequest(host, port, https, request) ⇒ IHttpRequestResponse

    Parameters:

    • host (String, java.net.URL, URI)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • useHttps (Boolean)

      Flags whether the protocol is HTTPS or HTTP.

    • request (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request.

  • #makeHttpRequest(request) ⇒ IHttpRequestResponse

    Parameters:

    • request (IHttpRequestResponse)

      The full HTTP request

  • #makeHttpRequest(url) ⇒ IHttpRequestResponse

    Parameters:

    • url (String, URI, java.net.URL)

      The url to make a GET request to. The request is built with ExtensionHelpers#buildHttpRequest

  • #makeHttpRequest(service, request) ⇒ IHttpRequestResponse

    Parameters:

    • service (IHttpService)

      Object with host, port, etc.

    • request (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request.

Returns:

  • (IHttpRequestResponse)

    The full response retrieved from the remote server.

Raises:

  • (ArgumentError)

455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
# File 'lib/buby.rb', line 455

def makeHttpRequest(*args)
  raise ArgumentError, "wrong number of arguments calling '#{__callee__}' (#{args.size} for 1,2,4)" unless [1,2,4].include?(args.size)
  host, port, https, req, serv = args

  case args.size
  when 1
    case host
    when Java::Burp::IHttpRequestResponse
      req = host
      serv = req.getHttpService
    else
      host = Java::JavaNet::URL.new host.to_s unless host.kind_of?(Java::JavaNet::URL)
      port = host.port
      https = host.protocol
      req = getHelpers.__buildHttpRequest host
      https = case https.to_s.downcase
      when 'https'
        true
      when 'http'
        false
      else
        !!https
      end

      port ||= https ? 443 : 80
      port = https ? 443 : 80 if port < 0

      host = host.host if host.respond_to? :host
      serv = getHelpers.buildHttpService(host, port, https)
    end
  when 2
    serv, req = args
  when 4
    # nop
  else
    raise ArgumentError
  end

  req = req.request if req.respond_to? :request
  req = req.to_java_bytes if req.respond_to? :to_java_bytes

  ret = if serv
    _check_and_callback(:makeHttpRequest, serv, req)
  else
    String.from_java_bytes _check_and_callback(:makeHttpRequest, host, port, https, req)
  end
end

#new_scan_issue(issue) ⇒ void

This method is abstract.
Note:

This maps to the newScanIssue callback in IScannerListener implemented by the BurpExtender side.

This method returns an undefined value.

This method is invoked when a new issue is added to Burp Scanner's results.

Parameters:

  • issue (IScanIssue)

    An IScanIssue object that the extension can query to obtain details about the new issue.


2056
2057
2058
2059
# File 'lib/buby.rb', line 2056

def new_scan_issue(issue)
  pp [:got_newScanIssue, issue] if $DEBUG
  ScanIssueHelper.implant issue
end

#printError(error) ⇒ void Also known as: print_error

This method returns an undefined value.

This method prints a line of output to the current extension's standard error stream.

Parameters:

  • error

    The message to print.


962
963
964
# File 'lib/buby.rb', line 962

def printError(error)
  _check_and_callback(:printError, error)
end

#printOutput(output) ⇒ void Also known as: print_output

This method returns an undefined value.

This method prints a line of output to the current extension's standard output stream.

Parameters:

  • output

    The message to print.


951
952
953
# File 'lib/buby.rb', line 951

def printOutput(output)
  _check_and_callback(:printOutput, output)
end

#process_http_message(toolFlag, messageIsRequest, messageInfo) ⇒ void

Note:

This is the 1.5.01+ version of this callback

This method returns an undefined value.

This method is invoked when an HTTP request is about to be issued, and when an HTTP response has been received.

Parameters:

  • toolFlag (Fixnum)

    A flag indicating the Burp tool that issued the request. Burp tool flags are defined in the IBurpExtenderCallbacks interface.

  • messageIsRequest (Boolean)

    Flags whether the method is being invoked for a request or response.

  • messageInfo (IHttpRequestResponse)

    Details of the request / response to be processed. Extensions can call the setter methods on this object to update the current message and so modify Burp's behavior.


2020
2021
2022
2023
# File 'lib/buby.rb', line 2020

def process_http_message(toolFlag, messageIsRequest, messageInfo)
  HttpRequestResponseHelper.implant(messageInfo)
  pp([:got_process_http_message, toolFlag, messageIsRequest, messageInfo]) if $DEBUG
end

#process_proxy_message(messageIsRequest, message) ⇒ void

This method returns an undefined value.

This method is invoked when an HTTP message is being processed by the Proxy.

Parameters:

  • messageIsRequest (Boolean)

    Indicates whether the HTTP message is a request or a response.

  • message (IInterceptedProxyMessage)

    An IInterceptedProxyMessage object that extensions can use to query and update details of the message, and control whether the message should be intercepted and displayed to the user for manual review or modification.

See Also:


1965
1966
1967
1968
# File 'lib/buby.rb', line 1965

def process_proxy_message(messageIsRequest, message)
  pp [:got_processProxyMessage] if $debug
  Buby::Implants::InterceptedProxyMessage.implant message
end

#register_callbacks(callbacks, alert = true) ⇒ IBurpExtenderCallbacks

This method is called by BurpExtender on startup to register Burp's IBurpExtenderCallbacks interface object.

This maps to the 'registerExtenderCallbacks' method in the Java implementation of BurpExtender.

Parameters:

  • callbacks (IBurpExtenderCallbacks)

    callbacks presented by burp

  • alert (Boolean) (defaults to: true)

Returns:

  • (IBurpExtenderCallbacks)

    cb


1756
1757
1758
1759
1760
1761
# File 'lib/buby.rb', line 1756

def register_callbacks callbacks, alert = true
  callbacks.issueAlert("[JRuby::#{self.class}] registered callback") if alert
  pp([:got_register_callbacks, callbacks]) if $DEBUG
  evt_register_callbacks(callbacks, false) if respond_to? :evt_register_callbacks
  @burp_callbacks = callbacks
end

#registerContextMenuFactory(factory) ⇒ Object #registerContextMenuFactory(&block) ⇒ Object Also known as: register_context_menu_factory

This method is used to register a factory for custom context menu items. When the user invokes a context menu anywhere within Burp, the factory will be passed details of the invocation event, and asked to provide any custom context menu items that should be shown.

Overloads:

  • #registerContextMenuFactory(factory) ⇒ Object

    Parameters:

    • factory (IContextMenuFactory)

      A listener for context menu invocation events

  • #registerContextMenuFactory(&block) ⇒ Object
    Note:

    It is probably better to use the more explicit factory argument version to ensure the IContextMenuInvocation Java classes have been wrapped properly.

    Parameters:

    • &block (Proc)

      A listener for context menu invocation events (Isn't JRuby fun?)


1199
1200
1201
1202
1203
1204
1205
# File 'lib/buby.rb', line 1199

def registerContextMenuFactory(factory = nil, &block)
  if block_given?
    _check_and_callback(:registerContextMenuFactory, &block)
  else
    _check_and_callback(:registerContextMenuFactory, factory)
  end
end

#registerExtensionStateListener(listener) ⇒ Object #registerExtensionStateListener(&block) ⇒ Object Also known as: register_extension_state_listener

This method is used to register a listener which will be notified of changes to the extension's state. Note: Any extensions that start background threads or open system resources (such as files or database connections) should register a listener and terminate threads / close resources when the extension is unloaded.

Overloads:

  • #registerExtensionStateListener(listener) ⇒ Object

    Parameters:

    • listener (IExtensionStateListener)

      A listener for extension state events

  • #registerExtensionStateListener(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A listener for extension state events (Isn't JRuby fun?)


980
981
982
983
984
985
986
# File 'lib/buby.rb', line 980

def registerExtensionStateListener(listener = nil, &block)
  if block_given?
    _check_and_callback(:registerExtensionStateListener, &block)
  else
    _check_and_callback(:registerExtensionStateListener, listener)
  end
end

#registerHttpListener(listener) ⇒ Object #registerHttpListener(&block) ⇒ Object Also known as: register_http_listener

This method is used to register a listener which will be notified of requests and responses made by any Burp tool. Extensions can perform custom analysis or modification of these messages by registering an HTTP listener.

Overloads:

  • #registerHttpListener(listener) ⇒ Object

    Parameters:

    • listener (IHttpListener)

      A listener for http events

  • #registerHttpListener(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A listener for http events (Isn't JRuby fun?)


1025
1026
1027
1028
1029
1030
1031
# File 'lib/buby.rb', line 1025

def registerHttpListener(listener = nil, &block)
  if block_given?
    _check_and_callback(:registerHttpListener, &block)
  else
    _check_and_callback(:registerHttpListener, listener)
  end
end

#registerIntruderPayloadGeneratorFactory(factory = nil, &block) ⇒ Object Also known as: register_intruder_payload_generator_factory

TODO:

Test - block version may work here

This method is used to register a factory for Intruder payloads. Each registered factory will be available within the Intruder UI for the user to select as the payload source for an attack. When this is selected, the factory will be asked to provide a new instance of an IIntruderPayloadGenerator object, which will be used to generate payloads for the attack.

Parameters:

  • factory (IIntruderPayloadGeneratorFactory) (defaults to: nil)

    An object to be used for generating intruder payloads.


1373
1374
1375
1376
1377
1378
1379
# File 'lib/buby.rb', line 1373

def registerIntruderPayloadGeneratorFactory(factory = nil, &block)
  if block_given?
    _check_and_callback(:registerIntruderPayloadGeneratorFactory, &block)
  else
    _check_and_callback(:registerIntruderPayloadGeneratorFactory, factory)
  end
end

#registerIntruderPayloadProcessor(processor) ⇒ Object Also known as: register_intruder_payload_processor

TODO:

Test - block version may work here

This method is used to register a custom Intruder payload processor. Each registered processor will be available within the Intruder UI for the user to select as the action for a payload processing rule.

Parameters:

  • processor (IIntruderPayloadProcessor)

    An object used for processing Intruder payloads


1413
1414
1415
1416
1417
1418
1419
# File 'lib/buby.rb', line 1413

def registerIntruderPayloadProcessor(processor)
  if block_given?
    _check_and_callback(:registerIntruderPayloadProcessor, &block)
  else
    _check_and_callback(:registerIntruderPayloadProcessor, processor)
  end
end

#registerMenuItem(menuItemCaption, menuItemHandler = nil, &block) ⇒ Object Also known as: register_menu_item

Deprecated.
Note:

This method is only available with Burp 1.3.07+ and is deprecated in 1.5.01.

This method can be used to register a new menu item which will appear on the various context menus that are used throughout Burp Suite to handle user-driven actions.

the menu item.

Parameters:

  • menuItemCaption

    The caption to be displayed on the menu item.

  • menuItemHandler (defaults to: nil)

    The handler to be invoked when the user clicks on


809
810
811
812
813
814
815
816
817
# File 'lib/buby.rb', line 809

def registerMenuItem(menuItemCaption, menuItemHandler = nil, &block)
  ret = if block_given?
    _check_and_callback(:registerMenuItem, menuItemCaption, &block)
  else
    _check_and_callback(:registerMenuItem, menuItemCaption, menuItemHandler)
  end
  issueAlert("Handler #{menuItemHandler} registered for \"#{menuItemCaption}\"")
  ret
end

#registerMessageEditorTabFactory(factory) ⇒ Object #registerMessageEditorTabFactory(&block) ⇒ Object Also known as: register_message_editor_tab_factory

This method is used to register a factory for custom message editor tabs. For each message editor that already exists, or is subsequently created, within Burp, the factory will be asked to provide a new instance of an IMessageEditorTab object, which can provide custom rendering or editing of HTTP messages.

Overloads:

  • #registerMessageEditorTabFactory(factory) ⇒ Object

    Parameters:

    • factory (IMessageEditorTabFactory)

      A listener for message editor tab events

  • #registerMessageEditorTabFactory(&block) ⇒ Object
    Note:

    It is probably better to use the more explicit factory argument version to ensure the IMessageEditorController Java classes have been wrapped properly.

    Parameters:

    • &block (Proc)

      A listener for message editor tab events (Isn't JRuby fun?)


1247
1248
1249
1250
1251
1252
1253
# File 'lib/buby.rb', line 1247

def registerMessageEditorTabFactory(factory = nil, &block)
  if block_given?
    _check_and_callback(:registerMessageEditorTabFactory, &block)
  else
    _check_and_callback(:registerMessageEditorTabFactory, factory)
  end
end

#registerProxyListener(listener) ⇒ Object #registerHttpListener(&block) ⇒ Object Also known as: register_proxy_listener

This method is used to register a listener which will be notified of requests and responses being processed by the Proxy tool. Extensions can perform custom analysis or modification of these messages, and control in-UI message interception, by registering a proxy listener.

Overloads:

  • #registerProxyListener(listener) ⇒ Object

    Parameters:

    • listener (IProxyListener)

      A listener for proxy events

  • #registerHttpListener(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A listener for proxy events (Isn't JRuby fun?)


1068
1069
1070
1071
1072
1073
1074
# File 'lib/buby.rb', line 1068

def registerProxyListener(listener = nil, &block)
  if block_given?
    _check_and_callback(:registerProxyListener, &block)
  else
    _check_and_callback(:registerProxyListener, listener)
  end
end

#registerScannerCheck(check = nil, &block) ⇒ Object Also known as: register_scanner_check

This method is used to register a custom Scanner check. When performing scanning, Burp will ask the check to perform active or passive scanning on the base request, and report any Scanner issues that are identified.

Parameters:

  • check (IScannerCheck) (defaults to: nil)

    An object that performs a given check.


1330
1331
1332
1333
1334
1335
1336
# File 'lib/buby.rb', line 1330

def registerScannerCheck(check = nil, &block)
  if block_given?
    _check_and_callback(:registerScannerCheck, &block)
  else
    _check_and_callback(:registerScannerCheck, check)
  end
end

#registerScannerInsertionPointProvider(provider) ⇒ Object #registerScannerInsertionPointProvider(&block) ⇒ Object Also known as: register_scanner_insertion_point_provider

This method is used to register a provider of Scanner insertion points. For each base request that is actively scanned, Burp will ask the provider to provide any custom scanner insertion points that are appropriate for the request.

Overloads:

  • #registerScannerInsertionPointProvider(provider) ⇒ Object

    Parameters:

    • provider (IScannerInsertionPointProvider)

      A provider of scanner insertion points

  • #registerScannerInsertionPointProvider(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A provider of scanner insertion points (Isn't JRuby fun?)


1292
1293
1294
1295
1296
1297
1298
# File 'lib/buby.rb', line 1292

def registerScannerInsertionPointProvider(provider = nil, &block)
  if block_given?
    _check_and_callback(:registerScannerInsertionPointProvider, &block)
  else
    _check_and_callback(:registerScannerInsertionPointProvider, provider)
  end
end

#registerScannerListener(listener) ⇒ Object #registerScannerListener(&block) ⇒ Object Also known as: register_scanner_listener

This method is used to register a listener which will be notified of new issues that are reported by the Scanner tool. Extensions can perform custom analysis or logging of Scanner issues by registering a Scanner listener.

Overloads:

  • #registerScannerListener(listener) ⇒ Object

    Parameters:

    • listener (IScannerListener)

      A listener for scanner events

  • #registerScannerListener(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A listener for scanner events (Isn't JRuby fun?)


1111
1112
1113
1114
1115
1116
1117
# File 'lib/buby.rb', line 1111

def registerScannerListener(listener = nil, &block)
  if block_given?
    _check_and_callback(:registerScannerListener, &block)
  else
    _check_and_callback(:registerScannerListener, listener)
  end
end

#registerScopeChangeListener(listener) ⇒ Object #registerScopeChangeListener(&block) ⇒ Object

This method is used to register a listener which will be notified of changes to Burp's suite-wide target scope.

Overloads:

  • #registerScopeChangeListener(listener) ⇒ Object

    Parameters:

    • listener (IScopeChangeListener)

      A listener for scope change events

  • #registerScopeChangeListener(&block) ⇒ Object

    Parameters:

    • &block (Proc)

      A listener for scope change events (Isn't JRuby fun?)


1152
1153
1154
1155
1156
1157
1158
# File 'lib/buby.rb', line 1152

def registerScopeChangeListener(listener = nil, &block)
  if block_given?
    _check_and_callback(:registerScopeChangeListener, &block)
  else
    _check_and_callback(:registerScopeChangeListener, listener)
  end
end

#registerSessionHandlingAction(action) ⇒ Object Also known as: register_session_handling_action

TODO:

Test - block version may work here

This method is used to register a custom session handling action. Each registered action will be available within the session handling rule UI for the user to select as a rule action. Users can choose to invoke an action directly in its own right, or following execution of a macro.

Parameters:

  • action (ISessionHandlingAction)

    An object used to perform a given session action.


1454
1455
1456
1457
1458
1459
1460
# File 'lib/buby.rb', line 1454

def registerSessionHandlingAction(action)
  if block_given?
    _check_and_callback(:registerSessionHandlingAction, &block)
  else
    _check_and_callback(:registerSessionHandlingAction, action)
  end
end

#removeContextMenuFactory(factory) ⇒ void Also known as: remove_context_menu_factory

This method returns an undefined value.

This method is used to remove a context menu factory that has been registered by the extension.

Parameters:

  • factory (IContextMenuFactory)

    The context menu factory to be removed.


1226
1227
1228
# File 'lib/buby.rb', line 1226

def removeContextMenuFactory(factory)
  _check_and_callback(:removeContextMenuFactory, factory)
end

#removeExtensionStateListener(listener) ⇒ void Also known as: remove_extension_state_listener

This method returns an undefined value.

This method is used to remove an extension state listener that has been registered by the extension.

Parameters:

  • listener

    The extension state listener to be removed.


1009
1010
1011
# File 'lib/buby.rb', line 1009

def removeExtensionStateListener(listener)
  _check_and_callback(:removeExtensionStateListener, listener)
end

#removeHttpListener(listener) ⇒ void Also known as: remove_http_listener

This method returns an undefined value.

This method is used to remove an HTTP listener that has been registered by the extension.

Parameters:

  • listener

    The HTTP listener to be removed.


1052
1053
1054
# File 'lib/buby.rb', line 1052

def removeHttpListener(listener)
  _check_and_callback(:removeHttpListener, listener)
end

#removeIntruderPayloadGeneratorFactory(factory) ⇒ Object Also known as: remove_intruder_payload_generator_factory

This method is used to remove an Intruder payload generator factory that has been registered by the extension.

Parameters:

  • factory (IIntruderPayloadGeneratorFactory)

    The Intruder payload generator factory to be removed.


1400
1401
1402
# File 'lib/buby.rb', line 1400

def removeIntruderPayloadGeneratorFactory(factory)
  _check_and_callback(:removeIntruderPayloadGeneratorFactory, factory)
end

#removeIntruderPayloadProcessor(processor) ⇒ void Also known as: remove_intruder_payload_processor

This method returns an undefined value.

This method is used to remove an Intruder payload processor that has been registered by the extension.

Parameters:

  • processor (IIntruderPayloadProcessor)

    The Intruder payload processor to be removed.


1441
1442
1443
# File 'lib/buby.rb', line 1441

def removeIntruderPayloadProcessor(processor)
  _check_and_callback(:removeIntruderPayloadProcessor, processor)
end

#removeMessageEditorTabFactory(factory) ⇒ void Also known as: remove_message_editor_tab_factory

This method returns an undefined value.

This method is used to remove a message editor tab factory that has been registered by the extension.

Parameters:

  • factory (IMessageEditorTabFactory)

    The message editor tab factory to be removed.


1275
1276
1277
# File 'lib/buby.rb', line 1275

def removeMessageEditorTabFactory(factory)
  _check_and_callback(:removeMessageEditorTabFactory, factory)
end

#removeProxyListener(listener) ⇒ void Also known as: remove_proxy_listener

This method returns an undefined value.

This method is used to remove a Proxy listener that has been registered by the extension.

Parameters:

  • listener (IProxyListener)

    The Proxy listener to be removed.


1095
1096
1097
# File 'lib/buby.rb', line 1095

def removeProxyListener(listener)
  _check_and_callback(:removeProxyListener, listener)
end

#removeScannerCheck(check) ⇒ void Also known as: remove_scanner_check

This method returns an undefined value.

This method is used to remove a Scanner check that has been registered by the extension.

Parameters:

  • check (IScannerCheck)

    The Scanner check to be removed.


1357
1358
1359
# File 'lib/buby.rb', line 1357

def removeScannerCheck(check)
  _check_and_callback(:removeScannerCheck, check)
end

#removeScannerInsertionPointProvider(provider) ⇒ void Also known as: remove_scanner_insertion_point_provider

This method returns an undefined value.

This method is used to remove a Scanner insertion point provider that has been registered by the extension.

Parameters:

  • provider (IScannerInsertionPointProvider)

    The Scanner insertion point provider to be removed.


1319
1320
1321
# File 'lib/buby.rb', line 1319

def removeScannerInsertionPointProvider(provider)
  _check_and_callback(:removeScannerInsertionPointProvider, provider)
end

#removeScannerListener(listener) ⇒ Object Also known as: remove_scanner_listener

This method is used to remove a Scanner listener that has been registered by the extension.

Parameters:

  • listener

    The Scanner listener to be removed.

Returns:

  • void


1138
1139
1140
# File 'lib/buby.rb', line 1138

def removeScannerListener(listener)
  _check_and_callback(:removeScannerListener, listener)
end

#removeScopeChangeListener(listener) ⇒ void Also known as: remove_scope_change_listener

This method returns an undefined value.

This method is used to remove a scope change listener that has been registered by the extension.

Parameters:

  • listener (IScopeChangeListener)

    The scope change listener to be removed.


1179
1180
1181
# File 'lib/buby.rb', line 1179

def removeScopeChangeListener(listener)
  _check_and_callback(:removeScopeChangeListener, listener)
end

#removeSessionHandlingAction(action) ⇒ void Also known as: remove_session_handling_action

This method returns an undefined value.

This method is used to remove a session handling action that has been registered by the extension.

Parameters:

  • action

    The extension session handling action to be removed.


1481
1482
1483
# File 'lib/buby.rb', line 1481

def removeSessionHandlingAction(action)
  _check_and_callback(:removeSessionHandlingAction, action)
end

#removeSuiteTab(tab) ⇒ Object Also known as: remove_suite_tab

This method is used to remove a previously-added tab from the main Burp Suite window.

Parameters:

  • tab (ITab)

    The tab to be removed from the suite's user interface.


1500
1501
1502
# File 'lib/buby.rb', line 1500

def removeSuiteTab(tab)
  _check_and_callback(:removeSuiteTab, tab)
end

#restoreState(filename) ⇒ void Also known as: restore_state

This method returns an undefined value.

Restores Burp session state from a previously saved state file. See also: saveState

IMPORTANT: This method is only available with Burp 1.2.09 and higher.

Parameters:

  • filename (String, java.io.File)

    path and filename of the file to restore from


729
730
731
# File 'lib/buby.rb', line 729

def restoreState(filename)
  _check_and_callback(:restoreState, Java::JavaIo::File.new(filename))
end

#saveBuffersToTempFiles(httpRequestResponse) ⇒ IHttpRequestResponsePersisted Also known as: save_buffers_to_temp_files

TODO:

move HttpRequestResponse to new Implants method…

This method is used to save the request and response of an IHttpRequestResponse object to temporary files, so that they are no longer held in memory. Extensions can used this method to convert IHttpRequestResponse objects into a form suitable for long-term storage.

Parameters:

  • httpRequestResponse (IHttpRequestResponse)

    The request and response messages to be saved to temporary files.

Returns:

  • (IHttpRequestResponsePersisted)

    A reference to the saved temp file.


1630
1631
1632
# File 'lib/buby.rb', line 1630

def saveBuffersToTempFiles(httpRequestResponse)
  _check_and_callback(:saveBuffersToTempFiles, httpRequestResponse).tap{|obj| Buby::HttpRequestResponseHelper.implant(obj)}
end

#saveConfigjava.util.Map Also known as: save_config, config

This method causes Burp to save all of its current configuration as a Map of name/value Strings.

This method is only available with Burp 1.3.09+

Returns:

  • (java.util.Map)

    A Map of name/value Strings reflecting Burp's current configuration.


842
843
844
# File 'lib/buby.rb', line 842

def saveConfig
  _check_and_callback(:saveConfig).to_hash
end

#saveExtensionSetting(name, value) ⇒ Object Also known as: save_extension_setting

This method is used to save configuration settings for the extension in a persistent way that survives reloads of the extension and of Burp Suite. Saved settings can be retrieved using the method #loadExtensionSetting.

Parameters:

  • name (String)

    The name of the setting.

  • value (String)

    The value of the setting. If this value is nil then any existing setting with the specified name will be removed.


1544
1545
1546
# File 'lib/buby.rb', line 1544

def saveExtensionSetting(name, value)
  _check_and_callback(:saveExtensionSetting, name, value)
end

#saveState(filename) ⇒ void Also known as: save_state

This method returns an undefined value.

Saves the current Burp session to a state file. See also restoreState.

IMPORTANT: This method is only available with Burp 1.2.09 and higher.

Parameters:

  • filename (String, java.io.File)

    path and filename of the file to save to


742
743
744
# File 'lib/buby.rb', line 742

def saveState(filename)
  _check_and_callback(:saveState, Java::JavaIo::File.new(filename))
end

#saveToTempFile(buffer) ⇒ ITempFile Also known as: save_to_temp_file

This method is used to create a temporary file on disk containing the provided data. Extensions can use temporary files for long-term storage of runtime data, avoiding the need to retain that data in memory. Not strictly needed in JRuby (use Tempfile class in stdlib instead) but might see use.

Parameters:

  • buffer (String, Array<byte>)

    The data to be saved to a temporary file.

Returns:

  • (ITempFile)

    A reference to the temp file.


1614
1615
1616
1617
# File 'lib/buby.rb', line 1614

def saveToTempFile(buffer)
  buffer = buffer.to_java_bytes if buffer.respond_to? :to_java_bytes
  Buby::Implants::TempFile.implant(_check_and_callback(:saveToTempFile, buffer))
end

#search_proxy_history(statefile = nil, urlrx = nil) ⇒ Object

Searches the proxy history for the url's matched by the specified regular expression (returns them all if urlrx is nil).

A statefile to search in can optionally be specified or the existing state will be used if statefile is nil.

This method also accepts an optional block which is passed each of the matched history members.


2220
2221
2222
2223
2224
2225
2226
2227
2228
# File 'lib/buby.rb', line 2220

def search_proxy_history(statefile=nil, urlrx=nil)
  ret = []
  with_proxy_history(statefile) do |r|
    if (not urlrx) or r.url.to_s =~ urlrx
      ret << r if (not block_given?) or yield(r)
    end
  end
  return ret
end

#sendToComparer(data) ⇒ Object #sendToComparer(data, use_req = nil) ⇒ Object Also known as: send_to_comparer, comparer

This method can be used to send data to the Comparer tool.

Overloads:

  • #sendToComparer(data) ⇒ Object

    Parameters:

    • data (Array<Byte>, String)

      The data to be sent to Comparer.

  • #sendToComparer(data, use_req = nil) ⇒ Object

    Parameters:

    • data (IHttpRequestResponse)

      Request/Response to be sent to Comparer.

    • use_req (Boolean) (defaults to: nil)

      Use request instead of response


586
587
588
589
590
591
592
# File 'lib/buby.rb', line 586

def sendToComparer(data, use_req=nil)
  if data.kind_of? Java::Burp::IHttpRequestResponse
    data = use_req ? data.request : data.response
  end
  data = data.to_java_bytes if data.respond_to? :to_java_bytes
  _check_and_callback(:sendToComparer, data)
end

#sendToIntruder(host, port, https, req, ip_off = nil) ⇒ void #sendToIntruder(request, ip_off = nil) ⇒ void #sendToIntruder(service, request, ip_off = nil) ⇒ void Also known as: send_to_intruder, intruder

This method returns an undefined value.

Send an HTTP request to the Burp Intruder tool

Overloads:

  • #sendToIntruder(host, port, https, req, ip_off = nil) ⇒ void

    Parameters:

    • host (String)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • https (Boolean, #to_s)

      Flags whether the protocol is HTTPS or HTTP.

    • req (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request.

    • ip_off (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

  • #sendToIntruder(request, ip_off = nil) ⇒ void

    Parameters:

    • request (IHttpRequestResponse)

      The complete request to send to Intruder.

    • ip_off (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.

  • #sendToIntruder(service, request, ip_off = nil) ⇒ void

    Parameters:

    • service (IHttpService)

      The HTTP service description for the request

    • request (IHttpRequestResponse, String, Array<byte>)

      The complete request to send to Intruder. If String or Array<byte> the request will first be analyzed with #analyzeRequest to obtain the required information

    • ip_off (Array<Array<Fixnum>>) (defaults to: nil)

      A list of index pairs representing the positions of the insertion points that should be scanned. Each item in the list must be an int array containing the start and end offsets for the insertion point.


536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
# File 'lib/buby.rb', line 536

def sendToIntruder(*args)
  host, port, https, req, ip_off = nil
  case args.first
  when String
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [4,5].include?(args.size)
    host, port, https, req, ip_off = *args
  when Java::Burp::IHttpRequestResponse
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [1,2].include?(args.size)
    req, ip_off = *args
    port  = req.port
    https = req.protocol
    host  = req.host
  when Java::Burp::IHttpService
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [2,3].include?(args.size)
    serv, req, ip_off = *args
    port  = serv.port
    https = serv.protocol
    host  = serv.host
  else
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)"
  end

  https = case https.to_s.downcase
  when 'https'
    true
  when 'http'
    false
  else
    !!https
  end

  req = req.request if req.respond_to?(:request)
  req = req.to_java_bytes if req.respond_to?(:to_java_bytes)
  if self.getBurpVersion.to_a[1..-1].join(".") < "1.4.04"
    _check_and_callback :sendToIntruder, host, port, https, req
  else
    _check_and_callback :sendToIntruder, host, port, https, req, ip_off
  end
end

#sendToRepeater(host, port, https, req, tab = nil) ⇒ void #sendToRepeater(service, request, tab = nil) ⇒ void #sendToRepeater(request, tab = nil) ⇒ void Also known as: send_to_repeater, repeater

This method returns an undefined value.

Send an HTTP request to the Burp Repeater tool.

Overloads:

  • #sendToRepeater(host, port, https, req, tab = nil) ⇒ void

    Parameters:

    • host (String)

      The hostname of the remote HTTP server.

    • port (Fixnum)

      The port of the remote HTTP server.

    • https (Boolean, #to_s)

      Flags whether the protocol is HTTPS or HTTP.

    • req (String, Array<byte>, IHttpRequestResponse)

      The full HTTP request. (String or Java byte[])

    • tab (String) (defaults to: nil)

      The tab caption displayed in Repeater. (default: auto-generated)

  • #sendToRepeater(service, request, tab = nil) ⇒ void

    Parameters:

    • service (IHttpService)

      The HTTP service description for the request

    • request (IHttpRequestResponse, String, Array<byte>)

      The complete request to send to Intruder. If String or Array<byte> the request will first be analyzed with #analyzeRequest to obtain the required information

    • tab (String) (defaults to: nil)

      The tab caption displayed in Repeater. (default: auto-generated)

  • #sendToRepeater(request, tab = nil) ⇒ void

    Parameters:

    • request (IHttpRequestResponse)

      The request to be sent to Repeater containing all the required information.

    • tab (String) (defaults to: nil)

      The tab caption displayed in Repeater. (default: auto-generated)


620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
# File 'lib/buby.rb', line 620

def sendToRepeater(*args)
  host, port, https, req, tab = nil
  case args.first
  when String
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [4,5].include?(args.size)
    host, port, https, req, tab = *args
  when Java::Burp::IHttpRequestResponse
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [1,2].include?(args.size)
    req, tab = *args
    port  = req.port
    https = req.protocol
    host  = req.host
  when Java::Burp::IHttpService
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)" unless [2,3].include?(args.size)
    serv, req, tab = *args
    port  = serv.port
    https = serv.protocol
    host  = serv.host
  else
    raise ArgumentError, "wrong number/type of arguments calling '#{__callee__}' (#{args.size} for 1..5)"
  end

  https = case https.to_s.downcase
  when 'https'
    true
  when 'http'
    false
  else
    !!https
  end

  req = req.request if req.kind_of?(Java::Burp::IHttpRequestResponse)
  req = req.to_java_bytes if req.respond_to?(:to_java_bytes)
  _check_and_callback :sendToRepeater, host, port, https, req, tab
end

#sendToSpider(url) ⇒ Object Also known as: send_to_spider, spider

Send a seed URL to the Burp Spider tool.

@param [String, URI, java.net.URL, IHttpRequestResponse] url The new seed URL to begin
  spidering from.
@return [void]

662
663
664
665
666
# File 'lib/buby.rb', line 662

def sendToSpider(url)
  url = url.url if url.respond_to? :url
  url = Java::JavaNet::URL.new(url.to_s) unless url.kind_of?(Java::JavaNet::URL)
  _check_and_callback :sendToSpider, url
end

#setExtensionName(name) ⇒ void Also known as: extension_name=, set_extension_name

This method returns an undefined value.

This method is used to set the display name for the current extension, which will be displayed within the user interface for the Extender tool.

Parameters:

  • name (String)

    The extension name.


899
900
901
# File 'lib/buby.rb', line 899

def setExtensionName(name)
  _check_and_callback(:setExtensionName, name)
end

#setProxyInterceptionEnabled(enabled) ⇒ void Also known as: proxy_interception_enabled, proxy_interception=

This method returns an undefined value.

This method sets the interception mode for Burp Proxy.

Parameters:

  • enabled (Boolean)

    Indicates whether interception of proxy messages should be enabled.


875
876
877
# File 'lib/buby.rb', line 875

def setProxyInterceptionEnabled(enabled)
  _check_and_callback(:setProxyInterceptionEnabled, enabled)
end

#start(extender = nil, args = []) ⇒ Object

Prepares the java BurpExtender implementation with a reference to self as the module handler and launches burp suite.

Parameters:

  • extender (defaults to: nil)

    Buby exender interface


2258
2259
2260
2261
2262
2263
2264
# File 'lib/buby.rb', line 2258

def start(extender = nil, args = [])
  # so we don't get error when this file is loaded
  extender ||= legacy_mode? ? Java.burp.BurpExtender : Object.const_get(:BurpExtender)
  activate!(extender)
  Java.burp.StartBurp.main(args.to_java(:string)) if legacy_mode?
  return self
end

#start_burpObject

Deprecated.

Use Buby#start instead

Prepares the java BurpExtender implementation with a reference to self as the module handler and launches burp suite.

Parameters:

  • extender

    Buby exender interface


2267
2268
2269
2270
2271
2272
2273
# File 'lib/buby.rb', line 2267

def start(extender = nil, args = [])
  # so we don't get error when this file is loaded
  extender ||= legacy_mode? ? Java.burp.BurpExtender : Object.const_get(:BurpExtender)
  activate!(extender)
  Java.burp.StartBurp.main(args.to_java(:string)) if legacy_mode?
  return self
end

#unloadExtensionObject Also known as: unload_extension

This method is used to unload the extension from Burp Suite.


2085
2086
2087
# File 'lib/buby.rb', line 2085

def unloadExtension
  _check_and_callback(:unloadExtension)
end

#updateCookieJar(cookie) ⇒ Object Also known as: update_cookie_jar

This method is used to update the contents of Burp's session handling cookie jar. Extensions that provide an ISessionHandlingAction can query and update the cookie jar in order to handle unusual session handling mechanisms.

Parameters:

  • cookie (ICookie)

    An object containing details of the cookie to be updated. If the cookie jar already contains a cookie that matches the specified domain and name, then that cookie will be updated with the new value and expiration, unless the new value is nil, in which case the cookie will be removed. If the cookie jar does not already contain a cookie that matches the specified domain and name, then the cookie will be added.

See Also:


1599
1600
1601
# File 'lib/buby.rb', line 1599

def updateCookieJar(cookie)
  _check_and_callback(:updateCookieJar, cookie)
end

#with_proxy_history(statefile = nil) ⇒ Object

This is a convenience wrapper which can load a given burp state file and lets its caller to perform actions inside of a block on the proxy history contained in the loaded session.

If a statefile argument isn't specified current burp session state is used.

Yields each entry in the proxy history to a block.


2179
2180
2181
2182
2183
# File 'lib/buby.rb', line 2179

def with_proxy_history(statefile=nil)
  with_statefile(statefile) do |this|
    this.proxy_history.each {|h| yield h }
  end
end

#with_site_map(urlprefix = nil, statefile = nil) ⇒ Object

This is a convenience wrapper which can load a given burp state file and lets its caller to perform actions inside of a block on the site map contained in the loaded session.

If a statefile argument isn't specified current burp session state is used.

Yields each entry in the site map to a block.


2166
2167
2168
2169
2170
# File 'lib/buby.rb', line 2166

def with_site_map(urlprefix=nil, statefile=nil)
  with_statefile(statefile) do |this|
    this.site_map(urlprefix).each {|h| yield h }
  end
end

#with_statefile(statefile = nil) {|_self| ... } ⇒ Object

This is a convenience wrapper which loads a given burp statefile and lets its caller perform actions via burp while its loaded on it inside of a block. The old state is restored after the block completes.

It can safely be run with a nil statefile argument in which the current burp session state is used.

Yields:

  • (_self)

Yield Parameters:

  • _self (Buby)

    the object that the method was called on


2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
# File 'lib/buby.rb', line 2191

def with_statefile(statefile=nil)
  if statefile
    # save current state:
    old_state=".#{$$}.#{Time.now.to_i}.state.bak"
    self.alert "Saving current state to temp statefile: #{old_state}"
    self.save_state(old_state)
    self.alert "Restoring state: #{statefile}"
    self.restore_state(statefile)
  end

  yield self

  if statefile
    # restore original state
    self.alert "Restoring temp statefile: #{old_state}"
    self.restore_state old_state
    self.alert "Deleting temp state file: #{old_state}"
    File.unlink old_state
  end
end