burpference

<p align="center"> <img src="https://d1lppblt9t2x15.cloudfront.net/logos/5714928f3cdc09503751580cffbe8d02.png" alt="Logo" align="center" width="144px" height="144px" /> </p> <div align="center">

Experimenting with yarrr' Burp Proxy tab going brrrrrrrrrrrrr.

</div>

• burpference
  • Prerequisites
  • Project Structure
  • Setup Guide
    • 1. Download and Install Burp Suite
    • 2. Download and import Jython standalone JAR file
      • Steps to Download and Set Up Jython:
    • 3. Add the Burpference Extension to Burp Suite
      • Steps to Add the Extension:
    • 4. Setup your configs
      • Checkout the config docs:
    • 5. Additional options:
  • Development and known bugs:
  • Support the Project and Contributing
    • Star History

<br>

"burpference" started as a research idea of offensive agent capabilities and is a fun take on Burp Suite and running inference. The extension is open-source and designed to capture in-scope HTTP requests and responses from Burp's proxy history and ship them to a remote LLM API in JSON format. It's designed with a flexible approach where you can configure custom system prompts, store API keys and select remote hosts from numerous model providers as well as the ability for you to create your own API configuration. The idea is for an LLM to act as an agent in an offensive web application engagement to leverage your skills and surface findings and lingering vulnerabilities. By being able to create your own configuration and model provider allows you to also host models locally via Ollama to prevent potential high inference costs and potential network delays or rate limits.

Some key features:

• Automated Response Capture: Burp Suite acts as your client monitor, automatically capturing responses that fall within your defined scope. This extension listens for, captures, and processes these details with an offensive-focused agent.

• API Integration: Once requests and response streams are captured, they are packaged and forwarded to your configured API endpoint in JSON format, including any necessary system-level prompts or authentication tokens.

  • Only in-scope items are sent, optimizing resource usage and avoiding unnecessary API calls.
  • By default, certain MIME types are excluded.
  • Color-coded tabs display critical/high/medium/low/informational findings from your model for easy visualization.

• Scanner Analysis: A dedicated scanner tab provides focused security analysis capabilities:

  • Direct analysis of URLs and OpenAPI specifications
  • Load the configuration files using the API adapter, the same as usual in burpference for efficient management of API keys/model selection etc
  • Automated extraction of security headers and server information
  • Real-time security header assessment (X-Frame-Options, CSP, HSTS, etc.)
  • Custom system prompts for specialized analysis scenarios
  • Support for both single-endpoint and full domain scanning
  • Integration with Burp's native issue reporting system

• Comprehensive Logging: A logging system allows you to review intercepted responses, API requests sent, and replies received—all clearly displayed for analysis.

  • A clean table interface displaying all logs, intercepted responses, API calls, and status codes for comprehensive engagement tracking.
  • Stores inference logs in both the "Inference Logger" tab as a live preview and a timestamped file in the /logs directory.

• Native Burp Reporting: burpference' system prompt invokes the model to make an assessment based on severity level of the finding which is color-coded (a heatmap related to the severity level) in the extenstion tab.

  • Additionally, burpference "findings" are created as issues in the Burp Scanner navigation bar available across all tabs in the Burp UI.

• Flexible Configuration: Customize system prompts, API keys, or remote hosts as needed. Use your own configuration files for seamless integration with your workflow.

  • Supports custom configurations, allowing you to load and switch between system prompts, API keys, and remote hosts
    • Several examples are provided in the repository, and contributions for additional provider plugins are welcome.

• Flexible System Prompts: Specialized prompt templates for focused API security testing with some examples:

  • Authentication bypass and access control analysis
  • Sensitive data exposure and PII leakage detection
  • Injection vulnerability assessment across all vectors
  • Additional templates can be created for specific testing scenarios
    • Dynamic prompt switching during runtime to tailor analysis based on target endpoints

• Persistent Findings Storage: All security findings are automatically stored and tracked:

  • Findings are saved to logs/findings.json in a structured format (example below)
  • Each finding includes timestamp, severity, details, and affected URLs and persist across Burp Suite sessions
  • Findings are synchronized between Scanner and Proxy analysis

  [
    {
      "detail": "{u'<FINDING>'model': u'<provider>/<model>'}",
      "host": "www.evil.io",
      "name": "burpference: <SEVERITY> Security Finding",
      "severity": "<SEVERITY>",
      "timestamp": "2025-02-09T19:35:56.667000",
      "url": "https://www.evil.io:443/"
    }
  ]
  

<br> So grab yer compass, hoist the mainsail, and let **burpference** be yer guide as ye plunder the seven seas of HTTP traffic! Yarrr'!

---

Prerequisites

Before using Burpference, ensure you have the following:

1. Due to it's awesomeness, burpference may require higher system resources to run optimally, especially if using local models. Trust the process and make the machines go brrrrrrrrrrrrr!
2. Installed Burp Suite (Community or Professional edition).
3. Downloaded and set up Jython standalone .jar file (a Python interpreter compatible with Java) to run Python-based extensions in Burp Suite.
   1. You do not need Python2.x runtime in your environment for this to work.
4. The registerExtenderCallbacks reads a configuration file specific to the remote endpoint's input requirements. Ensure this exists in your environment and Burp has the necessary permissions to access it's location on the filesystem.
   1. Important: as Burp Suite cannot read from a filesystem's os environment, you will need to explicitly include API key values in the configuration .json files per-provider.
   2. If you intend to fork or contribute to burpference, ensure that you have excluded the files from git tracking via .gitignore.
   3. There's also a pre-commit hook in the repo as an additional safety net. Install pre-commit hooks here.
5. Setup relevant directory permissions for burpference to create log files:

chmod -R 755 logs configs

In some cases when loading the extension you may experience directory permission write issues and as such its recommended to restart Burp Suite following the above.

6. Ollama locally installed if using this provider plugin, example config and the model running locally - ie ollama run mistral-small (model docs).
   1. Ollama is now compatible with any HuggingFace GGUF model which expands the capabilities for using this provider plugin.
      1. There's a template config here for you to clone and add your own models.

---

Project Structure

/Users/ads/git/burpference/
├── burpference/                 # Main package directory
│   ├── __init__.py             # Package initialization
│   ├── api_adapters.py         # API providers and adapters
│   ├── assets/                 # Internal assets
│   │   └── squid_ascii.txt     # ASCII art for extension
│   ├── burpference.py          # Main extension code
│   ├── consts.py              # Constants and configurations
│   ├── db_manager.py          # Database operations
│   ├── issues.py              # Burp issue implementations
│   └── scanner.py             # Security scanner functionality
├── configs/                    # API configuration files
│   └── *.json                 # JSON config files per provider
├── logs/                      # Log output directory
│   ├── findings.json          # Security findings database
│   └── *.txt                  # Generated log files
├── prompts/                   # Prompt template files
│   ├── proxy_prompt.txt       # Default proxy analysis prompt
│   ├── scanner_prompt.txt     # Scanner analysis prompt
│   └── openapi_prompt.txt     # OpenAPI anal