README.md

The first browser MCP built for security testing.

Other browser MCPs let your AI fill forms and take screenshots.
This one lets it find vulnerabilities.

What It Does • How It's Different • Quick Start • Examples • Tools • Architecture

What It Does

hackbrowser-mcp gives your AI agent a real Firefox browser and 39 security testing tools via the Model Context Protocol. The agent can launch the browser, browse a target, capture all traffic, and test for vulnerabilities — all through natural language.

You: "Log in as admin and as a regular user. Find endpoints the user shouldn't access."

Agent: → launches Firefox
       → creates two isolated containers (admin + user)
       → logs in both accounts
       → browses the app, captures traffic
       → compares responses across roles
       → "User can access GET /api/admin/users — should return 403, returns 200"

The AI handles the entire workflow: launching the browser, managing sessions, discovering endpoints, testing parameters, and generating a security report. You describe what to test. It does the rest.

How It's Different

There are dozens of browser MCPs. They all do the same thing: let an LLM navigate pages, click buttons, and extract text. They're built for automation — filling forms, scraping data, running UI tests.

None of them can test for vulnerabilities. That's the gap hackbrowser-mcp fills.

Core Capabilities

Multi-Container Isolation

Run 2-4 browser sessions simultaneously, each with completely isolated state. This is the foundation for access control testing.

``$ ┌────────────────────────────────────────────────────────┐ │ \text{Firefox} \text{Instance} │ ├───────────────┬───────────────┬────────────────────────-┤ │ \text{Container} 1 │ \text{Container} 2 │ \text{Container} 3 │ │ \text{role}: \text{admin} │ \text{role}: \text{user} │ \text{role}: \text{guest} │ │ │ │ │ │ \text{cookies}: \text{A} │ \text{cookies}: \text{B} │ \text{cookies}: \text{none} │ │ \text{storage}: \text{A} │ \text{storage}: \text{B} │ \text{storage}: \text{none} │ │ \text{session}: ✓ │ \text{session}: ✓ │ \text{session}: ✗ │ └───────────────┴───────────────┴─────────────────────────┘

\text{compare_access} → "\text{GET} /\text{api}/\text{admin}/\text{users} \text{returns} 200 \text{for} \text{user} (\text{expected} 403)" \text{access_matrix} → \text{role} \times \text{endpoint} \text{grid} \text{showing} \text{every} \text{authorization} \text{gap} $``

Traffic Intelligence

Every HTTP request and response is captured, stored, and queryable. Replay any request with modifications.

Browser → Network Interceptor → In-Memory Store (10K max, FIFO)
                                       │
                             ┌─────────┴──────────┐
                             │                     │
                       Auto-save (60s)       Replay / modify
                             │                     │
                             ▼                     ▼
                       HAR file (disk)      replay_request
                             │              (change method,
                       Resume on restart     headers, body)

Active Security Testing

Discover injection points from captured traffic, then test them with 60+ payloads across 7 vulnerability types.

When built-in payloads get blocked, the AI agent analyzes the WAF response and crafts custom bypass payloads using replay_request.

Quick Start

Install

git clone https://github.com/user/hackbrowser-mcp.git
cd hackbrowser-mcp
bun install

Connect to your AI agent

{
  "mcpServers": {
    "hackbrowser": {
      "command": "bun",
      "args": ["run", "/path/to/hackbrowser-mcp/src/index.ts", "--mcp"]
    }
  }
}

bun run src/index.ts --launch              # GUI mode
bun run src/index.ts --launch --headless   # headless
bun run src/index.ts --mcp                 # MCP server (stdio)

Start testing

You: "Launch the browser and scan https://target.com for vulnerabilities"

That's it. The agent handles the rest.

Workflow Examples

Full Security Scan

You: "Crawl https://app.com, find injection points, test them, generate a report."

