caido-mode

Caido Mode Skill

A CLI over Caido's API (built on the official @caido/sdk-client) for HTTP-history-driven testing. The tool lives at ~/.claude/skills/caido-mode/caido-client.ts; every command is npx tsx caido-client.ts <command> and outputs JSON unless noted.

How to operate (read this first)

There are two distinct modes:

1. Testing → use curl, always proxied through Caido. Find a real authenticated request in history, cache its auth into a reusable curl config (a faithful static snapshot of its headers
   • cookies), then probe with curl -K auth.cfg "$BASE/path". All traffic must go through Caido (the config carries the proxy), so every request lands in HTTP history.
2. Handoff → use replay sessions + collections. Only when handing a request (or a set) to the user do you materialize it as a named replay session inside a named collection.

Hard rules:

• Everything goes through Caido — except high-volume bruteforce/fuzzing. Never curl a single target request directly; always via the Caido proxy (the generated config does this; otherwise add -x <proxy>). The one exception: don't proxy bruteforce/fuzzing tools (ffuf, etc.) or any batch of 100+ requests at once through Caido — it bloats HTTP history. Run those direct (no -x), then bring any interesting hit back into Caido (re-send it through the proxy / promote to Replay) to investigate and hand off.
• Test with curl. Don't spin up replay sessions for probing — that's handoff only.
• To show the operator a request, send it to Replay. Whenever you want the operator to see a specific request, create a named replay session for it (in a named collection if there's more than one) — that's how they inspect and re-run it in Caido. A request you tested via curl only becomes something the operator can work with once you promote it into Replay (create-session <id> --name …, or send-raw … --name … for a crafted one).
• Cache auth in files, don't re-paste it. Use export-curl --config once per target; then reference the config. Don't dump cookies/JWTs into every command (or repeatedly into context).
• If you hand the operator a runnable command, make it a FULL self-contained curl (all headers inline, via export-curl) — for a PoC or something they'll run outside Caido. The -K config is for your internal testing only; never hand them a curl -K /tmp/… line.
• Replay session names are mandatory, and editing a session forces explicit name intent.
• Use collections for multi-request handoffs; refer to sessions/collections by name, not ID.

The primary workflow (do this by default)

# 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

Iterate step 3 freely — it's cheap, it's all in Caido, and the big auth blob stays in the file. Confirm a probe landed in Caido with search 'req.host.cont:"target.com"' --compact.

Send the path exactly as written

When testing path traversal / path-normalization (../, /.., /./, encoded variants), pass curl --path-as-is — otherwise curl collapses ../ and /./ client-side before sending, so the server never sees the payload and the test silently passes. Keep the path verbatim:

(Likewise add -g/--globoff if the URL contains [ ] { } you don't want curl to interpret.)

The config is a faithful STATIC snapshot (important)

export-curl --config captures every auth/identity header from the base request (not a curated subset) and inlines the cookies statically. Two deliberate choices, both learned the hard way:

• All headers, not an allowlist. Modern apps gate authorization on app-specific headers you can't predict — x-goog-ext-*, X-Browser-Validation, X-Client-Data, Origin, Referer, X-Same-Domain, Sec-*, … A narrow allowlist silently drops these and you get opaque 403/PERMISSION_DENIED. The config now mirrors what actually authorized the request. Only truly per-request/volatile headers are dropped: Host, Content-Length, Content-Type, Connection, Accept-Encoding (curl manages these per request).
  • ⚠ Because Content-Type is dropped, you MUST pass it yourself on every POST/PUT/PATCH: curl -K auth.cfg -X POST "$BASE/path" -H 'Content-Type: application/json' --data-binary @body. Use the exact Content-Type the endpoint expects (e.g. Google batchexecute needs application/x-www-form-urlencoded;charset=UTF-8) — a wrong/missing one is a common cause of 400/403. curl sets Content-Length itself; don't add it.
• Static cookies, no jar. It does not use cookie-jar by default, so curl never writes a response's rotated Set-Cookie back over your captured-good cookies (servers like Google rotate on every response, including error responses — a write-back jar drifts the session into failure). Need to follow rotation? export-curl <id> --config --cookie-jar opts in.

To drop a specific header: --exclude <name> (repeatable). To omit cookies entirely (e.g. when a Match & Replace rule injects auth): --exclude cookie.

Other conventions

• Per-target scratch dir: /tmp/caido/<host>/ holds auth.cfg, body files, notes.
• $BASE: set BASE=https://<host> once; write requests as "$BASE/path".
• Bodies in files: save large/complex bodies once and send with --data-binary @body.json (the correct use of --data-binary — a byte-exact body). Add -H 'Content-Type: …' per request since the config omits it.
• Lazy refresh: the snapshot is static, so when a request starts returning 401/403 (token expired / cookies aged out), re-run export-curl <fresh-id> --config to re-snapshot, then retry.
• CSRF: the matching X-CSRF*/double-submit header is captured automatically. For tokens that rotate per action, fetch fresh: T=$(curl -sK auth.cfg "$BASE/csrf" | jq -r .token).
• Proxy-injected auth (alternative): instead of a config, a Match & Replace rule can inject Authorization/cookies on all proxied traffic — then curl -x <proxy> -k "$BASE/path" needs no headers. See Match & Replace.

Giving commands to the user

To surface a request inside Caido for the operator, send it to Replay (see "Replay sessions" below) — that's the default. This section is for the other case: handing them a runnable command (a PoC, or something to run outside Caido). Then always produce a full, self-contained curl — every header inline, no -K:

Drop -x/-k for a portable PoC the user can run anywhere; keep them only if the user is meant to run it through their own Caido. Never hand the user a curl -K /tmp/... line — that file is yours.

The proxy

All curl testing must go through Caido's proxy. Its address defaults to the Caido URL (proxy and API share an address). Discover/confirm it any time:

export-curl --config bakes the proxy into the config (proxy = "…"). For an ad-hoc curl, add -x <proxy> -k yourself. Override the proxy only if its listener differs from the API URL — setup --proxy <addr> or export CAIDO_PROXY=<addr>.

Get the proxy from auth-status (the proxy/activeUrl fields) — don't parse secrets.json directly. Auth is URL-keyed now: the address lives under .caido.default / .caido.instances, not .caido.url.

Authentication setup

setup validates the PAT via the SDK's device-code flow (auto-approved by the PAT), then caches the PAT + access token (+ proxy) to ~/.claude/config/secrets.json. Subsequent runs use the cached token; a valid cached token works even without the PAT.

Multiple Caido instances

Credentials are keyed by instance URL — two instances on one machine never clobber each other. setup <pat> <url> stores that instance under its URL (and makes it the active default); setting up a second URL adds a second entry rather than overwriting the first.

The active instance is CAIDO_URL env → stored default → http://localhost:8080. Select per shell/agent with CAIDO_URL (concurrency-safe — no shared "current instance" to race on), e.g. CAIDO_URL=http://localhost:8081 npx tsx caido-client.ts recent. CAIDO_PAT/CAIDO_PROXY env override the active instance's stored values.

Searching HTTP history (HTTPQL)

• search is NEWEST FIRST by default (descending by request id). --limit N therefore returns the newest N matches. Pass --asc (alias --oldest) only when you actually want oldest first.
• To get "the most recent matching X", just run search '<filter>' --limit N — do NOT pull a large --limit and re-sort client-side (e.g. jq 'sort_by(.createdAt) | reverse'). That sorts only the truncated window you fetched, so any request newer than the Nth result is silently invisible — you'll mistake stale traffic for the latest. Let Caido do the ordering.
• recent is always newest-first but takes no filter; use search --limit N for newest-matching-a-filter.
• --compact → one terse line per request (id status METHOD host/path).
• Prefer search/recent --compact for browsing; get/export-curl once you've picked one.

See the HTTPQL Reference below for the full query language.

Replay sessions — for handoff only

Use these when giving a request to the user. Normal testing uses curl (above), not sessions. Sessions created from a raw request have their header line endings normalized to CRLF automatically — a handoff session is never built with bare-LF (\n) endings.

Editing a session forces name intent

If the user asks you to test inside Replay, use edit / edit-session. Because an edit changes what a session contains, declare what happens to its name — pass exactly one of --no-name-change (--nonach) or --new-name "<name>":

edit preserves cookies/auth from the original request; it supports --method, --path, --set-header, --remove-header, --body (auto Content-Length), --replace <from>:::<to>, and connection overrides (--sni, --connect-host, …).

Inspecting an existing replay tab

When a replay tab is already open in Caido and you want to work from its current state, look it up by name or id (no need to re-create it):

session-entries is an alias for replay-entries. Use these to read what's in a tab; use edit-session (above) to send a modified request into it.

Collections — use them heavily

Collections organize sessions for handoff. Before creating a session, list existing collections and decide where it belongs. Names are mandatory and collections are never auto-created.

Pass collections by name; the CLI resolves it (and tells you to create it first if missing):

When you report back, name the collection and sessions — never IDs.

Match & Replace — auto-rewrite traffic

Match & Replace (Caido calls these "Tamper" rules internally) rewrites requests/responses automatically as they pass through Caido. The killer use: inject auth at the proxy so your curl commands don't carry it — add a rule that sets Authorization on every proxied request, then curl -x <proxy> -k "$BASE/path" is authenticated with no -K/headers at all.

A rule is one section (which part) × one operation × a matcher × a replacer, with optional condition (HTTPQL scope) and sources:

Four gotchas, all defaulted for you:

• New rules are created DISABLED. Enable with toggle-mr-rule <id> --on.
• Default collection is Caido's "Default Collection" (override with --collection <name|id>).
• Default sources is INTERCEPT (proxy traffic), matching Caido. Add --sources to broaden.
• JS targets — pick matcher based on what you're matching against. --match-value is fine for stable literals (string constants, JSON keys, fixed API paths). Use --match-regex when matching near minified identifiers: symbol names rotate on every bundle deploy (e.g. _.ex → _.Ww), so a literal rule silently stops matching with no error. Anchor the regex to structurally stable neighbours — surrounding string literals, known function names, fixed JSON keys — rather than the minified identifier itself.

Preview before committing: test-mr-rule applies a rule to a raw request without creating anything — use it to confirm a rule does what you expect.

Manage collections with mr-collections, create-mr-collection, rename-mr-collection, delete-mr-collection; move-mr-rule <id> <collection>; update-mr-rule <id> … re-specs a rule (same flags as create); rename-mr-rule <id> <name>.

Output control (works with get, get-response, replay, edit, send-raw, edit-session)

HTTPQL Reference

Caido's query language for searching HTTP history.

CRITICAL: String values MUST be quoted; integers are NOT.

CRITICAL: HTTPQL has NO NOT operator. Use the negated operator variant instead:

• ncont (not contains), nlike, nregex, ne (not equals)
• Wrong: NOT req.path.cont:"/admin" — Right: req.path.ncont:"/admin"

Namespaces and Fields

Operators

• String: eq, ne, cont, ncont, like, nlike, regex, nregex
• Integer: eq, ne, gt, gte, lt, lte
• Boolean: eq, ne
• Logical: AND, OR, parentheses for grouping

Examples

Other capabilities (reference)

Findings — surface in Caido's Findings tab

Scopes / Filter presets / Environments

Fuzzing / intercept / projects / tasks / info

Full command reference

Every command (run npx tsx caido-client.ts <command>). Sessions/collections accept a name or id; output is JSON unless noted. Run --help for full flag lists.

Architecture

Built on @caido/sdk-client v0.2.0+. No raw fetch — high-level SDK methods plus client.graphql.query/mutation with gql documents for the few features the SDK doesn't expose.

Instructions for Claude (checklist)

1. Test with curl, always through Caido — the proxy must be in the path (config does this; otherwise -x <proxy>). Exception: bruteforce/fuzzing (ffuf) or 100+ requests at once go direct to avoid bloating HTTP history; bring interesting hits back into Caido.
2. Cache auth once: export-curl <id> --config → /tmp/caido/<host>/auth.cfg (faithful static snapshot of ALL auth headers + inline cookies). Test with curl -K auth.cfg "$BASE/path".
3. Refresh lazily — only on 401/403/login-redirect, regenerate the config from a fresh request.
4. Give the user FULL self-contained curl (export-curl <id>); never a -K line.
5. Browse with --compact; get/export-curl only the request you'll work from.
6. To show the operator a request, send it to Replay (named session). Replay = handoff only, names mandatory; collections used heavily, referred to by NAME.
7. Editing a session requires --nonach or --new-name.
8. Create findings for anything real.
9. NEVER use NOT in HTTPQL — use ne/ncont/nlike/nregex.

Operational notes (shell gotchas)

• Don't batch CLI calls inside while/for loops. Some shells strip PATH inside loop subshells, so head/python3/etc. become "command not found" and the loop body fails silently (sessions look like they weren't created). Run each send-raw/create-session as an individual top-level command, or as a standalone bash script with an explicit export PATH=….
• search --ids-only returns a JSON array (["123"]), not a bare id — unwrap before reuse, e.g. ID=$(… --ids-only | jq -r '.[0]').
• sessions / collections now list everything (paginated, not just the first page), so freshly-created items always appear. --limit N caps the count if you want a short list.

Error handling

• Auth errors → auth-status, re-setup <pat> (or set CAIDO_PAT).
• curl gets 401/403/login redirect → token expired; refresh the config from a fresh request.
• curl can't connect via proxy → confirm the proxy with auth-status; Caido must be running.
• Connection refused / not ready → Caido isn't up or is still starting; check health.