burpai

# burpai — Autonomous AI Pentest Agent for Burp Suite

A Burp Suite extension built on the Montoya API that embeds an autonomous AI penetration testing agent directly into Burp. All HTTP traffic flows through Burp's engine — every request the agent fires is visible in the HTTP history, and you can inspect it in Burp's native editors in real time.

Features at a Glance

Requirements

• Burp Suite Community or Pro — 2023.x or newer
• Java 17+ — only required if building from source; the prebuilt JAR runs on Burp's bundled JRE (no separate Java install needed)
• LLM backend — one of:
  • Ollama running locally (free, offline)
  • Google Gemini API key (aistudio.google.com)
  • Anthropic API key (console.anthropic.com)
  • DeepSeek API key (platform.deepseek.com)
  • OpenAI API key (platform.openai.com)
  • OpenRouter API key (openrouter.ai)

Quick Start

Option A — Prebuilt JAR (recommended)

1. Download the latest burp-ai-pentester-*.jar from Releases
2. In Burp: Extensions → Installed → Add
   Extension type: Java
   Path: the downloaded .jar
3. The AI Pentester tab appears — configure and go

No Java installation required. Burp Suite ships its own JRE.

Option B — Build from source

.\gradlew.bat jar

Output: dist/burp-ai-pentester-*.jar

OneDrive users: If Gradle hangs on cache files, add --no-build-cache --no-daemon

Then load dist/burp-ai-pentester-*.jar via Extensions → Installed → Add.

Set up your LLM

Ollama (local)

ollama serve
ollama pull glm-5:cloud               # fast, reliable tool-calling

Cloud Providers

• Gemini: Get a free key at aistudio.google.com.
• Anthropic: Get an API key at console.anthropic.com.
• DeepSeek: Get an API key at platform.deepseek.com.
• OpenAI: Get an API key at platform.openai.com.
• OpenRouter: Get an API key at openrouter.ai.

Run the agent

1. Open the AI Pentester tab in Burp
2. Set Provider, Ollama URL / Gemini API key, and Model
3. Enter a Target Base URL and a task prompt (e.g. Find SSRF)
4. Optionally right-click any request in Burp → Send to AI Pentester to give the agent a starting request
5. Click Start Agent

LLM Providers

Ollama (local)

Set Ollama URL to http://localhost:11434. Models with strong tool-calling give the best results:

The agent automatically falls back to text-mode tool parsing if the model returns HTTP 500 on the tool-calling endpoint — no manual configuration needed.

Gemini (Google)

1. Get a free key at aistudio.google.com
2. Select Gemini in the Provider dropdown
3. Enter your API key
4. Choose a model:

Anthropic Claude

1. Get an API key at console.anthropic.com
2. Select Anthropic in the Provider dropdown
3. Enter your API key
4. Choose a model:

Agent Tools

The agent picks the right tool for each step, guided by the system prompt in src/main/resources/burp-ai-agent-prompt.md.

Variable interpolation

Use {{var_name}} in any URL or request body to inject a stored variable:

url:  https://example.com/profile/{{user_id}}
body: csrf={{csrf_token}}&action=delete

Focused Task Mode

When your prompt names a specific vulnerability, the agent tests only that class and stops when done.

Supported vulnerability types (auto-detected from prompt):

Off-target findings

In focused mode, if the agent notices a different potential vulnerability while testing (e.g. a SQL error while looking for SSRF), it does not investigate it — but notes it in the final message:

ADDITIONAL NOTES FOR FURTHER TESTING:
- /post/<id> — single quote caused SQLite error, likely SQL Injection
- /console — Werkzeug debugger exposed at this path

Timing-Based Detection

fuzz_parameter records duration_ms for every payload. A result is flagged timing_anomaly if:

• Response took > 3 seconds (absolute), or
• Response took > 3× the baseline request duration

This catches blind SSRF and blind command injection where the server reaches out internally but returns a generic response body.

Reports

Click Generate Report after a run. A styled HTML report is saved to ~/burpai_logs/report_<timestamp>.html:

• Summary table (name, severity, location)
• Full detail per finding (description, impact, PoC, remediation, evidence request IDs)

All agent output is also written to ~/burpai_logs/agent_<timestamp>.log — every iteration, tool call result, and vulnerability report — for offline review and evidence archiving.

Configuration

