Burp Suite Python Extension

⚠️ ARCHIVED PROJECT: This project is now archived because Python extensions are now natively supported by Burp Suite. This was the first implementation enabling Python extensions with Burp Suite, originally created in August 2010.

A Python binding for Burp Suite that allows you to write extensions in Python using the same IBurpExtender interface available in Java.

Overview

This extension leverages Jython (the Java implementation of Python) to bridge Python code with Burp Suite's Java-based extension API. The project consists of a Java wrapper (BurpExtender.java) that dynamically loads and executes Python extensions, making it possible to write Burp extensions in Python while maintaining full compatibility with the standard IBurpExtender interface.

If you've written Burp extensions in Java, you already know how to write them in Python - the interface is identical.

Historical Significance

Created by David Robert in 2010, this was the first implementation of Python extension support for Burp Suite. Several security companies adopted this extension for their security testing workflows, and numerous tools (both internal and public) were built on top of this foundation. The success of this project demonstrated the value of Python extensibility and influenced Burp Suite's decision to implement native Python support.

Why Python?

Dynamically typed languages like Python are highly efficient for creating small, task-specific automation code quickly. Python's rich ecosystem of libraries and its interactive REPL make it ideal for web application security testing, where you often need to rapidly develop custom code tailored to specific applications or vulnerabilities.

Architecture

Project Structure

burp-python/
├── burppython.jar           # Compiled JAR containing Jython and Java wrapper
├── suite.bat / suite.sh     # Launch scripts for Windows/Unix
├── Lib/                     # Python extensions directory
│   └── BurpExtender.py      # Your Python extension goes here
├── src/                     # Java source code
│   ├── BurpExtender.java    # Java wrapper that loads Python extensions
│   └── burp/                # Burp Suite API interfaces
│       ├── IBurpExtender.java
│       ├── IBurpExtenderCallbacks.java
│       ├── IHttpRequestResponse.java
│       ├── IMenuItemHandler.java
│       ├── IScanIssue.java
│       └── IScanQueueItem.java
└── examples/                # Example Python extensions
    ├── BurpExtender-minimal.py
    ├── BurpExtender-interactive.py
    ├── BurpExtender-menu.py
    └── BurpExtender-w3af.py

How It Works

1. Java Wrapper: BurpExtender.java acts as a bridge, implementing the Burp Suite IBurpExtender interface in Java
2. Jython Integration: The wrapper initializes a Jython interpreter and loads BurpExtender.py from the Lib folder
3. Dynamic Introspection: The Java wrapper uses Python introspection to detect which methods the Python extension implements
4. Method Delegation: When Burp Suite calls extension methods, the Java wrapper delegates these calls to the corresponding Python methods
5. Transparent Operation: From Burp Suite's perspective, it's loading a standard Java extension; from the developer's perspective, they're writing pure Python

Features

• Write Burp Suite extensions in Python instead of Java
• Use the same IBurpExtender interface you're familiar with from Java
• Embed an interactive Python interpreter for real-time message inspection and manipulation
• Add custom menu items to Burp Suite's contextual menus
• Access to all Burp Suite callback functions (IBurpExtenderCallbacks)
• Partial implementation support - only implement the methods you need
• Full access to Python's standard library and any compatible Jython libraries

Requirements

• Burp Suite (Free or Professional version)
  • Professional version required for some features (e.g. custom menu items (minimum v1.3.07))
• burppython.jar (includes embedded Jython interpreter)
• Java Runtime Environment (compatible with your Burp Suite version)

Note: No separate Python or Jython installation is needed - everything is bundled in burppython.jar.

Installation

1. Clone or download this repository to a dedicated folder
2. Copy your Burp Suite JAR file into the project root folder
   • Example: burpsuite_pro_v1.3.07.jar or burpsuite_v1.3.03.jar
3. Update the launch script to match your Burp Suite JAR filename:
   • Edit suite.sh (Linux/Mac) or suite.bat (Windows)
   • Change burpsuite_v1.3.03.jar to your actual filename
4. Place your Python extension in the Lib subfolder:
   • Your extension must be named BurpExtender.py
   • See examples/ folder for templates
5. Launch Burp Suite using the appropriate script:
   • Linux/Mac: ./suite.sh
   • Windows: suite.bat

Quick Start

1. Minimal Extension

Create Lib/BurpExtender.py with this minimal example:

from burp import IBurpExtender

class BurpExtender(IBurpExtender):

    def processProxyMessage(self, messageReference, messageIsRequest, remoteHost, remotePort,
                            serviceIsHttps, httpMethod, url, resourceType, statusCode,
                            responseContentType, message, interceptAction):
        if not messageIsRequest:
            # Simple string replacement in responses
            message = message.tostring().replace("java", "python")
        return message

