/browser-probe

name: browser-probe
license: Apache-2.0
compatibility: Requires playwright-cli on PATH. Run `playwright-cli --help` for usage.
description: >-
  Probe a URL with escalating headless browser configurations to detect CDN bot
  protection (Akamai, Cloudflare, DataDome, AWS WAF) and produce a
  browser-recipe.json that downstream playwright-cli consumers use to bypass
  blocking. Runs an automated escalation ladder: default headless → stealth
  script injection → system Chrome (TLS fingerprint fix) → persistent profile.
  Use BEFORE any playwright-cli interaction with an untrusted domain. Triggers
  on: browser probe, site blocked, headless blocked, CDN blocking, bot
  detection, browser recipe, can't load page, 403 error page, access denied.

Browser Probe

Detect CDN bot protection blocking headless Chrome and produce a browser recipe for downstream `playwright-cli` consumers. Node 22+ required. No npm dependencies.

When to Use

Run **before** any `playwright-cli` interaction with an untested domain, or when a downstream script reports a blocked/empty page (403, "access denied", "captcha").

Script Location

if [[ -n "${CLAUDE_SKILL_DIR:-}" ]]; then
  PROBE_DIR="${CLAUDE_SKILL_DIR}/scripts"
else
  PROBE_DIR="$(dirname "$(command -v browser-probe.js 2>/dev/null || \
    find ~/.claude -path "*/browser-probe/scripts/browser-probe.js" \
    -type f 2>/dev/null | head -1)")"
fi

Workflow

Step 1 — Run the probe

node "$PROBE_DIR/browser-probe.js" "$URL" "$OUTPUT_DIR"

The script tries up to 5 browser configurations, stopping at the first success:

1. **default** — headless Chromium (baseline) 2. **stealth** — headless Chromium + JS stealth init script (patches `navigator.webdriver`, plugins, languages) 3. **stealth-ua** — headless Chromium + JS stealth + User-Agent override (removes `HeadlessChrome` from HTTP UA header via `--user-agent` launch arg) 4. **chrome** — system Chrome (`--browser=chrome`) + JS stealth + UA override (fixes TLS fingerprint detection) 5. **persistent** — system Chrome + JS stealth + UA override + persistent profile (cookie/session challenges)

Output: `$OUTPUT_DIR/probe-report.json`

Step 2 — Read the report

Load `probe-report.json`. Check `firstSuccess`:

• If non-null: a configuration worked. Proceed to Step 3.
• If null: all configurations failed. Skip to Step 5.

A step with `headerError` could not read response headers, so `detectedSignals` may be incomplete. Mention the error in the Step 5 report.

Step 3 — Interpret results

Match `detectedSignals` against the Provider Signature Table in `references/stealth-config.md` to confirm why blocking occurred and validate that `firstSuccess` is the minimum sufficient config.

Step 4 — Generate recipe

Write `browser-recipe.json` to `$OUTPUT_DIR`:

{
  "url": "<probed URL>",
  "generated": "<ISO timestamp>",
  "cliConfig": {
    "browser": {
      "browserName": "chromium",
      "launchOptions": { "channel": "<from firstSuccess step>" }
    }
  },
  "stealthInitScript": "<full script from stealth-config.md if stealth was needed>",
  "notes": "<1-2 sentence explanation of what was detected and why this config>"
}

**Config mapping from `firstSuccess`:**

| firstSuccess | channel | args | stealthInitScript | |---|---|---|---| | `default` | — | — | null | | `stealth` | — | — | from reference | | `stealth-ua` | — | `--user-agent=<realistic UA>` | from reference | | `chrome` | `chrome` | `--user-agent=<realistic UA>` | from reference | | `persistent` | `chrome` | `--user-agent=<realistic UA>` | from reference |

If `firstSuccess` is `persistent`, add `"persistent": true` to the recipe.

Step 5 — Report results

**If a configuration worked:**

Browser probe complete for <url>.
  Working config: <firstSuccess>
  Detected: <detectedSignals or "no bot protection detected">
  Recipe: <path to browser-recipe.json>

**If all configurations failed:**

Browser probe failed for <url>. No headless configuration could load the page.
  Tried: default, stealth, stealth-ua, chrome, persistent
  Detected signals: <detectedSignals>

  Options:
  1. Use --headed flag for manual browser interaction
  2. Provide pre-captured data (DOM snapshot, screenshots) manually
  3. Check if the URL requires authentication or VPN access

Do NOT produce a recipe when all steps fail. Do NOT silently continue with a broken configuration.

How Consumers Use the Recipe

Pass `--config=<path-to-cliConfig>` to `playwright-cli open`. If the recipe has `stealthInitScript`, add it to `browser.initScript` in the config (not via `eval` — eval is expression-only). If `"persistent": true`, also pass `--persistent`. Run `playwright-cli --help` for the full command reference.