Writing Burp Extensions (Shodan Scanner)
In this article, we will have an overview of writing Burp extensions. At the end of the post, we will have an extension that will take any HTTP request, determine the domain’s IP address, and get specific information using Shodan API.
I have divided the article into the following hierarchy so that you can skip some sections if you already know.
- Introducing Burp Extender Interfaces
- Environment Setup
Writing Simple Port Scanner using Shodan API
- Naming Extension
- Creating Context Menu
- Creating action function
Introducing Extender Interfaces
The theory behind writing Burp extensions revolves around the understanding of basic OOPS concepts and a little bit of familiarity with any programming language. Burp provides several ways to interact with its exposed interfaces and extend its functionality with different tools, such as Target, Repeater, Scanner, etc. In this phase, we will look into some of those interfaces and how we can use them to create our first extension.
We will be mainly using the following burp interfaces for this write-up:
Apart from the above-mentioned interfaces, we will also be using the following library from core java
Per the Burp documentation, it says, “All extensions must implement this interface.” The reason is quite simple, to create our extension, we need to register it first. This is done by extending the function named registerExtenderCallbacks. It provides us access to some functions implemented by IBurpExtenderCallbacks interface.
This interface mainly deals with context-specific data; it facilitates us with the number of functions implemented by IContextMenuInvocation interface. These functions can be used to fetch out or add information to any of the contexts provided by the burp, i.e., we can define where exactly our context menu item should show up in Burp tools (Repeater/Scanner/Target Section).
We will be using java’s swing library to create GUI.
Our aim for this write-up will be to create a context menu entry named “Scan with Shodan,” and when the user selects this option, our code should fetch out the HTTP host value from the selected request and send the IP address of the host to the Shodan API server and show us the results in the output section of extension tab.
Let’s break down our goal for this phase into different steps:
- Getting the Shodan API key
- Getting Jython Standalone Jar file
- Setting up Environment
Getting Shodan API Key
To obtain the Shodan API key, we must register an account here. Then go to the profile section and copy your key. Place this key start_scan function of the code shown in the below sections.
Downloading/Installing Jython Standalone Jar File
As we will be accessing Java libraries via Python, we need an interpreter that can translate our python code to java interfaces for that, we will be using Jython. Download the Jython jar file from here.
Setting up Environment
We will now set up our environment to load our extension after it is completed.
- Open the Burp tool
- Go to Extender tab > options
- In the Python Environment Section and select the downloaded Jython jar file
Writing Simple Port Scanner using Shodan API
Let’s import the necessary interfaces from the burp mentioned in the above section and register our extension by overloading registerExtenderCallbacks function. We further obtain the instance of IBurpExtenderCallbacks function by assigning the callbacks to the class variable self. callbacks. We set our Extension name using the function named “setExtensionName” from the callback instance. We also register ContextMenuFactory so that we will be able to create a context menu and add our desired entry to it.
Creating Context Menu
Let us create our context menu entry by overloading the function from IBurpContextMenuFactory interface. By looking at the documentation provided by the portswigger, we can see that we can use createMenuItems function, and it needs one argument, and that should be IContextMenuInvocatoin interface. Further, this function needs to return a list of JMenuItem.
Let’s overload the function and add our item name to the list of menu items. JMenuItem takes several arguments, such as item name, icon, action, etc. However, we are only interested in the name and actionPerformed. The actionPerformed argument takes a function and invokes it when the menu item is clicked.
Here we are using python lambda functions to pass more than one argument to our function. We then return the list of menu items being added so far.
Creating Action Function
We then added two functions named startThreaded and start_scan. The reason for adding startThreaded function is all mouse click events are asynchronous events therefore when we invoke our extension, our burp will completely hang up as it will be waiting for the event to be completed. As our desired task will take seconds to complete, we need it to run as a background thread.
The start_scan function will take the invocation instance and use the getSelectedMessages function to fetch the HTTP request/response objects from where it is invoked.
We further used IHttpRequestResponse interface to retrieve the HTTP service object and obtain hostname using the getHost function. As Shodan API will need an IP address to fetch the required information, we used gethostbyname function from python’s socket library to do that task.
We initiated the https request using the Python urllib2 module, loaded the JSON data in the response variable, and printed that to the output console.
Steps to load and execute a Burp Extension:
- Go to extender tab >extensions>add>select extension type>select extension file > click on next.
- If everything went well as directed, you should see your extension loaded in the extensions tab.
- Select any request from proxy history, and click on the context menu entry created earlier
You should now see the results in the extension output tab.
As we are currently obtaining the data in the output console, I leave it as a task for the diligent reader to update the target tab with the obtained information.
The target tab should now contain the following entries:
The complete Source code can be downloaded here.