agent-browser-shield

Alpha prototype: rulesets may change without notice

Agent Browser Shield is a Chromium extension for making agentic browser-use more effective and secure:

• Token efficiency: strip page chrome (footers, cookie banners, chat widgets, sponsored content) so agents spend tokens on the user's task.
• Security & compliance: mask PII and credentials before they reach the model, and suppress hidden text, HTML comments, and user-generated content that could carry prompt-injection payloads.
• Accuracy: block manipulative dark patterns and hide engagement rails and other content that could distract the model from the user's task.

Documentation — install guide, rule reference, and configuration.

Live demo site — RiverMart, a mock e-commerce SPA that exercises every rule. Load it with and without the extension to see the before/after difference.

ClawHub skill — for skill-aware OpenClaw agents, install with clawhub install agent-browser-shield to load the install paths and runtime behavior contract.

Before	After

Prerequisites

• Node ≥ 24 and Bun ≥ 1.3 — extension and demo site
• uv — runs the Python scripts (each declares its own PEP 723 deps; the repo pins Python 3.14 via .python-version, but scripts work on 3.11+)
• Chrome / Chromium 148+ — to load the unpacked extension

Repository layout

Path	What's there
extension/	Chromium MV3 extension (Bun + TypeScript)
demo-site/	Vite/React mock e-commerce site that exercises every rule
docs/	Astro Starlight docs site
benchmark/	Tasks, scenarios, and pricing for the agent benchmark harness
scripts/	PEP 723 scripts: agent task runner, benchmark harness, trace tools
skills/	Claude Code skills for installing, configuring, and diagnosing

Extension

The Chromium MV3 extension lives in extension/. Build output goes to extension/dist/, which is what you load as an unpacked extension at chrome://extensions.

Build

cd extension
bun install
bun run build

Customize build-time defaults

Which rules ship on by default is enumerated in extension/data/rule-defaults.json. To ship a build with a custom set without forking the repo, pass an override file to bun run build. The file is a flat JSON object whose keys are rule ids (same keys the Options-page export uses) plus a small set of reserved non-rule keys — currently optionsButton (boolean, default off) to enable the floating on-page button that opens the options page:

bun run build --defaults ./my-defaults.json
# or:
EXTENSION_DEFAULTS_FILE=./my-defaults.json bun run build

Overrides only apply to fresh chrome.storage; users with toggled state keep their preferences. See the install guide for details.

Watch for changes

bun run watch rebuilds extension/dist/ whenever a file in extension/src/ changes:

cd extension
bun run watch

After each rebuild, click the reload icon for the extension at chrome://extensions (or use a tool like Extensions Reloader) and refresh any open tabs to pick up the new content script.

Tests

Rule unit tests run under Jest against a jsdom DOM. They live alongside the source in extension/src/rules/__tests__/.

cd extension
bun install
bun run test

Filter to a single suite with the standard Jest CLI, e.g. bun run test -- pii-mask.

Refresh EasyList snapshot

The ads-hide rule bundles a snapshot of EasyList's generic element-hiding selectors (extension/src/rules/easylist-generic.generated.ts, ~13k selectors). Refresh it when ad-network selectors drift:

cd extension
bun run fetch-easylist   # alias for `uv run scripts/fetch_easylist.py`

The generated file is committed to keep builds deterministic and offline-capable; pre-commit hooks and Biome skip *.generated.* files.

Package for Browserbase

Bundle extension/dist/ into a ZIP suitable for uploading via the Browserbase extensions API:

cd extension
bun run build
bun run package           # writes output/agent-browser-shield-extension.zip at the repo root
# or specify an output path / directory:
bun run package -- ~/Downloads/agent-browser-shield.zip

The output/ directory is gitignored.

Demo site

demo-site/ is a Vite/React mock e-commerce SPA ("RiverMart") that deliberately packs the threats and dark patterns agent-browser-shield defends against onto a few pages. Load it with and without the extension to see the before/after difference.

Live deployment: https://shield-dark-pattern-demo.vercel.app/

To run it locally instead:

cd demo-site
bun install
bun run dev          # http://localhost:5173

See demo-site/README.md for the per-page rule coverage and Vercel deploy instructions.

Agent task

scripts/agent_task.py runs a Browserbase agent task via the Stagehand Python SDK. The script declares its dependencies inline (PEP 723), so uv will fetch them on first run.

Copy env.sample to .env and fill in the API keys, then:

# Without the extension
uv run scripts/agent_task.py --instruction "Find the top story on HN"

# With the agent-browser-shield extension uploaded and loaded into the session
# (requires running the packaging script above first)
uv run scripts/agent_task.py --with-extension \
    --instruction "Find the top story on HN"

Benchmark harness

scripts/benchmark_run.py compares agent performance across configurations (extension on/off, model vendor/size, step budget) over a fixed task set, judges each result inline, and writes a run bundle under output/results/<run_id>/. scripts/benchmark_report.py renders an HTML matrix with per-task side-by-side scenario diffs and a11y-tree comparisons.

# 1. Build + package the extension (only for scenarios with extension: true)
cd extension && bun run build && bun run package && cd ..

# 2. Run the benchmark
uv run scripts/benchmark_run.py \
    --scenarios benchmark/scenarios.example.yaml \
    --tasks benchmark/tasks.csv \
    --concurrency 25 -n 3

# 3. Render the report
uv run scripts/benchmark_report.py --run-id <run_id> --open

# 4. Resume / repair an incomplete run (idempotent)
uv run scripts/benchmark_resume.py --run-id <run_id>

Old run artifacts under output/results/ and output/reports/ are gitignored; prune them with uv run scripts/clean_artifacts.py (dry-run by default). See benchmark/README.md for the full workflow, BU Bench V1 fetch, and trace-bundle diagnostics.

Skills

skills/ holds Claude Code skills for installing, configuring, running tasks against, and diagnosing the extension. See each skill's SKILL.md for invocation details.

Contributing

See CONTRIBUTING.md for setup, expectations, and the contributor-license-agreement workflow. New rules are a great place to start — extension/src/rules/scarcity-hide.ts is a small worked example.

License

agent-browser-shield is source-available under PolyForm Shield 1.0.0. Use it commercially, internally, or for research at no cost — the only restriction is that you can't use it to build a product that competes with agent-browser-shield or with a PixieBrix product built on it. See LICENSING.md for details and how to obtain a commercial license if you need one.

Security

Please report vulnerabilities privately via GitHub's "Report a vulnerability" form. Do not open a public issue for security problems.

Disclaimer

agent-browser-shield reduces the threats a browser-use agent faces on a page, but it can't catch everything. Take precautions when using AI agents for browser use. The extension is provided as-is, without warranty of any kind — see LICENSE for the full terms.