Jython-Burp-API is an ISC Licensed library, written in Jython, Java and Python.
Jython-Burp-API exposes a Jython interface to the popular Burp Suite web security testing tool, as an alternative to Buby for those testers who prefer Python over Ruby.
- Burp Suite (free or professional)
- Jython 2.7+
-
Install Jython 2.7+ as a standalone jar
-
git clone git://github.com/mwielgoszewski/jython-burp-api.git -
cd jython-burp-api/ -
Copy Burp Suite jar file(s) into current directory
-
Compile BurpExtender files (Note: On Windows the classpath separator is a semi-colon):
$ javac -cp jython.jar java/src/*.java java/src/burp/*.java -
Start Burp by executing the following Jython script, specifying location of Burp as the command line argument -B (note, -i and -d are set to enable interactive console and debug logging):,
$ java -Xmx1g -jar jython.jar run.py -i -d -B burpsuite_pro_v1.5.03.jar
By default, we monitor a list of registered menu items for any changes. If a file has changed (i.e., its last modification time was updated), the API will automatically attempt to reload it. This is great for active development and debugging of Burp extensions.
To start an interactive console, simply pass the -i command line argument
when starting Burp. You can also click one or multiple items in Burp and
assign them to the items local variable like so:
$ java -Xmx1g -jar jython.jar run.py -i -d -B burpsuite_pro_v1.5.03.jar
>>> Burp
<BurpExtender at 0x2>
>>> Burp.history
[<HttpRequest [/]>, ...]
>>> items
[<HttpRequest [/firefox/headlines.xml]>]
>>> request = items[0]
>>> request.headers
{'Accept-Language': 'en-us,en;q=0.5', ...}
>>> request.response
<HttpResponse [302]>
>>> len(request.response)
256
and many more!
Check out the ConsoleMenu class for an example of how to add menu items to Burp's context menu. Below is an example of how to use one in your code.
from gds.burp.menu import MenuItem
class MyMenuItem(MenuItem):
CAPTION = 'my caption'
def menuItemClicked(self, menuItemCaption, messageInfo):
print('clicked %s' % (menuItemCaption, ))
To add your new menu (MyMenuItem) to Burp's context menu, specify it as an
option under [menus] section in burp.ini and set it to enabled. If you wish
to disable the built-in ConsoleMenu item that's registered, simply set it to
disabled, like so:
[menus]
gds.burp.menu.console.ConsoleMenu = disabled
myplugins.MyMenuItem = enabled
Once Burp is loaded, the new menu item should be available in Burp. You can also register menu items at runtime by initializing them within the interactive console. Note however, menu items registered in the console cannot be reloaded since there is no actual file to watch for changes.
>>> class MyMenuItem(MenuItem):
... CAPTION = 'my caption'
... def menuItemClicked(self, menuItemCaption, messageInfo):
... print('clicked %s' % (menuItemCaption, ))
...
>>> MyMenuItem(Burp)
Also, keep in mind that in order to load the menu, we need to import it,
thus requiring it to be in our class path. If you keep your plugins under the
Lib/ directory, you should be good.
One of the methods exposed by the Burp Extender interface is processHttpMessage.
This method, according to the API documentation [..] is invoked whenever any of
Burp's tools makes an HTTP or receives a response [..] For each request, the
method is invoked after the request has been fully processed by the invoking
tool and is about to be made on the network. For each response, the method is
invoked after the response has been received from the network and before any
processing is performed by the invoking tool. To write a plugin to hook into
one of these requests or responses, implement one of the interfaces from
gds.burp.api, such as IRepeaterRequestHandler, IProxyResponseHandler, and the
like. For example, the following plugin would hook requests as they are sent
via Intruder and Scanner, and responses that come in Proxy and Intruder.
from gds.burp.api import IIntruderRequestHandler, IScannerRequestHandler
from gds.burp.api import IProxyResponseHandler, IIntruderResponseHandler
from gds.burp.core import Component, implements
class ExamplePlugin(Component):
implements(IIntruderRequestHandler, IIntruderResponseHandler,
IScannerRequestHandler, IProxyResponseHandler)
def processRequest(self, request):
self.log.info("Request to %s sent through Intruder and Scanner",
request.url.geturl())
def processResponse(self, request):
self.log.info("This response from %s was received via Proxy and Intruder",
request.url.geturl())
To use this plugin, we need to first enable it under the [components] section
within burp.ini, as well as add it to the list of options under [handlers]
in the order in which we want it to be processed. Options in the [handlers]
section can be a comma separated list, specifying the order in which a plugin
will be called. This allows you to decouple tools and configure their use at
different times. If you are familiar with or have experience with request
filter chains, such as in Java web apps, this should be immediately clear.
[components]
testplugin.ExamplePlugin = enabled
[handlers]
intruder.request = ExamplePlugin
intruder.response = ExamplePlugin
proxy.request = ExamplePlugin
proxy.response = ExamplePlugin
Note, a plugin that implements an interface but is not enabled under
[components] and/or is not listed in its respective option in the [handlers]
configuration configuration, will not get called.
- Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
- Fork the repository on Github to start making your changes in a separate branch.
- Write a test which shows that the bug was fixed or that the feature works as expected.
- Send a pull request and bug the maintainer until it gets merged and published. :)