Add domain-firewall skill — CDP navigation security for browser agents

[aq17]

Summary

Adds a domain-firewall skill that protects Browserbase (and local Chrome) sessions from unauthorized navigations at the Chrome DevTools Protocol level. Designed to prevent prompt injection attacks that trick AI agents into navigating to attacker-controlled URLs.

Two interfaces:

• CLI script (agent-first) — node domain-firewall.mjs --session-id <id> --allowlist "example.com" attaches to a live session and enforces policies transparently. Works with the browse CLI, Stagehand, or any CDP client.
• TypeScript API (code integration) — installDomainFirewall(page, { policies, defaultVerdict }) for embedding directly in Stagehand projects with composable policies.

What it does

• Intercepts all Document navigations via Fetch.requestPaused CDP event
• Evaluates requests against a policy chain: denylist → allowlist → default verdict
• Blocks unauthorized navigations with Fetch.failRequest("BlockedByClient") — Chrome shows ERR_BLOCKED_BY_CLIENT
• Logs all decisions (allowed/blocked + which policy decided) to stdout or audit trail

Built-in policies (TypeScript API)

Policy	Purpose
allowlist(domains)	Static domain allowlist
denylist(domains)	Static domain denylist
pattern(globs, verdict)	Glob matching on domains
tld(rules)	TLD-based rules (.org, .edu, .ru)
interactive(handler)	Human-in-the-loop approval with session memory

CLI script flags

--session-id <id>      Browserbase session ID
--cdp-url <ws://...>   Direct CDP WebSocket URL (local Chrome)
--allowlist <domains>   Comma-separated allowed domains
--denylist <domains>    Comma-separated denied domains
--default <verdict>     allow or deny (default: deny)
--json                  Output events as JSON lines
--quiet                 Suppress per-request logging

Security demo results

Tested against a honeypot page containing hidden prompt injection that directs agents to an attacker URL:

Scenario	Result
Without firewall	Agent navigated to attacker URL, session token exfiltrated
With firewall (--allowlist localhost)	Navigation blocked at CDP level, attacker received zero data

Files

skills/domain-firewall/
├── SKILL.md                          # Skill docs (threat model, policies, usage)
├── REFERENCE.md                      # API reference, CDP protocol details
├── EXAMPLES.md                       # 6 usage examples
├── LICENSE.txt                       # MIT
├── package.json                      # ws dependency for CDP WebSocket
└── scripts/
    └── domain-firewall.mjs           # CLI-native firewall script (agent-first)

Test plan

• CLI script connects to Browserbase sessions via bb sessions debug
• CLI script connects to local Chrome via --cdp-url
• Allowlisted domains pass through (Fetch.continueRequest)
• Non-allowlisted domains blocked (Fetch.failRequest)
• Denylist takes priority over allowlist
• Browser-level CDP auto-attaches to page target (coexists with browse CLI)
• Fail-closed on policy errors (no hung requests)
• Graceful shutdown on SIGINT
• JSON output mode (--json)
• Honeypot attack demo: unprotected agent gets pwned, protected agent blocks exfiltration

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk because this PR is additive (new skill + documentation) and only touches plugin registration; it doesn’t modify existing automation logic, though the new CDP-interception script should be reviewed for correct fail-closed behavior and safe CLI parsing.

Overview
Adds a new domain-firewall skill that can attach to Browserbase or local Chrome via CDP and block/allow navigations by domain using Fetch.requestPaused interception, with CLI flags for --allowlist, --denylist, --default, --json, and --quiet.

Registers the skill in .claude-plugin/marketplace.json and ships supporting docs (SKILL.md, REFERENCE.md, EXAMPLES.md), plus a small Node package (ws dependency) and the domain-firewall.mjs script that resolves Browserbase CDP URLs via bb sessions debug, optionally auto-attaches from a browser target to a page target, and gracefully disables interception on shutdown.

