Caido (headless instance on Kali, driven seat-side)
Caido is a Rust web-security proxy: one caido binary on the VM runs the instance
(server), serves the web GUI, and exposes the GraphQL API the GUI itself uses.
The agent drives it through two surfaces; the operator watches the same data in
the GUI at http://192.168.23.128:8082. Wiki: [[wiki/tools/caido]].
- caido-mode CLI (primary API surface): vendored at
skills/surface/caido/caido-mode/
(upstream github.com/caido/skills, MIT; reference clone raw/git/caido-skills).
SDK-based (@caido/sdk-client), run seat-side against the VM instance. Output is
JSON unless noted.
~/caido.sh on the VM (helper for lifecycle, fuzz batteries, ad hoc gql),
source of truth scripts/caido.sh.
Wiki
Hub: [[moc]] - Primary page: [[wiki/tools/caido]]
Anchors: [[burp-mcp]], [[api-testing]]
REFS: [[wiki/tools/caido]]
The box (already set up)
- Kali VM:
caido 0.58.3 at /usr/local/bin/caido, instance runs headless
(--no-open --allow-guests --listen 0.0.0.0:8082 --proxy-listen 0.0.0.0:8080),
log /tmp/caido.log, data ~/.local/share/caido/ (SQLite, projects live here).
- Claimed by the account (instance name
kali-vm); Pro features active.
- Project
default selected. A project MUST be selected or the proxy 500s every
request ("Could not acquire a connection to the database"). Per engagement create
- select a fresh project (
~/caido.sh project <name> or CLI projects /
select-project) to isolate traffic.
- Ports: GUI/GraphQL
8082, proxy 8080, both reachable from the host. Note the
proxy address DIFFERS from the API URL here (upstream defaults proxy = API URL),
so the stored instance proxy entry or --proxy is load-bearing.
- MITM HTTPS:
curl -k through the proxy, or import Caido's CA
(Settings -> Certificates) into the client.
caido-mode CLI: install + auth (one-time per seat)
cd skills/surface/caido/caido-mode && npm install # node_modules is gitignored; node 22 works
Full command reference lives in the CLI itself: npx tsx caido-client.ts --help
(and <cmd> --help per command); the upstream SKILL.md/README were deliberately
not vendored. Seat note: the caido-mode non-.md files arrive via git clone only
(Obsidian sync carries .md alone), so a synced seat needs a git pull of the
vault repo before npm install works.
Auth lives in ~/.claude/config/secrets.json under .caido, keyed by instance URL
(.caido.default, .caido.instances[<url>] = {pat, proxy, cachedToken}).
- Durable (preferred): PAT. Operator creates one in the GUI
(Dashboard -> Developer -> Personal Access Tokens), then:
npx tsx caido-client.ts setup <pat> http://192.168.23.128:8082 --proxy http://192.168.23.128:8080
(validates via device-code flow, caches token + proxy).
- Quick prime (no PAT): reuse the VM's GUI bearer token, valid ~7 days:
TOK=$(bash /root/vm.sh 'cat ~/.caido-token' | tr -d "[:space:]")
F="$HOME/.claude/config/secrets.json"; mkdir -p "$HOME/.claude/config"; [ -f "$F" ] || echo '{}' > "$F"
jq --arg tok "$TOK" '.caido = {default: "http://192.168.23.128:8082", instances: {"http://192.168.23.128:8082": {proxy: "http://192.168.23.128:8080", cachedToken: {accessToken: $tok, expiresAt: ((now + 518400) | todateiso8601)}}}}' "$F" > "$F.tmp" && mv "$F.tmp" "$F"
- Verify with
npx tsx caido-client.ts auth-status (prints activeUrl, proxy,
authMode, token expiry). health checks the instance without auth.
- Env overrides:
CAIDO_URL, CAIDO_PAT, CAIDO_PROXY.
- VM-side
~/caido.sh token refresh (localStorage re-extract via
scripts/browser.sh + chrome-devtools) is unchanged and fixes both surfaces.
- Re-extract field notes (2026-10 re-prime): localStorage key is
CAIDO_AUTHENTICATION (JSON with .accessToken), NOT CAIDO_AUTHINATION as the
wiki once said. Headless flow: browser.sh start (needs sshpass -> run it from WSL
root when the seat lacks it), then drive CDP at 127.0.0.1:9222 with a node script:
/json/new?url= does NOT navigate on Chrome 138 - always send an explicit
Page.navigate over the tab websocket. If the GUI lands on #/login, click
"Continue as guest" via Runtime.evaluate; the fresh token (exp = now+7d) then sits
in localStorage. Gotcha: wsl.exe ... bash -c 'X=$(cmd)' silently returns EMPTY for
command substitution (Windows-launched WSL pipe EOF) - put multi-step pipelines in
a script file and run wsl.exe bash /mnt/c/.../script.sh instead. Write the token
VM-side as base64-into-command (printf %s <b64> | base64 -d > ~/.caido-token) so
the value never enters the transcript.
- Seat gap:
skills/surface/caido/caido-mode/ can be absent seat-side (git carries
only .md; origin fetch may fail publickey). Fall back to VM-side ~/caido.sh gql
for verification; replay sessions need createReplaySession + startReplayTask +
renameReplaySession(id, name) (create input has NO name field; mutation root is
MutationRoot, and renameReplaySession returns a RenameReplaySessionPayload
with a session field).
Operating doctrine (two modes, kept strictly separate)
- Testing -> curl, proxied through Caido. Find a real authenticated request in
History, cache its auth ONCE into a reusable curl config
(
export-curl <id> --config), then probe with
curl -K /tmp/caido/<host>/auth.cfg "$BASE/path". The config carries the proxy,
so every probe lands in History.
- Handoff -> named Replay sessions in named collections. When the operator
needs to SEE a request (a PoC, a chain step), materialize it as a named session.
This is the Caido equivalent of a Burp Repeater tab: probing stays in
History, load-bearing requests get promoted to Replay.
Hard rules:
- All target traffic goes through the Caido proxy. Never curl a target directly
off-proxy; the operator must be able to see every request. Exception: high-volume
brute/fuzz traffic (100+ requests) stays OFF the proxy (history bloat + VM CPU):
use the
~/caido.sh fuzz battery lane or Skill(fuzz), then bring interesting
hits back through the proxy / promote to Replay.
- Cache auth in files, don't re-paste it. One
export-curl --config per target;
the big cookie/token blob never enters the transcript.
- Operator PoCs are FULL self-contained curls (all headers inline, via
export-curl <id>), never a curl -K /tmp/... line; the config is internal.
- Replay session names are mandatory; collections for multi-request handoffs;
refer to sessions/collections by NAME, not id.
- Promote EVERY load-bearing request of a chain as it lands (each foothold,
pivot, privesc step; not just the first bypass), all into one named collection.
A chain closed with a single Replay entry is an incomplete handoff.
- Credential values stay in the proxy capture / config file, never in a vault file.
Primary workflow (do this by default)
Run from skills/surface/caido/caido-mode/; npx tsx caido-client.ts <cmd> below.
# 1. Find a base request that already has the auth/cookies you need.
npx tsx caido-client.ts search 'req.host.cont:"target.com" AND req.path.cont:"/api/user"' --compact
# -> 8431 200 GET target.com/api/user/me
# 2. ONCE per target: cache its auth into a reusable curl config.
npx tsx caido-client.ts export-curl 8431 --config
# -> /tmp/caido/target.com/auth.cfg (proxy + insecure + compressed + ALL auth
# headers + inline static cookies) and prints BASE + captured header list
# 3. Probe. -K carries proxy + auth, so it goes through Caido into History.
BASE=https://target.com
curl -K /tmp/caido/target.com/auth.cfg "$BASE/api/user/999"
curl -K /tmp/caido/target.com/auth.cfg -X POST "$BASE/api/profile" \
-H 'Content-Type: application/json' --data-binary @/tmp/caido/target.com/body.json
Confirm a probe landed: search 'req.host.cont:"target.com"' --limit 5 --compact.
The config is a faithful STATIC snapshot
- All auth/identity headers, not an allowlist. Modern apps gate on
app-specific headers (
X-*-Validation, Origin, Referer, Sec-*); a curated
subset silently 403s. Only per-request/volatile headers are dropped: Host,
Content-Length, Content-Type, Connection, Accept-Encoding.
- Content-Type is dropped, so pass it yourself on every POST/PUT/PATCH
(
-H 'Content-Type: application/json' or whatever the endpoint expects; a wrong
one is the classic cause of opaque 400/403). Never add Content-Length; curl does it.
- Static cookies, no jar. Response
Set-Cookie rotation never overwrites the
captured-good cookies. Opt in to rotation with --config --cookie-jar.
- Lazy refresh: on 401/403/login-redirect, re-run
export-curl <fresh-id> --config.
- Drop one header:
--exclude <name> (repeatable); --exclude cookie when an M&R
rule injects auth instead.
- Path traversal tests need
curl --path-as-is or curl collapses ../ and
/./ client-side and the payload never reaches the server. Add -g if the URL
contains [ ] { } curl would interpret.
- Per-target scratch dir
/tmp/caido/<host>/ holds auth.cfg, bodies, notes.
- Alternative: a Match & Replace rule can inject auth on all proxied traffic, then
curl -x <proxy> -k "$BASE/path" needs no headers at all (see M&R).
History + Replay commands
npx tsx caido-client.ts search '<httpql>' --compact --limit 50 # newest first
npx tsx caido-client.ts recent --compact # newest, no filter
npx tsx caido-client.ts get 8431 --compact # full detail
npx tsx caido-client.ts get-response 8431 --compact
npx tsx caido-client.ts raw 8431 --out /tmp/caido/target.com/body.json # byte-exact dump
npx tsx caido-client.ts export-curl 8431 # FULL curl, for the operator
# Handoff sessions (names mandatory; CRLF auto-normalized from raw files)
npx tsx caido-client.ts create-session 8431 --name "IDOR /api/user/:id"
npx tsx caido-client.ts send-raw --host target.com --raw @/tmp/req.txt --name "crafted repro"
npx tsx caido-client.ts sessions ; collections
npx tsx caido-client.ts rename-session "old" "new" ; move-session "<name>" "<collection>"
# Edit + send (preserves cookies/auth; requires --nonach or --new-name)
npx tsx caido-client.ts edit 8431 --path /api/user/999 --name "IDOR victim 999"
npx tsx caido-client.ts edit-session "IDOR victim 999" --body '{"role":"admin"}' --nonach
# Inspect an open replay tab (by name or id)
npx tsx caido-client.ts get-session "IDOR victim 999" --compact
npx tsx caido-client.ts replay-entries "IDOR victim 999" --limit 20
edit supports --method --path --set-header --remove-header --body (auto
Content-Length) --replace <from>:::<to> and connection overrides
(--sni --connect-host --connect-port ...) for v-host/upstream routing tests.
- Collections: query FIRST (
collections), never auto-create. One reproduced
request -> default collection, just name the session. Multi-request chain ->
Vuln chain - <description> with steps named 1. ..., 2. .... Endpoints from
one JS file -> JS File Endpoints; from a spec -> Swagger - <filename>.
- Evidence pairs:
raw <id> --out (or VM ~/caido.sh raw <id> req|resp) ->
targets/<eng>/poc/ (verbatim source), same policy as the evidence skill
(skills/workflow/closeout/evidence - merge into report/findings in phase 2; still at this path).
create-finding <id> --title ... --description ... logs confirmed finds in the
project so they surface in the GUI Findings tab alongside evidence-skill finding cards.
Match & Replace (tamper rules)
Rewrites requests/responses automatically as they pass through Caido. Killer use:
inject auth at the proxy, so probe curls carry no headers at all.
A rule = section x operation x matcher x replacer, optional HTTPQL --condition
and --sources:
| Piece |
Choices |
| section |
req: req-method req-path req-query req-body req-first-line req-header req-all req-sni ; resp: resp-body resp-status resp-first-line resp-header resp-all ; ws: ws-up ws-down |
| operation |
raw (match within section) ; update/add/remove (header + query only, by name) |
| matcher |
--match-value <s> / --match-regex <re> / --match-full / --match-name <n> |
| replacer |
--replace <term> (literal, "" allowed) / --workflow <id> |
# Preview without creating anything:
npx tsx caido-client.ts test-mr-rule --section req-header --operation add \
--match-name X-Test --replace hi --raw 'GET / HTTP/1.1\r\nHost: t.com\r\n\r\n'
# Inject auth on all proxied requests to one host, then enable:
ID=$(npx tsx caido-client.ts create-mr-rule --section req-header --operation add \
--match-name Authorization --replace "Bearer eyJ..." \
--condition 'req.host.eq:"target.com"' --name "auth inject" | jq -r '.created.id')
npx tsx caido-client.ts toggle-mr-rule "$ID" --on
npx tsx caido-client.ts mr-rules ; toggle-mr-rule <id> --off ; delete-mr-rule <id>
Gotchas: new rules are created DISABLED (toggle-mr-rule <id> --on); default
sources is INTERCEPT (proxy traffic) so add --sources REPLAY,... to broaden;
default collection is Caido's "Default Collection". For minified JS use
--match-regex anchored to structurally stable neighbours (string literals, JSON
keys), NOT --match-value on a minified identifier, since those rotate every
deploy and the rule silently stops matching.
HTTPQL reference
<ns>.<field>.<op>:"<value>"; string values MUST be quoted, integers are NOT.
There is no NOT operator: use the negated ops ne, ncont, nlike,
nregex.
| Namespace |
Field |
Type |
Meaning |
req |
ext host method path query raw |
string |
request parts (ext includes .) |
req |
port len |
int |
port, body length |
req |
created_at tls |
date/bool |
timestamp, HTTPS |
resp |
raw |
string |
full raw response |
resp |
code len roundtrip |
int |
status, body length, ms |
row |
id |
int |
request id |
source |
- |
special |
intercept replay automate workflow |
preset |
- |
special |
saved filter preset name |
Operators: string eq ne cont ncont like nlike regex nregex; int
eq ne gt gte lt lte; bool eq ne; combine with AND/OR and parentheses.
req.method.eq:"POST" AND resp.code.eq:200
req.host.cont:".target.com" AND resp.code.gte:500
"password" OR "secret" OR "api_key" # bare strings search req+resp raw
resp.len.gt:100000 # large responses
req.path.regex:"/(login|auth|signin|oauth)/"
source:"replay" OR source:"intercept"
req.created_at.gt:"2026-01-01T00:00:00Z"
req.path.ncont:"/static" # exclusion without NOT
Full reference: docs.caido.io/app/reference/httpql.
~/caido.sh (VM-local helper, over vm.sh)
bash /root/vm.sh '~/caido.sh status' # process + ui + proxy + token-valid
bash /root/vm.sh '~/caido.sh start' # detached; auto-skips if running
bash /root/vm.sh '~/caido.sh stop'
bash /root/vm.sh '~/caido.sh history "req.host.eq:\"target.com\"" 20'
bash /root/vm.sh '~/caido.sh raw 15 resp'
bash /root/vm.sh '~/caido.sh send /tmp/req.txt target.com 443 1' # Replay send
bash /root/vm.sh '~/caido.sh cookies target.com'
bash /root/vm.sh '~/caido.sh project' # list + selected; 'project <n>' create+select
bash /root/vm.sh '~/caido.sh gql "<query>" "<vars-json>"'
Source of truth scripts/caido.sh; re-push with (vm.sh does not forward
stdin, so ship the bytes inside the command):
B64=$(base64 -w0 scripts/caido.sh); bash /root/vm.sh "echo $B64 | base64 -d > ~/caido.sh && chmod +x ~/caido.sh".
Schema drifts between releases (0.58.3: startReplayTask(sessionId) takes NO input;
replayEntry needs the ReplayEntryHttp fragment). On a field error, introspect
first (__type(name:"...")), or check github.com/caido/schemas; do not trust older
doc snippets. The SDK CLI absorbs most of this; gql is the escape hatch.
Fuzz batteries (request-variation through Replay)
~/caido.sh fuzz <template> <payloads> <host> [port] [tls] [delay]: template =
full HTTP/1.1 request with {{PAYLOAD}} marker(s), payloads one per line; each
variant is its own Replay session (operator-visible); output STATUS bytes session payload per line, triage by differential. Authenticated batteries carry
{{COOKIE}} and refuse unless CAIDO_COOKIE is set
(CAIDO_COOKIE="$(~/caido.sh cookies target.com)"); one-command wrapper
bash scripts/caido-battery.sh target.com pays.txt.
Battery doctrine (one variation per run, 60-payload/0.3s bounds, RoE:
shape variation NEVER cred spraying, bash-native payload pre-encoding)
is owned BY REFERENCE by Skill(fuzz) - do not restate it here.
Caido-side specifics only: end-to-end authed lane = browser through
the proxy -> cookies <host> -> battery -> Autorize plugin diffs
triplets = IDOR lane ([[hunt-idor]]). Recon-phase variation routes
here when scanners are RoE-barred (serial, bounded, visible beats a
banned ffuf); where wordlist scanners are permitted, Skill(fuzz)
stays primary. Automate (CLI create-automate-session <id> then configure payloads in the GUI) is the Caido-native equivalent.
Caido-native workflow (GUI concepts)
- Proxying traffic: point any client at
192.168.23.128:8080 (curl -kx,
chromium proxy). Everything lands in History of the selected project.
- Scopes / Filters: scope preset from
targets/<eng>/scope.md
(create-scope "Target" --allow "*.target.com" --deny "*.cdn..."), filter
presets via create-filter "name" --query '<httpql>' --alias <short> then
search 'preset:"<alias>"'. Scoping inside Caido does NOT replace the RoE
scope-guard (API calls are invisible to it; you own the check).
- Environments / hosted Files: per-engagement vars + wordlists, referenced as
{{env.VAR}} in Replay; create-env, env-set <env> <var> <val>.
- Workflows (preprocessors, can emit Findings) and Exports (requests to
files for the report): GUI; raw pairs still go to
targets/<eng>/poc/.
- Plugins (Pro): install headless via gql
installPluginPackage(input: {source: {url: <release-zip>}}), toggle with
togglePlugin(id, enabled). Worth it: Scanner (passive mode adds ZERO target
requests, RoE-safe) and Autorize (IDOR triplets; needs one authenticated
session). Shift (BYO-key LLM) is redundant when the agent is the LLM lane.
- Intercept:
intercept-status / intercept-enable / intercept-disable
(rarely wanted: the agent works from History, not a held queue).
Output control + gotchas
--compact = --no-request --max-body 50 --max-body-chars 5000; also
--max-body <n> / --max-body-chars <n> (0 = unlimited), --headers-only.
Browse with --compact; get/export-curl only the request you work from.
search is NEWEST FIRST; --limit N = newest N matches. Never fetch a big
window and re-sort client-side (you only sort the truncated window); let Caido
order. recent takes no filter.
- Do NOT batch CLI calls inside
while/for loops (PATH can get stripped in loop
subshells and the body fails silently); one top-level command each, or a
standalone script with an explicit export PATH.
search --ids-only returns a JSON array (["123"]): unwrap with
jq -r '.[0]'.
Error handling
- Auth errors /
No Caido auth found -> auth-status; re-setup <pat>, or
re-prime from the VM token (above).
- Probes turn 401/403/login-redirect -> token aged out; regenerate the config from
a fresh history id.
- Proxy connect refused ->
health; if down, bash /root/vm.sh '~/caido.sh start'.
- gql field errors -> schema drifted; introspect (see
~/caido.sh section).
Relation to Burp
Burp stays the primary transport when its MCP is up ([[hunt-burp]]). Reach for
Caido when: Burp/MCP is down, you want a per-engagement isolated project, the
target needs Automate-style bulk runs, or the operator prefers the lighter GUI.
Same discipline either way: load-bearing requests must be visible to the operator
(Replay entries here, Repeater tabs there), never silent background curl.
1---2name: caido3description: "Caido stands in for Burp on the Kali VM: a headless proxy driven over the caido-mode CLI and `~/caido.sh` (HTTPQL history triage, proxied curl probes, Replay handoff, Match & Replace, Automate, fuzz). Use when Burp/MCP is down or for isolated per-engagement projects."4metadata:5 source: https://skillmd.com/skills/encod3d-sec/caido6 hermes:7 tags: [caido, proxy, httpql, replay]8 related_skills: [hunt-burp, hunt-idor, fuzz]9---1011# Caido (headless instance on Kali, driven seat-side)1213Caido is a Rust web-security proxy: one `caido` binary on the VM runs the instance14(server), serves the web GUI, and exposes the GraphQL API the GUI itself uses.15The agent drives it through two surfaces; the operator watches the same data in16the GUI at http://192.168.23.128:8082. Wiki: [[wiki/tools/caido]].17181. **caido-mode CLI** (primary API surface): vendored at `skills/surface/caido/caido-mode/`19 (upstream github.com/caido/skills, MIT; reference clone `raw/git/caido-skills`).20 SDK-based (`@caido/sdk-client`), run seat-side against the VM instance. Output is21 JSON unless noted.222. **`~/caido.sh`** on the VM (helper for lifecycle, fuzz batteries, ad hoc gql),23 source of truth `scripts/caido.sh`.2425## Wiki2627Hub: [[moc]] - Primary page: [[wiki/tools/caido]]28Anchors: [[burp-mcp]], [[api-testing]]29**REFS:** [[wiki/tools/caido]]3031## The box (already set up)3233- Kali VM: `caido` 0.58.3 at `/usr/local/bin/caido`, instance runs headless34 (`--no-open --allow-guests --listen 0.0.0.0:8082 --proxy-listen 0.0.0.0:8080`),35 log `/tmp/caido.log`, data `~/.local/share/caido/` (SQLite, projects live here).36- Claimed by the account (instance name `kali-vm`); Pro features active.37- **Project `default` selected. A project MUST be selected or the proxy 500s every38 request ("Could not acquire a connection to the database").** Per engagement create39 + select a fresh project (`~/caido.sh project <name>` or CLI `projects` /40 `select-project`) to isolate traffic.41- Ports: GUI/GraphQL `8082`, proxy `8080`, both reachable from the host. Note the42 proxy address DIFFERS from the API URL here (upstream defaults proxy = API URL),43 so the stored instance `proxy` entry or `--proxy` is load-bearing.44- MITM HTTPS: `curl -k` through the proxy, or import Caido's CA45 (Settings -> Certificates) into the client.4647## caido-mode CLI: install + auth (one-time per seat)4849```50cd skills/surface/caido/caido-mode && npm install # node_modules is gitignored; node 22 works51```5253Full command reference lives in the CLI itself: `npx tsx caido-client.ts --help`54(and `<cmd> --help` per command); the upstream SKILL.md/README were deliberately55not vendored. Seat note: the caido-mode non-.md files arrive via git clone only56(Obsidian sync carries `.md` alone), so a synced seat needs a `git pull` of the57vault repo before `npm install` works.5859Auth lives in `~/.claude/config/secrets.json` under `.caido`, keyed by instance URL60(`.caido.default`, `.caido.instances[<url>] = {pat, proxy, cachedToken}`).6162- **Durable (preferred): PAT.** Operator creates one in the GUI63 (Dashboard -> Developer -> Personal Access Tokens), then:64 `npx tsx caido-client.ts setup <pat> http://192.168.23.128:8082 --proxy http://192.168.23.128:8080`65 (validates via device-code flow, caches token + proxy).66- **Quick prime (no PAT):** reuse the VM's GUI bearer token, valid ~7 days:6768```69TOK=$(bash /root/vm.sh 'cat ~/.caido-token' | tr -d "[:space:]")70F="$HOME/.claude/config/secrets.json"; mkdir -p "$HOME/.claude/config"; [ -f "$F" ] || echo '{}' > "$F"71jq --arg tok "$TOK" '.caido = {default: "http://192.168.23.128:8082", instances: {"http://192.168.23.128:8082": {proxy: "http://192.168.23.128:8080", cachedToken: {accessToken: $tok, expiresAt: ((now + 518400) | todateiso8601)}}}}' "$F" > "$F.tmp" && mv "$F.tmp" "$F"72```7374- Verify with `npx tsx caido-client.ts auth-status` (prints activeUrl, proxy,75 authMode, token expiry). `health` checks the instance without auth.76- Env overrides: `CAIDO_URL`, `CAIDO_PAT`, `CAIDO_PROXY`.77- VM-side `~/caido.sh` token refresh (localStorage re-extract via78 `scripts/browser.sh` + chrome-devtools) is unchanged and fixes both surfaces.79- Re-extract field notes (2026-10 re-prime): localStorage key is80 `CAIDO_AUTHENTICATION` (JSON with `.accessToken`), NOT `CAIDO_AUTHINATION` as the81 wiki once said. Headless flow: `browser.sh start` (needs sshpass -> run it from WSL82 root when the seat lacks it), then drive CDP at `127.0.0.1:9222` with a node script:83 `/json/new?url=` does NOT navigate on Chrome 138 - always send an explicit84 `Page.navigate` over the tab websocket. If the GUI lands on `#/login`, click85 "Continue as guest" via Runtime.evaluate; the fresh token (exp = now+7d) then sits86 in localStorage. Gotcha: `wsl.exe ... bash -c 'X=$(cmd)'` silently returns EMPTY for87 command substitution (Windows-launched WSL pipe EOF) - put multi-step pipelines in88 a script file and run `wsl.exe bash /mnt/c/.../script.sh` instead. Write the token89 VM-side as base64-into-command (`printf %s <b64> | base64 -d > ~/.caido-token`) so90 the value never enters the transcript.91- Seat gap: `skills/surface/caido/caido-mode/` can be absent seat-side (git carries92 only `.md`; origin fetch may fail publickey). Fall back to VM-side `~/caido.sh gql`93 for verification; replay sessions need `createReplaySession` + `startReplayTask` +94 `renameReplaySession(id, name)` (create input has NO name field; mutation root is95 `MutationRoot`, and `renameReplaySession` returns a `RenameReplaySessionPayload`96 with a `session` field).9798## Operating doctrine (two modes, kept strictly separate)991001. **Testing -> curl, proxied through Caido.** Find a real authenticated request in101 History, cache its auth ONCE into a reusable curl config102 (`export-curl <id> --config`), then probe with103 `curl -K /tmp/caido/<host>/auth.cfg "$BASE/path"`. The config carries the proxy,104 so every probe lands in History.1052. **Handoff -> named Replay sessions in named collections.** When the operator106 needs to SEE a request (a PoC, a chain step), materialize it as a named session.107 This is the Caido equivalent of a Burp Repeater tab: probing stays in108 History, load-bearing requests get promoted to Replay.109110Hard rules:111112- **All target traffic goes through the Caido proxy.** Never curl a target directly113 off-proxy; the operator must be able to see every request. Exception: high-volume114 brute/fuzz traffic (100+ requests) stays OFF the proxy (history bloat + VM CPU):115 use the `~/caido.sh fuzz` battery lane or `Skill(fuzz)`, then bring interesting116 hits back through the proxy / promote to Replay.117- **Cache auth in files, don't re-paste it.** One `export-curl --config` per target;118 the big cookie/token blob never enters the transcript.119- **Operator PoCs are FULL self-contained curls** (all headers inline, via120 `export-curl <id>`), never a `curl -K /tmp/...` line; the config is internal.121- **Replay session names are mandatory**; collections for multi-request handoffs;122 refer to sessions/collections by NAME, not id.123- **Promote EVERY load-bearing request of a chain as it lands** (each foothold,124 pivot, privesc step; not just the first bypass), all into one named collection.125 A chain closed with a single Replay entry is an incomplete handoff.126- Credential values stay in the proxy capture / config file, never in a vault file.127128## Primary workflow (do this by default)129130Run from `skills/surface/caido/caido-mode/`; `npx tsx caido-client.ts <cmd>` below.131132```133# 1. Find a base request that already has the auth/cookies you need.134npx tsx caido-client.ts search 'req.host.cont:"target.com" AND req.path.cont:"/api/user"' --compact135# -> 8431 200 GET target.com/api/user/me136137# 2. ONCE per target: cache its auth into a reusable curl config.138npx tsx caido-client.ts export-curl 8431 --config139# -> /tmp/caido/target.com/auth.cfg (proxy + insecure + compressed + ALL auth140# headers + inline static cookies) and prints BASE + captured header list141142# 3. Probe. -K carries proxy + auth, so it goes through Caido into History.143BASE=https://target.com144curl -K /tmp/caido/target.com/auth.cfg "$BASE/api/user/999"145curl -K /tmp/caido/target.com/auth.cfg -X POST "$BASE/api/profile" \146 -H 'Content-Type: application/json' --data-binary @/tmp/caido/target.com/body.json147```148149Confirm a probe landed: `search 'req.host.cont:"target.com"' --limit 5 --compact`.150151### The config is a faithful STATIC snapshot152153- **All auth/identity headers, not an allowlist.** Modern apps gate on154 app-specific headers (`X-*-Validation`, `Origin`, `Referer`, `Sec-*`); a curated155 subset silently 403s. Only per-request/volatile headers are dropped: `Host`,156 `Content-Length`, `Content-Type`, `Connection`, `Accept-Encoding`.157- **Content-Type is dropped, so pass it yourself on every POST/PUT/PATCH**158 (`-H 'Content-Type: application/json'` or whatever the endpoint expects; a wrong159 one is the classic cause of opaque 400/403). Never add Content-Length; curl does it.160- **Static cookies, no jar.** Response `Set-Cookie` rotation never overwrites the161 captured-good cookies. Opt in to rotation with `--config --cookie-jar`.162- **Lazy refresh:** on 401/403/login-redirect, re-run `export-curl <fresh-id> --config`.163- Drop one header: `--exclude <name>` (repeatable); `--exclude cookie` when an M&R164 rule injects auth instead.165- **Path traversal tests need `curl --path-as-is`** or curl collapses `../` and166 `/./` client-side and the payload never reaches the server. Add `-g` if the URL167 contains `[ ] { }` curl would interpret.168- Per-target scratch dir `/tmp/caido/<host>/` holds `auth.cfg`, bodies, notes.169- Alternative: a Match & Replace rule can inject auth on all proxied traffic, then170 `curl -x <proxy> -k "$BASE/path"` needs no headers at all (see M&R).171172## History + Replay commands173174```175npx tsx caido-client.ts search '<httpql>' --compact --limit 50 # newest first176npx tsx caido-client.ts recent --compact # newest, no filter177npx tsx caido-client.ts get 8431 --compact # full detail178npx tsx caido-client.ts get-response 8431 --compact179npx tsx caido-client.ts raw 8431 --out /tmp/caido/target.com/body.json # byte-exact dump180npx tsx caido-client.ts export-curl 8431 # FULL curl, for the operator181182# Handoff sessions (names mandatory; CRLF auto-normalized from raw files)183npx tsx caido-client.ts create-session 8431 --name "IDOR /api/user/:id"184npx tsx caido-client.ts send-raw --host target.com --raw @/tmp/req.txt --name "crafted repro"185npx tsx caido-client.ts sessions ; collections186npx tsx caido-client.ts rename-session "old" "new" ; move-session "<name>" "<collection>"187188# Edit + send (preserves cookies/auth; requires --nonach or --new-name)189npx tsx caido-client.ts edit 8431 --path /api/user/999 --name "IDOR victim 999"190npx tsx caido-client.ts edit-session "IDOR victim 999" --body '{"role":"admin"}' --nonach191192# Inspect an open replay tab (by name or id)193npx tsx caido-client.ts get-session "IDOR victim 999" --compact194npx tsx caido-client.ts replay-entries "IDOR victim 999" --limit 20195```196197- `edit` supports `--method --path --set-header --remove-header --body` (auto198 Content-Length) `--replace <from>:::<to>` and connection overrides199 (`--sni --connect-host --connect-port ...`) for v-host/upstream routing tests.200- Collections: query FIRST (`collections`), never auto-create. One reproduced201 request -> default collection, just name the session. Multi-request chain ->202 `Vuln chain - <description>` with steps named `1. ...`, `2. ...`. Endpoints from203 one JS file -> `JS File Endpoints`; from a spec -> `Swagger - <filename>`.204- Evidence pairs: `raw <id> --out` (or VM `~/caido.sh raw <id> req|resp`) ->205 `targets/<eng>/poc/` (verbatim source), same policy as the evidence skill206 (skills/workflow/closeout/evidence - merge into report/findings in phase 2; still at this path).207- `create-finding <id> --title ... --description ...` logs confirmed finds in the208 project so they surface in the GUI Findings tab alongside evidence-skill finding cards.209210## Match & Replace (tamper rules)211212Rewrites requests/responses automatically as they pass through Caido. Killer use:213inject auth at the proxy, so probe curls carry no headers at all.214215A rule = section x operation x matcher x replacer, optional HTTPQL `--condition`216and `--sources`:217218| Piece | Choices |219|-------|---------|220| section | req: `req-method req-path req-query req-body req-first-line req-header req-all req-sni` ; resp: `resp-body resp-status resp-first-line resp-header resp-all` ; ws: `ws-up ws-down` |221| operation | `raw` (match within section) ; `update`/`add`/`remove` (header + query only, by name) |222| matcher | `--match-value <s>` / `--match-regex <re>` / `--match-full` / `--match-name <n>` |223| replacer | `--replace <term>` (literal, `""` allowed) / `--workflow <id>` |224225```226# Preview without creating anything:227npx tsx caido-client.ts test-mr-rule --section req-header --operation add \228 --match-name X-Test --replace hi --raw 'GET / HTTP/1.1\r\nHost: t.com\r\n\r\n'229230# Inject auth on all proxied requests to one host, then enable:231ID=$(npx tsx caido-client.ts create-mr-rule --section req-header --operation add \232 --match-name Authorization --replace "Bearer eyJ..." \233 --condition 'req.host.eq:"target.com"' --name "auth inject" | jq -r '.created.id')234npx tsx caido-client.ts toggle-mr-rule "$ID" --on235236npx tsx caido-client.ts mr-rules ; toggle-mr-rule <id> --off ; delete-mr-rule <id>237```238239Gotchas: new rules are created DISABLED (`toggle-mr-rule <id> --on`); default240sources is `INTERCEPT` (proxy traffic) so add `--sources REPLAY,...` to broaden;241default collection is Caido's "Default Collection". For minified JS use242`--match-regex` anchored to structurally stable neighbours (string literals, JSON243keys), NOT `--match-value` on a minified identifier, since those rotate every244deploy and the rule silently stops matching.245246## HTTPQL reference247248`<ns>.<field>.<op>:"<value>"`; string values MUST be quoted, integers are NOT.249**There is no `NOT` operator**: use the negated ops `ne`, `ncont`, `nlike`,250`nregex`.251252| Namespace | Field | Type | Meaning |253|-----------|-------|------|---------|254| `req` | `ext` `host` `method` `path` `query` `raw` | string | request parts (ext includes `.`) |255| `req` | `port` `len` | int | port, body length |256| `req` | `created_at` `tls` | date/bool | timestamp, HTTPS |257| `resp` | `raw` | string | full raw response |258| `resp` | `code` `len` `roundtrip` | int | status, body length, ms |259| `row` | `id` | int | request id |260| `source` | - | special | `intercept` `replay` `automate` `workflow` |261| `preset` | - | special | saved filter preset name |262263Operators: string `eq ne cont ncont like nlike regex nregex`; int264`eq ne gt gte lt lte`; bool `eq ne`; combine with `AND`/`OR` and parentheses.265266```267req.method.eq:"POST" AND resp.code.eq:200268req.host.cont:".target.com" AND resp.code.gte:500269"password" OR "secret" OR "api_key" # bare strings search req+resp raw270resp.len.gt:100000 # large responses271req.path.regex:"/(login|auth|signin|oauth)/"272source:"replay" OR source:"intercept"273req.created_at.gt:"2026-01-01T00:00:00Z"274req.path.ncont:"/static" # exclusion without NOT275```276277Full reference: docs.caido.io/app/reference/httpql.278279## `~/caido.sh` (VM-local helper, over vm.sh)280281```282bash /root/vm.sh '~/caido.sh status' # process + ui + proxy + token-valid283bash /root/vm.sh '~/caido.sh start' # detached; auto-skips if running284bash /root/vm.sh '~/caido.sh stop'285bash /root/vm.sh '~/caido.sh history "req.host.eq:\"target.com\"" 20'286bash /root/vm.sh '~/caido.sh raw 15 resp'287bash /root/vm.sh '~/caido.sh send /tmp/req.txt target.com 443 1' # Replay send288bash /root/vm.sh '~/caido.sh cookies target.com'289bash /root/vm.sh '~/caido.sh project' # list + selected; 'project <n>' create+select290bash /root/vm.sh '~/caido.sh gql "<query>" "<vars-json>"'291```292293Source of truth `scripts/caido.sh`; re-push with (vm.sh does not forward294stdin, so ship the bytes inside the command):295`B64=$(base64 -w0 scripts/caido.sh); bash /root/vm.sh "echo $B64 | base64 -d > ~/caido.sh && chmod +x ~/caido.sh"`.296Schema drifts between releases (0.58.3: `startReplayTask(sessionId)` takes NO input;297`replayEntry` needs the `ReplayEntryHttp` fragment). On a field error, introspect298first (`__type(name:"...")`), or check github.com/caido/schemas; do not trust older299doc snippets. The SDK CLI absorbs most of this; `gql` is the escape hatch.300301## Fuzz batteries (request-variation through Replay)302303`~/caido.sh fuzz <template> <payloads> <host> [port] [tls] [delay]`: template =304full HTTP/1.1 request with `{{PAYLOAD}}` marker(s), payloads one per line; each305variant is its own Replay session (operator-visible); output `STATUS bytes session306payload` per line, triage by differential. Authenticated batteries carry307`{{COOKIE}}` and refuse unless `CAIDO_COOKIE` is set308(`CAIDO_COOKIE="$(~/caido.sh cookies target.com)"`); one-command wrapper309`bash scripts/caido-battery.sh target.com pays.txt`.310311Battery doctrine (one variation per run, 60-payload/0.3s bounds, RoE:312shape variation NEVER cred spraying, bash-native payload pre-encoding)313is owned BY REFERENCE by Skill(fuzz) - do not restate it here.314Caido-side specifics only: end-to-end authed lane = browser through315the proxy -> `cookies <host>` -> battery -> Autorize plugin diffs316triplets = IDOR lane ([[hunt-idor]]). Recon-phase variation routes317here when scanners are RoE-barred (serial, bounded, visible beats a318banned ffuf); where wordlist scanners are permitted, `Skill(fuzz)`319stays primary. Automate (CLI `create-automate-session320<id>` then configure payloads in the GUI) is the Caido-native equivalent.321322## Caido-native workflow (GUI concepts)323324- **Proxying traffic**: point any client at `192.168.23.128:8080` (`curl -kx`,325 chromium proxy). Everything lands in History of the selected project.326- **Scopes / Filters**: scope preset from `targets/<eng>/scope.md`327 (`create-scope "Target" --allow "*.target.com" --deny "*.cdn..."`), filter328 presets via `create-filter "name" --query '<httpql>' --alias <short>` then329 `search 'preset:"<alias>"'`. Scoping inside Caido does NOT replace the RoE330 scope-guard (API calls are invisible to it; you own the check).331- **Environments / hosted Files**: per-engagement vars + wordlists, referenced as332 `{{env.VAR}}` in Replay; `create-env`, `env-set <env> <var> <val>`.333- **Workflows** (preprocessors, can emit Findings) and **Exports** (requests to334 files for the report): GUI; raw pairs still go to `targets/<eng>/poc/`.335- **Plugins** (Pro): install headless via gql336 `installPluginPackage(input: {source: {url: <release-zip>}})`, toggle with337 `togglePlugin(id, enabled)`. Worth it: Scanner (passive mode adds ZERO target338 requests, RoE-safe) and Autorize (IDOR triplets; needs one authenticated339 session). Shift (BYO-key LLM) is redundant when the agent is the LLM lane.340- **Intercept**: `intercept-status` / `intercept-enable` / `intercept-disable`341 (rarely wanted: the agent works from History, not a held queue).342343## Output control + gotchas344345- `--compact` = `--no-request --max-body 50 --max-body-chars 5000`; also346 `--max-body <n>` / `--max-body-chars <n>` (0 = unlimited), `--headers-only`.347 Browse with `--compact`; `get`/`export-curl` only the request you work from.348- `search` is NEWEST FIRST; `--limit N` = newest N matches. Never fetch a big349 window and re-sort client-side (you only sort the truncated window); let Caido350 order. `recent` takes no filter.351- Do NOT batch CLI calls inside `while`/`for` loops (PATH can get stripped in loop352 subshells and the body fails silently); one top-level command each, or a353 standalone script with an explicit `export PATH`.354- `search --ids-only` returns a JSON array (`["123"]`): unwrap with355 `jq -r '.[0]'`.356357## Error handling358359- Auth errors / `No Caido auth found` -> `auth-status`; re-`setup <pat>`, or360 re-prime from the VM token (above).361- Probes turn 401/403/login-redirect -> token aged out; regenerate the config from362 a fresh history id.363- Proxy connect refused -> `health`; if down, `bash /root/vm.sh '~/caido.sh start'`.364- gql field errors -> schema drifted; introspect (see `~/caido.sh` section).365366## Relation to Burp367368Burp stays the primary transport when its MCP is up ([[hunt-burp]]). Reach for369Caido when: Burp/MCP is down, you want a per-engagement isolated project, the370target needs Automate-style bulk runs, or the operator prefers the lighter GUI.371Same discipline either way: load-bearing requests must be visible to the operator372(Replay entries here, Repeater tabs there), never silent background curl.