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; no plaintext in preferences.
• 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

• 11 AI Backends — Burp AI (built-in), 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 BApp 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).
• Available on the BApp Store — Install Custom AI Agent directly from Burp's BApp Store, or grab the full build from Releases.
• 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

Install Custom AI Agent from Burp's BApp Store, 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) — 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.

6. Connect Claude Desktop via MCP (Optional)

Enable the MCP server in Settings > MCP Server and add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "burp-ai-agent": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://127.0.0.1:9876/sse"
      ]
    }
  }
}

Requires Node.js 18+. If you enable External Access, the MCP client must send Authorization: Bearer <token> on every request.

You can also register external or custom MCP servers in Settings > MCP > External Servers (SSE or stdio transports). External server auth tokens are stored encrypted at rest. See docs/external-mcp-servers.md for setup details and security notes.

Burp Scan Skill (Terminal AI Scanning)

The burp-scan skill lets you use any AI coding assistant (Claude Code, Gemini CLI, Codex, etc.) as a Burp scanner from your terminal. Instead of the plugin's built-in AI, your terminal AI becomes the reasoning engine while Burp provides the tools via MCP.

What It Contains

• MCP tool reference (up to all 59 tools in the full build) organized by scanning action
• Passive analysis protocol (traffic analysis without sending requests)
• Active testing payload library (200+ payloads for 62 vuln classes with detection patterns)
• End-to-end scanning workflow (scope -> passive -> active -> OOB -> report)
• Issue creation protocol with severity/confidence mapping

Install for Claude Code

Copy the skill to your Claude Code skills directory:

# Global (available in all projects)
cp -r skills/burp-scan ~/.claude/skills/burp-scan

# Or project-specific
cp -r skills/burp-scan .claude/skills/burp-scan

Then use /burp-scan in Claude Code or let it trigger automatically when you mention Burp scanning.

Install for Other AI Assistants

The skill is a standalone Markdown file at skills/burp-scan/SKILL.md. You can use it with any AI assistant that supports system prompts or context files:

• Gemini CLI / Codex / OpenCode: Add as a context file or paste into your system prompt
• Custom MCP clients: Include the skill content as system context alongside your MCP connection
• Any LLM: The file is self-contained — feed it as context along with your MCP tool definitions

Usage Example

You: Connect to Burp MCP at localhost:9876 and scan the proxy history for IDOR vulnerabilities

AI: [Uses proxy_http_history to pull traffic]
    [Identifies endpoints with numeric IDs]
    [Sends http1_request with ID+1, ID-1 payloads]
    [Compares responses for different user data]
    [Creates issue_create for confirmed IDOR]

The skill and the plugin's built-in scanner are complementary: the plugin runs automated background scanning, while the skill enables interactive, analyst-guided scanning from your terminal.

Documentation

Full documentation is available at burp-ai-agent.six2dez.com.

• Installation
• Quick Start
• UI Tour
• Agent Profiles
• Passive Scanner
• Active Scanner
• MCP Overview
• Privacy Modes
• Settings Reference
• Troubleshooting
• Burp Scan Skill

Operator Playbooks

• MCP Hardening
• UI Safety Guide
• Backend Troubleshooting
• Anthropic Backend Setup
• External MCP Servers

Privacy and Security Notes

• All stored API keys and tokens (Anthropic, MCP bearer token, TLS keystore password, etc.) are encrypted at rest with AES-256-GCM using a per-install master key.
• STRICT privacy mode anonymizes hosts using real HKDF (HMAC-SHA256 extract/expand). BALANCED mode redacts cookies, tokens, and auth headers. OFF mode sends traffic as-is.
• External MCP server outputs are wrapped in a trust-boundary marker before entering the AI prompt, preventing prompt injection from untrusted server responses.

Settings are schema-versioned internally (settings.schema.version) and migrated additively on load for safe upgrades.

Requirements

• Burp Suite Community or Professional (2023.12+)
• Java 21 (bundled with modern Burp for runtime; required separately for building from source)
• At least one AI backend configured (see table above)

License

This project is licensed under the MIT License.

Disclaimer

Usage of Custom AI Agent for attacking targets without prior consent is illegal. It is the user's responsibility to obey all applicable laws. The developers assume no liability for misuse or damage caused by this tool. Use responsibly.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for development setup and guidelines, or the Developer docs for architecture details.