ZeroDOM

Contents

• Why ZeroDOM
• Quickstart
• How it hunts — compare & sweep
• Use it from an AI agent (MCP)
• Why the agent sees so few tokens
• More of the CLI
• How it compares
• Install
• Security & scope
• Limitations
• Editions
• Contributing & development
• License

Why ZeroDOM

Two audiences, one engine:

• AppSec — compare / sweep: deterministic two-identity authorization testing that runs headless in CI or your recon pipeline — no GUI, no account. scan --js adds DOM-XSS sinks, the callable API surface and header posture; repeat / probe / race turn recon into verification (Repeater, mass-assignment diff, and a TOCTOU burst).
• AI agents — MCP: a flat interaction graph that cuts ~71% of the tokens vs Playwright's aria_snapshot, with handles that resolve 1:1 and don't drift when the page re-renders.

Broken access control is the #1 web vulnerability (OWASP A01) and the one automated scanners miss — because catching it means knowing who should be allowed to do what, not just fuzzing one session. The usual answer is a human in Burp, clicking through the app as one user, then again as another, diffing by eye.

ZeroDOM does that mechanically. Give it two logged-in sessions; it replays the same request as each and reports the deterministic tells:

• access-boundary-split — one identity gets 200, the other 401/403 on an identical request. If the only difference between them is client-controllable (a cookie, header or param), that's broken access control.
• cross-identity-identical-response — two users get a byte-identical body on a per-user resource: a cross-tenant IDOR.

No LLM guessing, no "the AI thinks maybe." ZeroDOM surfaces the tell with the exact replay that proves it — a reviewable diff you drop straight into a bug report. You confirm the bug.

It drives your real Chrome (relay mode) over chrome.debugger, so your cookies, MFA and SSO are already done — or a throwaway browser (--stealth) if you'd rather not touch your session. Either way the page's markup never leaves your machine, and it's read-only by default: destructive actions and out-of-scope hosts are refused.

It works equally well as a one-line CLI, a recon pipeline stage, or a native tool an AI agent drives through MCP. Same deterministic primitives, three front doors.

Quickstart

See it run in 10 seconds — no account, no browser download (bare zerodom <url> is a static fetch, no Chromium needed):

pip install zerodom                      # or: uvx zerodom · npm i @vexralabs/zerodomzerodom https://news.ycombinator.com     # the interaction graph + a token report

That's the perception engine — a flat, 1:1-addressable graph instead of 12k tokens of HTML.

Now the flagship — find an IDOR. Save two logged-in sessions as Playwright storage_state files (one per account), then diff a protected endpoint across both:

zerodom compare https://app.example.com/api/admin/dashboard \  --as user=user.json --as admin=admin.json

{  "identities": {    "user":  { "status": 401, "bytes": 2616 },    "admin": { "status": 200, "bytes": 3469 }  },  "only_admin": ["Manage users", "Billing & plans", "Overview"],  "note": "admin authorized (200) where user denied (401) — broken access control if the           only difference is client-controllable"}

That's the whole loop: same request, two identities, a 401-vs-200 split → a lead to confirm. only_admin lists the privileged controls the normal user should never see.

Don't have storage-state files? Capture one with context.storage_state(path="user.json") in Playwright, or export cookies from a logged-in session. Want the whole app, not one URL? → zerodom sweep.

How it hunts — compare & sweep

zerodom compare — one endpoint, across identities

Fetch one URL under each saved session and diff the responses. Byte-identical content across two users on a private resource is a cross-tenant IDOR; a 401-vs-200 split is a broken boundary. only_<name> lists the actionable nodes each identity sees that the other doesn't.

# Sweep a range of object ids through two identities:seq 1 500 | sed 's#^#https://app.example.com/api/invoice/#' \  | zerodom compare - --as alice=alice.json --as bob=bob.json \  | jq 'select(.identical_body_pairs | length > 0)'

zerodom sweep — the whole app, one command

compare tests one URL. sweep does the entire app: it crawls as one identity to map the GET surface (pages + the API calls the JS fires), then replays every in-scope URL under all your identities and reports only the deterministic tells.