config/burp_ai_config.json — loaded at startup, all fields also editable in the UI:

{
  "llm_provider": "ollama",
  "ollama_base_url": "http://localhost:11434",
  "ollama_model": "glm-5:cloud",
  "gemini_api_key": "",
  "gemini_model": "gemini-3-flash-preview",
  "anthropic_api_key": "",
  "target_base_url": "https://example.com/",
  "log_enabled": true,
  "max_iterations": 20
}

Persona and vector memory are configured in the UI, not in this file.
Persona: dropdown in the AI Pentester tab. Vector memory is automatic — no configuration needed.

System Prompt

The agent's full methodology is in src/main/resources/burp-ai-agent-prompt.md — a human-readable Markdown file bundled in the JAR. Edit it to customise attack strategies, add new vulnerability classes, or adjust tool usage rules without recompiling.

Feature: Repeater Copilot

An AI assistant embedded inside every Repeater tab — as an AI Copilot tab alongside Raw / Pretty / Hex.

Workflow:

1. Send any request in Repeater — the copilot auto-triggers on each response
2. The AI Copilot tab shows reasoning and a suggested next test request
3. The suggestion is ready in the editor with all original auth headers preserved
4. Click Approve → then Burp's Send to fire it
5. Use Analyze Again for a fresh suggestion, or Reject to discard

Repo Layout

src/main/java/com/burpai/aipentester/
  Extension.java                    — Montoya entrypoint; registers AgentTab and RepeaterCopilotEditor

  agent/
    AgentEngine.java                — Thin facade wiring all agent services; public API consumed by AgentTab
    AgentLoop.java                  — Orchestrates the agentic iteration loop (per-iteration LLM call + tool dispatch)
    AgentStateSnapshot.java         — Builds compact structured signals injected into each iteration's LLM prompt
    AgentUtils.java                 — Pure static utilities shared across agent services
    AgentLogger.java                — Centralised logging to UI callback and timestamped log file
    MemoryManager.java              — Thread-safe per-run state (responseBodyStore, sessionVars, vulnStore, AttackGraph)
    TargetMemoryStore.java          — Persistent cross-session target memory (endpoints, params, WAF flags, vuln history)

  clients/
    OllamaClient.java               — Ollama HTTP client with automatic text-mode fallback
    GeminiClient.java               — Gemini REST API client
    DeepSeekClient.java             — DeepSeek platform API client; supports deepseek-chat and deepseek-reasoner (R1/CoT)
    OpenRouterClient.java           — OpenRouter OpenAI-compatible client with automatic text-mode fallback
    ClaudeClient.java               — Anthropic Claude direct REST API client
    OpenAIClient.java               — OpenAI direct REST API client

  llm/
    LlmClient.java                  — LLM client interface (ConnResult, ToolCall, ChatResult)
    LlmGateway.java                 — LLM client creation, system-prompt loading, persona overlays, tool schema

  model/
    AttackGraph.java                — Deterministic graph of endpoints, parameters, tested payload types, extracted variables
    EndpointNode.java               — Single node in the attack graph
    ReportService.java              — Generates the HTML vulnerability report
    VulnClass.java                  — String constants for vulnerability class names

  tools/
    ToolExecutor.java               — Executes all 11 tool calls (HTTP, fuzz, spider, decode, sitemap, report, etc.)
    CollaboratorManager.java        — Manages Burp Collaborator OAST session; OOB payload generation and interaction polling
    Imported.java                   — Immutable model of a request imported via Burp context menu
    ToolResult.java                 — Tool call result model; serialises to JSON for LLM consumption

  ui/
    AgentTab.java                   — AI Pentester tab UI (provider selector, request log, editors)
    RepeaterCopilot.java            — Per-tab AI analysis engine (Repeater Copilot)
    RepeaterCopilotEditor.java      — ExtensionProvidedHttpRequestEditor implementation

src/main/resources/
  burp-ai-agent-prompt.md          — Agent system prompt (edit to customise without recompiling)

config/
  burp_ai_config.json              — Startup defaults (provider, model, target URL, API key)

Responsible Use

• Use only against systems you own or have explicit written permission to test
• Do not commit real API keys, session tokens, cookies, or target-specific data to this repository
• The agent can send many requests quickly — respect rate limits and applicable laws

License

This project is licensed under the MIT License.