Writing Burp Extensions (Shodan Scanner)

Sahil Dhar
December 22, 2016 by
Sahil Dhar

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.

What should you learn next?

What should you learn next?

From SOC Analyst to Secure Coder to Security Manager — our team of experts has 12 free training plans to help you hit your goals. Get your free copy now.

  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 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:

  • IBurpExtender
  • IContextMenuFactory

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

  • Javax.swing


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.

Environment Setup

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.


  1. Open the 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 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:

  1. Go to extender tab >extensions>add>select extension type>select extension file > click on next.
  2. If everything went well as directed, you should see your extension loaded in the extensions tab.
  3. 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.

What should you learn next?

What should you learn next?

From SOC Analyst to Secure Coder to Security Manager — our team of experts has 12 free training plans to help you hit your goals. Get your free copy now.


The target tab should now contain the following entries:

  • www.example.com:80
  • www.example.com:443
  • www.example.com:22

The complete Source code can be downloaded here.






Sahil Dhar
Sahil Dhar

Sahil Dhar is an Information Security Enthusiast having more than two years of hands-on experience in Application Security, Penetration Testing, Vulnerability Assessments and Server Config Reviews. He has also been acknowledged and rewarded by various organizations like Google, Apple, Microsoft, Adobe, Barracuda, Pinterest, Symantec, Oracle etc for finding vulnerabilities in their online services.