WebXRay

Turn any website load into a living, replayable map of its requests, dependencies, trackers, storage, workers, and persistent connections—entirely on your machine.

Explore the live WebXRay showcase and field guide

WebXRay is a local web observatory, not another table-shaped DevTools clone. Paste a URL and a clean Chromium context reconstructs the page as an animated dependency system. Watch services wake up, follow who invited whom, inspect recognition and cookie lifecycles, replay the load, compare the state after consent, then export the evidence as JSON, a standalone report, or a branded forensic film.

Try it in two commands

Requirements: Node.js 22+, npm, and Chrome/Chromium.

npm ci
npm run dev

Open http://127.0.0.1:4178, then choose Watch the 8-second demo for a deterministic, offline product tour—no URL, account, API key, or network access required.

If Chrome is not installed, install Playwright Chromium once:

npx playwright install chromium

Why WebXRay exists

A modern website is a supply chain: first-party code invites CDNs, tag managers invite analytics, analytics invite advertising systems, cookies appear and rotate, and workers or WebSockets continue after the visible page has loaded. Traditional network panels expose the raw entries but leave the causal system for the reader to reconstruct.

WebXRay makes that system the product:

Lens	Question it answers
Organism	What belongs to the site, and what orbits outside it?
Cascade	When did each service wake up?
Lineage	Who invited whom through redirects and sanitized initiators?
Recognition	Which relationships can recognize a visit across time or context?

The inspector explains each relationship in plain language, including transfer, runtime behavior, browser security boundaries, storage changes, and causal ancestry.

What it observes

• Requests, responses, redirects, failures, types, timing, and transfer size
• First-party and registrable-domain relationships
• Known analytics, advertising, attribution, session-replay, support, CDN, and functional services
• Conservative tracker/recognition classification with explainable purposes
• Server cookie offers plus browser-confirmed set, update, and removal transitions
• Dedicated workers and service workers
• WebSocket open/activity/close state and frame counts
• Browser-facing security posture: HTTPS, HSTS, CSP, framing, MIME, referrer, permissions, and window isolation
• An isolated Consent aftershock that clicks only an unambiguous “accept all” control in a fresh browser context
• Replay at 0.5×, 1×, 2×, or 4×
• Portable JSON, standalone HTML reports, and self-playing 1280×720 WebM forensic films

Real interface evidence

First run	Causal focus

Mobile interface

Privacy and security boundary

WebXRay binds to 127.0.0.1 by default and launches an isolated browser context. It has no telemetry, account, hosted backend, or cloud persistence.

It deliberately does not preserve:

• request or response bodies
• page or frame contents
• WebSocket frame contents
• cookie values
• URL credentials or fragments
• query values (keys remain; values become redacted)
• passwords or everyday browser history

Cookie values are discarded immediately. A random, scan-local HMAC exists only long enough to detect that a stored value changed; it is never exported. Mutating API routes reject cross-site browser control, scans and retained sessions are bounded, and production responses carry a restrictive CSP and browser security headers.

The last completed baseline can be stored as sanitized metadata in browser localStorage (under 4 MB). The first-run screen exposes Forget to delete it. Server sessions are memory-only, retain at most 24 observations by default, and expire after 30 minutes.

Read the complete privacy model and security policy.

Usage

1. Paste an HTTP or HTTPS address.
2. Watch the live browser observation assemble the graph.
3. Switch lenses or select any signal to inspect its role and ancestry.
4. Pause, scrub, or replay the observation.
5. Optionally run Consent aftershock in a separate clean context.
6. Export the raw sanitized observation, living HTML report, or forensic film.

Keyboard shortcuts:

• Space: play or pause replay
• 1–4: switch visualization lens
• Arrow keys on the canvas: step through services
• Escape: close the inspector or export menu

Production build

npm ci
npm run build
npm start

npm run build produces a static client in dist/ and a compiled Node.js server in dist-server/. npm start never depends on the TypeScript development runner.