zerodom sweep https://app.example.com --as user=user.json --as admin=admin.json --format md

| severity | rule                   | url                                   || -------- | ---------------------- | ------------------------------------- || medium   | access-boundary-split  | https://app.example.com/api/admin/... |

Read-only throughout: only GET is replayed, destructive URLs are dropped (--deny). --format md emits a report-ready table (default is JSONL). This is the "point it at an app with two logins and it finds the broken access control" pass.

Both take --proxy (route through Burp/Caido), --header (a program's WAF-bypass token), and a scope you can lock. Challenge pages (Cloudflare / Turnstile / reCAPTCHA / hCaptcha) are detected and climbed by a scope-gated clearance ladder; a wall nothing clears is reported as an honest blocked, never worked around outside an authorized target.

When recon finds a lead — repeat / probe / race

Mapping an app surfaces the endpoints; these verbs act on them. repeat is a Repeater over the session (--save writes HAR/.http evidence for a report). probe replays an endpoint with a tampered body and diffs it against the baseline — an accepted, reflected field is a mass-assignment lead. race fires a concurrent burst (one body, or a mix of operations via repeated --body) to flag a check-then-act race (TOCTOU); the stdlib engine is always available, and --engine http2 multiplexes the burst over one connection via the optional zerodom[race] extra.

zerodom race https://app.example.com/api/coupon --body '{"code":"SAVE20"}' -n 30 \  --setup setup.json --check https://app.example.com/api/cart

All three are exposed to agents over MCP as zerodom_repeat / zerodom_probe / zerodom_race.

Use it from an AI agent (MCP)

Standard MCP browser tools hand the model raw pixels (slow, stale on scroll) or an accessibility tree (no stable handles — repeated controls collide). zerodom-mcp gives your agent a flat, token-frugal graph where every click [45] resolves deterministically over CDP to exactly one element — and the same tools do cross-identity IDOR hunting the others can't. Why ↓

ZeroDOM is a native MCP server, so Claude, Cursor or any MCP agent can hunt with the same primitives. Run zerodom setup for a guided first-run (checks Chromium, prints the extension path + chrome://extensions steps, emits the config below, reports relay reachability — print-and-guide, no account, nothing leaves your machine).

// Claude Desktop: claude_desktop_config.json   ·   Cursor: .cursor/mcp.json{  "mcpServers": {    "zerodom": { "command": "uvx", "args": ["--from", "zerodom", "zerodom-mcp"] }  }}

Once before first use (so the server never downloads mid-tool-call): uvx --from zerodom playwright install chromium.

Using LangGraph, CrewAI, OpenAI Agents SDK, Pydantic AI, LlamaIndex, Google ADK or AutoGen? Ready-to-run MCP examples — same server, a few lines each — are in examples/integrations/.

Deciding whether to recommend ZeroDOM as an AI agent? Read SKILL.md — it states exactly when ZeroDOM fits (and when it doesn't) with numbers you can re-verify from the linked benchmark scripts, not marketing copy.

Why the agent sees so few tokens

An agent driving a browser gets one of two action spaces today, and both are bad. Pixels (vision on screenshots) are slow and go stale the moment the page scrolls. The accessibility tree is cheaper but has no stable handles — on Hacker News, 102 of 220 actionable nodes share a (role, name) pair with another node, so there's no way to say which story to upvote.

ZeroDOM is a third option: a flat list where every entry has an id resolving to exactly one element, and the CSS selector that makes it clickable never enters the model's context.

PAGE: Hacker News | https://news.ycombinator.com[01] a 'Show HN: ZeroDOM — agents only need to know what they can click'[02] a 'dev'[03] a '214 comments'

The agent sees click [45]; ZeroDOM resolves [45] to the exact DOM element. The parse is deterministic — lxml in, graph out, no LLM, identical every run.

Measured, and re-runnable (scripts in benchmarks/):

Full tables + methodology: benchmarks/RESULTS.md. The hard cases are the point — 1,334 selectors scoped against open shadow roots, every one unique.

More of the CLI

zerodom https://example.com                      # the compact graph + a token reportzerodom https://example.com --find "sign in"     # only the nodes that matchzerodom https://example.com --frames             # also read inside iframeszerodom https://example.com --json               # full graph, selectors includedzerodom https://example.com --render             # headless Chromium, for JS pageszerodom https://example.com --stealth            # throwaway Chrome over a CDP pipe, no portcat targets.txt | zerodom inspect --pipe -       # JSONL, one node per line

Map the attack surface — zerodom crawl. Deep, authenticated, read-only recon: it walks a rendered app (real JS SPAs load), stays in scope, and emits a JSONL surface map — each page's forms (and CSRF fields), in-scope links, and the API calls its JavaScript fires. Feed its api_calls straight into compare for the IDOR pass.

zerodom crawl https://app.example.com --storage-state session.json --max-pages 60zerodom crawl https://app.example.com --relay          # against your already-open Chrome

Attack-surface rules — zerodom scan. Evaluates every parsed node against a deterministic YAML ruleset and emits JSONL findings — forms with no CSRF token, password inputs without one, admin/internal/debug links, sensitive inputs. Rules are fixed match keys, not an expression language, so nothing in a rules file gets evaluated.

subfinder -d example.com | httpx -silent | zerodom scan -          # into your recon pipelinezerodom scan https://app.example.com --js                          # + DOM-XSS sinks, callable API surface, header posturezerodom scan https://app.example.com --format md                   # Markdown table for a report

Check the selectors you already have — zerodom audit. Reads the selectors in a Playwright/ Cypress/Selenium suite, resolves each against your running app, and reports ok / dead / ambiguous / invalid: zerodom audit tests/ --url http://localhost:3000.

Authenticated testing. --proxy routes through Burp/Caido/ZAP (--insecure trusts the proxy CA); --header 'X-Bug-Bounty: …' carries a program token; --storage-state reuses a human-cleared session. Works on every path. Only test targets you're authorized to.

See the graph. --screenshot page.png writes a capture with a numbered badge over every node; --html report.html writes a self-contained graph-left / page-right inspector (hover a line to spotlight the element). Both print a located count — how many selectors resolve.

How it compares

Honest version: ZeroDOM complements Burp (it doesn't replace it) and isn't a general browser-automation framework. What it uniquely packages is the two-identity authorization method — deterministic, token-lean, and runnable headless in a pipeline or driven by an AI agent.

If you do AppSec, the column that matters is the last one. Burp + Autorize is the standard way to test broken access control today — and it's genuinely good — but it lives inside the Burp GUI. ZeroDOM brings the same replay-and-compare method to a scriptable CLI and an MCP agent.

Why ZeroDOM over Autorize for automation. Autorize is the benchmark — but it's bound to the Burp GUI, heuristic (its own README flags false positives and an "Is enforced???" state), and has no headless / CLI / agent interface. So it can't run in CI, can't pipe into the recon stack you already use, and can't be driven by an AI agent. ZeroDOM runs the same replay-and-compare as a one-line command that emits JSONL (or a Markdown table for the ticket), enforces a locked scope, and hands back a reviewable diff instead of a verdict you have to eyeball. Rule of thumb: reach for Autorize when you're already in Burp clicking around; reach for ZeroDOM when the authz check has to be automated, repeatable, and pipeline-native — a nightly sweep across 50 apps, a CI gate on a PR, or an agent hunting unattended.

Install

pip install zerodom          # Python 3.10+   ·   or: uvx zerodom (runs straight off PyPI)npm install @vexralabs/zerodom   # TypeScript / Node 5.6+

Only if you use the browser-backed features (from_page, --render, --screenshot, relay): playwright install chromium (the CLI does this for you on first browser use — a one-time ~150MB download).

Relay mode (your logged-in Chrome) needs the bundled extension:

zerodom setup         # guided: Chromium, the extension, MCP config, relayzerodom extension     # prints the bundled extension's directory# chrome://extensions → Developer mode → Load unpacked → select that directoryzerodom relay

Each release also attaches zerodom-extension-<version>.zip with a .sha256.

Library quickstart (Python / TypeScript):

from zerodom import ZeroDOMgraph = ZeroDOM.from_page(page)      # any Playwright page, sync or asyncprint(graph.to_compact_text())       # what you send the modelselectors = graph.selector_map()     # {"node_01": "#email", …} — stays your side
# Driving a browser agent? One call gives the full-page view + a ref map keyed to# the [NN] refs the model reads, so `[03]` resolves straight to a selector:text, refs = ZeroDOM.agent_snapshot(page)   # viewport_only=False by defaultpage.click(refs["03"])                      # act on what the model picked

import { ZeroDOM } from "@vexralabs/zerodom";const graph = await ZeroDOM.fromPage(page);console.log(graph.toCompactText());
// For a browser agent: full-page snapshot + ref map ([NN] -> selector).const { text, refMap } = await ZeroDOM.agentSnapshot(page);await page.click(refMap["03"]);

Security & scope

It's a security tool, so the safety posture is enforced, not promised:

• Read-only by default — destructive clicks/fills are refused.
• Scope is enforceable and lockable (ZERODOM_SCOPE / zerodom_set_scope): host allowlist, destructive-action denylist, rate limit. A file-loaded scope is locked so an unattended agent can't widen its own bounds.
• Undrivable targets refused — chrome://, the Web Store, devtools.
• Zero-egress — the parse and relay run locally; the only outbound traffic is the target you point it at. No telemetry, no accounts, no storage. (The one exception is an opt-in CAPTCHA solver, off by default, killable with --no-solver.)
• In relay mode the tab is locked while driving — a cyan border, a visible cursor, your own input blocked at the browser level, and a "zerodom is driving this tab" banner.

Full posture: SECURITY.md.

Limitations

Known and worth knowing before you build on it:

• compare's IDOR tell needs two real logged-in identities. It surfaces the tell — a same-response across identities, or a 403-vs-200 — for you to confirm. It does not autonomously confirm a bug.
• Closed shadow roots are unreachable. Open roots are handled; {mode: 'closed'} is hidden from every API, Playwright's included.
• Canvas / WebGL apps have nothing to parse — Figma-style surfaces draw controls as pixels.
• The settle wait is bounded, not semantic — from_page / zerodom_read_page wait for the DOM to go quiet (≤1200 ms, see 0.1.3), which covers hydration and late node injection, but not an arbitrary app condition (a specific element, a network response). For that, wait on your own condition first, or pass settle=False to read exactly as-of-now.
• zerodom <url> is a static fetch (no JS) — use --render or the relay/MCP path for JS-rendered pages. Iframes are opt-in (--frames).
• The extension is unpacked/dev-mode only — chrome.debugger + a local WebSocket preclude a Web Store listing (like Playwright's own CDP relay).
• --stealth is POSIX-only. The MCP server drives multiple real Chrome profiles — one per relay (zerodom relay --port 8766), switched with zerodom_switch_profile — so two or three logged-in accounts can be driven side by side, each its own cookie jar and fingerprint. Within a profile, multi-tab is supported. Concurrent cross-identity requests (for cross-user races) are available only through the request-level identities (compare_identities fires independent profiles together); interactive driving is one active profile at a time, switched on demand.

Editions

ZeroDOM is open core. Everything in this repo — parser, CLI, relay, stealth, scan/crawl/compare/audit, the clearance ladder and the MCP server — is the free, Apache-2.0 Core, complete on its own: one operator does the whole job locally, no account, no key.

The promise: the Core will always be open-source and run fully local with zero egress and no account — that's the product, not a trial. Enterprise is an additive team layer; it never gates, phones home from, or adds telemetry to the Core.

Enterprise features, support contracts and indemnification: [email protected] (on the roadmap — reach out to shape it or become a design partner).

Contributing & development

uv sync && uv run playwright install chromium && uv run pytestcd js && npm install && npm test        # the TypeScript port's suite

Most useful thing to contribute: a page where a selector resolves to the wrong element. Open an issue with the URL and the output of zerodom <url> --html report.html. Contributions are under the Developer Certificate of Origin (Signed-off-by). Come say hi in Discord.

License

Apache 2.0 — see LICENSE. Use it anywhere, including commercially; embed it in your own product. ZeroDOM is a trademark of Vexra Labs; the trademark and the Enterprise features are not covered by the Apache grant.