OpenBurp

Use Burp Suite Professional with Claude Code, Codex, or both from one setup flow.

Optionally pair it with a bundled Kali Linux Docker container so the AI agent can run recon, exploitation, and post-exploitation tooling (nmap, sqlmap, impacket, evil-winrm, etc.) in an isolated environment while Burp MCP handles web traffic analysis. See CLAUDE.md for the full pentesting workflow.

Quick start

Auto-detect the available client and configure it:

cd /path/to/OpenBurp
./setup.sh /your-workspace

Choose a specific client:

./setup.sh --client claude /your-workspace
./setup.sh --client codex /your-workspace
./setup.sh --client both /your-workspace

On Windows:

.\setup.ps1 -Client codex -Workspace C:\path\to\your-workspace
.\setup.ps1 -Client both -Workspace C:\path\to\your-workspace

What setup does

Common steps:

• Checks node, npm, and npx
• Detects Burp embedded Chromium
• Detects Burp Java
• Extracts mcp-proxy-all.jar from the installed Burp MCP extension when needed

If Claude Code is selected:

• Checks or installs Claude Code
• Checks or installs chrome-devtools-mcp
• Copies local permissions to /your-workspace/.claude/settings.local.json
• Registers Claude project MCPs: burpsuite + chrome-devtools

If Codex is selected:

• Detects Codex CLI
• Installs the reusable skill openburp-codex into $CODEX_HOME/skills
• Registers Codex global MCPs:
  • burp via the official PortSwigger stdio proxy
  • burp-browser via Playwright MCP using Burp's Chromium through 127.0.0.1:8080

Why Codex is different:

• Claude can connect directly to Burp's SSE MCP endpoint for burpsuite
• Codex works more reliably with the official mcp-proxy-all.jar, which bridges Burp's SSE server into a local stdio MCP process

Requirements

• Burp Suite Professional
• Burp extension MCP Server installed from the BApp Store
• Burp proxy listening on 127.0.0.1:8080
• Burp MCP SSE listening on 127.0.0.1:9876
• Node.js >= 18
• Docker (only if you want to use the Kali pentest container)

Kali pentest container (optional)

Build the image and launch a persistent container with VPN support:

docker build -t kali-htb -f docker/Dockerfile.kali .
./docker/start-kali.sh /path/to/vpn.ovpn <target-ip>

The agent then runs tools inside the container via docker exec kali-pentest <command>. Reports and evidence are persisted to ./reports/ through a mounted volume. Full methodology, phase-by-phase tooling, and execution patterns are documented in CLAUDE.md.

Verify

For Claude:

cd /your-workspace
claude mcp list

Expected project MCPs:

• burpsuite
• chrome-devtools

For Codex:

codex mcp list
curl -i --max-time 3 http://127.0.0.1:9876

Expected Codex MCPs:

• burp
• burp-browser

Expected SSE signal:

• Content-Type: text/event-stream

Note: curl can time out after printing the headers because SSE stays open by design. A visible text/event-stream header is healthy.

Manual setup

Run the script without writing MCP config:

./setup.sh --manual-mcp --client codex /your-workspace
./setup.sh --manual-mcp --client claude /your-workspace

Claude project MCPs:

cd /your-workspace
claude mcp add -s project -t sse burpsuite http://localhost:9876/
claude mcp add -s project -t stdio chrome-devtools -- chrome-devtools-mcp --executablePath "/Applications/Burp Suite Professional.app/Contents/Resources/app/burpbrowser/145.0.7632.46/Chromium.app/Contents/MacOS/Chromium" --proxy-server=http://127.0.0.1:8080 --accept-insecure-certs --isolated

Codex global MCPs:

codex mcp add burp -- "/Applications/Burp Suite Professional.app/Contents/Resources/jre.bundle/Contents/Home/bin/java" -jar "$HOME/.BurpSuite/mcp-proxy/mcp-proxy-all.jar" --sse-url http://127.0.0.1:9876
codex mcp add burp-browser -- npx -y @playwright/mcp@latest --executable-path "/Applications/Burp Suite Professional.app/Contents/Resources/app/burpbrowser/145.0.7632.46/Chromium.app/Contents/MacOS/Chromium" --proxy-server=http://127.0.0.1:8080 --ignore-https-errors --isolated

If you prefer editing Codex config directly, see mcp-example.toml.

Included files

• CLAUDE.md is the full pentesting framework reference for the AI agent
• docker/Dockerfile.kali builds the Kali pentest image
• docker/start-kali.sh launches the container with VPN and report volumes
• .mcp.json is the Claude MCP example
• settings.local.json is the Claude local permission template
• mcp-example.toml is the Codex MCP example
• skills/openburp-codex/SKILL.md is the Codex skill bundled with this repo
• examples/xss-lab-walkthrough.md shows an example workflow

Recommended Burp config

Import burp-configs/scope-exclude-noise.json:

1. Burp -> Project options -> Load from file
2. Select burp-configs/scope-exclude-noise.json

Troubleshooting

• burpsuite disconnected in Claude: confirm Burp is open and the MCP Server tab is healthy
• burp disconnected in Codex: confirm Burp is open, the MCP Server tab is healthy, and ~/.BurpSuite/mcp-proxy/mcp-proxy-all.jar exists
• burp-browser disconnected: run npx -y @playwright/mcp@latest --help
• Wrong Chromium path: rerun setup and provide the path manually
• New Codex tools not visible yet: restart Codex Desktop or start a new thread after codex mcp add
• Raw burp requests may not appear in Proxy > HTTP history; use burp-browser when you want traffic recorded by the proxy listener

Safety

Use this repo only on systems, labs, staging environments, or domains you are explicitly authorized to test.