Health endpoints:

• GET /api/health — process liveness
• GET /api/ready — Chromium availability and scan capacity

Docker

Docker keeps the exposed host port on loopback even though the server must listen on the container interface:

docker compose up --build

Open http://127.0.0.1:4178. The container runs as a non-root user, uses a read-only application filesystem, and gives Chromium isolated temporary and shared-memory space.

Configuration

Every variable is optional. See .env.example for safe defaults.

Variable	Default	Purpose
WEBXRAY_HOST	127.0.0.1	Listening address
WEBXRAY_PORT	4178	Local HTTP port
WEBXRAY_ALLOW_REMOTE	0	Must be 1 before a non-loopback host is accepted
WEBXRAY_BROWSER_PATH	auto	Explicit Chromium-compatible executable
WEBXRAY_MAX_CONCURRENT_SCANS	2	Maximum simultaneous clean browsers
WEBXRAY_MAX_SESSIONS	24	Maximum retained in-memory sessions
WEBXRAY_MAX_EVENTS	20000	Per-observation metadata safety limit
WEBXRAY_SESSION_RETENTION_MS	1800000	Finished-session retention (30 minutes)
WEBXRAY_SCAN_TIMEOUT_MS	60000	Whole-observation safety deadline
WEBXRAY_LOG_LEVEL	info	quiet, info, or debug structured logs
WEBXRAY_SOURCE_MAP	0	Set to 1 to emit browser source maps

Non-loopback binding is intentionally explicit. If you expose WebXRay beyond your own machine, place authentication and TLS at a trusted reverse proxy; the built-in API is designed as a local control plane.

Development and verification

Command	Result
npm run dev	Start Vite middleware and the local scanner
npm run format	Format source and documentation
npm run format:check	Verify formatting without writes
npm run check:docs	Verify local documentation and image links
npm run lint	Run ESLint, including React Hooks rules
npm run typecheck	Strict TypeScript validation
npm test	Run deterministic unit and server-boundary tests
npm run build	Build browser and compiled server artifacts
npm run test:e2e	Run real Chromium journeys with Playwright
npm run test:production	Build and smoke-test the compiled server and production CSP
npm run check	Run docs, format, lint, types, unit tests, and both builds
npm run ci	Run the full local equivalent of GitHub CI

GitHub Actions runs the static checks, unit tests, production builds, nine browser journeys, a compiled-production smoke test, and a production container build without repository secrets. Third-party Actions are pinned to reviewed revisions.

See CONTRIBUTING.md and the architecture guide for module boundaries and extension points.

Repository map

server/                 local control plane, validated config, Chromium scanner
src/components/         canvas visualization, icons, recovery boundary
src/domain/             privacy, classification, lineage, cookies, security
src/runtime/            observation state and privacy-safe exports
tests/                  real-browser journeys and responsive checks
docs/                   architecture, privacy, troubleshooting, product evidence
.github/                CI, dependency updates, issue and PR templates

Honest limitations

• WebXRay observes a finite load window, not an indefinitely open browsing session.
• Extremely short script-created cookies can appear and disappear between the 125 ms browser-jar samples; response cookie attempts are still captured immediately.
• Recognition labels combine a curated service catalog with conservative URL/type heuristics. They are evidence for inspection, not a legal determination.
• WebSocket payloads and HTTP bodies are intentionally excluded, so WebXRay explains relationships rather than application semantics.
• Bot protection, client certificates, unsupported browser features, or site policy can prevent an automated clean browser from loading a page.
• A site can behave differently for the WebXRay user agent or in a fresh browser profile.

See Troubleshooting for actionable recovery steps.

Project

• Changelog
• Contributing
• Security
• Code of Conduct
• Release checklist
• MIT License

Focused future work belongs in a small set of areas: community-maintained service intelligence, opt-in longer observation windows with the same bounded memory model, and more causal browser signals as Chromium exposes them safely.