{"id":51002834,"url":"https://github.com/pixiebrix/agent-browser-shield","last_synced_at":"2026-07-08T16:00:32.988Z","repository":{"id":361313895,"uuid":"1253999202","full_name":"pixiebrix/agent-browser-shield","owner":"pixiebrix","description":"Browser extension with 35+ rules for keeping your AI agent safe while browsing","archived":false,"fork":false,"pushed_at":"2026-07-01T23:04:59.000Z","size":3064,"stargazers_count":30,"open_issues_count":5,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T00:15:54.072Z","etag":null,"topics":["ai-agents","browser-extension","browser-use","security"],"latest_commit_sha":null,"homepage":"https://pixiebrix.github.io/agent-browser-shield/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pixiebrix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":".github/CLA.md"}},"created_at":"2026-05-30T03:02:10.000Z","updated_at":"2026-07-01T23:05:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pixiebrix/agent-browser-shield","commit_stats":null,"previous_names":["pixiebrix/agent-browser-shield"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/pixiebrix/agent-browser-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixiebrix%2Fagent-browser-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixiebrix%2Fagent-browser-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixiebrix%2Fagent-browser-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixiebrix%2Fagent-browser-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixiebrix","download_url":"https://codeload.github.com/pixiebrix/agent-browser-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixiebrix%2Fagent-browser-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35270196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","browser-extension","browser-use","security"],"created_at":"2026-06-20T17:00:21.328Z","updated_at":"2026-07-08T16:00:32.926Z","avatar_url":"https://github.com/pixiebrix.png","language":"TypeScript","funding_links":[],"categories":["AI Web Automation Tools"],"sub_categories":["Dev Tools"],"readme":"\u003c!-- markdownlint-disable MD033 MD041 --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/twitter/twemoji@14.0.2/assets/72x72/1f6e1.png\" width=\"84\" alt=\"Agent Browser Shield\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAgent Browser Shield\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eYour agent sees the page, not the traps.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/pixiebrix/agent-browser-shield/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/pixiebrix/agent-browser-shield?style=flat-square\u0026label=last%20commit\" alt=\"Last commit\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pixiebrix/agent-browser-shield/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/pixiebrix/agent-browser-shield/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pixiebrix/agent-browser-shield/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/pixiebrix/agent-browser-shield?style=flat-square\u0026label=release\" alt=\"Latest release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://chromewebstore.google.com/detail/agent-browser-shield/gnejacdioaelglahihpagpfjpddpnamd\"\u003e\u003cimg src=\"https://img.shields.io/chrome-web-store/v/gnejacdioaelglahihpagpfjpddpnamd?style=flat-square\u0026label=Chrome%20Web%20Store\" alt=\"Chrome Web Store\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-PolyForm--Shield--1.0.0-orange?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Chromium-supported-4285F4?style=flat-square\u0026logo=googlechrome\u0026logoColor=white\" alt=\"Chromium\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Chrome%20Extension-MV3-555?style=flat-square\" alt=\"Chrome Extension MV3\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/works%20with-browser--use-1f1f1f?style=flat-square\" alt=\"Works with browser-use\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/works%20with-Browserbase-1f1f1f?style=flat-square\" alt=\"Works with Browserbase\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e~11% fewer tokens \u0026middot; prompt injection blocked \u0026middot; PII masked\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003eThe token number is measured: gpt-5-mini via Browserbase, 19 real-web tasks, 3 runs each. Injection blocking and PII masking are built-in protections, not part of that token benchmark. A directional signal, not a published paper. Full method and task list in \u003ca href=\"./benchmark\"\u003ebenchmark/\u003c/a\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#what-it-does\"\u003eWhat it does\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#measure-it-on-your-own-sites\"\u003eTest your sites\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#try-it\"\u003eInstall\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://shield-dark-pattern-demo.vercel.app/\"\u003eLive demo\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://pixiebrix.github.io/agent-browser-shield/\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **Alpha prototype:** rulesets may change without notice\n\n______________________________________________________________________\n\n**The safety layer for the agentic web.** Agent Browser Shield sits between a\nbrowser-use AI agent and the web pages it visits, cleaning and securing each\npage before it ever reaches the model.\n\nAI agents are powerful but blind to manipulation. They burn tokens reading\ncookie banners and ad rails, get steered by prompt injection hidden in invisible\ntext, and chase dark patterns instead of the user's task. Agent Browser Shield\nstrips the noise, masks sensitive data, and blocks injection, so your agent sees\nthe page, not the traps.\n\n![Agent task with and without agent-browser-shield](./images/demo.webp)\n\n## What it does\n\n- **Token efficiency.** Strips page chrome (footers, cookie banners, chat\n  widgets, sponsored content) so the agent spends its context on the user's\n  task.\n- **Security and compliance.** Masks PII and credentials before they reach the\n  model, and suppresses hidden text, HTML comments, and user-generated content\n  that could carry prompt-injection payloads.\n- **Accuracy.** Blocks manipulative dark patterns and hides engagement rails\n  that distract the model from the user's task.\n\n## Benchmarks\n\nSame agent, same tasks, extension off vs on:\n\n```text\n┌─────────────────────────────────────────────────────────┐\n│  MEASURED   gpt-5-mini, 19 real-web tasks, 3 runs each  │\n│                                                         │\n│  TOKENS SAVED (avg)   ██░░░░░░░░  ~11%                  │\n│  TASK SUCCESS         █████████░  81% → 91%             │\n└─────────────────────────────────────────────────────────┘\n```\n\nThe injection and PII rows are protections the shield always applies, not\noutcomes of this token benchmark (the 19 tasks are all scraping tasks). Token\nsavings climb much higher on noisy pages, our single biggest drop was −71% on\nGitHub's trending feed. Here are some clean, repeatable wins, every run passed\nboth with and without the shield:\n\n| Page                  | Tokens vs baseline |\n| --------------------- | ------------------ |\n| weather.gov forecast  | **−62%**           |\n| GitHub issue search   | **−42%**           |\n| MDN docs              | **−26%**           |\n| Python docs           | **−26%**           |\n| Amazon product search | **−19%**           |\n\nOverall it's ~11% fewer tokens and task success from 81% to 91%. We keep the\nmisses in the data too, a few pages regress under the shield. See the\n[full per-task results](./benchmark/RESULTS.md) for every site and the\n[harness docs](./benchmark) for the method.\n\n## Measure it on your own sites\n\nOur ~11% is an average across 19 tasks. **Your** number depends entirely on what\nyour agent visits: noisy pages save far more (weather.gov −62%), lean pages save\nlittle, and a few regress (we're honest!). So don't take our word for it, get\nyours.\n\nPoint the harness at your own task list. It runs the same off-vs-on comparison\nand hands back a report with your real token and accuracy deltas:\n\n```sh\n# add the URLs + tasks your agent actually runs to a CSV, then:\nuv run scripts/benchmark_run.py \\\n    --scenarios benchmark/scenarios.example.yaml \\\n    --tasks your-tasks.csv -n 3\nuv run scripts/benchmark_report.py --run-id \u003crun_id\u003e --open\n```\n\nIt runs on your own Browserbase account, nothing leaves your machine but the\nagent traffic you already send. Full guide in [`benchmark/`](./benchmark).\n\n## Try it\n\n**[Install from the Chrome Web Store](https://chromewebstore.google.com/detail/agent-browser-shield/gnejacdioaelglahihpagpfjpddpnamd)**\nworks on any Chromium-based browser (Chrome, Edge, Brave, Arc, Opera). For agent\nruntimes that need an unpacked extension or a ZIP, see the\n[install guide](https://pixiebrix.github.io/agent-browser-shield/install/).\n\n**[Live demo site](https://shield-dark-pattern-demo.vercel.app/):** RiverMart, a\nmock e-commerce SPA that exercises every rule. Load it with and without the\nextension to see the before/after difference.\n\n**[Documentation](https://pixiebrix.github.io/agent-browser-shield/):** install\nguide, rule reference, and configuration.\n\n**[ClawHub skill](https://clawhub.ai/pixiebrix/agent-browser-shield):** for\nskill-aware [OpenClaw](https://openclaw.ai) agents, install with\n`clawhub install agent-browser-shield` to load the install paths and runtime\nbehavior contract.\n\n| Before                                              | After                                             |\n| --------------------------------------------------- | ------------------------------------------------- |\n| ![Before agent-browser-shield](./images/before.png) | ![After agent-browser-shield](./images/after.png) |\n\n## Where this is going\n\nThe agentic web is new, and its safety layer isn't solved yet. We're building it\nin the open: more rules, benchmarks across more models and sites, and a runtime\ncontract agents can rely on.\n\nIf that's a problem you care about, star the repo to follow along, and\n[open an issue](https://github.com/pixiebrix/agent-browser-shield/issues) with\nthe sites or attacks you want covered.\n\n## Prerequisites\n\n- **Node** ≥ 24 and **Bun** ≥ 1.3 — extension and demo site\n- **uv** — runs the Python scripts (each declares its own PEP 723 deps; the repo\n  pins Python 3.14 via `.python-version`, but scripts work on 3.11+)\n- **Chrome / Chromium 148+** — to load the unpacked extension\n\n## Repository layout\n\n| Path         | What's there                                                       |\n| ------------ | ------------------------------------------------------------------ |\n| `extension/` | Chromium MV3 extension (Bun + TypeScript)                          |\n| `demo-site/` | Vite/React mock e-commerce site that exercises every rule          |\n| `docs/`      | Astro Starlight docs site                                          |\n| `benchmark/` | Tasks, scenarios, and pricing for the agent benchmark harness      |\n| `scripts/`   | PEP 723 scripts: agent task runner, benchmark harness, trace tools |\n| `skills/`    | Claude Code skills for installing, configuring, and diagnosing     |\n\n## Extension\n\nThe Chromium MV3 extension lives in [`extension/`](./extension). Build output\ngoes to `extension/dist/`, which is what you load as an unpacked extension at\n`chrome://extensions`.\n\n### Build\n\n```sh\ncd extension\nbun install\nbun run build\n```\n\n### Customize build-time defaults\n\nWhich rules ship on by default is enumerated in\n[`extension/src/rules/rule-metadata.ts`](./extension/src/rules/rule-metadata.ts).\nTo ship a build with a custom set without forking the repo, pass an override\nfile to `bun run build`. The file is a flat JSON object whose keys are rule ids\n(same keys the Options-page export uses) plus a small set of reserved non-rule\nkeys:\n\n- `optionsButton` (boolean, default off) — floating on-page button that opens\n  the options page.\n- `runOnInactiveTabs` (boolean, default off) — keep observing while the tab is\n  hidden.\n- `debugTrace` (boolean, default off) — start with the dev-mode trace recorder\n  enabled so the popup's **Export** button can dump a JSONL trace without a\n  human flipping the toggle. Intended for automation builds (CDP, Browserbase).\n  The export shape is documented in\n  [`extension/data/debug-trace.schema.json`](./extension/data/debug-trace.schema.json).\n- `siteDenylist` (array of URL Pattern strings, default `[]`) — start with these\n  hosts already in the per-site enforcement denylist. When the active tab's\n  top-frame URL matches any entry, every rule is paused on that tab. Each entry\n  must satisfy `new URLPattern(entry)`; the build fails otherwise.\n\nSee\n[`extension/data/defaults-overrides.example.json`](./extension/data/defaults-overrides.example.json)\nfor a starting template:\n\n```sh\nbun run build --defaults ./my-defaults.json\n# or:\nEXTENSION_DEFAULTS_FILE=./my-defaults.json bun run build\n```\n\nOverrides only apply to fresh `chrome.storage`; users with toggled state keep\ntheir preferences. See\n[the install guide](https://agent-browser-shield.pixiebrix.com/install/#customizing-defaults-at-build-time)\nfor details.\n\n### Watch for changes\n\n`bun run watch` rebuilds `extension/dist/` whenever a file in `extension/src/`\nchanges:\n\n```sh\ncd extension\nbun run watch\n```\n\nAfter each rebuild, click the reload icon for the extension at\n`chrome://extensions` (or use a tool like\n[Extensions Reloader](https://chromewebstore.google.com/detail/extensions-reloader))\nand refresh any open tabs to pick up the new content script.\n\n### Tests\n\nRule unit tests run under [Jest](https://jestjs.io) against a\n[jsdom](https://github.com/jsdom/jsdom) DOM. They live alongside the source in\n`extension/src/rules/__tests__/`.\n\n```sh\ncd extension\nbun install\nbun run test\n```\n\nFilter to a single suite with the standard Jest CLI, e.g.\n`bun run test -- pii-redact`.\n\n### Refresh EasyList snapshot\n\nThe `ads-hide` rule bundles a snapshot of EasyList's generic element-hiding\nselectors (`extension/src/rules/easylist-generic.generated.ts`, ~13k selectors).\nRefresh it when ad-network selectors drift:\n\n```sh\ncd extension\nbun run fetch-easylist   # alias for `uv run scripts/fetch_easylist.py`\n```\n\nThe generated file is committed to keep builds deterministic and\noffline-capable; pre-commit hooks and Biome skip `*.generated.*` files.\n\n### Package for Browserbase\n\nBundle `extension/dist/` into a ZIP suitable for uploading via the\n[Browserbase extensions API](https://docs.browserbase.com/platform/browser/core-features/browser-extensions#browser-extensions):\n\n```sh\ncd extension\nbun run build\nbun run package           # writes output/agent-browser-shield-extension.zip at the repo root\n# or specify an output path / directory:\nbun run package -- ~/Downloads/agent-browser-shield.zip\n```\n\nThe `output/` directory is gitignored.\n\n## Demo site\n\n[`demo-site/`](./demo-site) is a Vite/React mock e-commerce SPA (\"RiverMart\")\nthat deliberately packs the threats and dark patterns agent-browser-shield\ndefends against onto a few pages. Load it with and without the extension to see\nthe before/after difference.\n\nLive deployment: \u003chttps://shield-dark-pattern-demo.vercel.app/\u003e\n\nTo run it locally instead:\n\n```sh\ncd demo-site\nbun install\nbun run dev          # http://localhost:5173\n```\n\nSee [`demo-site/README.md`](./demo-site/README.md) for the per-page rule\ncoverage and Vercel deploy instructions.\n\n## Agent task\n\n[`scripts/agent_task.py`](./scripts/agent_task.py) runs a\n[Browserbase agent task](https://docs.browserbase.com/use-cases/agents) via the\nStagehand Python SDK. The script declares its dependencies inline (PEP 723), so\n`uv` will fetch them on first run.\n\nCopy [`env.sample`](./env.sample) to `.env` and fill in the API keys, then:\n\n```sh\n# Without the extension\nuv run scripts/agent_task.py --instruction \"Find the top story on HN\"\n\n# With the agent-browser-shield extension uploaded and loaded into the session\n# (requires running the packaging script above first)\nuv run scripts/agent_task.py --with-extension \\\n    --instruction \"Find the top story on HN\"\n```\n\n## Benchmark harness\n\n[`scripts/benchmark_run.py`](./scripts/benchmark_run.py) compares agent\nperformance across configurations (extension on/off, model vendor/size, step\nbudget) over a fixed task set, judges each result inline, and writes a run\nbundle under `output/results/\u003crun_id\u003e/`.\n[`scripts/benchmark_report.py`](./scripts/benchmark_report.py) renders an HTML\nmatrix with per-task side-by-side scenario diffs and a11y-tree comparisons.\n\n```sh\n# 1. Build + package the extension (only for scenarios with extension: true)\ncd extension \u0026\u0026 bun run build \u0026\u0026 bun run package \u0026\u0026 cd ..\n\n# 2. Run the benchmark\nuv run scripts/benchmark_run.py \\\n    --scenarios benchmark/scenarios.example.yaml \\\n    --tasks benchmark/tasks.csv \\\n    --concurrency 25 -n 3\n\n# 3. Render the report\nuv run scripts/benchmark_report.py --run-id \u003crun_id\u003e --open\n\n# 4. Resume / repair an incomplete run (idempotent)\nuv run scripts/benchmark_resume.py --run-id \u003crun_id\u003e\n```\n\nOld run artifacts under `output/results/` and `output/reports/` are gitignored;\nprune them with `uv run scripts/clean_artifacts.py` (dry-run by default). See\n[`benchmark/README.md`](./benchmark/README.md) for the full workflow, BU Bench\nV1 fetch, and trace-bundle diagnostics.\n\n## Skills\n\n[`skills/`](./skills) holds Claude Code skills for installing, configuring,\nrunning tasks against, and diagnosing the extension. See each skill's `SKILL.md`\nfor invocation details.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, expectations, and the\ncontributor-license-agreement workflow. New rules are a great place to start —\n`extension/src/rules/scarcity-redact.ts` is a small worked example.\n\n## License\n\n`agent-browser-shield` is **source-available** under\n[PolyForm Shield 1.0.0](./LICENSE). Use it commercially, internally, or for\nresearch at no cost — the only restriction is that you can't use it to build a\nproduct that competes with `agent-browser-shield` or with a PixieBrix product\nbuilt on it. See [LICENSING.md](./LICENSING.md) for details and how to obtain a\ncommercial license if you need one.\n\n## Security\n\nPlease report vulnerabilities privately via GitHub's\n[\"Report a vulnerability\"](https://github.com/pixiebrix/agent-browser-shield/security/advisories/new)\nform. Do **not** open a public issue for security problems.\n\n## Privacy\n\nThe extension does not collect, store, or send any telemetry, analytics, or\nusage data. Rule processing runs locally in your browser; nothing is reported\nback to PixieBrix or any other server.\n\nThe one outbound network call the extension can make is the optional\n`irrelevant-sections-redact` rule (off by default), which sends a compressed\npage tree to OpenAI's API for classification when you enable the rule and\nconfigure an API key.\n\n## Disclaimer\n\n`agent-browser-shield` reduces the threats a browser-use agent faces on a page,\nbut it can't catch everything. Take precautions when using AI agents for browser\nuse. The extension is provided **as-is, without warranty of any kind** — see\n[LICENSE](./LICENSE) for the full terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixiebrix%2Fagent-browser-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixiebrix%2Fagent-browser-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixiebrix%2Fagent-browser-shield/lists"}