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 Java 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 trade-marks of PortSwigger Ltd.

    Copyright 2011 PortSwigger Ltd. All rights reserved.
    See http://portswigger.net for license terms.
    
  • This ruby library and the accompanying BurpExtender.java implementation were written by Eric Monti @ Matasano Security.

    Matasano claims no professional or legal affiliation with PortSwigger LTD. nor do we sell or officially endorse any of their products.

    However, this author would like to express his personal and professional respect and appreciation for their making available the BurpExtender extension API. The availability of this interface in an already great tool goes a long way to make Burp Suite a truly first-class application.

  • Forgive the name. It won out over “Burb” and “BurpRub”. It’s just easier to type and say out-loud. Mike Tracy gets full credit as official Buby-namer.

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.05'
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:



125
126
127
128
129
130
131
# File 'lib/buby.rb', line 125

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

Class Method Details

.burp_loaded?Boolean

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

Returns:

  • (Boolean)


1610
1611
1612
1613
1614
1615
1616
1617
# File 'lib/buby.rb', line 1610

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)


1621
1622
1623
1624
1625
1626
1627
1628
# File 'lib/buby.rb', line 1621

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.



1642
1643
1644
# File 'lib/buby.rb', line 1642

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.



1604
1605
1606
1607
# File 'lib/buby.rb', line 1604

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.



1652
1653
1654
# File 'lib/buby.rb', line 1652

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.



1663
1664
1665
1666
1667
1668
1669
# File 'lib/buby.rb', line 1663

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



1584
1585
1586
1587
1588
1589
# File 'lib/buby.rb', line 1584

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:



1593
1594
1595
# File 'lib/buby.rb', line 1593

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



356
357
358
359
360
361
362
# File 'lib/buby.rb', line 356

def _check_and_callback(meth, *args, &block)
  cb = _check_cb
  unless cb.respond_to?(meth)
    raise "#{meth} is not available in your version of Burp"
  end
  cb.__send__ meth, *args, &block
end

#_check_cbObject

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



152
153
154
# File 'lib/buby.rb', line 152

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



136
137
138
# File 'lib/buby.rb', line 136

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.



1049
1050
1051
# File 'lib/buby.rb', line 1049

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.



859
860
861
# File 'lib/buby.rb', line 859

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

    Details of the item to be added to the site map



504
505
506
# File 'lib/buby.rb', line 504

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.



1434
1435
1436
# File 'lib/buby.rb', line 1434

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[2] array containing the start and end offsets for the marker. This parameter is optional and may be nil if no request 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[2] array containing the start and end offsets for the marker. This parameter is optional and may be nil if no response markers are required.

Returns:

  • (IHttpRequestResponseWithMarkers)

    A marked request/response pair.



1023
1024
1025
# File 'lib/buby.rb', line 1023

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.



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

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.



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

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.



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

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.



935
936
937
# File 'lib/buby.rb', line 935

def createTextEditor()
  _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.



879
880
881
# File 'lib/buby.rb', line 879

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