This simple extension intercepts all HTTP responses and replaces "java" with "python".

2. Launch Burp Suite

Run the launch script:

# Linux/Mac
./suite.sh

# Windows
suite.bat

When Burp Suite starts, you should see output confirming the Python extension loaded:

BurpExtender.py needs to be in a folder listed below:
['/path/to/burp-python/Lib', ...]

Available Extension Methods

Your Python BurpExtender class can implement any of these methods from the IBurpExtender interface:

Core Methods

• processProxyMessage(...) - Intercept and modify HTTP messages passing through Burp Proxy
• processHttpMessage(toolName, messageIsRequest, messageInfo) - Process HTTP messages from any Burp tool
• registerExtenderCallbacks(callbacks) - Receive callback object to interact with Burp Suite
• newScanIssue(issue) - Receive notifications when Scanner finds new issues
• setCommandLineArgs(args) - Receive command-line arguments passed to Burp Suite
• applicationClosing() - Perform cleanup when Burp Suite is closing

Note: You only need to implement the methods you actually use. The Java wrapper uses introspection to detect which methods are available and only delegates calls to implemented methods.

Example Extensions

The examples/ folder contains four complete example extensions demonstrating different capabilities:

1. BurpExtender-minimal.py

Purpose: Basic string replacement
Use Case: Learning the basic extension structure

Simple extension that replaces "java" with "python" in all HTTP responses. Great starting point for understanding the processProxyMessage method.

2. BurpExtender-interactive.py

Purpose: Interactive Python REPL for message inspection
Use Case: Real-time debugging and analysis

Launches an interactive Python console when responses are intercepted (for in-scope URLs only), allowing you to:

• Inspect all method parameters interactively
• Modify messages in real-time using Python REPL
• Test transformations before committing them to code
• Access pprint for pretty-printing data structures

3. BurpExtender-menu.py

Purpose: Custom context menu items
Use Case: Parameter comparison and analysis
Requires: Burp Suite Professional v1.3.07+

Adds a "python diff" menu item to compare GET and POST parameters between two selected requests. Demonstrates:

• Registering custom menu items
• Implementing IMenuItemHandler
• Parsing HTTP requests and extracting parameters
• Comparing request structures

4. BurpExtender-w3af.py

Purpose: Integration with w3af security framework
Use Case: Leveraging existing Python security tools

Integrates w3af (Web Application Attack and Audit Framework) plugins with Burp Suite, allowing you to:

• Use w3af's grep plugins to analyze responses
• Apply w3af's evasion plugins to requests
• Combine Burp Suite's proxy capabilities with w3af's vulnerability detection

See the examples/README.md for detailed documentation on each example.

Example: Custom Menu Item

Here's a complete example adding a parameter comparison menu item:

from burp import IBurpExtender, IMenuItemHandler
from cgi import parse_qs

class BurpExtender(IBurpExtender):
    def registerExtenderCallbacks(self, callbacks):
        self.mCallBacks = callbacks
        # Register a custom menu item
        self.mCallBacks.registerMenuItem("Compare parameters", ArgsDiffMenuItem())

class ArgsDiffMenuItem(IMenuItemHandler):
    def menuItemClicked(self, menuItemCaption, messageInfo):
        print "--- Parameter Comparison ---"
        if len(messageInfo) == 2:
            request1 = HttpRequest(messageInfo[0].getRequest())
            request2 = HttpRequest(messageInfo[1].getRequest())
            print "Diff in GET parameters:"
            self.diff(request1.query_params, request2.query_params)
            print "Diff in POST parameters:"
            self.diff(request1.body_params, request2.body_params)
        else:
            print "You need to select two messages to do a comparison"
        print "\n\n"

    def diff(self, params1, params2):
        for param in params1:
            if param not in params2:
                print "Param %s=%s is missing in second request" % (param, params1[param])
            elif params1[param] != params2[param]:
                print "Request1 %s=%s | Request2 %s=%s" % \
                      (param, params1[param], param, params2[param])
        for param in params2:
            if param not in params1:
                print "Param %s=%s is missing in first request" % (param, params2[param])

API Reference

IBurpExtenderCallbacks Methods

When you implement registerExtenderCallbacks(callbacks), you receive a callbacks object with these methods:

