browser-bridge

Bridge opencode into your browser. Read pages, execute JavaScript, and audit for security flaws — all from your terminal. Purpose-built for bug bounty hunting.

Why

Bug bounty hunters spend half their time switching between browser and tools. browser-bridge puts opencode directly inside the page. Browse normally, then ask opencode to read the DOM, run JS, or scan for vulnerabilities — no proxies, no manual export, no context switching.

Related MCP server: opencode-lens

Why not firefox-devtools-mcp

Alternative MCP servers like Mozilla's firefox-devtools-mcp drive Firefox externally through WebDriver BiDi. That approach works, but it leaves a detectable fingerprint:

• Sets navigator.webdriver = true and enables Marionette

• Alters other browser fingerprint signals

• Gets blocked by Cloudflare, Akamai, and other bot detection on the very targets you want to test

browser-bridge takes the opposite approach. Instead of driving the browser from outside, it runs inside the page as a Firefox addon. No WebDriver flag, no Marionette, no modified fingerprint — sites can't tell you're there. You see the page exactly as a real user does, which means the security findings you get are the ones that actually matter in the wild.

ZAP integration

browser-bridge works wonderfully alongside OWASP ZAP. Run ZAP as your proxy for active/passive scanning, and use browser-bridge to navigate, read responses, and dig into DOM sinks, CORS, and CSP from inside the page. The two complement each other: ZAP finds server-side issues, browser-bridge finds client-side ones — without either tipping off the target.

Architecture

opencode ──▶ MCP server (stdio) ──▶ Unix socket ──▶ host.js (native messaging) ──▶ browser addon ──▶ page

The MCP server talks to opencode over stdio. It forwards commands through a Unix socket to the native messaging host, which relays them into the browser's active tab. Responses flow back the same way.

Requirements

• opencode

• Firefox

• Node.js ≥ 18

Install

git clone https://github.com/jordandubu/browser-bridge
cd browser-bridge
npm install
./install.sh

install.sh registers the native messaging host with Firefox. Then add this to ~/.config/opencode/opencode.jsonc:

"mcp": {
  "browser-bridge": {
    "type": "local",
    "command": "node",
    "args": ["/path/to/browser-bridge/host/mcp-server.js"]
  }
}

Install the addon from the Firefox Add-ons store. Restart opencode.

Tools

Page Interaction

Recon & Monitoring

Vulnerability Hunting

Example: security audit

User: audit this page for vulnerabilities
opencode → browser_security → returns forms, scripts, cookies, external domains
opencode: "Found 3 issues:
  1. Login form submits over HTTP (no TLS)
  2. No CSP meta tag detected
  3. Inline script uses innerHTML with user-controlled input"

Example: DOM XSS hunt

User: check for DOM XSS on this page
opencode → browser_dom_sinks → returns sink list
opencode: "Found innerHTML usage in 2 inline scripts, eval() in 1 script"
opencode → browser_postmessage → returns postMessage logs
opencode: "postMessage listener at line 42 accepts any origin — potential XSS vector"

Example: CORS audit

User: check CORS on this page
opencode → browser_cors → returns cross-origin resources
opencode: "3 cross-origin scripts, 1 cross-origin stylesheet. Test each for misconfigured CORS"

CLI

For testing without opencode:

node host/bridge.js read              # read page text
node host/bridge.js html              # get page HTML
node host/bridge.js js "document.title"  # run JS
node host/bridge.js security          # extract security data
node host/bridge.js dom_sinks         # find DOM XSS sinks
node host/bridge.js storage           # dump cookies + storage
node host/bridge.js csp               # analyze CSP
node host/bridge.js cors              # find cross-origin resources
node host/bridge.js postmessage       # capture postMessage events
node host/bridge.js websocket         # capture WebSocket messages
node host/bridge.js event_listeners   # enumerate event handlers
node host/bridge.js strip_headers true  # strip security headers
node host/bridge.js strip_headers false # restore headers
node host/bridge.js navigate "https://example.com"  # navigate
node host/bridge.js tabs list         # list tabs
node host/bridge.js tabs switch 2     # switch to tab 2

Files

Testing

Tool tests — tests/

devbox run test-tools

Runs 16 tests covering all 15 browser_* tools against a local test page. Orchestrates HTTP server, extension (temp profile), and host bridge — then tears down on exit. CI-ready.

UI navigation bench — bench/ui/

Multi-page shop (catalog, cart, checkout, account) for exercising the navigation tools against realistic UI (menus, toasts, modals, tabs, pagination, late-injected elements).

devbox run bench-ui      # serve the shop on :8765
devbox run test-ui       # judge: run the shop through the MCP socket and grade each task

bench/ui/judge.js verifies the shop's interactions against a running bridge; bench/ui/grade.js scores a previously-run AI session from its evidence log. Regenerate the pages after editing shared markup with node bench/ui/build.js.

For fast dev iteration:

npm run dev          # start extension with temp profile
npm run reload-host  # restart host bridge

Contributing

PRs welcome. Only opencode is supported — if you want Cursor, Claude Code, or another MCP client, add it yourself. The bridge is client-agnostic (stdio MCP), so it should just work. Test with devbox run test-tools and npm run lint.

License

MIT