#doActiveScan(host, port, useHttps, request, insertionPointOffsets = nil) ⇒ IScanQueueItem #doActiveScan(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)

      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>)

      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(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.



185
186
187
188
189
190
191
192
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
# File 'lib/buby.rb', line 185

def doActiveScan(*args)
  host, port, https, req, ip_off = args
  case args.size
  when 1,2
    req = args.first
    ip_off = args[1]
    if req.kind_of? Java::Burp::IHttpRequestResponse
      serv = req.getHttpService
      https = serv.getProtocol == "https"
      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 = getHelpers.buildHttpRequest req
      host = url.host
      port = url.port
      if url.scheme.downcase == "https"
        https = true
        port = 443 if port == -1
      else
        https = false
        port = 80 if port == -1
      end
    end
  when 4,5
    host, port, https, req, ip_off = args
  else
    raise ArgumentError
  end
  req = req.to_java_bytes if req.respond_to? :to_java_bytes
  scanq = if getBurpVersion
    _check_cb.doActiveScan(host, port, https, req, ip_off)
  else
    _check_cb.doActiveScan(host, port, https, req)
  end
  Buby::Implants::ScanQueueItem.implant scanq
end

#doPassiveScan(host, port, https, req, rsp) ⇒ Object 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.

* host = The hostname of the remote HTTP server.
* port = The port of the remote HTTP server.
* https = Flags whether the protocol is HTTPS or HTTP.
* req  = The full HTTP request. (String or Java bytes[])
* rsp  = The full HTTP response. (String or Java bytes[])


233
234
235
236
237
# File 'lib/buby.rb', line 233

def doPassiveScan(host, port, https, req, rsp)
  req = req.to_java_bytes if req.is_a? String
  rsp = rsp.to_java_bytes if rsp.is_a? String
  _check_cb.doPassiveScan(host, port, https, req, rsp)
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.



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

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.



1089
1090
1091
# File 'lib/buby.rb', line 1089

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.



1064
1065
1066
1067
# File 'lib/buby.rb', line 1064

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.



1362
1363
1364
1365
# File 'lib/buby.rb', line 1362

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


1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
# File 'lib/buby.rb', line 1298

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

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



1166
1167
1168
1169
1170
1171
1172
1173
1174
# File 'lib/buby.rb', line 1166

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



1104
1105
1106
1107
1108
# File 'lib/buby.rb', line 1104

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.



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

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

#excludeFromScope(url) ⇒ Object Also known as: exclude_from_scope, exclude_scope

Exclude the specified URL from the Suite-wide scope.

* url = The URL to exclude from the Suite-wide scope.


243
244
245
246
# File 'lib/buby.rb', line 243

def excludeFromScope(url)
  url = Java::JavaNet::URL.new(url) if url.is_a? String
  _check_cb.excludeFromScope(url)
end

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

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



467
468
469
# File 'lib/buby.rb', line 467

def exitSuite(prompt_user=false)
  _check_and_callback(:exitSuite, prompt_user ? true : false)
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)


1076
1077
1078
1079
# File 'lib/buby.rb', line 1076

def extender_initialize ext
  @burp_extender = ext
  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.



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

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

#getBurpVersionObject Also known as: burp_version, get_burp_version

This method can be used to determine the version of the loaded burp at runtime. This is included in the Javadoc for the extension interfaces but not the supplied interface files.

Returns:

  • String array containing the product name, major version, and minor version.



556
557
558
559
560
561
562
# File 'lib/buby.rb', line 556

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.



1457
1458
1459
# File 'lib/buby.rb', line 1457

def getCommandLineArguments
  _check_and_callback(:getCommandLineArguments)
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.



948
949
950
# File 'lib/buby.rb', line 948

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

#getHeaders(message) ⇒ Object Also known as: headers, get_headers

Deprecated.

Use

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.

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

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

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

Parameters:

  • message

    The request to be parsed.

Returns:

  • An array of HTTP headers.



458
459
460
461
# File 'lib/buby.rb', line 458

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



585
586
587
# File 'lib/buby.rb', line 585

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

#getParameters(request) ⇒ Object Also known as: parameters, get_parameters

Deprecated.

Use IExtensionHelpers.analyzeRequest() instead.

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.

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

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

Parameters:

  • request

    The request to be parsed.

Returns:

  • An array of: String[] { name, value, type } containing details of the parameters contained within the request.



435
436
437
438
# File 'lib/buby.rb', line 435

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

#getProxyHistoryObject 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.



368
369
370
# File 'lib/buby.rb', line 368

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

#getScanIssues(urlprefix = nil) ⇒ Object 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.

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



390
391
392
# File 'lib/buby.rb', line 390

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

#getSiteMap(urlprefix = nil) ⇒ Object 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.



379
380
381
# File 'lib/buby.rb', line 379

