BurpSuiteMcp

<div align="center"> <h1>BurpSuiteMcp</h1> <p><strong>English</strong>&nbsp;|&nbsp;<a href="README_CN.md">简体中文</a></p> <p> <a href="https://github.com/AJings3c/BurpSuiteMcp/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/AJings3c/BurpSuiteMcp"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="pom.xml"><img alt="Java 17+" src="https://img.shields.io/badge/Java-17%2B-orange.svg"></a> </p> </div> A local-first Burp Suite MCP extension that exposes HTTP, WebSocket, Scanner, and Collaborator/OAST capabilities to AI clients over authenticated Stateful Streamable HTTP—while showing exactly what the AI called, sent, and received inside Burp. ## Why BurpSuiteMcp Many Burp MCP integrations focus only on letting an AI call tools. They do not give the operator a clear view of what the AI actually did. BurpSuiteMcp treats observability and operator control as first-class features: - **Native Streamable HTTP**: built on the official MCP Java SDK 2.0.0, without legacy HTTP+SSE or in-process stdio. - **Complete in-Burp auditing**: records the input, actual output, status, duration, related artifacts, active requests, and asynchronous events for every tool/resource call. - **Operator-controlled capabilities**: active HTTP, Active WebSocket, Collaborator/OAST, and Active Scanner are disabled by default and can only be enabled in the local Burp UI. - **On-demand evidence access**: raw messages are exposed through bounded artifact/resource chunks instead of flooding the AI context with complete histories. - **Secure defaults**: listens only on `127.0.0.1`, authenticates every request with a Bearer Token, restricts access to the Burp suite scope, and redacts sensitive data by default. ## Quick Installation ### Option 1: Download a Release 1. Download `burp-suite-mcp.jar` from [GitHub Releases](https://github.com/AJings3c/BurpSuiteMcp/releases). 2. In Burp Suite, open `Extensions` → `Installed` → `Add`. 3. Select `Java` as the extension type and load the downloaded JAR. 4. Open Burp's `MCP` tab and confirm that the server status is running. 5. Copy the displayed `MCP address` and `Bearer token`. ### Option 2: Build from Source JDK 17 or later is required. The repository includes Maven Wrapper, so a system Maven installation is not needed. Windows PowerShell: ```powershell .\mvnw.cmd clean verify ``` Linux/macOS: ```bash chmod +x mvnw ./mvnw clean verify ``` The loadable extension is generated at: ```text target/burp-suite-mcp.jar ``` ## Configure an MCP Client Use the following connection settings: | Field | Value | |---|---| | Transport | `Streamable HTTP` | | URL | `http://127.0.0.1:9876/mcp` | | Header | `Authorization: Bearer <token from Burp's MCP tab>` | Clients that support remote/HTTP MCP servers generally accept an equivalent configuration: ```json { "mcpServers": { "burp-suite-mcp": { "url": "http://127.0.0.1:9876/mcp", "headers": { "Authorization": "Bearer REPLACE_WITH_TOKEN_FROM_BURP" } } } } ``` The top-level field may be named `servers`, `mcpServers`, or represented by a GUI form, depending on the client. The URL, Streamable HTTP transport, and Authorization header must remain the same. Do not select `SSE` or `stdio`. After connecting, call: ```text server_status ``` A successful response includes `RUNNING`, the endpoint, version, and current concurrency state. > Never commit the real Bearer Token to Git or expose it in public issues, screenshots, or shared configuration. The extension generates it randomly and stores it in Burp user-level preferences. ### Common Connection Problems - `401 Unauthorized`: verify that the header exists, includes the `Bearer ` prefix, and does not contain an old token. - `403 Forbidden`: the request contains a browser Origin or a Host outside the local allowlist. Do not connect directly from ordinary web-page JavaScript. - Connection refused: make sure Burp is running, the extension is loaded, the server was not stopped manually, and local port `9876` is available. - Active tools are missing: enable the corresponding operator switch in Burp's `MCP` tab and confirm that the current Burp Edition supports the capability. - Only redacted data is returned: switch the data profile to `FULL_FIDELITY` and confirm that the target is inside the current suite scope. ## Default Permission Model The extension starts with the following safe defaults: | Setting | Default | Effect | |---|---|---| | Data profile | `REDACTED` | Returns usable evidence while masking common passwords, tokens, cookies, and other secrets | | Data scope | `SUITE_SCOPE_ONLY` | Allows access only to targets in the current Burp suite scope | | Active HTTP | Disabled | Prevents the AI from sending active HTTP requests | | Active WebSocket | Disabled | Prevents the AI from creating or sending WebSocket sessions | | Collaborator/OAST | Disabled | Prevents the AI from creating or polling Collaborator clients | | Active Scanner | Disabled | Prevents the AI from starting Burp Scanner audits | | Cross-restart audit persistence | Disabled | Keeps audit data in the current Burp process only | To read exact raw bytes, the local operator can switch the data profile to `FULL_FIDELITY`. Before enabling an active capability, add the target to Burp's suite scope and then enable only the required switch. AI-provided fields such as `force` or `unsafe` cannot bypass these local policies. ## Capability Overview ### HTTP and Evidence - `proxy_history_list`: search and page through Proxy history. - `site_map_list` / `site_map_get`: search the Site map and obtain complete HTTP evidence. - `operator_selection_list` / `operator_selection_get`: read HTTP messages explicitly exposed through Burp's context menu. - `http_exchange_get` / `http_exchange_search`: read or search requests, responses, headers, bodies, and timing information. - `artifact_read`: read artifacts or raw byte chunks for clients that do not support MCP resources. - `http_send`: send a raw HTTP request while retaining a complete active-request audit trail. - `http_timing_compare`: interleave baseline/probe samples and compare TTFB or complete-response timing. ### WebSocket - `websocket_history_list` / `websocket_message_get`: read Proxy WebSocket history. - `websocket_connect` / `websocket_send`: create active sessions and send text or binary frames. - `websocket_receive` / `websocket_session_status` / `websocket_close`: receive incrementally, inspect, and close sessions. ### Scanner - `scanner_issue_list` / `scanner_issue_get`: read Scanner issues, markers, HTTP evidence, and linked OAST interactions. - `scanner_audit_list` / `scanner_audit_start` / `scanner_audit_status` / `scanner_audit_cancel`: manage Professional active-audit tasks. ### Collaborator/OAST - `collaborator_create` / `collaborator_generate_payload`: create temporary client handles and correlated payloads without exposing secret keys. - `collaborator_poll` / `collaborator_wait`: incrementally obtain DNS, HTTP, and SMTP interactions. ### MCP Resources Structured evidence and raw bytes use a unified set of `burp://` resources: ```text burp://artifact/{artifactId} burp://artifact/{artifactId}/{side}/raw/{offset}/{length} burp://artifact/{artifactId}/body/{side}/{offset}/{length} ``` EvidenceStore uses a 30-minute TTL, a maximum of 500 artifacts, and a 256 MiB total budget by default. Artifact IDs are non-enumerable random values bound to the current Bearer principal. ## AI Activity Auditing Burp's `MCP` tab contains three workspaces: - **Server overview**: server state, endpoint, token, data profile, scope, and active-capability switches. - **MCP call log**: each call moves from running to succeeded/failed, with complete input, actual output, related activity, and asynchronous events. - **AI request log**: separately shows active HTTP requests, responses, status, timing, and source calls, with actions for sending to Repeater or adding to the Site map. Sensitive values are masked only at the display layer by default; the local operator can explicitly reveal the complete content. Optional cross-restart auditing derives an AES-256-GCM key from the current Bearer Token and stores the encrypted journal at: ```text ~/.burpsuitemcp/audit-v1.enc ``` The server can only audit tool/resource calls that the client actually sends over MCP. It cannot see conversations, reasoning, or plans that remain internal to the AI client. ## Burp Edition Support | Capability | Community | Professional | |---|:---:|:---:| | Proxy/Site map HTTP evidence | ✅ | ✅ | | Operator selection | ✅ | ✅ | | Active HTTP and timing comparison | ✅ | ✅ | | WebSocket history / Active WebSocket | ✅ | ✅ | | Scanner issues / Active Scanner | — | ✅ | | Collaborator/OAST | — | ✅ | Tools that are unavailable in the current Edition are not registered, instead of returning ambiguous errors on every call. ## Security Boundaries - The listener is fixed to `127.0.0.1`; `0.0.0.0`, remote binding, and built-in TLS are not supported. - Every GET, POST, and DELETE request must include the same Bearer Token. - Host is restricted to local addresses and ordinary browser Origins are rejected; wildcard CORS is never enabled. - Active HTTP, WebSocket, and Scanner actions re-check the suite scope at execution time and block the extension's own MCP listener as a target. - Complete inputs, outputs, and raw traffic may contain sensitive data. Enable `FULL_FIDELITY` and persistent auditing carefully. Do not open a public issue for an unpatched security vulnerability. Use GitHub Private Vulnerability Reporting instead. ## Current Limitations - Legacy HTTP+SSE and built-in stdio transports are not provided. - The Montoya Repeater API cannot read the current tab. In Repeater, Proxy, Site map, or an HTTP message editor, use the `Expose selected HTTP message(s) to MCP` context-menu action. - Scanner status events are recorded when a task is created, queried, canceled, expired, or evicted. The extension does not continuously poll Burp Scanner just for auditing. - Per-call approval, audit-file import/export, and complete MCP progress/cancellation integration are not implemented yet. ## Technology and Development Verification - Java 17+ - Burp Montoya API `2025.10` with `provided` scope - MCP Java SDK `2.0.0` - Embedded Tomcat `11.0.24` - Maven Wrapper `3.9.11` - JUnit + ArchUnit Run the complete verification suite before submitting code: ```powershell .\mvnw.cmd clean verify ``` The test suite covers MCP initialization, tools/resources, Bearer/Host/Origin security checks, EvidenceStore, active HTTP/WebSocket, Scanner, OAST, complete call auditing, and architecture dependency boundaries. ## License BurpSuiteMcp is available under the [MIT License](LICENSE).