Content
# Burp MCP Bridge
> Bridge 33 capabilities of Burp Suite (26 core + 7 Phase 3 advanced tools) to AI clients through MCP protocol, enabling agents like `@burp-suite-arsenal` to fully utilize Burp's arsenal.
*Complete end-to-end testing see [docs/demo-phase3.md](docs/demo-phase3.md) — 32/33 tools real call PASS. ZCode is a command-line IDE that cannot directly take screenshots, and the document contains Mermaid architecture diagrams + real JSON output.*
## ✨ Core Features
### 🔌 Bridging Official Burp Suite MCP 27 Tools Gap
The official `burp-mcp-all.jar` (PortSwigger official) can only expose Burp core (Proxy/Repeater/Intruder/Scanner/Collaborator), **but not third-party plugins from BApp store**. This project actively reads plugin annotations/logs/discoveries through Montoya API to fill this gap.
### 🎯 33 Differentiated Tools (26 core + 7 Phase 3 advanced)
| Category | Tool | Bridged Burp Plugin / Capability |
|------|------|--------------------------|
| **Shiro** | `shiro_detect` / `shiro_exploit` | Read BurpShiroPassiveScan annotations + gadget chain payload generation |
| **Fastjson** | `fastjson_detect` | Read FastjsonScan annotations + response features |
| **WAF** | `waf_bypass` | 7 bypass variants (encoding/Unicode/comment splitting/chunked, etc.) |
| **Request Smuggling** | `smuggler_detect` | CL.TE / TE.CL detection payload |
| **JWT** | `jwt_decode` / `jwt_forge` / `jwt_bruteforce` | Standard JWT decoding + alg:none forgery + key bruteforce |
| **Passive Annotations** | `hae_get_highlights` / `domain_hunter_get_results` / `xkeys_get_findings` | Read HaE / domain_hunter / Xkeys plugin output |
| **Scan Scheduling** | `active_scan_start` / `active_scan_get_status` / `get_scan_issues_enhanced` / `get_scan_queue` | Active scanning + result reading |
| **Intruder** | `intruder_start` / `intruder_get_results` | Attack orchestration + results |
| **Target Management** | `get_target_sitemap` / `get_scope` / `add_to_scope` / `get_target_issues` | Site map + scope + vulnerabilities |
| **Traffic** | `get_all_proxy_history` / `get_annotated_items` | Proxy history + annotated items |
| **💥 Phase 3 High-Speed Attack** | `turbo_intruder_run` | TI script scheduling (attack_id) |
| **🗄️ Phase 3 SQL Injection** | `sqlmap_run` | 100% invoke sqlmap.py with full parameters |
| **🖼️ Phase 3 Captcha** | `captcha_solve` | 100% invoke ddddocr (image → text) |
| **🧮 Phase 3 Front-end Encryption** | `js_encrypt` | GraalVM JS engine execute JS functions |
| **📤 Phase 3 File Upload** | `upload_test` | Multipart 4 variants (.php/.php.jpg/.phtml/%00.jpg) |
| **🔓 Phase 3 Access Control** | `authorizer_run` | Double cookie IDOR automatic detection |
| **✅ Phase 3 POC Verification** | `poc_verify_xpoc` | 100% run xpoc.exe cloud POC library |
## 📦 Installation
### Prerequisites
- Burp Suite Pro 2026.6+ (Montoya API)
- JDK 21 (for compilation) + Python 3.10+ (for runtime)
- ZCode IDE
### Step 1: Load to Burp Suite
1. Download `burp-mcp-bridge-1.0.0.jar` (from Releases page)
2. Burp Suite → Extender → Extensions → Add → Type: Java
3. Select jar → Next
4. Output tab should see "Registered 25 tools" + "MCP SSE service started, port 9877"
### Step 2: Register to ZCode
Edit `~/.zcode/cli/config.json` `mcp.servers`, add:
```json
"mcpBridge": {
"enabled": true,
"type": "stdio",
"command": "C:\\Users\\Zhouxin\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
"args": ["D:\\claude code\\burp-mcp-bridge\\scripts\\mcp-bridge-stdio.py"]
}
```
> Adjust Python path according to your machine; the script will listen to stdin JSON-RPC and forward to Burp port 9877.
### Step 3: Restart ZCode
Completely close and reopen; `@burp-suite-arsenal` can now invoke **33** `mcp__mcpBridge__*` tools (26 core + 7 Phase 3 advanced).
### Phase 3 Tool External Dependencies (optional)
Phase 3 has 4 tools requiring external binaries. **These dependencies are optional** — if not installed, corresponding tools return explicit error messages, and other 26 core tools still work normally.
| Tool | External Dependency | Default Path (can be overridden by JVM `-D...`) |
|------|----------|--------------------------------|
| `sqlmap_run` | sqlmap.py | `-Dmcpbridge.sqlmap.path=C:/path/sqlmap.py` |
| `poc_verify_xpoc` | xpoc.exe | `-Dmcpbridge.xpoc.path=C:/path/xpoc.exe` |
| `captcha_solve` | Python + ddddocr | `-Dmcpbridge.sqlmap.python=C:/path/python.exe` |
| `js_encrypt` | GraalVM JS (included in jar) | None |
**Full startup command example** (with Phase 3 paths):
```powershell
java "-Dmcpbridge.sqlmap.path=C:/Users/Zhouxin/AppData/Local/sqlmap/sqlmapproject-sqlmap-bb54601/sqlmap.py" `
"-Dmcpbridge.xpoc.path=D:/桌面/安全/xpoc_windows_amd64.exe" `
-jar "D:\BurpSuite_Pro_V2026.6\burpsuite_pro.jar"
```
## 🚀 Get Started in 30 Seconds
In ZCode:
```
@burp-suite-arsenal decode this JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```
Agent will automatically invoke `mcp__mcpBridge__jwt_decode` and return 3 segments of decoded output.
## 🛠️ Complete List of 33 Tools
### Phase 1+2 Core Tools (26)
| Category | Tool | Description |
|------|------|------|
| Extension Management | `list_extensions` | List all loaded Burp extensions |
| Extension Management | `get_extension_output` | Read extension output logs |
| Extension Management | `get_extension_findings` | Read extension discoveries |
| Traffic Reading | `get_all_proxy_history` | Read proxy history |
| Traffic Reading | `get_annotated_items` | Read annotated items |
| Target Management | `get_target_sitemap` | Site map |
| Target Management | `get_scope` / `add_to_scope` | Scan scope |
| Target Management | `get_target_issues` | Site vulnerabilities |
| Active Scanning | `active_scan_start` / `get_status` | Active scan scheduling |
| Active Scanning | `get_scan_issues_enhanced` / `get_scan_queue` | Scan results |
| Attack Orchestration | `intruder_start` / `get_results` | Intruder attack |
| Shiro | `shiro_detect` / `shiro_exploit` | Detection + exploitation |
| Fastjson | `fastjson_detect` | Detection |
| WAF | `waf_bypass` | 7 bypass variants |
| Request Smuggling | `smuggler_detect` | CL.TE / TE.CL |
| JWT | `jwt_decode` / `jwt_forge` / `jwt_bruteforce` | JWT toolkit |
| Passive Annotations | `hae_get_highlights` / `domain_hunter_get_results` / `xkeys_get_findings` | Read plugin output |
### Phase 3 Advanced Tools (7, 100% functional)
| Category | Tool | Description | External Dependency |
|------|------|------|----------|
| High-Speed Attack | `turbo_intruder_run` | Turbo Intruder script scheduling | - |
| SQL Injection | `sqlmap_run` | 100% invoke sqlmap.py, full technique/level/risk | sqlmap.py |
| Captcha | `captcha_solve` | 100% invoke ddddocr (image base64 → text) | ddddocr |
| Front-end Encryption | `js_encrypt` | GraalVM JS engine execute JS functions | GraalVM JS |
| File Upload | `upload_test` | Multipart/form-data send 4 extension variants | - |
| Access Control | `authorizer_run` | Double cookie switching + response comparison | - |
| POC Verification | `poc_verify_xpoc` | 100% run xpoc.exe, cloud POC library | xpoc.exe |
## 🏗️ Architecture
```
[ZCode IDE] → [ZCode MCP Dispatcher] → stdio
↓
[Python stdio Converter (mcp-bridge-stdio.py)]
↓ HTTP POST + SSE stream
[Burp Suite :9877] ← mcp-bridge Extension
↓ Montoya API
[Burp Suite Core + all loaded BApp plugins]
```
**4 Components**:
1. **ZCode** (MCP client) — IDE + agent scheduling
2. **Python Converter** (stdio → HTTP+SSE) — cross-language bridging
3. **burp-mcp-bridge Extension** (MCP server) — this project (port 9877)
4. **Montoya API** (Burp extension API) + existing BApp plugins (Shiro/Fastjson/HaE, etc.)
## 🧪 Testing
Test logs see [TEST_LOG.md](TEST_LOG.md) (to be supplemented).
## 🛠️ Development
```bash
$env:JAVA_HOME = "C:\Program Files\Java\jdk-21"
cd "D:\claude code\burp-mcp-bridge"
.\gradlew.bat clean shadowJar --no-daemon
```
## 📜 License
MIT — see [LICENSE](LICENSE)
## ⚠️ Disclaimer
This tool is for **authorized penetration testing** and **security research** only. Prohibited from using on unauthorized systems. Developer not responsible for any legal consequences resulting from misuse.
## 🙏 Acknowledgements
- [PortSwigger Montoya API](https://github.com/PortSwigger/burp-extender-montoya-api) — Burp extension development framework
- [Anthropic MCP](https://modelcontextprotocol.io/) — Model Context Protocol
- [ZCode](https://zcode.z.ai) — AI programming IDE
## 🚀 Agent One-Click Deployment (5 Phase 3 key agents)
Repository `agents/` directory provides 5 carefully curated ZCode agent files. Run setup script to automatically copy to ZCode loading path:
### Windows (PowerShell / CMD)
```cmd
scripts\setup-agents.bat
```
### Linux / macOS / Git Bash
```bash
./scripts/setup-agents.sh
```
### 5 Agent Roles
| Agent | Equipped Tools | Role Positioning |
|-------|------------|----------|
| 🛡️ **anci** | 33 (full) | End-to-end red team attack chain orchestration |
| 🗡️ **burp-suite-arsenal** | 33 (full) | Penetration striker |
| 🔭 **recon-scout** | 19 (simplified) | Reconnaissance and middleware identification |
| 🛡️ **code-auditor** | 12 (simplified) | Dynamic vulnerability verification |
| 🚨 **incident-responder** | 15 (simplified) | IOC active verification |
**Note**: ZCode agent files are actually located in `~/.zcode/agents/` (ZCode loading path); setup script synchronizes 5 agents to this path. ZCode restart takes effect.
