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 IP address of domain and get specific information using Shodan API.

I have divided the article in the following hierarchy so that you can skip some sections if you already know.

  1. Introducing Burp Extender Interfaces
  2. Environment Setup
  3. Writing Simple Port Scanner using Shodan API
    1. Naming Extension
    2. Creating Context Menu
    3. Creating action function
  4. References

Introducing Extender Interfaces

The theory behind writing Burp extensions revolves around the understanding of basic OOPS concepts and little bit familiarity with any programming language. Burp provides a number of ways to interact with its exposed interfaces and extend its functionality of different tools provided within it, such as Target, Repeater, Scanner, etc. In this phase, we will be looking into some of those interfaces and how we can use them to create our first extension.

We will be mainly using following burp interfaces for this write-up:

  • IBurpExtender
  • IContextMenuFactory

Apart from above mentioned interfaces, we will also be using the following library from core java

  • Javax.swing


As 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 a number of functions implemented by IBurpExtenderCallbacks interface.


This interface mainly deals with context-specific data; it facilitates us with the number functions implemented by IContextMenuInvocation interface. These functions can be used to fetch out or add information to any of the context 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.

Environment Setup

Our aim for this write up will be creating 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 send the IP address of host to Shodan API server and show us the results in output section of extension tab.

Let’s break down our goal for this phase into different steps:

  • Getting Shodan API key
  • Getting Jython Standalone Jar file
  • Setting up Environment

Getting Shodan API Key

To obtain Shodan API key, we need to 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 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 be setting up our environment so that we can load our extension after it is being completed.


  1. Open Burp tool.
  2. Go to Extender tab > options.
  3. In the Python Environment Section and select the downloaded Jython jar file.

Writing Simple Port Scanner using Shodan API

Naming Extension

Let’s import necessary interfaces from the burp mentioned in above section and register our extension by overloading registerExtenderCallbacks function. We further obtain the instance of IBurpExtenderCallbacks function by assigning the callbacks to class variable self.callbacks. Using the function named “setExtensionName” from the callback instance we set our Extension name. We also register ContextMenuFactory so that we will be able to create 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 us overload the function and add our item name to the list of menu items. JMenuItem takes a number of arguments such 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 being clicked.

Here we are using python lambda functions just 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 hung up as it will be waiting for the event to be completed. As our desired task will take some seconds to complete, we need it to run it as a background thread.

The start_scan function will simply take the invocation instance and use getSelectedMessages function to fetch out the HTTP request/response objects from where it is being 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 out required information we used gethostbyname function from python’s socket library to do that task.

We initiated the https request using Python urllib2 module and load the JSON data in response variable and print that to output console.

Steps to load and execute a Burp Extension:

  1. Go to extender tab >extensions>add>select extension type>select extension file > click on next.

  1. If everything went well as directed, you should see your extension loaded in extensions tab.

Ethical Hacking Training – Resources (InfoSec)

  1. Select any request from proxy history, and click on the context menu entry created earlier.

You should now see the results in extension output tab.

As we are currently obtaining the data in output console, I leave it as a task for the diligent reader to update target tab with the obtained information.


Target tab should now contain following entries:

Complete Source code can be downloaded here.