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

# 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

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

# 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:

{
  "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"
}

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

{
  "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