WEBXRAY FIELD GUIDE / 0.1 View source ↗

WebXRay field guide

WEBXRAY DOCUMENTATION

Field guide to the
invisible web.

Install the local observatory, understand its causal model, and preserve evidence without turning the tool into another browsing-history service.

Node.js 22+Local-firstMITPre-1.0
QUICK START01
npm ci
npm run dev

Open: http://127.0.0.1:4178. The built-in 8-second demo needs no URL, account, API key, or network access.

02 / CORE CONCEPTS

One observation. Four projections.

WebXRay converts sanitized browser events into a single derived model. Its canvas does not maintain four separate data sets; each lens asks a different question of the same preserved observation.

01

Organism

Groups the owned site core, non-recognition supply chain, and outer recognition frontier into deterministic semantic orbits.

02

Cascade

Places services on the load timeline so you can see when each dependency first became active.

03

Lineage

Reconstructs inviter relationships from redirects and sanitized initiators: who caused whom to appear.

04

Recognition

Surfaces evidence that a service may recognize a visit across time or context. This is evidence, not a legal determination.

WebXRay lineage lens showing the inviter hierarchy
Lineage projects each service by causal depth while preserving the same sanitized observation model.

03 / WORKFLOW

From target to evidence.

  1. 01

    Start a clean observation

    Paste an HTTP or HTTPS address. URL credentials and oversized inputs are rejected before a browser launches.

  2. 02

    Interrogate the load

    Watch services assemble live, switch lenses, select signals, pause, scrub, and replay at 0.5×, 1×, 2×, or 4×.

  3. 03

    Compare consent—optionally

    Consent aftershock runs in a separate clean context and clicks only an unambiguous “accept all” control.

  4. 04

    Export intentionally

    Create sanitized JSON, a portable HTML report, or a purpose-built 1280×720 WebM forensic film.

Target traffic is real. A live scan sends normal browser requests to the entered target and the services that target loads. The deterministic demo sends no target request.

04 / PRIVACY MODEL

Useful evidence. Deliberate absence.

Processing happens on your machine with no account, telemetry endpoint, hosted database, or cloud retention. WebXRay records only the metadata needed to reconstruct a page load.

Observed metadataNever retained
Sanitized URL structure and timingQuery values, credentials, fragments
Resource types and transfer sizeRequest and response bodies
Cookie names and attributesCookie values
Worker and WebSocket lifecyclePage content and frame payloads
Security headers and causalityNormal profile or browsing history

Retention and deletion

Server sessions live only in memory, are bounded in count, and expire after the configured window. The latest completed baseline may be stored as sanitized browser localStorage metadata under 4 MB. Use Forget on the first-run screen to remove it. Exported files remain under your control.

Cookie change detection

Values are discarded immediately. A random, scan-local HMAC may establish that a cookie changed without revealing its value. The key and derived identity do not survive the scan or enter exports.

05 / ARCHITECTURE

A narrow local control plane.

01React instrumentStart, cancel, replay, inspect
→
02Express control planeBounded local sessions
→
03Clean ChromiumIsolated observation context
→
04Sanitized eventsSSE into the derived model

src/runtime/useObservation.ts owns the scan lifecycle and replay clock. Deterministic functions in src/domain/ derive services, causal edges, cookies, recognition, and security findings. The scanner sanitizes data before events enter retained memory.

Remote access boundary: binding outside loopback requires WEBXRAY_ALLOW_REMOTE=1, but that acknowledgment does not add authentication. Put TLS, authentication, and network controls at a trusted reverse proxy.

06 / EXPORTS

Three evidence formats.

.JSON

Sanitized observation

The portable raw evidence model for further analysis.

.HTML

Living report

A standalone report designed to remain usable offline.

.WEBM

Forensic film

A self-playing 1280×720 canvas recording generated locally.

WebXRay cannot delete a file after you download it. Manage created exports with the operating system.

07 / CONFIGURATION

Safe defaults, explicit escape hatches.

Variable Default Purpose
WEBXRAY_HOST 127.0.0.1 Listening address
WEBXRAY_PORT 4178 Local HTTP port
WEBXRAY_ALLOW_REMOTE 0 Required before non-loopback binding
WEBXRAY_BROWSER_PATH auto Explicit Chromium-compatible binary
WEBXRAY_MAX_CONCURRENT_SCANS 2 Simultaneous clean browsers
WEBXRAY_MAX_SESSIONS 24 Maximum retained in-memory sessions
WEBXRAY_MAX_EVENTS 20000 Per-observation metadata limit
WEBXRAY_SESSION_RETENTION_MS 1800000 Finished-session retention
WEBXRAY_SCAN_TIMEOUT_MS 60000 Whole-observation deadline
WEBXRAY_LOG_LEVEL info quiet, info, or debug logs

All variables are optional. Production logs intentionally omit target URLs and captured data.

08 / KEYBOARD

The instrument stays navigable.

Space
Play or pause replay
1—4
Switch visualization lens
← →
Step through services on the canvas
Esc
Close the inspector or export menu

09 / TROUBLESHOOTING

Common field conditions.

Chromium is not ready

Check http://127.0.0.1:4178/api/ready. Install the managed browser if necessary:

npx playwright install chromium
Port 4178 is already in use

Choose another local port without changing the safe host default:

WEBXRAY_PORT=4180 npm run dev
A scan fails or stops early

Confirm the URL is HTTP or HTTPS with no embedded credentials. Run the deterministic demo to separate interface problems from target-network or automation policy problems.

Production differs from development

Rebuild both artifacts, then inspect health, readiness, and the browser console.

npm run build && npm start

SECURITY NOTE

A local tool with real browser power.

The API can launch a browser toward public, local, and private-network targets. That capability is intentional and is why the control plane must not be exposed to untrusted users. Mutating routes reject cross-site browser control, starts are rate-limited, and concurrency, events, duration, listeners, and retained sessions are bounded.

Report a vulnerability privately ↗

10 / HONEST LIMITATIONS

What the evidence cannot promise.

  • Observations cover a finite load window, not an indefinitely open browsing session.
  • Very short script-created cookies can change between browser-jar samples; response attempts are still captured immediately.
  • Recognition uses a curated catalog plus conservative heuristics. It is inspection evidence, not a legal determination.
  • HTTP bodies and WebSocket payloads are excluded, so WebXRay explains relationships rather than application semantics.
  • Bot protection, client certificates, unsupported browser features, or site policy can prevent a clean automated load.
  • A target may behave differently for the WebXRay user agent or a fresh browser profile.

Ready to observe?

Open the repository ↗