hack/tools/scripts/cdp-capture/README.md

# CDP Capture — Browser Session Recorder

> Connects to your **real Chrome browser** via Chrome DevTools Protocol and records everything you do.

## Quick Start

### 1. Launch Chrome with debugging enabled

```powershell
# Fresh profile (no logins)
.\tools\scripts\launch-chrome.ps1

# Your real profile (with all your logins/cookies)
.\tools\scripts\launch-chrome.ps1 -UseRealProfile

# Custom port and starting URL
.\tools\scripts\launch-chrome.ps1 -Port 9223 -Url "https://example.com"
```

### 2. Start the capture tool

```powershell
cd tools\scripts\cdp-capture
npm install          # first time only
node capture.js      # start capturing
```

### 3. Browse normally

Open tabs, log in, click around, fill forms. Everything is recorded in real-time.

### 4. Press `Ctrl+C` to stop

Cookies, localStorage, and session summary are saved on exit.

---

## Options

```
node capture.js [options]

  --port=<port>        CDP port (default: 9222)
  --host=<host>        CDP host (default: localhost)
  --tab=<index>        Tab to attach to (default: 0, use -1 for all tabs)
  --screenshot         Take screenshot on each navigation
  --dom                Save DOM snapshot on each navigation
  --bodies             Capture response bodies (heavy!)
  --filter=<regex>     Only capture network requests matching URL pattern
  --outdir=<path>      Base output directory (default: project root)
  --no-interactions    Disable interaction capture
  --no-network         Disable network capture
  --no-console         Disable console capture
```

### Examples

```powershell
# Capture everything from all tabs, with screenshots and DOM
node capture.js --tab=-1 --screenshot --dom

# Only capture API calls, ignore static resources
node capture.js --filter="/api/|/graphql|/auth"

# Capture response bodies too (for analyzing API responses)
node capture.js --bodies --filter="/api/"

# Capture from a specific tab
node capture.js --tab=2
```

---

## What Gets Captured

| Data | File | Description |
|---|---|---|
| **Network requests** | `logs/<session>/network.jsonl` | Every HTTP request: URL, method, headers, POST data |
| **Network responses** | `logs/<session>/network.jsonl` | Status, headers, MIME type, remote IP |
| **Response bodies** | `logs/<session>/network_bodies.jsonl` | Response body content (with `--bodies`) |
| **Console messages** | `logs/<session>/console.jsonl` | console.log/warn/error + exceptions |
| **User interactions** | `logs/<session>/interactions.jsonl` | Clicks, inputs, form submits, keydowns |
| **Navigations** | `logs/<session>/navigations.jsonl` | URL changes, page loads |
| **Screenshots** | `evidence/screenshots/<session>/` | PNG screenshots (with `--screenshot`) |
| **DOM snapshots** | `scans/host/<session>/` | Full HTML of page (with `--dom`) |
| **Cookies** | `loot/credentials/<session>/cookies_tab*.json` | All cookies (on exit) |
| **localStorage** | `loot/credentials/<session>/localStorage_tab*.json` | All localStorage (on exit) |
| **sessionStorage** | `loot/credentials/<session>/sessionStorage_tab*.json` | All sessionStorage (on exit) |
| **Summary** | `logs/<session>/summary.json` | Session stats and metadata |

---

## Interaction Data Format

Each interaction is a JSON line in `interactions.jsonl`:

```json
{
  "type": "click",
  "target": {
    "tag": "button",
    "id": "submit-btn",
    "class": "btn btn-primary",
    "text": "Login",
    "xpath": "/html[1]/body[1]/div[1]/form[1]/button[1]"
  },
  "timestamp": 1722000000000,
  "url": "https://example.com/login"
}
```

```json
{
  "type": "input",
  "target": {
    "tag": "input",
    "name": "username",
    "type": "text",
    "value": "admin"
  },
  "timestamp": 1722000001000,
  "url": "https://example.com/login"
}
```

```json
{
  "type": "submit",
  "target": {
    "tag": "form",
    "action": "https://example.com/api/login",
    "method": "post"
  },
  "formData": {
    "username": "admin",
    "password": "secret123"
  },
  "timestamp": 1722000002000,
  "url": "https://example.com/login"
}
```

---

## How It Works

```
Chrome (--remote-debugging-port=9222)
  │
  ├── CDP WebSocket connection
  │
  ├── Network domain → all HTTP requests/responses
  ├── Runtime domain → console messages + JS evaluation
  ├── Page domain → navigation events + screenshots
  ├── DOM domain → DOM snapshots
  │
  └── Injected JS listeners → clicks, inputs, form submits
        │
        └── __capture() binding → CDP event → JSONL file
```

The script injects JavaScript event listeners into every page via `Runtime.addBinding`. These listeners capture user interactions and send them back through CDP's binding mechanism — no console.log pollution, no polling, real-time capture.

---

## Use Cases

1. **Login flow capture** — Record yourself logging into a site, then replay/automate it
2. **API reverse engineering** — See all API calls, headers, and payloads as you browse
3. **Session extraction** — Grab cookies and tokens for use in scripts
4. **Evidence collection** — Screenshots and DOM snapshots for reports
5. **User behavior analysis** — See exactly what was clicked and typed

---

## Files

```
tools/scripts/
├── cdp-capture/
│   ├── package.json     # Dependencies
│   ├── capture.js       # Main capture script
│   └── README.md        # This file
└── launch-chrome.ps1    # Chrome launcher with CDP enabled
```