lib/buby.rb in emonti-buby-1.0.1 vs lib/buby.rb in emonti-buby-1.1.0.0

- old
+ new

@@ -16,12 +16,18 @@ # * evt_proxy_message # * evt_command_line_args # * evt_register_callbacks # * evt_application_closing # -# This class also exposes several methods used to access Burp functionality -# and user interfaces (note also, abbreviated aliases exist for each): +# 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 @@ -29,34 +35,46 @@ # * makeHttpRequest # * sendToIntruder # * sendToRepeater # * sendToSpider # +# Buby also provides front-end ruby methods for the new callback methods added +# since Burp 1.2.09: +# * getProxyHistory +# * getSiteMap +# * restoreState +# * saveState +# * getParameters +# * getHeaders +# +# 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 2008 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 their products. +# 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 IBurpExtender +# 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. # class Buby # :stopdoc: - VERSION = '1.0.1' + VERSION = '1.1.0' LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR # :startdoc: def initialize(other=nil) @@ -77,13 +95,16 @@ # reference gets set from Java through the evt_extender_init method. def burp_extender; @burp_extender; end # Returns the internal reference to the IBupExtenderCallbacks instance. # This reference gets set from Java through the evt_register_callbacks - # method. + # method. It is exposed to allow you to access the IBurpExtenderCallbacks + # instance directly if you so choose. def burp_callbacks; @burp_callbacks; end + # Internal method to check for the existence of the burp_callbacks reference + # before doing anything with it. def _check_cb @burp_callbacks or raise "Burp callbacks have not been set" end # Send an HTTP request to the Burp Scanner tool to perform an active @@ -93,11 +114,10 @@ # * https = Flags whether the protocol is HTTPS or HTTP. # * req = The full HTTP request. def doActiveScan(host, port, https, req) _check_cb.doActiveScan(host, port, https, req.to_java_bytes) end - alias do_active_scan doActiveScan alias active_scan doActiveScan # Send an HTTP request and response to the Burp Scanner tool to perform a # passive vulnerability scan. @@ -107,49 +127,44 @@ # * req = The full HTTP request. # * rsp = The full HTTP response. def doPassiveScan(host, port, https, req, rsp) _check_cb.doPassiveScan(host, port, https, req.to_java_bytes, rsp.to_java_bytes) end - alias do_passive_scan doPassiveScan alias passive_scan doPassiveScan # Exclude the specified URL from the Suite-wide scope. # * url = The URL to exclude from the Suite-wide scope. def excludeFromScope(url) _check_cb.excludeFromScope(java.net.URL.new(url.to_s)) end - alias exclude_from_scope excludeFromScope alias exclude_scope excludeFromScope # Include the specified URL in the Suite-wide scope. # * url = The URL to exclude in the Suite-wide scope. def includeInScope(url) _check_cb.includeInScope(java.net.URL.new(url.to_s)) end - alias include_in_scope includeInScope alias include_scope includeInScope # Query whether a specified URL is within the current Suite-wide scope. # * url = The URL to query # # Returns: true / false def isInScope(url) _check_cb.isInScope(java.net.URL.new(url.to_s)) end - alias is_in_scope isInScope alias in_scope? isInScope # Display a message in the Burp Suite alerts tab. # * msg = The alert message to display. def issueAlert(msg) _check_cb.issueAlert(msg.to_s) end - alias issue_alert issueAlert alias alert issueAlert # Issue an arbitrary HTTP request and retrieve its response # * host = The hostname of the remote HTTP server. @@ -161,11 +176,10 @@ def makeHttpRequest(host, port, https, req) String.from_java_bytes( _check_cb.makeHttpRequest(host, port, https, req.to_java_bytes) ) end - alias make_http_request makeHttpRequest alias make_request makeHttpRequest # Send an HTTP request to the Burp Intruder tool # * host = The hostname of the remote HTTP server. @@ -173,11 +187,10 @@ # * https = Flags whether the protocol is HTTPS or HTTP. # * req = The full HTTP request. def sendToIntruder(host, port, https, req) _check_cb.sendToIntruder(host, port, https, req.to_java_bytes) end - alias send_to_intruder sendToIntruder alias intruder sendToIntruder # Send an HTTP request to the Burp Repeater tool. # * host = The hostname of the remote HTTP server. @@ -186,24 +199,102 @@ # * req = The full HTTP request. # * tab = The tab caption displayed in Repeater. (default: auto-generated) def sendToRepeater(host, port, https, req, tab=nil) _check_cb.sendToRepeater(host, port, https, req.to_java_bytes, tab) end - alias send_to_repeater sendToRepeater alias repeater sendToRepeater # Send a seed URL to the Burp Spider tool. # * url = The new seed URL to begin spidering from. def sendToSpider(url) _check_cb.includeInScope(java.net.URL.new(url.to_s)) end - alias send_to_spider sendToSpider alias spider sendToSpider + # This method is a __send__ call back 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. + # + # This method was added for provisional calling of new callbacks added since + # Burp 1.2.09 + # + # * meth = string or symbol name of method + # * args = variable length array of arguments to pass to meth + def _check_and_callback(meth, *args) + cb = _check_cb + unless cb.respond_to?(meth) + raise "#{meth} is not available in your version of Burp" + end + cb.__send__ meth, *args + end + # Returns a Java array of IHttpRequestResponse objects pulled directly from + # the Burp proxy history. + def getProxyHistory + _check_and_callback(:getProxyHistory) + end + alias proxy_history getProxyHistory + alias get_proxy_history getProxyHistory + + # Returns a Java array of IHttpRequestResponse objects pulled directly from + # the Burp site map. + def getSiteMap + _check_and_callback(:getSiteMap) + end + alias site_map getSiteMap + alias get_site_map getSiteMap + + # 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 + def restoreState(filename) + _check_and_callback(:restoreState, java.io.File.new(filename)) + end + alias restore_state restoreState + + # 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 + def saveState(filename) + _check_and_callback(:saveState, java.io.File.new(filename)) + end + alias save_state saveState + + # 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 higher. + # + # req = raw request string (converted to Java bytes[] in passing) + def getParameters(req) + _check_and_callback(:getParameters, req.to_s.to_java_bytes) + end + alias parameters getParameters + alias get_parameters getParameters + + # 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 higher. + # + # msg = raw request/response string (converted to Java bytes[] in passing) + def getHeaders(msg) + _check_and_callback(:getHeaders, msg.to_s.to_java_bytes) + end + alias headers getHeaders + alias get_Headers getHeaders + + ### Event Handlers ### # 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 @@ -281,12 +372,12 @@ # # * url: # The requested URL. Set in both the request and response. # # * resourceType: - # The filetype of the requested resource, or a zero-length string if the - # resource has no filetype. + # 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. # @@ -375,9 +466,55 @@ [:req_content_type, req_content_type], [:message, message], [:action, action[0]] ]) if $DEBUG return message + end + + + # 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 with only + # proxied messages. Note, however, the IHttpRequestResponse Java object is + # not used in evt_proxy_http_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. + # + def evt_http_message tool_name, is_request, message_info + pp([:got_http_message, tool_name, is_request, message_info]) if $DEBUG + end + + # 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 newScanIssue BurpExtender Java method. + # + # Parameters: + # * issue = an instance of the IScanIssue Java class with methods for viewing + # information on the scan issue that was generated. + def evt_scan_issue(issue) + pp([:got_scan_issue, issue]) if $DEBUG end # 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.