def getSiteMap(urlprefix=nil)
  HttpRequestResponseList.new(_check_and_callback(:getSiteMap, urlprefix))
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.



611
612
613
# File 'lib/buby.rb', line 611

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.



598
599
600
# File 'lib/buby.rb', line 598

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.



1034
1035
1036
# File 'lib/buby.rb', line 1034

def getToolName(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.



1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
# File 'lib/buby.rb', line 1547

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) ⇒ Object Also known as: include_in_scope, include_scope

Include the specified URL in the Suite-wide scope.

* url = The URL to exclude in the Suite-wide scope.


252
253
254
255
# File 'lib/buby.rb', line 252

def includeInScope(url)
  url = Java::JavaNet::URL.new(url) if url.is_a? String
  _check_cb.includeInScope(url)
end

#isInScope(url) ⇒ Object Also known as: is_in_scope, in_scope?

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

* url = The URL to query

Returns: true / false



263
264
265
266
# File 'lib/buby.rb', line 263

def isInScope(url)
  url = Java::JavaNet::URL.new(url) if url.is_a? String
  _check_cb.isInScope(url)
end

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

Display a message in the Burp Suite alerts tab.

* msg =  The alert message to display.


272
273
274
# File 'lib/buby.rb', line 272

def issueAlert(msg)
  _check_cb.issueAlert(msg.to_s)
end

#legacy_mode?Boolean

Returns:

  • (Boolean)


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

def legacy_mode?
  self.class.legacy_mode?
end

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

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.

configuration.

This method is only available with Burp 1.3.09+

Parameters:

  • config

    A map of name/value Strings to use as Burp’s new



534
535
536
# File 'lib/buby.rb', line 534

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.



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

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

#makeHttpRequest(*args) ⇒ Object Also known as: make_http_request, make_request

Issue an arbitrary HTTP request and retrieve its response

* host  = The hostname of the remote HTTP server.
* port  = The port of the remote HTTP server.
* https = Flags whether the protocol is HTTPS or HTTP.
* req   = The full HTTP request. (String or Java bytes[])

also may be called with new IHttpService as an argument

* service = IHttpService object with host, port, etc.
* request = request string

Returns:

  • The full response retrieved from the remote server.



289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
# File 'lib/buby.rb', line 289

def makeHttpRequest(*args)
  ret = case args.size
  when 2
    service, req = args
    req = req.to_java_bytes if req.is_a? String
    _check_and_callback(:makeHttpRequst, service, req)
  when 4
    host, port, https, req = args
    req = req.to_java_bytes if req.is_a? String
    _check_cb.makeHttpRequest(host, port, https, req)
  else
    raise ArgumentError
  end
  String.from_java_bytes(ret)
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.



1418
1419
1420
1421
# File 'lib/buby.rb', line 1418

def new_scan_issue(issue)
  pp [:got_newScanIssue, issue] if $DEBUG
  ScanIssueHelper.implant issue
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.



1382
1383
1384
1385
# File 'lib/buby.rb', line 1382

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:



1327
1328
1329
1330
# File 'lib/buby.rb', line 1327

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



1119
1120
1121
1122
1123
1124
# File 'lib/buby.rb', line 1119

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?)



731
732
733
734
735
736
737
# File 'lib/buby.rb', line 731

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?)



630
631
632
633
634
635
636
# File 'lib/buby.rb', line 630

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?)



650
651
652
653
654
655
656
# File 'lib/buby.rb', line 650

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.



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

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



829
830
831
832
833
834
835
# File 'lib/buby.rb', line 829

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.

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. This method is only available with Burp 1.3.07+ and is deprecated in 1.5.01.

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



484
485
486
487
488
489
490
491
492
# File 'lib/buby.rb', line 484

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?)



756
757
758
759
760
761
762
# File 'lib/buby.rb', line 756

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?)



670
671
672
673
674
675
676
# File 'lib/buby.rb', line 670

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.



