Modifying and Building Burp Extensions


James Kettle (@albinowax) has released an updated method for modifying and building burp extensions using gradle. It is the recommended way of building custom modifications to extensions. The article can be found here: The content below is being kept for reference sake.


Last week James Kettle (@albinowax) released a blog post/whitepaper on the PortSwigger blog titled Cracking the Lens: Targeting HTTP's Hidden Attack-Surface. In short, it's about probing hidden systems that make up modern day application infrastructures by submitting intentionally malformed requests. If you haven't read it yet, I would recommend you check it out. A link to the post can be found here.

Like Kettle's release last year, Backslash Powered Scanning, this one came with another great open source Burp extension, collaborator-everywhere. The source for which can be found here.

This post uses the extension above as an example, but this same process can be applied to any Burp extension written in Java. This post will focus on re-packaging modified extensions on Windows, but a similar solution could probably be deployed with OpenJDK 8 on *nix. This modification process is specifically for extensions written in Java. For those written in Python (like ActiveScan++), you can just modify the Python file in place. For Python extensions, follow the steps in Determining what to Modify below to locate the Python file(s).

The Setup

To initially test and explore the collaborator-everywhere extension I logged in to HackerOne, and picked out a few ongoing bug bounty programs. I added them to my Burp scope and started browsing.

From the Burp Proxy > HTTP History > Edited request tab, you can see an example of the modified request with collaborator-everywhere in action:

Collaborator Everywhere Example

The Problem

The problem I ran into was that on the second site I tested I was repeatedly sent back to the login screen. Presumably, one of these headers added was causing an issue.

I sent a few of the requests to Repeater, and by process of elimination determined it was the Referer header. Depending on which asset was being requested, any referer containing a different domain than the application either caused the request to timeout, or returned a HTTP/1.1 401 Unauthorized. Obviously this has potential security implications related to authentication and authorization and needed to be investigated on its own. But that's not what today's post is about.

We have a burp extension, and we need to modify it (remove the additional Referer header). How do we do that quickly and efficiently?

The steps outlined below may look complicated, but it really boils down to just a few commands. Once you've gone through the process, doing it again in the future only takes a few minutes.

For those who have done any Java development, nothing below will be new. You may even be able to just skip to the Quick Reference section at the bottom if you are only rusty on javac/jar command syntax.

Determining what to Modify

The first thing I did was to go into the BurpSuite bapps directory where collaborator-everywhere is located. The location for any BurpSuite plugin can be found by going to the Extender > Extensions tab, clicking on the extension, then looking at the Filename in the Details tab. On Windows, this filename correlates to a folder in C:\Users\yourusername\AppData\Roaming\BurpSuite\bapps\.

An example of locating the collaboratorEverywhere.jar is pictured below:

Locating BurpSuite plugin

I then made a backup of the existing collaboratorEverywhere.jar to my desktop. Always make a backup first.

Reading the source of the extension is an exercise for the reader. The source is very cleanly written and readable at about 300 lines. Also, the source has a just few functions, and a lot of stubs. That said, finding what to modify did not require reading everything. After unzipping the jar, right in the root directory, I saw a file named injections, with lines like this:

# Lines starting with # are ignored

Searching the code I confirmed around line 241 this file was used in the Injector class to add injection points to the scanner.

Modifying Burp Extensions without Recompiling

Some of these steps were covered above, but to keep the process complete end-to-end they are being covered again here.

Step 1: Back Up The Original

The first step, if you haven't done this already is to back up the original jar file. If things go sideways, this will make it easier to restore to a good state. So make a copy of C:\Users\yourusername\AppData\Roaming\BurpSuite\bapps\126139eafd024b23920ba541040f03b5\build\libs\collaboratorEverywhere.jar and drop it somewhere safe or onto your desktop, somewhere outside of the libs folder.

Step 2: Extract the Jar and Delete the Archive