^{Reviewed by Cursor Bugbot for commit 93df23b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[aq17]

Inspired by @shubh24 's sample script for Notion who raised this as a top-of-mind guardrail for security

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Missing await on sendCDP calls in event handler
  • I confirmed the missing awaits in installDomainFirewall and added await to all page.sendCDP calls in the Fetch.requestPaused handler to prevent unhandled rejections and stuck paused requests.

Or push these changes by commenting:

@cursor push 36f6f7fbd8

Preview (36f6f7fbd8)

diff --git a/skills/domain-firewall/SKILL.md b/skills/domain-firewall/SKILL.md
--- a/skills/domain-firewall/SKILL.md
+++ b/skills/domain-firewall/SKILL.md
@@ -300,7 +300,7 @@
       // Pass through non-document requests (images, CSS, JS, fonts, etc.)
       const resourceType = params.resourceType || "";
       if (resourceType !== "Document" && resourceType !== "") {
-        page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
+        await page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
         return;
       }
 
@@ -310,7 +310,7 @@
         url.startsWith("about:") ||
         url.startsWith("data:")
       ) {
-        page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
+        await page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
         return;
       }
 
@@ -318,7 +318,7 @@
       try {
         domain = normalizeDomain(new URL(url).hostname);
       } catch {
-        page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
+        await page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
         return;
       }
 
@@ -334,13 +334,13 @@
           time: ts(), domain, url: url.substring(0, 80),
           action: "ALLOWED", decidedBy,
         });
-        page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
+        await page.sendCDP("Fetch.continueRequest", { requestId: params.requestId });
       } else {
         auditLog?.push({
           time: ts(), domain, url: url.substring(0, 80),
           action: "BLOCKED", decidedBy,
         });
-        page.sendCDP("Fetch.failRequest", {
+        await page.sendCDP("Fetch.failRequest", {
           requestId: params.requestId,
           errorReason: "BlockedByClient",
         });

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Case-sensitive www prefix strip before lowercasing
  • Updated domain normalization to lowercase before stripping the www prefix in both the runtime script and SKILL example code.

Or push these changes by commenting:

@cursor push e179cf303d

Preview (e179cf303d)

diff --git a/skills/domain-firewall/SKILL.md b/skills/domain-firewall/SKILL.md
--- a/skills/domain-firewall/SKILL.md
+++ b/skills/domain-firewall/SKILL.md
@@ -180,7 +180,7 @@
 
 ```typescript
 function normalizeDomain(hostname: string): string {
-  return hostname.replace(/^www\./, "").toLowerCase();
+  return hostname.toLowerCase().replace(/^www\./, "");
 }
 
 function ts(): string {

diff --git a/skills/domain-firewall/scripts/domain-firewall.mjs b/skills/domain-firewall/scripts/domain-firewall.mjs
--- a/skills/domain-firewall/scripts/domain-firewall.mjs
+++ b/skills/domain-firewall/scripts/domain-firewall.mjs
@@ -95,7 +95,7 @@
 // =============================================================================
 
 function normalizeDomain(hostname) {
-  return hostname.replace(/^www\./, "").toLowerCase();
+  return hostname.toLowerCase().replace(/^www\./, "");
 }
 
 function ts() {

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[aq17]

Potential messaging:

Your browser agent just got prompt injected. One hidden link on a page, and your session
   token is on its way to an attacker.

  We built a fix: domain-firewall. One CLI command, zero code changes. It intercepts every
   navigation at the Chrome DevTools Protocol level — before the request ever leaves the
  browser.

  node domain-firewall.mjs --session-id <id> --allowlist "stripe.com" --default deny

  Not on the allowlist? Killed instantly. No bytes reach the attacker.

  We tested it: same page, same malicious link. Without the firewall — data exfiltrated.
  With it — ERR_BLOCKED_BY_CLIENT. Done.

  Open source, ships as a Browserbase skill. Go protect your agents.

How it works

  1. Agent creates a Browserbase session via bb sessions create
  2. Agent runs node domain-firewall.mjs --session-id <id> --allowlist "example.com"
  --default deny
  3. The script connects to the session's CDP WebSocket (resolved via bb sessions debug)
  4. It sends Fetch.enable to intercept all network requests at the protocol level
  5. On every Fetch.requestPaused event, it checks the domain against the denylist →
  allowlist → default verdict
  6. Allowed: Fetch.continueRequest. Blocked: Fetch.failRequest("BlockedByClient")
  7. Logs every decision to stdout. Runs until Ctrl+C or session ends.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5c7e9f4. Configure here.}