Module: Buby::Extender

Includes:
Java::Burp::IBurpExtender, Java::Burp::IContextMenuFactory, Java::Burp::IExtensionStateListener, Java::Burp::IHttpListener, Java::Burp::IProxyListener, Java::Burp::IScannerListener, Java::Burp::IScopeChangeListener
Included in:
BurpExtender
Defined in:
lib/buby/extender.rb

Overview

TODO:

move implant logic to extender interfaces

Note:

This class, unlike the Java implementation, does not fire the deprecated evt_* callbacks, only the new versions.

This is the JRuby implementation of IBurpExtender for use as a JRuby extension. This class handles the type conversions and other ruby sugar. BurpExtender further extends this by adding additional things during startup, like setting up Buby as the handler class and starting console tabs.

Buby internals collapse

@@handler =

Internal reference to ruby handler class (usually Buby)

nil

Buby internals collapse

Burp extender collapse

Listeners collapse

Class Method Details

.handler ⇒ Object

Returns the internal Ruby handler reference.

The handler is the ruby class or module used for proxying BurpExtender events into a ruby runtime. Usually, this is Buby or a subclass.



30
31
32
 
# File 'lib/buby/extender.rb', line 30

def self.handler
  @@handler
end

.handler=(hndlr) ⇒ Object

Sets an internal reference to the ruby handler class or module to use for proxied BurpExtender events into a ruby runtime.

Generally, this should probably be called in #registerExtenderCallbacks. However, it is also possible to set this afterwards and even swap in new objects during runtime.



41
42
43
 
# File 'lib/buby/extender.rb', line 41

def self.handler=(hndlr)
  @@handler = hndlr
end

Instance Method Details

#createMenuItems(invocation) ⇒ Array<JMenuItem>?

This method is abstract.

This method will be called by Burp when the user invokes a context menu anywhere within Burp. The factory can then provide any custom context menu items that should be displayed in the context menu, based on the details of the menu invocation.

Parameters:

  • invocation (IContextMenuInvocation) —

    An object the extension can query to obtain details of the context menu invocation.

Returns:

  • (Array<JMenuItem>, nil) —

    A list of custom menu items (which may include sub-menus, checkbox menu items, etc.) that should be displayed. Extensions may return nil from this method, to indicate that no menu items are required.



142
143
144
 
# File 'lib/buby/extender.rb', line 142

def createMenuItems invocation
  @@handler.create_menu_items(invocation) if @@handler.respond_to? :create_menu_items
end

#extensionUnloaded ⇒ Object

This method is called when the extension is unloaded. This, in turn, calls Buby#extension_unloaded on the handler instance



83
84
85
 
# File 'lib/buby/extender.rb', line 83

def extensionUnloaded
  @@handler.extension_unloaded if @@handler.respond_to? :extension_unloaded
end

#handler ⇒ Object 



45
46
47
 
# File 'lib/buby/extender.rb', line 45

def handler
  @@handler
end

#handler=(hndlr) ⇒ Object 



49
50
51
 
# File 'lib/buby/extender.rb', line 49

def handler= hndlr
  @@handler = hndlr
end

#initialize(*args) ⇒ Object

This callback usually fires before the handler is set.



56
57
58
 
# File 'lib/buby/extender.rb', line 56

def initialize *args
  @@handler.extender_initialize(*args) if @@handler.respond_to? :extender_inititialize
end

#newScanIssue(issue) ⇒ Object

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.



125
126
127
 
# File 'lib/buby/extender.rb', line 125

def newScanIssue(issue)
  @@handler.new_scan_issue(issue) if @@handler.respond_to? :new_scan_issue
end

#processHttpMessage(toolFlag, messageIsRequest, messageInfo) ⇒ void

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.



115
116
117
 
# File 'lib/buby/extender.rb', line 115

def processHttpMessage(toolFlag, messageIsRequest, messageInfo)
  @@handler.process_http_message(toolFlag, messageIsRequest, messageInfo) if @@handler.respond_to? :process_http_message
end

#processProxyMessage(messageIsRequest, message) ⇒ void

This method returns an undefined value.

This method is invoked when an HTTP message is being processed by the Proxy and calls Buby#process_proxy_message on the handler.

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.



98
99
100
 
# File 'lib/buby/extender.rb', line 98

def processProxyMessage(messageIsRequest, message)
  @@handler.process_proxy_message(messageIsRequest, message) if @@handler.respond_to? :process_proxy_message
end

#registerExtenderCallbacks(callbacks) ⇒ void

This method returns an undefined value.

This method is invoked when the extension is loaded. It registers an instance of the IBurpExtenderCallbacks interface, providing methods that may be invoked by the extension to perform various actions.

Parameters:

  • callbacks (IBurpExtenderCallbacks) —

    Burp’s Java object for querying Burp’s data.



68
69
70
71
72
73
74
75
76
77
 
# File 'lib/buby/extender.rb', line 68

def registerExtenderCallbacks(callbacks)
  @callbacks = callbacks
  callbacks.issueAlert("[#{self.class}] registering JRuby handler callbacks")
  callbacks.registerExtensionStateListener(self)
  callbacks.registerHttpListener(self)
  callbacks.registerScannerListener(self)
  callbacks.registerContextMenuFactory self
  callbacks.registerScopeChangeListener self
  @@handler.register_callbacks(callbacks) if @@handler.respond_to? :register_callbacks
end

#scopeChanged ⇒ void

This method is abstract.

This method returns an undefined value.

This method is invoked whenever a change occurs to Burp’s suite-wide target scope.



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

def scopeChanged
  @@handler.scope_changed if @@handler.respond_to? :scope_changed
end