login

Burp Suite, the leading toolkit for web application security testing

PortSwigger Web Security Blog

Wednesday, 8 April 2009

Using Burp Extender

From time to time, people ask me for help getting their code working with Burp Extender, so here is a quick worked example of how to do this. The example is based on a plugin written by Daniele Costa, which extracts HTML comments from HTTP responses, and writes these to file and to the command line.

The core of the plugin code is simple. It implements the processProxyMessage method in IBurpExtender, to get a handle to all requests and responses passing through Burp Proxy. For response messages, it checks whether the requested URL is in scope, and if so uses a regular expression to match any HTML comments within the response. Anyone with some basic Java skills can create code like this. What may be less familiar is actually getting your code to load and run within Burp.

If you want to play with this example yourself, you can download the source code. The steps to compile and run the plugin are as follows:
  1. If you don't already have it, download and install the Java Development Kit (JDK) from Sun.
  2. Create a directory to work in, and cd into it from the command line.
  3. Copy the plugin source file (BurpExtender.java) into your working directory.
  4. Create a subdirectory called "burp", and copy the IBurpExtenderCallbacks.java file into this directory. You will need this file in the correct relative path, because the plugin code makes use of the IBurpExtenderCallbacks interface.
  5. In your working directory, compile the BurpExtender.java source file into a .class file using javac, the Java compiler. The exact command will depend on the location of your JDK - for example, on Windows, you might type: "\Program Files\Java\jdk1.6.0_04\bin\javac.exe" BurpExtender.java
  6. Confirm that the file BurpExtender.class has appeared in your working directory.
  7. Build a Java archive (JAR) file containing your .class file. Depending again on your JDK location, you might type: "\Program Files\Java\jdk1.6.0_04\bin\jar.exe" -cf burpextender.jar BurpExtender.class
  8. Confirm that the file burpextender.jar has appeared in your working directory.
  9. Copy your normal Burp JAR file into your working directory.
  10. Using the actual name of your Burp JAR file, start Burp using the command: java -Xmx512m -classpath burpextender.jar;burp.jar burp.StartBurp
If everything works, Burp should launch with a number of entries in the alerts tab, confirming which IBurpExtender methods were successfully loaded from your plugin (in this case, processProxyMessage and registerExtenderCallbacks):



To make use of the actual functionality of this plugin, you simply need to add the domains that interest you to Burp's Target Scope, and then browse to them via Burp Proxy. Any HTML comments contained within in-scope responses will be printed to the command line, and saved to a file in your working directory.

19 comments:

pierz said...

Hi,

When will it be possible to directly extend Intruder/Repeater ?

We can use a hack like proxify Intruder request to another Burp instance but... lazy...

PortSwigger said...

@Pierz

Later this year, I would say. At the very least, you will be able to handle requests for all Suite tools before they are sent. Hopefully a bunch of other useful APIs will also be exposed.

D1sc0nt3nt said...

I'd like to create plugins for the scanner, but the thing stopping me is that there doesn't seem to be any support to write a result to the results page. I don't want to be writing random files everywhere for custom tests.

Is it possible to create an interface to allow extender to generate a result for the scanner?

Thanks,
D1sc0nt3nt

PortSwigger said...

@D1sc0nt3nt

Yes, this would be a useful feature. I'm intending to add the facility to define custom checks within the UI at some point, with an option to use Burp Extender to write the check logic, so this will come along at some point.

Cheers

Anonymous said...

How can I use this feature using Linux?

I've tried the example with success using Windows, but on Linux (Sun JRE/JDK (SE): 1.6.0_07-b06) it doesn't work.

I get the following error message after:
java -Xmx512m -classpath 'burpextender.jar;burpsuite_v1.2.01.jar' burp.StartBurp


Error message:
Exception in thread "main" java.lang.NoClassDefFoundError: burp/StartBurp
Caused by: java.lang.ClassNotFoundException: burp.StartBurp
at java.net.URLClassLoader$1.run(URLClassLoader.java:200)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:276)
at java.lang.ClassLoader.loadClass(ClassLoader.java:251)
at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:319)

Eric Monti said...

BurpExtender is pretty awesome, though there are some limitations that seem like they ought to go away with regards to interaction with the UI. Also, it would be great to be able to extend burp with a logger that trapped *EVERY* HTTP request made. On lots of engagements, it helps -- or is even a requirement -- to have a complete log of everything you have sent to a target. This helps for CYA, and contrawise, figuring out what you did to break things if by accident.

