caido-mode

What this skill does

# Caido Mode Skill

## Overview

Full-coverage CLI for Caido's API, built on the official `@caido/sdk-client` package. Covers:

- **HTTP History** - Search, retrieve, replay, edit requests with HTTPQL
- **Replay & Sessions** - Sessions, collections, entries, fuzzing
- **Scopes** - Create and manage testing scopes (allowlist/denylist patterns)
- **Filter Presets** - Save and reuse HTTPQL filter presets
- **Environments** - Store test variables (victim IDs, tokens, etc.)
- **Findings** - Create, list, update security findings
- **Tasks** - Monitor and cancel background tasks
- **Projects** - Switch between testing projects
- **Hosted Files** - Manage files served by Caido
- **Intercept** - Enable/disable request interception programmatically
- **Plugins** - List installed plugins
- **Export** - Convert requests to curl commands for PoCs
- **Health** - Check Caido instance status

All traffic goes through Caido, so it appears in the UI for further analysis.

### Why This Model?

**Cookies and auth tokens can be huge** - session cookies, JWTs, CSRF tokens can easily be 1-2KB. Rather than manually copy-pasting:

1. **Find an organic request** in Caido's HTTP history that already has valid auth
2. **Use `edit` to modify just what you need** (path, method, body) while keeping all auth headers intact
3. **Send it** - response comes back with full context preserved

## Authentication Setup

### Setup (One-Time)