• makeHttpRequest(host, port, useHttps, request) - Issue arbitrary HTTP requests
• sendToRepeater(host, port, useHttps, request, tabCaption) - Send requests to Repeater tool
• sendToIntruder(host, port, useHttps, request) - Send requests to Intruder tool
• sendToSpider(url) - Add URLs to Spider queue
• doActiveScan(host, port, useHttps, request) - Perform active vulnerability scans
• isInScope(url) - Check if URL is in current scope
• registerMenuItem(caption, handler) - Register custom context menu items
• getHeaders(message) - Extract headers from HTTP message
• getBody(message) - Extract body from HTTP message

Message Processing

HTTP messages are passed as byte[] arrays. Convert to strings using:

message_string = message.tostring()

To return modified messages, convert back to bytes or return as string (Jython handles conversion).

Configuration

Launch Scripts

The launch scripts (suite.sh and suite.bat) configure the classpath and start Burp Suite:

Linux/Mac (suite.sh):

java -Xmx512m -classpath burpsuite_v1.3.03.jar:burppython.jar burp.StartBurp

Windows (suite.bat):

java -Xmx512m -classpath burpsuite_v1.3.03.jar;burppython.jar burp.StartBurp

Important: Update the JAR filename to match your Burp Suite version.

Memory Settings

The -Xmx512m flag allocates 512MB of heap memory. Increase this for larger workloads:

java -Xmx1024m -classpath burpsuite_v1.3.03.jar:burppython.jar burp.StartBurp

Usage Tips

Scope Configuration

• Configure scope in Burp Suite's Target > Scope tab
• Use callbacks.isInScope(url) to respect scope settings in your extensions
• This prevents your extension from processing every intercepted message

Debugging

• Python print statements output to the terminal where you launched Burp Suite
• Use pprint for pretty-printing complex data structures
• The interactive console example (BurpExtender-interactive.py) is excellent for debugging

Extension Development Workflow

1. Start with BurpExtender-minimal.py as a template
2. Implement only the methods you need
3. Test incrementally using print statements
4. Use the interactive console for rapid prototyping
5. Restart Burp Suite to reload modified extensions

Common Pitfalls

• Extension must be named BurpExtender.py and located in the Lib folder
• The class must be named BurpExtender and implement IBurpExtender
• Python 2 syntax (this was created in 2010, uses Jython 2.x)
• Modifications require restarting Burp Suite (no hot reload)

Troubleshooting

Extension Not Loading

Check the terminal output when Burp Suite starts. You should see:

BurpExtender.py needs to be in a folder listed below:

If you see import errors, verify:

1. BurpExtender.py is in the Lib folder
2. The file is named exactly BurpExtender.py (case-sensitive)
3. The class is named BurpExtender

Method Not Being Called

The Java wrapper uses Python introspection to detect available methods. If your method isn't being called:

1. Verify the method signature matches the IBurpExtender interface exactly
2. Check for typos in the method name
3. Ensure proper indentation (Python requirement)

Import Errors

Jython has limited compatibility with CPython libraries. If you encounter import errors:

1. Use Java libraries instead (accessible via Jython)
2. Check Jython compatibility of the Python library
3. Consider bundling pure-Python libraries in the Lib folder

Limitations

• Jython 2.x: Uses Python 2 syntax (not Python 3)
• Single Extension: Only one BurpExtender.py can be loaded at a time
• No Hot Reload: Modifications require restarting Burp Suite
• Library Compatibility: Limited to Jython-compatible libraries
• Performance: Slight overhead from Java-Python bridge

Project History

Created: August 30, 2010
Author: David Robert (castlebbs)
Original Blog: http://blog.ombrepixel.com/ (Discontinued)

This project was developed when Burp Suite had no official Python support. It demonstrated the feasibility and value of Python extensions, which eventually influenced PortSwigger's decision to add native Python support to Burp Suite.

Several security companies adopted this extension for their testing workflows, and it served as the foundation for numerous custom security tools. The project represents an important milestone in the evolution of Burp Suite's extensibility.

License

This code is provided for use with Burp Suite and Burp Suite Professional, subject to the license terms for those products. The Burp Suite API interfaces (src/burp/*.java) are copyright PortSwigger Ltd.

Contact & Support

Author: David Robert
Email: david@ombrepixel.com

Modern Alternatives

⚠️ Important: For new projects, use Burp Suite's native Python extension support instead of this project. This repository is maintained for historical reference and legacy purposes only.

Modern Burp Suite versions include:

• Native Python 3 support
• Better performance and integration
• Extensive official documentation
• Active maintenance and updates
• Support for multiple extensions simultaneously

Contributing

While this project is now archived, contributions for documentation improvements or historical accuracy are welcome. Please note that no new features will be added, as this project has been superseded by Burp Suite's native Python support.

---

Archived Project Notice: This repository is maintained for historical purposes and as a reference implementation. For active development, please use Burp Suite's native Python extension capabilities.