The second step is to extract the original jar file. Now that you've backed up the original, you can extract the version in libs by renaming it from collaboratorEverywhere.jar to, right-clicking and choosing Extract All.... After that delete the .zip file.

Step 3: Install the Correct Java JDK

Whether you recompile the extension, or simply re-jar, it's easiest to use the Java Development Kit (JDK) to perform Java related actions. Even if you aren't fully recompiling from source, you can still use the JDK's jar utility to re-jar your unzipped archive.

To make life easier, make sure to use the same version of the JDK that the author originally compiled the collaboratorEverywhere.jar with.

There are a few ways to determine what the version is. Sometimes the version is actually in the jar's manifest file, located in .\META-INFO\MANIFEST.MF. There you may find a "Created-By" line that gives the JDK version. In this case we weren't so lucky. The easiest and quickest way is to use Linux or Cygwin to run the file command on one of the class files that was extracted:

[email protected]:/tmp# file BurpExtender.class  
BurpExtender.class: compiled Java class data, version 52.0 (Java 1.8)  

Additional Ways to Verify: On Windows you can also confirm the version using the Java Class File Disassembler (javap) utility that ships with the JDK. But of course you can't do this until you've already installed the JDK... A hex editor could work too, reading certain bytes of the jar and looking them up, but that also takes a bit longer.

And there we have it! Java 1.8. Downloading and installing the JDK is beyond the scope of what I want to cover here, but for those who haven't done it before the steps basically are:

  1. Download the JDK. In this case, JDK 8 here:
  2. Install it (Next, Next, Next, etc)
  3. Create a JAVA_HOME environment variable and point to your JDK install path (C:\Program Files\Java\jdk1.8.0_144). Then add %JAVA_HOME%\bin to your system %PATH%.
  4. Confirm everything worked by opening a new command prompt window and running: java -version. You should see:
C:\>java -version  
java version "1.8.0_144"  
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)  
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)  

Step 4: Make your Modifications

Once the correct JDK is installed and configured, it's time to make your modifications. In my case I just needed to open up C:\Users\dg\AppData\Roaming\BurpSuite\bapps\126139eafd024b23920ba541040f03b5\build\libs\collaboratorEverywhere\injections in a text editor and comment out the following line:


Step 5: Re-Jar

To re-archive everything as a jar, just open a command prompt, navigate to the libs\ directory where your extracted archive is, and use the Java jar command to re-archive everything properly:

cd "C:\Users\yourusername\AppData\Roaming\BurpSuite\bapps\126139eafd024b23920ba541040f03b5\build\libs"  
jar cvf collaboratorEverywhere.jar -C collaboratorEverywhere/ .  

Example output:

C:\>cd "C:\Users\dg\AppData\Roaming\BurpSuite\bapps\126139eafd024b23920ba541040f03b5\build\libs"  
C:\Users\dg\AppData\Roaming\BurpSuite\bapps\126139eafd024b23920ba541040f03b5\build\libs>jar cvf collaboratorEverywhere.jar -C collaboratorEverywhere/ .  
added manifest  
adding: burp/(in = 0) (out= 0)(stored 0%)  
adding: burp/BurpExtender.class(in = 1312) (out= 728)(deflated 44%)  
adding: burp/Correlator.class(in = 4472) (out= 2063)(deflated 53%)  
adding: burp/CustomScanIssue.class(in = 2106) (out= 819)(deflated 61%)  
adding: burp/Injector.class(in = 3857) (out= 2072)(deflated 46%)  
adding: burp/MetaRequest.class(in = 1083) (out= 576)(deflated 46%)  
adding: burp/Monitor.class(in = 6223) (out= 3232)(deflated 48%)  
adding: burp/Utilities.class(in = 3910) (out= 2126)(deflated 45%)  
adding: injections(in = 1117) (out= 437)(deflated 60%)  
ignoring entry META-INF/  
ignoring entry META-INF/MANIFEST.MF  