1. Open [Dashboard → Developer → Personal Access Tokens](https://docs.caido.io/dashboard/guides/create_pat.html)
2. Create a new token
3. Run:

```bash
npx tsx ~/.claude/skills/caido-mode/caido-client.ts setup <your-pat>

# Non-default Caido instance
npx tsx ~/.claude/skills/caido-mode/caido-client.ts setup <pat> http://192.168.1.100:8080

# Or set env var instead
export CAIDO_PAT=caido_xxxxx
```

The `setup` command validates the PAT via the SDK (which exchanges it for an access token), then saves both the PAT and the cached access token to `~/.claude/config/secrets.json`. Subsequent runs load the cached token directly, and a valid cached token can be used even when the PAT is absent.

### Check Status

```bash
npx tsx ~/.claude/skills/caido-mode/caido-client.ts auth-status
```

### How Auth Works

The SDK uses a device code flow internally — the PAT auto-approves it and receives an access token + refresh token. A custom `SecretsTokenCache` (implementing the SDK's `TokenCache` interface) persists these tokens to secrets.json so they survive across CLI invocations.

Auth resolution: `CAIDO_PAT` env var → `secrets.json` PAT → valid cached access token → error with setup instructions

## CLI Tool

Located at `~/.claude/skills/caido-mode/caido-client.ts`. All commands output JSON.

---

## HTTP History & Testing Commands

### search - Search HTTP history with HTTPQL

```bash
npx tsx caido-client.ts search 'req.method.eq:"POST" AND resp.code.eq:200'
npx tsx caido-client.ts search 'req.host.cont:"api"' --limit 50
npx tsx caido-client.ts search 'req.host.cont:"api"' --desc --limit 10
npx tsx caido-client.ts search 'req.path.cont:"/admin"' --ids-only
npx tsx caido-client.ts search 'resp.raw.cont:"password"' --after <cursor>
```

### recent - Get recent requests

```bash
npx tsx caido-client.ts recent
npx tsx caido-client.ts recent --limit 50
```

### get / get-response - Retrieve full details

```bash
npx tsx caido-client.ts get <request-id>
npx tsx caido-client.ts get <request-id> --headers-only
npx tsx caido-client.ts get-response <request-id>
npx tsx caido-client.ts get-response <request-id> --compact
```

### edit - Edit and replay (KEY FEATURE)

Modifies an existing request while preserving all cookies/auth headers:

```bash
# Change path (IDOR testing)
npx tsx caido-client.ts edit <id> --path /api/user/999

# Change method and add body
npx tsx caido-client.ts edit <id> --method POST --body '{"admin":true}'

# Add/remove headers
npx tsx caido-client.ts edit <id> --set-header "X-Forwarded-For: 127.0.0.1"
npx tsx caido-client.ts edit <id> --remove-header "X-CSRF-Token"

# Find/replace text anywhere in request
npx tsx caido-client.ts edit <id> --replace "user123:::user456"

# Combine multiple edits
npx tsx caido-client.ts edit <id> --method PUT --path /api/admin --body '{"role":"admin"}' --compact

# Reuse an existing replay tab/session for repeated probes
npx tsx caido-client.ts edit <id> --path /api/user/1001 --session <session-id> --compact
```

| Option | Description |
|--------|-------------|
| `--method <METHOD>` | Change HTTP method |
| `--path <path>` | Change request path |
| `--set-header <Name: Value>` | Add or replace a header (repeatable) |
| `--remove-header <Name>` | Remove a header (repeatable) |
| `--body <content>` | Set request body (auto-updates Content-Length) |
| `--replace <from>:::<to>` | Find/replace text anywhere in request (repeatable) |
| `--session <id>` | Reuse an existing replay session instead of creating a new tab |
| `--collection <id>` | Put a newly created replay session in a collection |
| `--sni <host>` | Override TLS SNI |
| `--connect-host <host>` | Connect to a different host while preserving the HTTP request |
| `--connect-port <port>` | Connect to a different port |
| `--connect-tls` / `--connect-no-tls` | Force TLS/plaintext for the connection |

### replay / send-raw - Send requests

```bash
# Replay as-is
npx tsx caido-client.ts replay <request-id>

# Replay with custom raw
npx tsx caido-client.ts replay <id> --raw "GET /modified HTTP/1.1\r\nHost: example.com\r\n\r\n"

# Send completely custom request
npx tsx caido-client.ts send-raw --host example.com --port 443 --tls --raw "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n"
npx tsx caido-client.ts send-raw --host example.com --raw @request.txt --name "G /"
cat request.txt | npx tsx caido-client.ts send-raw --host example.com --raw -

# Connect elsewhere while preserving the request Host/SNI you need
npx tsx caido-client.ts replay <id> --connect-host 10.0.0.5 --connect-port 8443 --sni example.com
```

`--raw` accepts a string with `\r\n` escapes, `@file` to read from disk, or `-` to read from stdin.

### export-curl - Convert to curl for PoCs

```bash
npx tsx caido-client.ts export-curl <request-id>
```

Outputs a ready-to-use curl command with all headers and body.

---

## Replay Tab Lookup

Use these when a Caido replay tab is already open and you want to work from its active entry directly.

```bash
npx tsx caido-client.ts get-session <session-id-or-name> --compact
npx tsx caido-client.ts replay-entries <session-id-or-name> --limit 20
npx tsx caido-client.ts replay-entries <session-id-or-name> --raw --compact
npx tsx caido-client.ts edit-session <session-id-or-name> --body '{"test":true}' --compact
```

`session-entries` is accepted as an alias for `replay-entries`.

---

## Replay Sessions & Collections

### Sessions

```bash
# Create replay session from an existing request
npx tsx caido-client.ts create-session <request-id>
npx tsx caido-client.ts create-session <request-id> --collection <collection-id>

# ALWAYS rename sessions for easy identification in Caido UI
npx tsx caido-client.ts rename-session <session-id> "idor-user-profile"

# List all replay sessions
npx tsx caido-client.ts replay-sessions
npx tsx caido-client.ts replay-sessions --limit 50

# Move sessions between collections
npx tsx caido-client.ts move-session <session-id> <collection-id>

# Delete replay sessions
npx tsx caido-client.ts delete-sessions <session-id-1>,<session-id-2>
```

### Collections

Organize replay sessions into collections:

```bash
# List replay collections
npx tsx caido-client.ts replay-collections
npx tsx caido-client.ts replay-collections --limit 50

# Create a collection
npx tsx caido-client.ts create-collection "IDOR Testing"

# Rename a collection
npx tsx caido-client.ts rename-collection <collection-id> "Auth Bypass Tests"

# Delete a collection
npx tsx caido-client.ts delete-collection <collection-id>
```

### Fuzzing

```bash
# Create automate session for fuzzi