792
793
794
795
796
797
798
# File 'lib/buby.rb', line 792

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?)



777
778
779
780
781
782
783
# File 'lib/buby.rb', line 777

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?)



690
691
692
693
694
695
696
# File 'lib/buby.rb', line 690

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?)



708
709
710
711
712
713
714
# File 'lib/buby.rb', line 708

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.



846
847
848
849
850
851
852
# File 'lib/buby.rb', line 846

def registerSessionHandlingAction(action)
  if block_given?
    _check_and_callback(:registerSessionHandlingAction, &block)
  else
    _check_and_callback(:registerSessionHandlingAction, action)
  end
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.



869
870
871
# File 'lib/buby.rb', line 869

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

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

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.

  • filename = path and filename of the file to restore from



403
404
405
# File 'lib/buby.rb', line 403

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.



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

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

#saveConfigObject Also known as: save_config, config

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

configuration.

This method is only available with Burp 1.3.09+

Returns:

  • A Map of name/value Strings reflecting Burp’s current



516
517
518
# File 'lib/buby.rb', line 516

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.



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

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

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

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.

  • filename = path and filename of the file to save to



414
415
416
# File 'lib/buby.rb', line 414

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.



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

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.



1526
1527
1528
1529
1530
1531
1532
1533
1534
# File 'lib/buby.rb', line 1526

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

#sendToIntruder(host, port, https, req, ip_off) ⇒ Object Also known as: send_to_intruder, intruder

Send an HTTP request to the Burp Intruder tool

* host  = The hostname of the remote HTTP server.
* port  = The port of the remote HTTP server.
* https = Flags whether the protocol is HTTPS or HTTP.
* req   = The full HTTP request.  (String or Java bytes[])
* ip_off = 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[2] array containing the start and end offsets
* for the insertion point. *1.4.04+* only
*


317
318
319
320
321
322
323
324
# File 'lib/buby.rb', line 317

def sendToIntruder(host, port, https, req, ip_off)
  req = req.to_java_bytes if req.is_a? String
  if self.getBurpVersion.to_a[1..-1].join(".") < "1.4.04"
    _check_cb.sendToIntruder(host, port, https, req)
  else
    _check_cb.sendToIntruder(host, port, https, req, ip_off)
  end
end

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

Send an HTTP request to the Burp Repeater tool.

* host  = The hostname of the remote HTTP server.
* port  = The port of the remote HTTP server.
* https = Flags whether the protocol is HTTPS or HTTP.
* req   = The full HTTP request. (String or Java bytes[])
* tab   = The tab caption displayed in Repeater. (default: auto-generated)


334
335
336
337
# File 'lib/buby.rb', line 334

def sendToRepeater(host, port, https, req, tab=nil)
  req = req.to_java_bytes if req.is_a? String
  _check_cb.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.

* url = The new seed URL to begin spidering from.


343
344
345
346
# File 'lib/buby.rb', line 343

def sendToSpider(url)
  url = Java::JavaNet::URL.new(url) if url.is_a? String
  _check_cb.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.



572
573
574
# File 'lib/buby.rb', line 572

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

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

This method sets the interception mode for Burp Proxy.

be enabled.

Parameters:

  • enabled

    Indicates whether interception of proxy messages should



547
548
549
# File 'lib/buby.rb', line 547

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



1564
1565
1566
1567
1568
1569
1570
# File 'lib/buby.rb', line 1564

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



1573
1574
1575
1576
1577
1578
1579
# File 'lib/buby.rb', line 1573

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.



1447
1448
1449
# File 'lib/buby.rb', line 1447

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:



968
969
970
# File 'lib/buby.rb', line 968

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.



1485
1486
1487
1488
1489
# File 'lib/buby.rb', line 1485

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.



1472
1473
1474
1475
1476
# File 'lib/buby.rb', line 1472

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



1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
# File 'lib/buby.rb', line 1497

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