Proxy and Caido integration
The proxy system gives scan agents a shared view of web traffic and a safe way to inspect or resend requests. Caido runs with each scan so browser and shell traffic can be captured, while the agent tools and host UI can use the same scan-bound proxy resources. For the wider settings model, see Configuration and external integrations, Configuration and provider settings, MCP integration, and Runtime backends and sessions.
System role
Proxy purpose
The HTTP proxy records traffic made by the scan and turns that traffic into evidence for security testing. Agents can search captured requests, inspect raw content, replay a request with controlled changes, and browse the discovered site structure.
The proxy is not a separate target scanner. It is a shared observation and testing layer around traffic that the scan already creates. This lets an agent move from discovery to a focused request test without rebuilding the request by hand.
References: docs/…/proxy.mdx• L6-16 docs/…/proxy.mdx• L78-105
Traffic path
Processes that run inside the scan sandbox use proxy environment settings. As a result, shell commands and browser traffic pass through the Caido sidecar and become available to the agent tools. Local browser control traffic stays outside this path so the browser connection itself does not loop through the proxy.
The following diagram shows how scan traffic reaches Caido and how the agent reads it back.
flowchart LR
A[Scan agent] --> B[Browser or shell process]
B -->|HTTP_PROXY / HTTPS_PROXY| C[Caido sidecar]
C --> D[Target]
C --> E[Captured requests and sitemap]
E --> F[Agent proxy tools]
References: strix/…/session_manager.py• L297-314 strix/…/README.md• L25-32 docs/…/proxy.mdx• L73-76
Agent tool surface
The agent receives the proxy tools with its normal tool set. Root agents and child agents use the scan context that carries the scan's Caido resource, so they can work from the same captured traffic.
| Tool | Purpose |
|---|---|
list_requests | Search and sort captured requests with HTTPQL. HTTPQL is Caido's query language for request and response fields. |
view_request | Read a request or response, either as paged text or as compact search hits. |
repeat_request | Resend a captured request after changing its URL, parameters, headers, body, or cookies. |
list_sitemap | Browse Caido's tree of domains, paths, requests, and request variants. |
view_sitemap_entry | Inspect one sitemap item and its related recent requests. |
scope_rules | Create, inspect, update, or delete allow and deny rules that limit proxy results. |
The normal request workflow is:
- Generate traffic with the browser or another sandbox process.
- Find the captured request with
list_requestsor locate an endpoint inlist_sitemap. - Inspect the request or response with
view_request. - Use
repeat_requestfor a focused variation of the captured request.
References: strix/…/tools.py• L157-214 strix/…/tools.py• L291-324 strix/…/tools.py• L412-442 strix/…/tools.py• L492-524 strix/…/tools.py• L546-560 strix/…/tools.py• L574-619 strix/…/factory.py• L517-547
Caido integration
Runtime network boundary
Caido has two network views. Inside the sandbox it listens on a fixed local address. Outside the sandbox the runtime exposes that port at a host endpoint. The sandbox uses the first address for proxying and readiness checks. The host-side API client uses the second address for GraphQL calls.
This split keeps target traffic inside the sandbox while still allowing Strix to control Caido from the host process. It also gives the operator a host URL for interactive Caido access when the UI exposes it.
References: strix/…/session_manager.py• L297-336 strix/…/caido_bootstrap.py• L1-8 strix/…/state.py• L147-151 strix/…/utils.py• L453-459
API client access
The integration authenticates to Caido as a guest and selects a temporary project for the scan. The agent-facing wrappers resolve the scan's client from the run context before they call the API. If setup is still in progress, the wrapper waits for it. If no client is available, the tool returns a clear unavailable result instead of acting on a different scan.
The shared GraphQL connection is used one request at a time. This protects the client from concurrent calls when several agents or tool actions use the same scan resources. Sandbox Python scripts can also use the image-provided caido_api helpers for request search, inspection, replay, sitemap access, and scope work.
Proxy request IDs can also link a finding to captured traffic. Before reporting uses those links, the integration checks each ID against the current Caido project with a small existence query and retries once. If Caido does not answer in time, reporting keeps the IDs with an unverified warning instead of losing the finding's evidence.
References: strix/…/caido_bootstrap.py• L81-115 strix/…/tools.py• L54-111 strix/…/tools.py• L66-70 strix/…/caido_api.py• L92-127 strix/…/tool.py• L225-264 docs/…/proxy.mdx• L31-76
Scope and site map
Scopes reduce noise in the proxy view. An allowlist includes matching domains, and a denylist removes matching traffic even when it is allowed by the allowlist. An empty allowlist means that all domains are allowed. Agents can pass a scope to request and site-map queries when they need to focus on one target.
The sitemap presents captured traffic as a hierarchy. Agents start at domain roots, move through path groups, and then inspect request-level entries. This gives the agent a compact view of the attack surface before it reads full request bodies.
References: strix/…/tools.py• L492-524 strix/…/tools.py• L574-619 strix/…/caido_api.py• L639-726
Resource lifecycle
Bootstrap sequence
Caido setup runs in parallel with scan startup because the sidecar may need time before its GraphQL listener is ready. A CaidoBootstrapHandle is the shared handle for this in-flight setup. It lets the scan become usable while the first proxy consumer waits only when it needs the client.
The bootstrap follows this sequence:
- Start the sandbox with Caido's local proxy address in the process environment.
- Resolve the exposed Caido port for host-side access.
- Poll the in-sandbox GraphQL endpoint until guest login returns a token.
- Connect the host-side client and select a fresh temporary project.
- Resolve the handle on the first proxy use.
The diagram shows the boundary between scan startup and first proxy use.
sequenceDiagram
participant S as Scan session
participant H as Bootstrap handle
participant G as Caido in sandbox
participant C as Host Caido client
participant T as Agent proxy tool
S->>G: Start sidecar and proxy environment
S->>H: Start bootstrap task
S-->>T: Continue scan startup
T->>H: Request client at first proxy use
H->>G: Poll guest login
G-->>H: Return access token
H->>C: Connect and select temporary project
C-->>H: Ready client
H-->>T: Return scan client
References: strix/…/session_manager.py• L332-359 strix/…/caido_bootstrap.py• L32-78 strix/…/caido_bootstrap.py• L81-115 strix/…/caido_handle.py• L25-42
Scan resource boundary
The Caido handle belongs to one scan session. Cleanup first closes the handle, which either cancels unfinished setup or closes the connected client, and then removes the sandbox session. The temporary project, captured traffic, sitemap, scopes, and request identifiers therefore belong to that scan lifetime.
A caller timeout does not cancel shared bootstrap. In contrast, scan cleanup cancels bootstrap that is still in flight. This separates local tool failure from the final release of scan resources.
References: strix/…/caido_handle.py• L36-60 strix/…/session_manager.py• L363-391 strix/…/runner.py• L350-363
Operator access
The host endpoint can be shown in the scan status view so a person can open the same Caido instance while the scan runs. This supports live traffic review and manual replay without changing the agent's scan context.
References: docs/…/proxy.mdx• L107-126 strix/…/state.py• L147-151 strix/…/utils.py• L453-459
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the sandbox proxy address and the exposed host endpoint aligned. They serve different network boundaries and must not be swapped.
- Preserve the
caido_clientcontext contract between session creation, runner context construction, and every proxy tool. - Keep bootstrap cancellation safe at every await point. A client created before a failed or cancelled setup must still be closed.
- Treat the temporary project and its request, sitemap, and scope IDs as scan-scoped. Do not make them cross-scan cache keys.
- Keep proxy environment changes consistent with the shell and browser paths. Local control traffic must remain excluded from the proxy route.
- Keep request-ID checks lightweight and project-bound. A slow Caido check must warn about unverified evidence without dropping the IDs from a finding.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Caido is not ready when the sandbox starts | Guest login cannot return a token and proxy tools stay unavailable | Bootstrap retries the in-sandbox login request before reporting failure. |
| A proxy tool runs without a client in its run context | The agent receives no proxy data or replay result | The tool returns a structured client-unavailable result. |
| Two calls use the shared GraphQL transport at once | Caido can reject a call because the transport is already connected | The client creation and host-side proxy calls use locks. |
| Bootstrap fails or is cancelled after creating the client | A half-connected Caido transport can remain open | Bootstrap closes the client on setup failure, and scan cleanup closes the handle. |
| A caller times out while bootstrap is shared | One tool stops waiting, but other users could lose the shared setup if cancellation propagates | Handle resolution shields the shared bootstrap task from caller cancellation. |
| A scan ends while bootstrap is still running | The task can outlive the sandbox or leave a client behind | Cleanup cancels the handle before it deletes the sandbox session. |
| Caido is slow during request-ID verification | A finding can contain IDs that are not confirmed in the current project, so nonexistent IDs will not render as evidence | The check selects only each ID, retries once, and reporting keeps the IDs with an unverified warning when the project does not respond. |
Key files
| File | Why to read it |
|---|---|
| strix/…/session_manager.py | Shows how the scan creates the sandbox proxy route, exposes Caido, starts the bootstrap handle, and releases it. |
| strix/…/caido_bootstrap.py | Defines the guest login, readiness retry, client connection, and temporary project setup. |
| strix/…/caido_handle.py | Defines the boundary between asynchronous bootstrap and first proxy use. |
| strix/…/tools.py | Describes the agent-facing request, replay, sitemap, scope, and request-ID capabilities. |
| strix/…/caido_api.py | Shows the shared API boundary used by host tools and sandbox Python helpers. |
| strix/…/tool.py | Shows how captured request IDs become finding evidence and how slow verification is handled. |
| strix/…/factory.py | Shows where the proxy tools join the common tool set for scan agents. |
| docs/…/proxy.mdx | Gives the user-facing model for proxy capabilities, scripted access, and interactive Caido use. |