CanaryAgent is a Burp Suite extension that finds indirect prompt injection in web apps that use LLM agents.
-
Plant a unique marker in something the agent will read: a forum post, a document, a profile field.
-
Or let the Payload Builder write the injection for you: pick a template (echo, tool coercion, out-of-band, text-protocol), press Generate, and it mints a fresh marker and builds a ready-to-plant string around it. Tool names come from what the agent actually offered, never invented. It only writes text — you still plant and trigger it.
-
Use the app normally. Ask the agent (the chatbot) something that needs a tool. A tool is a function the agent can call on your behalf: search the docs, read recent posts, look up an order, fetch a URL.
-
CanaryAgent watches the traffic through Burp and reports where the marker came back.
-
Marker in a tool result: your content reached the model.
-
Marker inside a tool call's arguments: your content steered the agent. Injection confirmed.
-
Plant a Burp Collaborator payload instead of a marker (Pro) and you also learn whether the agent actually reached out.
-
A marker shows your content moved the agent. A Collaborator hit shows the agent made a real outbound request to a host you control. That is the exfiltration and SSRF case: content the agent read made a tool call out to Collaborator, or to a VPS in a real attack.
-
Each Collaborator hit is labelled from its own headers, browser-attributed, agent-attributed or unattributed, so you know whether a human clicked it or the agent fetched it.
-
It also highlights agent traffic in Proxy history and inventories every tool the agent is offered.
-
Works with any LLM provider or framework. Reads traffic structure only. Never sends anything itself.
Click any image to open it at full size.
- Markers. Right-click in any request, response or WebSocket editor to insert a unique
cnry...token at the selection or caret, insert your own text, track selected text, or copy a fresh marker for pasting into a browser form. Each placement is recorded immediately. - Encoding-tolerant tracking. Every message Burp sends or receives, in any tool and in or out of
scope, is scanned once for markers as raw text, re-cased, JSON
\u-escaped, percent-encoded and base64. A marker found insidetool_calls,function_call,tool_use,argumentsorinputis reported as "seen in tool call". Outbound traffic from Repeater, Intruder or other extensions never counts as a hit; that is you re-sending your own marker. - Collaborator payloads (Professional). Insert a Collaborator hostname the same way. In-band echoes are tracked like markers, and a background poller correlates DNS/HTTP/SMTP interactions to the row, which then shows "collaborator interaction".
- Passive detection. Request and response bodies (JSON, NDJSON, SSE, form data) are parsed and matched
structurally against strong signals (
tools,tool_calls,tool_use,messageswith roles, tool schemas) and medium signals (role arrays, schema keys, framework keys, agent-like paths). Proxy history rows get a highlight and a note: orange for strong, yellow for medium, red for a marker hit. - Tool Inventory. Tool names and the parameter or argument keys that were visible, counted once per message, with first/last seen and source URL.
- Scanner issues (Professional). A passive scan check reports marker findings in Burp's issue list: High for a marker inside a tool call, Medium for one inside a tool result, Informational for a plain resurfacing. Detection itself never depends on the Scanner - markers are tracked by the traffic handlers on every edition, including WebSocket traffic the Scanner never sees.
- CanaryAgent tab. Tool Inventory, Marker Hits and Annotated Traffic in one suite tab. Filter and sort each table, select a tool to narrow the traffic to it, view the selected request and response read-only, and double-click to send to Repeater. The tab never edits messages.
- Payload Builder tab. A second suite tab, "CanaryAgent Payload Builder", writes a ready-to-plant injection sentence around a fresh marker: echo, tool coercion, out-of-band or a text-protocol tool result. Tool names and parameters come from the Tool Inventory, never invented, and the marker is recorded as placed the moment you press Generate. The builder only produces text. You copy it, plant it through the application and trigger the agent; the extension sends nothing.
- Build the JAR (below) or take
build/libs/canaryagent-1.2.0-all.jar. - Burp → Extensions → Installed → Add → type Java → select the JAR.
- The Output tab logs a startup line and a hint about proxying your backend.
- Proxy the backend, not just the browser. Tool definitions and tool calls travel from your backend to
the LLM provider. Point the backend's
HTTP_PROXY/HTTPS_PROXYat Burp and trust Burp's CA. Step by step for Python, Node and the JVM:docs/DEVELOPMENT.md, section 6. - Use the application normally. Agent-related requests turn orange or yellow in Proxy history; the Tool Inventory fills in.
- Find content the agent will read (a document body, a tool result, a page the agent fetches), right-click in the editor → Extensions → CanaryAgent → Insert new marker, and send it.
- Trigger the agent. Watch the Marker Hits row: placed → seen in request / seen in response → seen in tool result → seen in tool call, or collaborator interaction for an out-of-band fetch.
- Double-click an annotated traffic row to continue in Repeater.
| Action | Where | What it does |
|---|---|---|
| Insert new marker | editable HTTP or WebSocket editor | Generates cnry + 8 base36 chars and inserts it at the selection or caret |
| Insert custom marker... | editable editor | Inserts and tracks text you type (matched case-insensitively) |
| Insert Collaborator payload | editable editor, Professional | Inserts a fresh Collaborator hostname and tracks it |
| Track selected text as marker | any editor with a selection | Tracks the selection without changing the message |
| Copy new marker / Collaborator payload to clipboard | anywhere | For pasting into a browser or another tool |
| Mark as agent content | editor or selected history rows | Forces annotation and inventory even when matching is off |
| Send to Repeater as tool: name | message containing a tool | Sends the original request to a Repeater tab named after the tool |
| Copy tool snippet | message containing tools | Copies name(key, key) lines |
Settings → Extensions → CanaryAgent (saved per project):
- Automatically flag agent-related traffic: on by default. Off means only manually marked items are annotated. Marker tracking is never affected.
- Only annotate in-scope traffic: off by default. Markers are tracked everywhere regardless, because they usually reappear on LLM provider hosts outside your scope.
- Do not persist markers and tool inventory in the project: off by default, so state is saved. Ticked stops saving immediately; what is already stored still comes back at load until you press Clear table.
- Collaborator polling interval: 30 seconds by default, read before every poll.
All settings take effect immediately; nothing needs a reload.
| Status | Meaning |
|---|---|
| placed | Inserted, not seen again yet |
| seen in request | Found in an outgoing Proxy request or client→server WebSocket frame |
| seen in response | Found in a response or server→client frame, outside tool-call keys |
| seen in tool result | Found inside a tool result handed to the model (a role: tool message, a tool_result block, function_call_output): content the agent read was delivered to it |
| seen in tool call | Found inside a tool call's arguments or input |
| collaborator interaction | Burp Collaborator recorded a DNS, HTTP or SMTP interaction for the payload. The Attribution column says what that interaction's own evidence suggests caused it: browser-attributed (Sec-Fetch headers or a /favicon.ico fetch; Sec-CH-UA, Upgrade-Insecure-Requests and Referer are listed as evidence but do not decide), agent-attributed (no browser evidence, and the payload had already been seen in agent traffic) or unattributed (most DNS lookups). The label never changes the status |
Status only ever moves to a stronger value. The Encodings column lists every form the marker was seen in. Hits counts distinct messages: the same body from the same URL again (a poll, a page reload) updates Last hit but not the count, while a new chat turn or a changed page counts. Collaborator interactions always count.
- Markers and the tool inventory are saved in the Burp project and come back after a reload or restart, including each marker's last hit with its request and response. The Clear table buttons remove the stored data too. The Collaborator client is saved with them, so payloads inserted before a reload keep polling for interactions. The Annotated Traffic list is in memory only. A setting turns persistence off.
- Parameter keys are shown alphabetically; the JSON library does not preserve source order.
- No conversation threading. Related turns are grouped only by a hashed session hint (cookie or Authorization header), shown in the Session column and selectable via "Show only this session".
- Streamed responses are not observed. When Burp treats a response as streaming, which it does by
default for
text/event-stream, the Proxy passes it straight to the client and extensions never see it. Markers echoed in a streamed LLM response go unseen. While testing, untick "Treat responses with the text/event-stream MIME type as streaming" under Settings → Network → HTTP → Streaming responses, or turn off streaming in the client. The extension logs a WARNING line at load when that setting or a streaming prefix is active. A separate one-time warning covers the other case, a partial body that does arrive. - "Send to Repeater as tool" cannot carry the Proxy note; Burp's own send does.
The Gradle wrapper (./gradlew, gradlew.bat on Windows) drives everything; no local Gradle install
is needed. It also fetches a JDK 21 toolchain on its own if none is present, so no system Java is
required beyond what Gradle itself runs on. The JAR targets Java 21 bytecode and runs on Burp's
bundled runtime.
Common tasks:
./gradlew test # unit tests only, no Burp needed (detector, scanner, payload builder)
./gradlew shadowJar # the loadable fat JAR -> build/libs/canaryagent-1.2.0-all.jar
./gradlew build # compile + test + shadowJar in one go
./gradlew clean # delete build/ ; combine as `./gradlew clean shadowJar`shadowJar produces the single bundled JAR you load into Burp (Kotlin stdlib and org.json inside;
the Montoya API is compileOnly, supplied by Burp at runtime). Plain jar is not enough — it omits
the bundled dependencies.
Useful flags:
--offline— build without touching the network once dependencies are cached (e.g../gradlew --offline shadowJar).-i/--info,-s/--stacktrace— more output when a task fails.--rerun-tasks— force a rebuild when Gradle reportsUP-TO-DATEbut you want everything re-run.--tests "com.canaryagent.payload.*"— run one test class or package, e.g../gradlew test --tests "com.canaryagent.markers.*".
- Rebuild the JAR:
./gradlew shadowJar(or./gradlew clean shadowJarafter larger changes). The output path is alwaysbuild/libs/canaryagent-<version>-all.jar; the version comes frombuild.gradle.kts. - Reload it in Burp. Burp does not auto-reload a rebuilt JAR, so in Extensions → Installed select CanaryAgent, click Remove, then Add the freshly built JAR again. (Replacing the file in place is not picked up.)
- The Output tab should show the startup line again. Table state (markers, tool inventory) is restored from the Burp project, so a reload keeps what you had.
Changing version in build.gradle.kts changes the JAR filename — update the path you point Burp at
when you bump it.
docs/USAGE.md: hands-on walkthrough for testing an app with CanaryAgentdocs/payload-builder.md: the Payload Builder tab, its templates and out-of-band correlationdocs/DEVELOPMENT.md: IntelliJ setup, proxying the backend, remote debuggingdocs/CanaryAgent-Architecture.md: architecture and implementation notes- Montoya API: https://portswigger.github.io/burp-extensions-montoya-api/javadoc/
Licensed under the GNU General Public License v3.0. See LICENSE.
Bootstrapped from KotlinBurpExtensionBase by Nick Coblentz.




