<h1 align="center">reburp</h1>
<p align="center">
<img src="static/reburp.svg" alt="reburp" title="reburp" width="200">
</p>
<p align="center">
<b>Burp's API/MCP is LIMITED - reburp is a Burp Suite extension that exposes the full Montoya API as a locally served openapi REST API, optimized for your AI agents.</b>
</p>
<p align="center">
<a href="https://github.com/forefy/reburp/releases/"><img alt="reburp releases" title="reburp releases" src="https://img.shields.io/github/release/forefy/reburp"></a>
<a href="https://github.com/forefy/reburp/actions/workflows/build.yml"><img alt="Build" title="Build" src="https://img.shields.io/github/actions/workflow/status/forefy/reburp/build.yml"></a>
<img alt="reburp code size" title="reburp code size" src="https://img.shields.io/github/languages/code-size/forefy/reburp">
<img alt="reburp commit activity" title="reburp commit activity" src="https://img.shields.io/github/commit-activity/m/forefy/reburp">
<img alt="GitHub last commit" title="GitHub last commit" src="https://img.shields.io/github/last-commit/forefy/reburp">
<a href="https://github.com/forefy/reburp/issues/new/choose"><img alt="Issues" title="Issues" src="https://img.shields.io/github/issues-raw/forefy/reburp"></a>
<a href="https://twitter.com/forefy"><img alt="Forefy Twitter" title="Forefy Twitter" src="https://img.shields.io/twitter/follow/forefy.svg?logo=twitter"></a>
</p>
<p align="center">
<a href="https://github.com/forefy/reburp/issues/new/choose" title="reburp Issues">Issues</a>
| <a href="https://github.com/forefy/reburp/discussions" title="reburp Discussions">Discussions</a>
</p>
## What is reburp
reburp turns Burp Suite into something you can script. It loads as a Java extension and serves
the [Montoya API](https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html)
over an HTTP REST API on `http://127.0.0.1:9090`, with an OpenAPI spec and Swagger UI. Anything
you would click in Burp - reading proxy history, sending a request, editing scope, running a
scan, decoding a token - becomes a JSON call an agent or a `curl` line can make.
It pairs with the [`burp-interaction`](.claude/skills/burp-interaction) agent skill so an AI
assistant can drive Burp directly.
- [What reburp unlocks](#what-reburp-unlocks)
- [Install](#install)
- [Load into Burp Suite](#load-into-burp-suite)
- [API docs](#api-docs)
- [Endpoints](#endpoints)
- [Quick start](#quick-start)
- [Security](#security)
- [API coverage](#api-coverage)
- [Notes](#notes)
- [Contributing](#contributing)
## What reburp unlocks
Burp features your agent can now drive over REST:
- **Scanner** - start an active audit or crawl, stop a running task, pull the report
- **Intruder & request engine** - fuzz, plus a Turbo Intruder-style high-throughput engine (queue, pause, resume, cancel)
- **Target site map** - iterate and search the whole target tree, not just proxy history
- **WebSockets** - open a connection and send text/binary frames, not just read history
- **Engagement tools** - generate a CSRF PoC, discover content, find references, send to decoder
- **Access-control testing** - replay a request with and without its token and diff the responses, Autorize-style (BOLA/BFLA)
- **BChecks & Bambda** - import custom scan rules, build filter chains, raise custom issues
- **The Burp window itself** - screenshot it, switch tabs (including extension sub-tabs), and click, type into or select any visible element, context menu or dialog over REST, with no OS accessibility or screen capture needed
## Install
Grab the latest `reburp-*.jar` from [Releases](https://github.com/forefy/reburp/releases), or
build it from source (requires Java 17+).
### Compatibility
Each reburp release is built against a minimum Burp Suite (Montoya) version. On an older Burp,
grab the matching jar from [Releases](https://github.com/forefy/reburp/releases).
| reburp | Minimum Burp Suite (Montoya) |
|--------|------------------------------|
| [1.1.15](https://github.com/forefy/reburp/releases/tag/v1.1.15) | 2026.7 |
| [1.1.14](https://github.com/forefy/reburp/releases/tag/v1.1.14) | 2026.7 |
| [1.1.13](https://github.com/forefy/reburp/releases/tag/v1.1.13) | 2026.7 |
| [1.1.12](https://github.com/forefy/reburp/releases/tag/v1.1.12) | 2026.7 |
| [1.1.11](https://github.com/forefy/reburp/releases/tag/v1.1.11) | 2026.7 |
| [1.1.10](https://github.com/forefy/reburp/releases/tag/v1.1.10) | 2026.7 |
| [1.1.9](https://github.com/forefy/reburp/releases/tag/v1.1.9) | 2026.7 |
| [1.1.8](https://github.com/forefy/reburp/releases/tag/v1.1.8) | 2026.7 |
| [1.1.7](https://github.com/forefy/reburp/releases/tag/v1.1.7) | 2026.7 |
| [1.1.6](https://github.com/forefy/reburp/releases/tag/v1.1.6) | 2026.7 |
| [1.1.5](https://github.com/forefy/reburp/releases/tag/v1.1.5) | 2026.7 |
| [1.1.4](https://github.com/forefy/reburp/releases/tag/v1.1.4) | 2026.7 |
| [1.1.3](https://github.com/forefy/reburp/releases/tag/v1.1.3) | 2026.7 |
| [1.1.2](https://github.com/forefy/reburp/releases/tag/v1.1.2) | 2026.7 |
| [1.1.1](https://github.com/forefy/reburp/releases/tag/v1.1.1) | 2026.7 |
| [1.1.0](https://github.com/forefy/reburp/releases/tag/v1.1.0) | 2026.7 |
| [1.0.x](https://github.com/forefy/reburp/releases/tag/v1.0.1) | 2025.12 |
### Build from source
```bash
git clone https://github.com/forefy/reburp.git
cd reburp
./gradlew shadowJar
# Output: build/libs/reburp.jar (plus a versioned copy, reburp-<version>.jar)
```
Load `reburp.jar` rather than the versioned copy. Burp reloads an extension from the path
it was loaded from, and the versioned name changes on every release, so the unversioned one
keeps reloading after an upgrade instead of quietly leaving you on the previous build.
If your `JAVA_HOME` isn't set, point it at your JDK:
```bash
JAVA_HOME=/path/to/jdk17 ./gradlew shadowJar
```
## Load into Burp Suite
1. Open Burp Suite → **Extensions** → **Installed** → **Add**
2. Extension type: **Java**
3. Extension file: `build/libs/reburp.jar` (or the `reburp-*.jar` you downloaded from Releases)
4. Click **Next** - the extension starts automatically on port **9090**
A **reburp** tab appears in Burp showing every REST call as it happens.
<p align="center">
<img src="static/reburp-in-action.png" alt="The reburp tab in Burp Suite: an API Log of GET, POST and DELETE calls with method, status, timing, target host, path and AI notes; a filter bar with a field selector, a Bodies option, an In scope only toggle and an Export button; and the selected call's target request and response below" title="reburp in action" width="700">
</p>
Each row is one REST call. Selecting it shows the API request and response, plus the request
and response reburp sent to the target on your behalf.
- **Host column** - the target each call reached, next to its path
- **Filter** - a case insensitive match against Host + Path, a single column, or every column;
tick **Bodies** to also search the raw requests and responses
- **In scope only** - keep the rows whose target is in Burp's scope
- **Export** - save the rows on screen as a self-contained HTML report or a CSV file. Exports
contain any cookies and tokens in the logged traffic
- **Send to Repeater / Intruder** - right-click a row, or use Burp's own menu inside the request
panes; the target host and port are already filled in
## API docs
Once loaded, open in your browser:
- **Swagger UI**: http://127.0.0.1:9090/docs
- **OpenAPI spec**: http://127.0.0.1:9090/openapi.json
The spec is the source of truth for request and response shapes.
## Endpoints
| Group | Prefix | Highlights |
|-------|--------|------------|
| Status | `/api/status` | Extension info, Burp version |
| Proxy | `/api/proxy/` | History, search, annotate, intercept toggle, WebSocket history |
| Site Map | `/api/sitemap/` | List, search |
| Scope | `/api/scope/` | Check URL in scope, add/remove scope rules |
| HTTP | `/api/http/` | Send HTTP/1.1 & HTTP/2, auth-token injection, parse, diff, params, reflection, insertion points, cookies |
| Messages | `/api/http/message/` | Inspect and rewrite requests and responses: headers, parameters, markers, MIME types, timing |
| Scanner | `/api/scanner/` | Issues, start audit/crawl, task status (Pro only) |
| Collaborator | `/api/collaborator/` | Generate payloads, poll interactions (Pro only) |
| Repeater / Intruder | `/api/repeater/`, `/api/intruder/` | Send requests to Repeater and Intruder |
| Request Engine | `/api/http/engine/` | High-throughput async request engine: resource pools, concurrency limit, throttle, retries, live stats, pause/resume/cancel, results (Burp 2026.x) |
| Config | `/api/config/` | Get/set project & user options, task engine state |
| Match & Replace | `/api/proxy/match-replace/` | List, add, remove proxy match-and-replace rules |
| Sessions | `/api/sessions/` | List and delete session-handling rules (Burp has no add-header action) |
| Engagement | `/api/engagement/` | CSRF PoC generator, content discovery, find references, send to decoder |
| Bambda | `/api/bambda/` | Import Bambda scripts, generate filter chains |
| Organizer | `/api/organizer/` | List items, send requests to the Organizer |
| Issues | `/api/issues/` | Create custom audit issues |
| Events | `/api/events/` | Turn passive traffic observers on and off, then read the captured events |
| Extension Data | `/api/extension-data/` | Typed key/value storage held in the Burp project file |
| Preferences | `/api/preferences/` | Persisted extension preferences by type |
| Logging | `/api/logging/` | Write to the extension output and error tabs and Burp's event log |
| Activity Log | `/api/log/` | Query reburp's own persisted call log |
| AI | `/api/ai/` | Burp AI status and chat (where available) |
| Meta | `/api/meta/` | Burp version components, extension load info, enum vocabularies |
| UI | `/api/ui/` | Screenshot windows or elements, list and switch tabs (nested too), inventory every visible element, click, type, select and send keys |
| Utilities | `/api/utils/` | URL encode/decode, base64, hash, JWT decode, random string, decompress |
| Numbers | `/api/utils/number/` | Convert between binary, octal, decimal, hex and arbitrary radixes |
| JSON | `/api/utils/json/` | Validate, read and edit by pointer, inspect structure, normalise |
| Bytes | `/api/utils/bytes/` | Search, slice, append, allocate and inspect byte buffers |
| Ranking | `/api/utils/rank` | Rank proxy history by how anomalous each exchange looks |
| Shell | `/api/utils/shell/` | OS command execution. Disabled by default, see [Security](#security) |
## Quick start
```bash
# Is the extension up?
curl -s http://127.0.0.1:9090/api/status
# Last 10 proxy entries
curl -s "http://127.0.0.1:9090/api/proxy/history?limit=10"
# Send a request through Burp
curl -s http://127.0.0.1:9090/api/http/send \
-H 'Content-Type: application/json' \
-d '{"host":"example.com","port":443,"use_https":true,"method":"GET","path":"/"}'
# Add a host to scope
curl -s http://127.0.0.1:9090/api/scope/include \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com"}'
```
## Security
The REST server binds **`127.0.0.1` only**, but the port is **unauthenticated** and responds to
**any origin**. Anything that can reach `localhost:9090` can drive Burp, including a web page
open in your browser. Treat the port as trusted-local-only and never expose it beyond loopback.
Because of that, OS command execution is **off by default**. `/api/utils/shell/execute` and
`/api/utils/shell/execute-raw` return `403` unless the extension sees this in Burp's own process
environment:
```bash
REBURP_ENABLE_SHELL=1
```
With it set, any origin that can reach the port gets remote code execution on the host. Enable it
only when you accept that. Every invocation is written to the extension output tab.
`GET /api/utils/shell/status` reports whether it is on and never requires it to be.
## API coverage
The "full Montoya API" claim is verified mechanically by [`tools/api_coverage.py`](tools/api_coverage.py),
which the CI [build workflow](.github/workflows/build.yml) runs on every push and fails if any mappable
method is left unexposed. Behaviour is exercised separately by `tools/smoke_test.py` against a loaded extension.
## Notes
- **Port** is hardcoded to `9090`. Change `port` in `BurpRestApiExtension.kt` and rebuild if needed.
- **Pro-only endpoints** (scanner, collaborator) return HTTP 403 on Community edition with an explanatory message.
- **Montoya API** is `compileOnly` - it is not bundled; Burp provides it at runtime.
- All responses are JSON. Errors return `{ "error": "..." }`.
- **OpenAPI spec** is assembled from `OpenApiSpec.kt` plus fragments in `docs/`. To add a route
group, write a `*Paths()` and `*Schemas()` fragment and list it in `docs/OpenApiSpecExtra.kt`.
## Contributing
Issues and pull requests are welcome. Please run `python3 tools/api_coverage.py` and
`./gradlew shadowJar` before opening a PR. New route groups should ship with their OpenAPI fragment
so the docs stay complete.