Anyway I just published a JRuby <-> Burp bridge based on BurpExtender. It was actually quite straightforward to implement.

Check out:

http://github.com/emonti/buby

PortSwigger said...

@Eric

Thanks. I'm actually working on some enhancements to Burp extender right now that will provide a suite-wide request/response interceptor. It should be with pro users in a week or two.

Regarding your CYA, there is already a built-in logging function for all tools' requests, which you can use if all you need is simple logging.

Cheers

Extender said...

With getParameters(), is it possible to tell the type of parameter? ie cookie, URL, or body?

Aq said...

Linux users will have to launch burp with this command:

java -Xmx512m -classpath burpextender.jar:burp.jar burp.StartBurp

Note the use of a : separator instead of a ;

PortSwigger said...

@Extender

Good idea. As of version 1.2.13, each element in the array returned by the getParameters method will contain the following, which shouldn't impact on any legacy code:

String[] { name, value, type }

Anonymous said...

@Aq:

Omg, I've overseen it. 8-O

Anonymous said...

I can't get the example to work. I get the following error message:

Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong n
ame: burp/BurpExtender)
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClassCond(Unknown Source)
at java.lang.ClassLoader.defineClass(Unknown Source)
at java.security.SecureClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.access$000(Unknown Source)
at java.net.URLClassLoader$1.run(Unknown Source)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at java.lang.Class.forName0(Native Method)
at java.lang.Class.forName(Unknown Source)
at burp.tpb.(Unknown Source)
at burp.tpb.a(Unknown Source)
at burp.tpb.a(Unknown Source)
at burp.yf.a(Unknown Source)
at burp.StartBurp.main(Unknown Source)

Anonymous said...

try java burp.jar;burp.burpextender.jar burp.StartBurp, I got my burp running using this but not sure if the plugin works.

Anonymous said...

I am getting the following error, any suggestions:
Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong
ame: burp/BurpExtender)
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(Unknown Source)
at java.security.SecureClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.access$100(Unknown Source)
at java.net.URLClassLoader$1.run(Unknown Source)
at java.net.URLClassLoader$1.run(Unknown Source)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at java.lang.Class.forName0(Native Method)
at java.lang.Class.forName(Unknown Source)
at burp.wpb.(Unknown Source)
at burp.wpb.a(Unknown Source)
at burp.wpb.a(Unknown Source)
at burp.ag.a(Unknown Source)
at burp.StartBurp.main(Unknown Source)

Anonymous said...

I am getting a similar error as some of the other posters:

Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong name: burp/BurpExtender)

Any idea what's causing this?

Anonymous said...

Same errors, no idea what to do - im no java developer but just want to write a simple plugin. No hope if i cant even get the example to run.

I just dont know what im doing wrong. :(

C:\Documents and Settings\Administrator\Desktop>java -Xmx512m -classpath burpext
ender.jar;burp.jar burp.StartBurp
Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong n
ame: burp/BurpExtender)
at java.lang.ClassLoader.defineClass1(Native Method)

Anonymous said...

I figured out how to fix the Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong name: burp/BurpExtender) error:

Place the BurpExtender.class file into the burp subdirectory and compile the jar with:

jar -cf burpextender.jar burp/BurpExtender.class

Then it works great for me!

Scott said...

I'm getting this error.

"c:\Program Files\Java\jdk1.6.0_26\bin\javac.exe" BurpExtender.java
BurpExtender.java:40: cannot find symbol
symbol : method ProcessHTMLComments(java.lang.String,java.lang.String,java.lang
.String)
location: class burp.BurpExtender
ProcessHTMLComments(new String(message), remoteHost, url);

Any ideas?

Scott said...

> I figured out how to fix the Exception in thread "main" java.lang.NoClassDefFoundError: BurpExtender (wrong name: burp/BurpExtender) error:

Place the BurpExtender.class file into the burp subdirectory and compile the jar with:

jar -cf burpextender.jar burp/BurpExtender.class

Tried that. Didn't work. Ideas?


User Forum

Get help from other users, at the Burp Suite User Forum:

Visit the forum ›

Copyright 2014 PortSwigger Ltd. All rights reserved.