Tamandua Browser Guard

Alpha Manifest V3 browser extension for browser-native telemetry, Shadow AI, SaaS/DLP metadata, extension risk, and Web3 wallet-flow signals.

The extension is intentionally dependency-free so it can be loaded as an unpacked extension while the product contract stabilizes.

Current Status

Browser Guard is an alpha implementation, not a production-validated browser security product.

Evidence that is currently in place:

• Unit tests for shared classifiers, managed-policy handling, native bridge contract helpers, server contract filtering, scenario coverage, platform contracts, background health, browser exploit replay, and browser RASP replay.
• Static extension validation through npm run validate.
• Packaging through npm run package, producing local extension artifacts when the local packaging prerequisites are available.
• Metadata-only contracts for managed policy, extension health, native bridge health probes, exploit replay, and RASP replay.

Evidence that is not yet complete:

• Real E2E validation depends on a working Playwright Chromium extension environment and, for enterprise scenarios, managed browser policy and backend/agent lab services.
• Native bridge and endpoint-health integration are contract-level only. The extension declares nativeMessaging and can emit/query metadata fields, but there is no production-installed native host or agent identity binding proven here.
• Browser policy is local/AI-Gateway metadata enforcement only. Signed server policy, tenant policy UI, immutable audit, and production rollout controls remain gaps.
• Health reporting exists as browser.extension_health metadata, but there is no server-side source freshness dashboard or production SLO gate yet.

Load Locally

1. Open chrome://extensions.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select apps/tamandua_browser_extension.
5. Open the extension options page.
6. Configure:
   • Tamandua API base URL, for example https://agents.tamandua.treantlab.org;
   • API token;
   • tenant id when required by the backend;
   • user id or username for attribution.

Current Capabilities

• Navigation metadata and AI provider detection.
• Download metadata and risky download scoring.
• Upload, form submit, and paste metadata from content scripts.
• Lightweight local DLP categories without sending raw content.
• Web3 wallet provider/connect/sign metadata through a page bridge.
• Extension inventory and dangerous permission risk events.
• Batch ingest to /api/v1/ai-security/gateway/events/batch.
• Optional policy evaluation via /api/v1/ai-security/gateway/evaluate.
• Dynamic local block rules through declarativeNetRequest.
• Warning interstitial with audited continue-once bypass.
• Managed enterprise configuration through storage.managed.
• Metadata-only native messaging host manifest generation for Windows, macOS, and Linux enterprise deployment planning.
• RASP-derived runtime metadata classification for debugger/DevTools, function replacement, integrity drift, suspicious network, automation, and behavior anomaly signals, mapped to App Guard-compatible event names without raw DOM, request body, prompt, cookie, authorization header, or wallet secret capture.

Privacy Boundary

Default events are metadata-only. The extension does not send:

• prompt or response bodies;
• form values;
• cookies;
• authorization headers;
• wallet secrets, seed phrases, private keys;
• uploaded file contents.

Local classifiers emit category names, counts, and risk scores.

Backend Dependency

The extension currently sends events to the existing AI Gateway API:

• POST /api/v1/ai-security/gateway/events/batch
• POST /api/v1/ai-security/gateway/evaluate

The backend already rejects sensitive fields.

Production Gaps

• Signed managed policy cache, rollout controls, and immutable policy audit.
• Production native messaging bridge to the endpoint agent, including signed host validation and agent identity binding.
• Native host binary packaging, signing, install scripts, and production endpoint-agent validation.
• Server-side extension health source, stale/disabled detection, and dashboard/SLO gate.
• Server-side browser policy model beyond AI Gateway policy.
• Enterprise deployment profiles with stable extension id/update channel and managed policy evidence.
• Firefox packaging.
• Dedicated browser security dashboard.
• Backend alert/case correlation for browser events.
• Shared enterprise DLP classifier/policy path instead of lightweight local classifiers only.
• Threat-intel/reputation enrichment for URLs, extensions, and dapps.

Native Host Packaging Metadata

scripts/package-native-host.js generates and validates Chrome/Chromium native messaging host manifests for the Browser Guard host name com.tamandua.agent. The generated files live under native_host/generated and include Windows, macOS, and Linux manifest JSON plus enterprise install-location metadata.

This is metadata-only and not production validated. It does not ship or sign a native host binary, install registry/plist/filesystem entries, or claim endpoint agent availability.

node scripts/package-native-host.js
node scripts/package-native-host.js --validate-only
node scripts/package-native-host.js --extension-id <32-character-chrome-extension-id>

Validation

npm test
npm run validate
npm run package
npm run export:scenarios
npm run coverage:scenarios
npm run test:e2e
npm run benchmark

npm test, npm run validate, and npm run package are the core local gates for unit/static/package evidence. npm run package writes local artifacts under dist/browser-extension/.

test:e2e uses Playwright Chromium because Google Chrome stable ignores the sideload flags needed for automated extension tests. Treat this as environment-dependent: it requires a working local Chromium extension automation setup and does not by itself prove enterprise managed deployment, backend correlation, native bridge installation, or production policy rollout.

export:scenarios writes dist/browser-extension/security-scenarios.json with a 475-case cross-platform validation matrix covering Windows, macOS, Linux, managed browsers, backend behavior, and Browser Guard RASP replay.

coverage:scenarios writes dist/browser-extension/scenario-coverage.json; the current local run records 82 automated scenarios, including 5 automated browser_rasp_replay cases.

npm test also writes dist/browser-extension/browser-rasp-replay.json, a metadata-only replay artifact for debugger/DevTools, function replacement, integrity drift, suspicious network, and automation/behavior RASP fixtures.

npm run benchmark chains multiple local gates, including E2E and packaging. Use it as a broad local smoke/benchmark run, not as a production readiness claim.