Agent: browser_launch → navigate → crawl (100 pages)
       → find_injection_points → test_injection (SQLi, XSS)
       → test_csrf → test_rate_limit
       → generate_report
       → "Found 3 XSS, 1 SQLi, 2 missing CSRF tokens"

IDOR / Access Control Audit

You: "Login as admin and regular user. Find what the user shouldn't access."

Agent: container_setup (admin + user) → container_login (both)
       → navigate admin pages → compare_access
       → access_matrix
       → "User can reach GET /api/admin/users (200 instead of 403)"

WAF Bypass

You: "Test the search param for XSS. Bypass any WAF."

Agent: test_injection {types: ["xss"]} → all blocked
       → analyzes response: <script> stripped, events filtered
       → replay_request with <details/open/ontoggle=alert(1)> → REFLECTED
       → "Confirmed XSS via HTML5 ontoggle event bypass"

Offline HAR Analysis

You: "Import this HAR file and find injection candidates."

Agent: import_har → get_endpoints (87 found)
       → find_injection_points (23 candidates)
       → test_injection → "2 reflected XSS confirmed"

Tools Reference (39 tools)

Library Usage

Use hackbrowser-mcp as a TypeScript library for custom tooling:

import {
  launchFirefox, closeFirefox,
  NetworkInterceptor, BrowserInteraction, Crawler,
  extractEndpoints, findInjectionPoints, testInjection,
  compareAccess, generateReport,
  buildHar, saveHar, loadHar,
} from "hackbrowser-mcp";

// Offline HAR analysis
const har = await loadHar("./capture.har");
const requests = harEntriesToRequests(har.log.entries);
const endpoints = extractEndpoints(requests);
const points = findInjectionPoints(requests);

console.log(`${endpoints.length} endpoints, ${points.length} injection candidates`);

Architecture

src/
├── browser/                 Firefox control
│   ├── bidi-client.ts       WebDriver BiDi protocol
│   ├── cdp-client.ts        CDP fallback
│   ├── launcher.ts          Binary detection + profile setup
│   ├── container-manager.ts Container isolation + extension WS
│   ├── interaction.ts       Click, type, scroll, hover
│   ├── crawler.ts           BFS spider
│   └── auth-detector.ts     Session detection
├── capture/                 Traffic
│   ├── network-interceptor.ts  Capture + auto-save (10K cap)
│   ├── har-builder.ts          HAR 1.2 builder
│   └── har-storage.ts          HAR I/O + merge
├── analysis/                Security engines
│   ├── active-tester.ts     60+ injection payloads
│   ├── injection-mapper.ts  Param → vuln type mapping
│   ├── endpoint-extractor.ts  API endpoint discovery
│   ├── container-differ.ts  Cross-role comparison
│   ├── access-matrix.ts     Role x endpoint matrix
│   └── report-generator.ts  Report formatting
├── protocol/
│   ├── tools.ts             39 tool definitions (Zod schemas)
│   └── mcp-server.ts        MCP stdio transport
└── types/                   TypeScript types

Design decisions:

• Firefox + BiDi first — Native Firefox protocol. Different rendering engine catches bugs Chrome-based tools miss. CDP available as fallback.
• Container isolation — Firefox Multi-Account Containers for true session separation. Not separate browser instances.
• Server-side fetch for testing — Active testing uses fetch() outside the browser to avoid polluting browser state.
• HAR 1.2 standard — Import/export for session continuity. Auto-save every 60s, resume on restart.
• Memory-bounded — 10K entry cap with FIFO eviction. 30s fetch timeout.
• Stealth by default — navigator.webdriver, UA, plugins, WebGL fingerprint all spoofed.

Limitations

• Firefox only (container isolation requires Firefox Multi-Account Containers)
• macOS / Linux (Windows not tested)
• One Firefox instance per port
• WebSocket frames not captured (only upgrade request)

For authorized security testing only.
Always obtain proper permission before testing any application.

MIT License • Built with Bun + TypeScript