Custom AI Agent

The bridge between Burp Suite and modern AI.

A note on the name: This extension is published as Custom AI Agent (formerly Burp AI Agent). It was renamed to comply with PortSwigger's BApp Store naming requirements and to avoid confusion with Burp Suite's built-in Burp AI provider. The GitHub repository (github.com/six2dez/burp-ai-agent), the documentation site (burp-ai-agent.six2dez.com), and the configuration directory (~/.burp-ai-agent/) keep the burp-ai-agent identifier for continuity.

Custom AI Agent is an extension for Burp Suite that integrates AI into your security workflow. Use local models or cloud providers, connect external AI agents via MCP, and let passive/active scanners find vulnerabilities while you focus on manual testing.

What's new in v0.9.0

• Native Anthropic backend (CAP-01) — direct Anthropic Messages API via Burp's HTTP transport; all traffic appears in Proxy history.
• AES-256-GCM secrets at rest (SEC-01) — all stored API keys and tokens are encrypted with a per-install key using javax.crypto. The master key lives in Burp Preferences alongside the ciphertext, so this defends against casual inspection of a preferences file, not against a local attacker — see Privacy and Security Notes.
• Real HKDF host anonymization (PRIV-01) — STRICT mode now uses genuine HMAC-SHA256 extract/expand (not salted SHA-256) for host anonymization.
• Request/response body redaction + custom patterns (PRIV-02) — redaction pipeline covers body fields and user-configurable regex patterns validated against ReDoS.
• Pre-send secret tripwire (PRIV-03) — warns before high-entropy values leave Burp; allowlist actions are audit-logged.
• External MCP servers (CAP-02) — connect to external/custom MCP servers (SSE or stdio) so AI agents can call their tools alongside Burp's built-in tools.
• Per-session token-budget guardrails (CAP-04) — BudgetGuard caps passive-scanner spend with WARN/CAP/OFF states; passive scanner pauses automatically at the hard cap.

Highlights

• 12 AI Backends — Burp AI (built-in), Anthropic, Ollama, LM Studio, NVIDIA NIM, Perplexity, Generic OpenAI-compatible, Gemini CLI, Claude CLI, Codex CLI, OpenCode CLI, Copilot CLI.
• 59 MCP Tools — Let Claude Desktop (or any MCP client) drive Burp autonomously (8 extension-native AI tools in the store build, all 59 in the full build).
• Scoped MCP Access — Optionally confine every MCP tool to your in-scope hosts, so external AI clients can't reach out-of-scope targets through Burp.
• 62 Vulnerability Classes — Passive and Active AI scanners across injection, auth, crypto, and more. The passive scanner runs as a Burp PassiveScanCheck (Burp Pro).
• Install from Releases — Download the JAR from Releases. Not on the BApp Store: the submission has been open since January 2026.
• Theme-Aware UI — An internal design system styles the settings panel and re-themes automatically with Burp's light/dark switch.
• Burp Scan Skill — Use your preferred AI coding assistant (Claude Code, Gemini CLI, Codex, etc.) as a scanner via MCP.
• 3 Privacy Modes — STRICT / BALANCED / OFF. Redact sensitive data before it leaves Burp.
• Custom Prompt Library — Save free-form prompts per context (HTTP request or scanner issue); launch them from the right-click menu or type ad-hoc ones via Custom….
• Audit Logging — JSONL with SHA-256 integrity hashing for compliance; every launch stamped with promptSource / contextKind for reproducibility.

Quick Start

1. Install

Download the latest JAR from Releases, or build from source (Java 21):

git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent

# Full build (default, GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar

# Store build (BApp Store submission) — 8 extension-native AI MCP tools only
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. Load into Burp

1. Open Burp Suite (Community or Professional).
2. Go to Extensions > Installed > Add.
3. Select Java as extension type and choose the .jar file.

The extension registers in Burp as Custom AI Agent (the name in the Extensions list and the Suite tab) to distinguish it from Burp's built-in Burp AI provider.

3. Agent Profiles

The extension auto-installs the bundled profiles into ~/.burp-ai-agent/AGENTS/ on first run. Drop additional *.md files in that directory to add custom profiles.

4. Configure a Backend

Open the AI Agent tab and go to Settings. Pick a backend:

Backend	Type	Setup
Burp AI (built-in)	In-process	Use Burp Suite Pro's built-in AI when available; no extra config required.
Ollama	Local HTTP	Install Ollama, run ollama serve, pull a model (ollama pull llama3.1).
LM Studio	Local HTTP	Install LM Studio, load a model, start the server.
NVIDIA NIM	HTTP	Use the default https://integrate.api.nvidia.com endpoint, set your NVIDIA API key, and choose a model such as moonshotai/kimi-k2.5.
Perplexity	HTTP	Use the default https://api.perplexity.ai endpoint, set your pplx-... API key, and choose a model such as sonar, sonar-pro, or sonar-reasoning.
Generic OpenAI-compatible	HTTP	Provide a base URL and model for any OpenAI-compatible provider.
Gemini CLI	Cloud CLI	Install gemini, run gemini auth login.
Claude CLI	Cloud CLI	Install claude, set ANTHROPIC_API_KEY or run claude login.
Codex CLI	Cloud CLI	Install codex, set OPENAI_API_KEY.
OpenCode CLI	Cloud CLI	Install opencode, configure provider credentials.
Copilot CLI	Cloud CLI	Install copilot and sign in with your GitHub account.
Anthropic	Cloud API	Enter your Anthropic API key in Settings. API traffic routes through Burp's proxy. See docs/anthropic-backend.md.

For NVIDIA NIM, the backend expects the same chat-completions style flow as the NVIDIA hosted endpoint. A working configuration is:

Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>

Leave extra headers empty unless your gateway requires them. The extension sends requests to /v1/chat/completions and uses the configured bearer token automatically.

5. Run Your First Analysis

1. Browse a target through Burp Proxy.
2. Right-click any request in Proxy > HTTP History.
3. Select Extensions > Custom AI Agent > Analyze this request.
4. A chat session opens with the AI analysis.