Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Caido integration
kali-mcp can drive Caido — a web security toolkit (intercepting proxy, Replay, HTTPQL history search, scope, workflows, findings). The goal: anything Caido can do, Vulnerator can do, without wrapping every operation by hand.
Tools
| Tool | What it does | Scope-guard |
|---|---|---|
caido_graphql |
Passthrough to Caido's entire public GraphQL API (Replay, scope, workflows, projects, intercept, findings, schema introspection…). Version-agnostic: if a query does not match the running Caido version, the server's GraphQL error is returned verbatim. | Partial. With scope.json active, documents that send traffic (Replay/Automate/workflows/intercept) are rejected and redirected to caido_request, because the destination is opaque inside a query. This is a best-effort denylist of send-capable fields (Caido's schema changes every release), not a proof. Without an active scope the passthrough is total. |
caido_request |
Sends an HTTP request to a target through Caido's Replay, waits for and returns the response: status_code, length, roundtrip_ms and the full raw response (headers + body, capped at max_response_bytes, default 20000, with raw_truncated). Traffic is logged in Caido (reproducible, searchable). Method, path and header names/values are validated (CR/LF/NUL are rejected, never sanitized) to prevent request injection. |
Yes — same gate as kali_run/kali_exec. The full scheme://host:port is validated, so allow, deny and ports in scope.json are all honored. Blocked requests send no traffic. |
caido_history |
Searches captured traffic with an HTTPQL expression (e.g. resp.code.eq:401, req.host.cont:"juice-shop"). Read-only. |
No (read-only) |
caido_automate |
Intruder/ffuf-style fuzzing: mark one injection point with § in the URL, a header or the body, give a payloads list, and Caido's Automate reissues the request once per payload, returning per-payload status_code/length/roundtrip_ms (differences are the signal). strategy ALL/SEQUENTIAL/PARALLEL/MATRIX, workers/delay. |
Yes — same gate as caido_request (full scheme://host:port); blocked = no traffic. |
caido_intercept |
Hold / list / read / edit-forward / drop proxy traffic. One tool, action: set (enable holding, optional HTTPQL filter), status, queue (list held), get (raw of a held entry), forward (unchanged, or an edited raw), drop, pause, resume. Operates on traffic going through Caido's proxy (see caido_proxy). |
No. Operates on requests already in flight; an edited Host on forward is not re-validated (documented). |
caido_proxy |
Route the Kali's own HTTP tool traffic (kali_run curl/nuclei/ffuf/sqlmap/wget) through Caido's proxy so it lands in Caido's history, and install Caido's CA for HTTPS. action: enable / status / disable. Opt-in at startup via CAIDO_PROXY_CAPTURE=1 (auto-retries until Caido is reachable). Only HTTP(S)_PROXY-aware clients are captured; raw-socket tools (nmap/masscan) are not. kali-mcp's own Caido calls are excluded via NO_PROXY (no loop). |
n/a (configures capture; the tools it captures keep their own gating) |
Known limitations
caido_graphqlscope filter is a heuristic over mutation verbs, not a proof: a send-capable field whose name has none of them would pass while a scope is active, and a harmless mutation that contains one is rejected. Blocked calls are not written to the findings store (the tool has noengagement_id), unlikecaido_request.- Response correlation matches the replayed request by method/host/port/path and a history-id baseline taken before sending. Other traffic to the same method+path+host going through Caido's proxy at the same moment (e.g. a browser pointed at it) could be mistaken for the replay's response.
- IPv6: IPv4-mapped IPv6 literals (
::ffff:a.b.c.d) are normalized to the IPv4 address before the scope check.scope_guarditself compares CIDRs only within one address family, which also affectskali_run; that is outside this change.
All data returned by Caido is untrusted: it is transported verbatim, never interpreted.
Deployment
The caido service in docker-compose.yml runs the official caido/caido image on the internal
docker network only (http://caido:8080, not published to the host), with a persistent named
volume and a one-shot caido-init that fixes the volume's ownership (Caido runs as uid 996).
No configuration is needed — the defaults work out of the box:
docker compose up -d --build
Proxy capture (opt-in)
Set CAIDO_PROXY_CAPTURE=1 in .env to route kali_run's HTTP-client traffic through Caido so it
is captured in the history (and interceptable). kali-mcp fetches Caido's per-instance CA from
http://caido:8080/ca.crt at startup and retries in the background until Caido is reachable (so
service start order does not matter), then injects HTTP(S)_PROXY into kali_run/kali_exec
subprocesses only — never the kali-mcp process itself — with NO_PROXY set to Caido's host to avoid a
loop. To also route the headless browser (playwright-mcp) through Caido, add
--proxy-server=http://caido:8080 and --ignore-https-errors to its command in docker-compose.yml
(the browser must trust or ignore Caido's CA). Raw-socket scanners (nmap/masscan) do not honor
HTTP_PROXY and are not captured.
Authentication (zero-touch by default)
Caido's API only serves schema introspection unauthenticated; every real operation needs a
Bearer token and a selected project. caido_client handles both:
- Token —
CAIDO_PAT/CAIDO_ACCESS_TOKENif set; otherwise theloginAsGuestmutation (the service starts with--allow-guests), which needs no account and no GUI. - Project — selects the first
READYproject, or creates one if there is none.
The session is cached, and renewed automatically (once) if Caido is recreated and the cached token/project go stale.
Security trade-off. --allow-guests means anything that can reach http://caido:8080 can obtain
a full-privilege token (read all captured traffic, send arbitrary Replay requests). "Not published
to the host" does not isolate Caido from other containers on the compose network — including a
deliberately vulnerable lab target, or an SSRF in one. That is fine for a local lab and for engagements
whose targets are external. If you run untrusted workloads on the same network, or publish the Caido
port, remove --allow-guests from the service command, set CAIDO_ALLOW_GUEST=0 and use a
CAIDO_PAT (mint it once through an SSH tunnel to the GUI). CAIDO_ALLOW_GUEST is fail-closed: only
1/true/yes/on (or empty) enable the guest login; anything else (0, no, off, typos) disables it.
CAIDO_PAT lives in the kali container's environment, so the agent can read it through kali_exec.
Failure modes are explicit, never faked: unauthenticated, unreachable, graphql_error,
timeout, failed. server_info reports the configured Caido URL and whether a token is set.
Schema versions
Caido states that its GraphQL schema changes on every release. The documents used by
caido_request / caido_history were verified end-to-end against Caido 0.59.0, which is the
default image tag (caido/caido:0.59.0). Override it with CAIDO_IMAGE to try another release;
caido_graphql keeps working across versions.
Verifying the integration
Bring up Caido plus the OWASP Juice Shop lab target (internal network only) and call the tools:
docker compose -f docker-compose.yml -f docker-compose.target.yml up -d caido juice-shop
Gotcha, already fixed in the compose file: Caido's own anti-DNS-rebinding protection rejects requests whose
Hostisn'tlocalhostby default (same mechanism asplaywright-mcp's--allowed-hosts). Thecaidoservice command passes--ui-domain caidoso it accepts the internal DNS name kali-mcp connects with; without it every call fails withunauthenticatedand Caido logsDomain caido not allowed.
Then, from an MCP client connected to kali-mcp: caido_request with url=http://juice-shop:3000/
(expect status_code: 200), a POST to /rest/user/login with bad credentials (expect 401),
and caido_history with resp.code.eq:401 (expect that login entry). With a scope.json that
does not allow juice-shop, caido_request must fail with SCOPE_VIOLATION and the history
count must not change.
Unit tests: docker/kali/tests/test_caido_client.py and test_caido_scope.py (stdlib-only; no
Caido or network needed).