The key command above is: jar cvf collaboratorEverywhere.jar -C collaboratorEverywhere/ .

Here is the breakdown of what that command is doing:

  • jar : Use the JDK Java archive utility
  • c : creates a new archive
  • v : give me verbose output for this
  • f : I want to specify a jar filename
  • collaboratorEverywhere.jar : argument to -f above, this is the filename I am specifying
  • -C collaboratorEverwhere/ : don't use the contents of the current libs\ directory, change directories to the extracted collaboratorEverywhere/ and use its contents for our jar
  • . : drop the final jar file in the current directory

Step 6: Re-Load

Now that you've rebuilt the jar file it's time to reload it. Go to the Extender > Extensions tab, and uncheck the box in the Loaded column next to the Collaborator Everywhere plugin. Click Yes to the confirmation dialog to unload the extension.

Now just check the Loaded box again, and the extension should be reloaded:

Reloading Burp Extension

Step 7: Test Changes

In this case, testing changes is easy. With the modified plugin loaded in Burp, make sure your browser is using Burp as a proxy, navigate to any web page, and in Proxy > HTTP history > Edited Request you will see that the modified Referer header is no longer being sent.

Compiling Burp Extensions

There may come a time when you need to make changes to how a plugin actually works. In which case you'll need to fully recompile the plugin from source.

Step 1: Make sure JDK is Installed

Make sure you've followed Step 3 above and have the proper JDK installed before continuing.

Step 2: Clone (or Download) the Source

After JDK is installed, download or clone the git repository from In my case, I was working from a sandbox VM that didn't have git installed and I was in a hurry. I ended up just visiting, and used the Clone or download button to download the zip of the repository to my Downloads directory.

If you plan on making serious modifications, I highly suggest you make your own fork of the repository and make a proper clone.

Step 3: Make your Modifications

Now make whatever changes you need. Just as an example, let's alter the name printed when the extension is loaded.

Open collaborator-everwhere\src\burp\ in your favorite editor. If you downloaded the zip of the repository, this file will actually be located at collaborator-everywhere-master\collaborator-everywhere-master\src\burp\

Now, change line 10 to include some additional text that will let us know our modified version of the plugin was loaded. In this example, I've added - pointless mod to the extension name:

public class BurpExtender implements IBurpExtender {  
    private static final String name = "Collaborator Everywhere - pointless mod";
    private static final String version = "1.0";

Save and close the modified Java file.

Step 4: Compile

First let's set up a landing spot for our build. In the root collaborator-everywhere\ (or collaborator-everywhere-master\collaborator-everywhere-master\ depending on your setup), in the same location as src, resources and the file create a new folder named build.

Open a command prompt window to the collaborator-everywhere\ directory (or equivalent), and execute the following:

javac -cp "C:\Program Files\BurpSuitePro\burpsuite_pro.jar" -d build src\burp\*.java  

Here is the breakdown of what that command is doing:

  • javac : Use the JDK Java compile utility
  • -cp "C:\Program Files\BurpSuitePro\burpsuite_pro.jar" : Include the Burp Suite Pro jar in our classpath. If you get a bunch of cannot find symbol errors related to Burp classes, you're missing this
  • -d build : Tell javac where to drop the compiled .class files. In this case, we want them in the build\ directory.
  • src\burp\*.java: Finally, pass the location of the Java source files we want javac to compile

If everything went well there will be no additional output and in the build\ directory you will now see a bunch of .class files in a newly created build\burp\ directory.

Step 5: Building the Jar

Once everything is built it is time to archive it into a Jar. One thing to keep in mind though, is this project relies on the injections file being located in the root of the jar at /injections (see source code for usage).

To make sure you meet this requirment, first copy the injections file into your build directory, then use the jar utility to create your jar:

cd wherever\you\have\collaborator-everywhere\build\  
copy /Y ..\resources\injections .  
jar cvf collaboratorEverywhere.jar burp/*.class injections  

A breakdown of what the jar command is doing:

  • jar : Use the JDK Java archive utility
  • cvf collaboratorEverywhere.jar : creates a new archive, give me verbose output, and I want to specify a jar filename. The filename given is collaboratorEverywhere.jar.
  • burp/*.class injections : Include these files in our archive: the .class files in the burp folder as well as the injections file

If all goes well you'll see output like this:

C:\Users\dg\Downloads\collaborator-everywhere-master\collaborator-everywhere-master\build>jar cvf collaboratorEverywhere.jar burp/*.class injections  
added manifest  
adding: burp/BurpExtender.class(in = 1122) (out= 657)(deflated 41%)  
adding: burp/Correlator.class(in = 3832) (out= 1826)(deflated 52%)  
adding: burp/CustomScanIssue.class(in = 1703) (out= 738)(deflated 56%)  
adding: burp/Injector.class(in = 3349) (out= 1881)(deflated 43%)  
adding: burp/MetaRequest.class(in = 864) (out= 508)(deflated 41%)  
adding: burp/Monitor.class(in = 5447) (out= 2876)(deflated 47%)  
adding: burp/Utilities.class(in = 3192) (out= 1789)(deflated 43%)  
adding: injections(in = 1115) (out= 436)(deflated 60%)  

And in the build\ directory, you will have a shiny new collaboratorEverywhere.jar.

Step 4: Loading as a New Burp Extension

We could just replace the existing version of collaboratorEverywhere.jar with our new one, but loading it as a new extension is much cleaner.

To load the jar as a new extension, go to the Burp tab Extender > Extensions, and click Add underneath Burp Extensions.

In the Load Burp Extension window that opens, choose the Java extension type and locate your newly compiled collaboratorEverywhere.jar file:

Load Jar

Once you've done that, click Next to load the extension. If all goes well you will see a message telling you the extension was successfully loaded, and you will see the additional text - pointless mod added:

Successfully loaded jar

In your list of Burp Extensions, be sure to disable the original and only enable your new version to avoid conflicts:

List of Active Extensions

When loading the extension into Burp, if you see an error with a stack trace that contains::

java.lang.NullPointerException ....  
    at java.util.Scanner.<init>(

It probably means you've misplaced the injections file. Unzip your jar and confirm it is in the right spot.

That's all there is to it! Now go out and modify your favorite Burp Extension :)

Modifying and Building Burp Extensions Quick Reference

This section is a boiled down version of everything above. It should serve as an easy reference. These steps assume you've identified and installed the correct JDK.

Modify and Re-Jar Extension

  1. Locate the jar file: Extender > Extensions > Select extension > Details. bapps\ directory is located at C:\Users\yourusername\AppData\Roaming\BurpSuite\bapps
  2. Backup the original jar file to a different folder, outside of bapps.
  3. Change extension from .jar to .zip, extract contents, delete .zip file
  4. Make your modifications
  5. Re-jar: jar cvf yourJarName.jar -C extractedContentsDirectory/ .
  6. Reload extension in Burp: Extender > Extensions, uncheck Load and check it again

Compile Extension from Source

  1. Clone or download extension source code
  2. Make your modifications, and create build location
  3. Compile source code: javac -cp "C:\Program Files\BurpSuitePro\burpsuite_pro.jar" -d buildLocation sourceCodeLocation\*.java
  4. Create Jar: jar cvf yourJarName.jar buildLocation/*.class anyOtherDependencies1 anyOtherDependencies2
  5. Load Jar into Burp: Extender > Extensions, Add, Extension type Java and locate built jar, Next, Close
  6. Disable original version of extension from BApp store

This Quick Reference has also been captured as a GitHub gist here:

Thanks for reading

I hope this info helped you. If you have any questions or feedback, please email: dg at castle dot neomailbox dot ch, or hit me up on twitter @decidedlygray.