Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / proxy-and-caido-integration

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.

ToolPurpose
list_requestsSearch and sort captured requests with HTTPQL. HTTPQL is Caido's query language for request and response fields.
view_requestRead a request or response, either as paged text or as compact search hits.
repeat_requestResend a captured request after changing its URL, parameters, headers, body, or cookies.
list_sitemapBrowse Caido's tree of domains, paths, requests, and request variants.
view_sitemap_entryInspect one sitemap item and its related recent requests.
scope_rulesCreate, inspect, update, or delete allow and deny rules that limit proxy results.

The normal request workflow is:

  1. Generate traffic with the browser or another sandbox process.
  2. Find the captured request with list_requests or locate an endpoint in list_sitemap.
  3. Inspect the request or response with view_request.
  4. Use repeat_request for 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:

  1. Start the sandbox with Caido's local proxy address in the process environment.
  2. Resolve the exposed Caido port for host-side access.
  3. Poll the in-sandbox GraphQL endpoint until guest login returns a token.
  4. Connect the host-side client and select a fresh temporary project.
  5. 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_client context 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

TriggerConsequenceGuard
Caido is not ready when the sandbox startsGuest login cannot return a token and proxy tools stay unavailableBootstrap retries the in-sandbox login request before reporting failure.
A proxy tool runs without a client in its run contextThe agent receives no proxy data or replay resultThe tool returns a structured client-unavailable result.
Two calls use the shared GraphQL transport at onceCaido can reject a call because the transport is already connectedThe client creation and host-side proxy calls use locks.
Bootstrap fails or is cancelled after creating the clientA half-connected Caido transport can remain openBootstrap closes the client on setup failure, and scan cleanup closes the handle.
A caller times out while bootstrap is sharedOne tool stops waiting, but other users could lose the shared setup if cancellation propagatesHandle resolution shields the shared bootstrap task from caller cancellation.
A scan ends while bootstrap is still runningThe task can outlive the sandbox or leave a client behindCleanup cancels the handle before it deletes the sandbox session.
Caido is slow during request-ID verificationA finding can contain IDs that are not confirmed in the current project, so nonexistent IDs will not render as evidenceThe check selects only each ID, retries once, and reporting keeps the IDs with an unverified warning when the project does not respond.

Key files

FileWhy to read it
strix/…/session_manager.pyShows how the scan creates the sandbox proxy route, exposes Caido, starts the bootstrap handle, and releases it.
strix/…/caido_bootstrap.pyDefines the guest login, readiness retry, client connection, and temporary project setup.
strix/…/caido_handle.pyDefines the boundary between asynchronous bootstrap and first proxy use.
strix/…/tools.pyDescribes the agent-facing request, replay, sitemap, scope, and request-ID capabilities.
strix/…/caido_api.pyShows the shared API boundary used by host tools and sandbox Python helpers.
strix/…/tool.pyShows how captured request IDs become finding evidence and how slow verification is handled.
strix/…/factory.pyShows where the proxy tools join the common tool set for scan agents.
docs/…/proxy.mdxGives the user-facing model for proxy capabilities, scripted access, and interactive Caido use.