> 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/user-guide/context-menus.md).
# Context Menus
The extension adds actions to Burp right-click menus in tools where HTTP traffic or scanner findings are selected.
## Where Context Menus Appear
* **Proxy -> HTTP History**: Right-click any request.
* **Repeater**: Right-click the request or response.
* **Site Map**: Right-click any entry or directory/root node. When a tree node is selected (not an individual request), the extension falls back to querying the full site map under that node, with labels showing "(site map - N)" to indicate broader scope.
* **Scanner -> Issues** (Pro only): Right-click any finding.
## Request Actions
When you right-click HTTP request/response items, these actions are available under **Extensions -> Custom AI Agent**:
| Action | Description |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AI Passive Scan** | Queues selected request(s) for passive AI analysis in the background. |
| **AI Active Scan** | Queues selected request(s) for active testing. Sends traffic to the target. |
| **AI Scan on Selected Insertion Point** | Surgical active scan scoped to a single parameter/header/JSON field/XML element/path-segment under the request-editor selection. Hidden until the selection overlaps a candidate. See [Insertion Point Scan](/user-guide/insertion-point-scan.md). |
| **Test 403 Bypass** | Queues selected 403-status requests for active bypass testing using IP spoofing headers, path manipulation, and HTTP method switching. Sends traffic to the target. |
| **Extract JS Endpoints** | Extracts API endpoints from JavaScript responses using regex pattern matching. Shows results in a scrollable dialog. |
| **Targeted tests** | Submenu for focused active checks (SQLi, XSS, SSRF, IDOR, etc.). Sends traffic to the target. |
| **BountyPrompt** | Curated submenu of tag-aware prompts loaded from JSON files. Uses selective context extraction before model invocation. |
| **Find vulnerabilities** | Broad security analysis for injection, auth/access, disclosure, and misconfiguration classes. |
| **Analyze this request** | Compact endpoint summary (method, route, auth, params, response type, security notes). |
| **Explain JS** | JavaScript behavior and risk analysis. |
| **Access control** | Authorization test plan for horizontal/vertical privilege escalation paths. |
| **Login sequence** | Login flow extraction and replay guidance from observed traffic. |
| **Custom prompts** | Submenu of your saved custom prompts (filtered by applicability tag) plus a `Custom…` entry that opens a free-form editor. See [Custom Prompt Library](#custom-prompt-library) below. |
## BountyPrompt Submenu
The **BountyPrompt** submenu is grouped by category:
* **Detection**: API key exposure, CSRF assessment, security headers, vulnerable software, sensitive errors, vulnerable file upload endpoints.
* **Recon**: Endpoint extraction from observed traffic.
* **Advisory**: Suggested follow-up attack vectors.
Menu entries use the prompt title only; neither the entry nor the submenu label includes the selected-item count.
If BountyPrompt integration is disabled or no curated prompts are loadable from the configured directory, the submenu appears disabled with a tooltip.
## Custom Prompt Library
The **Custom prompts** submenu surfaces saved free-form prompts plus an ad-hoc editor. It appears in both the request/response context menu and the scanner issue context menu. Prompts are filtered by applicability tag (`HTTP_SELECTION`, `SCANNER_ISSUE`, or both) and by the per-entry `Show in context menu` flag.
### Launching a saved prompt
Click any entry in the submenu to run it against the selected context. The flow is:
1. Context capture runs the same way as canned actions (privacy mode redaction, body-size limits).
2. The **Context Preview** dialog opens with the saved prompt and the redacted JSON. **No** extra excerpt-preview step — custom-prompt flows use this single action preview.
3. On **Send**, a new chat session opens titled `Custom: ` and the current built-in backend delivers the completed response as one rendered block.
### Running an ad-hoc prompt
Pick **Custom…** at the bottom of the submenu to open the free-form editor:
* Multi-line `Prompt` text area.
* Optional **Start from a saved prompt** dropdown (only shown if you have saved prompts tagged for the current context). Picking one fills the text area; you can then edit before sending.
* `Next: preview & send` opens the action preview; `Cancel` aborts.
Ad-hoc prompts do not persist — if you want to reuse one, add it to **Settings → Custom Prompts**.
### Managing saved prompts
Open **Settings → Custom Prompts** (the dedicated tab; previously folded under **Prompt Templates**). Each entry has:
| Field | Meaning |
| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Title** | Menu label and session-title stem. Truncated to 50 chars in the submenu. |
| **Prompt text** | Free-form text sent as the user prompt. No variable substitution in v1 (see below). |
| **Tag `HTTP_SELECTION`** | Show in the HTTP request/response context menu. |
| **Tag `SCANNER_ISSUE`** | Show in the scanner-issue context menu. |
| **Show in context menu** | Master toggle. Hidden entries stay in the library but are not exposed in menus. |
| **Favorite (★)** | Pins the entry to the top of its context-menu group. Favorites keep their relative order; non-favorites follow. |
Buttons: `Add`, `Edit`, `Duplicate`, `Delete`, `Move Up`, `Move Down`. Move Up / Move Down respect the favorite grouping — you cannot reorder a non-favorite past a favorite. The list order is the menu order — no auto-sort.
The editor also exposes:
* **Search** — a live filter that matches case-insensitively against title and prompt text. Clears with one click.
* **Import JSON** / **Export JSON** — bulk operations. Export writes the entire library as pretty-printed JSON. Import merges incoming entries by `id`: existing entries are updated in place, new entries are appended, and duplicate IDs across the import payload are de-duplicated.
The library is persisted globally (per Burp extension, not per project) as JSON. Malformed JSON loads as an empty library with an error in Burp's extension log.
### Launch metadata
Every custom-prompt launch carries `promptSource` (`CUSTOM_SAVED` or `CUSTOM_AD_HOC`), `contextKind` (`HTTP_SELECTION` or `SCANNER_ISSUE`), and — for saved prompts — `promptId` (UUID) and `promptTitle`. These are recorded in:
* `AuditLogger` prompt bundles in `~/.burp-ai-agent/bundles/`
* The `prompt` records in `~/.burp-ai-agent/audit.jsonl`
* The `AiRequestLogger` metadata map visible in the AI Logger panel
Filter a jsonl tail for custom launches:
```
tail -n 200 ~/.burp-ai-agent/audit.jsonl \
| jq 'select(.type=="prompt" and .payload.promptSource!="FIXED") | .payload'
```
Canned actions continue to work unchanged, now stamped with `promptSource=FIXED` plus the correct `contextKind`.
### No variable substitution in v1
Placeholders such as `$URL`, `$REQUEST`, `$RESPONSE` are **not supported** in v1. The prompt text travels through a different path than the context JSON, so interpolating the raw request/response into the prompt string would bypass the `PrivacyMode` redaction pipeline. If variable substitution is added later it will resolve against the already-redacted capture, not the raw HTTP message.
## AI Scan on Selected Insertion Point
Highlight the value of a single parameter, header, JSON field, XML element, or path-segment ID in any request editor and the **AI Scan on Selected Insertion Point** entry appears in the context menu, labelled with the resolved type and name (for example `AI Scan on Selected Insertion Point (json field: user_id)`). It runs an active AI scan scoped to that one insertion point, ahead of the regular manual/passive queue (priority 60). The action is hidden when the selection is empty, on the response side, or does not overlap any candidate.
See [Insertion Point Scan](/user-guide/insertion-point-scan.md) for the supported insertion-point types, the vuln-class picker filtering rules, queue/scope behavior, and safety boundaries.
## Targeted Tests Submenu
Examples:
* SQLi
* XSS (Reflected/Stored/DOM)
* SSRF
* IDOR / BOLA
* Path Traversal / LFI
* Command Injection
* SSTI
* XXE
* Open Redirect
* **Custom...** — Opens a multi-select dialog with all 62 vulnerability classes. Includes Select All / Deselect All buttons for quick selection. *Not to be confused with the `Custom…` entry under the `Custom prompts` submenu, which opens a free-form prompt editor; see* [*Custom Prompt Library*](#custom-prompt-library)*.*
## Issue Actions (Burp Pro)
When you right-click scanner issues, these actions are available:
| Action | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Analyze this issue** | Detailed analysis with root cause, evidence, and validation flow. |
| **Generate PoC & validate** | Step-by-step proof-of-concept with expected responses and success criteria. |
| **Impact & severity** | CIA impact, exploitability, business risk, and CVSS-style reasoning. |
| **Full report** | Structured vulnerability report for delivery. |
| **Custom prompts** | Submenu of saved custom prompts tagged for scanner issues plus a `Custom…` free-form editor. See [Custom Prompt Library](#custom-prompt-library) below. |
## Execution Flow
1. Select one or more requests/responses or scanner issues.
2. Trigger a context menu action.
3. The extension collects selection context.
4. Privacy mode redaction is applied.
5. Context payload size controls are applied (manual request/response body truncation + optional compact JSON serialization).
6. Action prompt/template is composed.
7. **Context Preview Dialog** opens (see below).
8. If confirmed, the prompt is sent to the selected AI backend.
9. The response is delivered into a chat session (current built-in backends emit one completed chunk).
For BountyPrompt actions, tag resolution runs after redaction and before prompt composition.
## Context Preview Dialog
Before captured context from a menu action is dispatched, a modal confirmation shows the action-level prompt and context produced at that point in the pipeline.
| Field | What it shows |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action** | The menu action that triggered the capture (e.g. `Analyze this request`). |
| **Privacy mode** | Current mode plus a one-line hint: STRICT, BALANCED (recognized cookies/tokens redacted, hosts kept), or OFF. Under OFF the dialog distinguishes raw built-in behavior from the case where saved custom patterns still apply. |
| **Prompt** | The resolved action prompt before backend framing. Tool mode can prepend a tool-use preamble later, and HTTP backends can receive the active agent profile as a separate system-role message. |
| **Context** | The post-policy context JSON captured for this action. It is included on the first turn of the new session; BountyPrompt embeds its resolved tag data in the prompt and uses an empty context envelope. |
Two buttons at the bottom:
* **Send** — proceeds with the request, creates the chat session, and renders the completed response.
* **Cancel** (default focus) — aborts. No session is created and nothing leaves the plugin.
The dialog applies to context captured from menus (proxy items, scanner issues, site-map nodes, Repeater). Messages you type inside an existing chat session do not open the dialog because you are the author of that text.
The dialog is therefore a confirmation boundary for the captured action data, not a byte-for-byte wire inspector for the complete backend request. The selected backend adds its protocol envelope, conversation history, and—where supported—the separate agent-profile system message after confirmation.
## Context Size Controls for Manual Actions
The **AI Passive Scanner** settings tab includes manual context controls that also affect context-menu actions:
* **Req body chars (manual)** and **Resp body chars (manual)** bound the request/response body content captured for prompt context.
* **Manual context JSON** toggles compact vs pretty JSON serialization for the context envelope.
These controls reduce token usage for non-local models while keeping request/response headers and core metadata intact.
## Multiple Selections
You can select multiple requests in Proxy History or Site Map and run actions across all selected items. This is useful for:
* Batch passive scanning.
* Batch queuing for active scanning.
* Running the same BountyPrompt action across related endpoints.
## Active Scan Safety and Queue Visibility
For active scan actions, the context flow enforces safety and visibility:
* Confirmation dialogs before queueing active tests.
* Target validation before enqueue.
* Queue state visibility (current and maximum queue size).
* Explicit warning when no target is queued (filtered target or full queue).
## Next Steps
* [Chat & Sessions](/user-guide/chat-sessions.md)
* [Passive AI Scanner](/scanners/passive.md)
* [Active AI Scanner](/scanners/active.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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://burp-ai-agent.six2dez.com/user-guide/context-menus.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.
