> For the complete documentation index, see [llms.txt](https://burp-ai-agent.six2dez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://burp-ai-agent.six2dez.com/examples/typical-workflows.md).

# Typical Workflows

These workflows show common ways to use Custom AI Agent in security assessments.

## Bug Bounty Triage

Assess endpoints and generate submission reports.

1. Browse the target application with Burp Proxy.
2. In **Proxy → HTTP History**, right-click an interesting request → **Find vulnerabilities**.
3. Review the AI's analysis in the chat panel.
4. If a vulnerability is identified, right-click the same request → **AI Active Scan** (with `SAFE` risk level).
5. If confirmed, use the chat to ask: *"Generate a PoC with curl commands for this finding."*
6. Create an issue in Burp via the MCP `issue_create` tool or manually.
7. Use **Full report** to generate a structured write-up for submission.

## Large Scope Reconnaissance

Map and analyze a large application surface.

1. Set your target in **Target → Scope**.
2. Enable the **Passive** toggle in the top bar.
3. Browse the application thoroughly (or use Burp's crawler on Pro).
4. The passive scanner automatically analyzes traffic in the background.
5. Check findings in the extension's **View Findings** panel.
6. Filter by severity (HIGH/CRITICAL) and review the most interesting endpoints.
7. For promising findings, right-click the request → **Find vulnerabilities** for a deeper analysis.
8. Promote high-confidence findings by enabling **Auto-Queue to Active**.

## API Security Assessment

Systematic testing of REST/GraphQL APIs.

1. Proxy API traffic through Burp.
2. Right-click API endpoints → **Analyze this request** to understand each endpoint's purpose, parameters, and auth mechanism.
3. For authentication endpoints, use **Login sequence** to document the auth flow.
4. Test authorization with **Access control** to generate a test plan for IDOR/BOLA/BAC.
5. Enable the passive scanner with **Scope Only** to catch common API misconfigurations.
6. Use the MCP server with Claude Desktop for supervised MCP testing: *"Check all API endpoints in proxy history for missing authorization checks."*

## MCP-Driven Pentesting

Use an external AI agent to execute Burp tools under your supervision.

1. Enable the **MCP** toggle. Note the token from **MCP Server tab in the bottom settings panel**.
2. Configure Claude Desktop (or another MCP client) with the Burp MCP server connection.
3. Start a conversation: *"List the last 20 requests in proxy history for the target domain."*
4. The AI calls `proxy_http_history_regex` and returns results.
5. Ask: *"Analyze the `/api/users/{id}` endpoint for IDOR. Send test requests with different IDs."*
6. The AI calls `http1_request` to send test payloads and reports differences.
7. If a vulnerability is found: *"Create an issue in Burp with the evidence."*
8. The AI calls `issue_create` with full details.

> **Safety note**: Enable unsafe MCP tools only when you are actively supervising the AI agent. Disable them when not in use.

## JavaScript Analysis

Deep-dive into client-side code for security issues.

1. Browse the target and let Burp capture JavaScript responses.
2. In **Proxy → HTTP History**, find JS files.
3. Right-click → **Explain JS** to get a summary of the code's behavior and security implications.
4. For large JavaScript bundles, use **Gemini** as the backend (1M+ token context window).
5. Ask follow-up questions in the chat: *"Are there any hardcoded API keys or secrets in this JavaScript?"*

## Compliance Audit with Audit Logging

Produce a reviewable, correlatable record of extension activity for compliance workflows. Authenticity requires an external integrity control, and prompt bundles do not contain separate system-role profile text or reconstructed history.

1. Enable **Audit Logging** in **Privacy & Logging tab in the bottom settings panel**.
2. Set **Privacy Mode** to **STRICT** for sensitive engagements.
3. Enable **Determinism Mode** for stable covered ordering and host pseudonyms; this improves comparisons but does not make model output deterministic.
4. Perform your assessment normally using context menus and chat.
5. After the assessment, review `~/.burp-ai-agent/audit.jsonl` for the captured audit event stream. It is not a complete provider wire transcript and does not attach a trace ID to every event.
6. Use the per-event SHA-256 payload hashes (`payloadSha256`) in the audit log to detect edits to individual records. Note that there is no Merkle chain — deletion of entire lines cannot be detected from the file alone.
7. Archive the generated JSON bundles from `~/.burp-ai-agent/bundles/`. The code contains a ZIP-export helper, but the current production UI does not invoke it.

## Terminal-First Workflow (Burp Scan Skill)

Drive Burp from a terminal-based AI (Claude Code, Gemini CLI, etc.) while keeping the UI out of the loop.

1. Enable **MCP** in the extension, note the bearer token, and confirm `/__mcp/health` responds on `127.0.0.1:9876`.
2. Install the `/burp-scan` skill ([Burp Scan Skill](/examples/burp-scan-skill.md)) into your terminal AI's skills directory.
3. From the terminal, invoke `/burp-scan` — the skill instructs the AI to call MCP tools like `proxy_http_history`, `http1_request`, `scanner_issues`, and `issue_create`.
4. The AI narrates each step; confirmed findings land as Burp issues via `issue_create` and appear in Burp's Target view without you leaving the terminal.
5. External MCP calls produce audit/tool telemetry, but they do not automatically become one `chat-turn-*` trace. Use trace IDs in the AI Request Logger for extension-driven chat/scanner chains and correlate terminal-client calls by tool metadata and timestamps. See [Audit Logging](/privacy-and-logging/audit-logging.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://burp-ai-agent.six2dez.com/examples/typical-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.