EventLens is a local/self-hosted Windows Event Log incident reconstruction tool. It turns a real .evtx export into normalized evidence, deterministic incident windows and a readable timeline that helps answer: what happened, in what order, and which records are probably related?

What it solves

Windows event logs are detailed but difficult to scan during an incident. EventLens provides a bounded workflow:

EVTX upload -> size/resource gate -> normalize -> deterministic correlation -> timeline/evidence inspector -> redacted export

It preserves source evidence, makes every grouping explainable, and keeps the analysis local.

Product boundary

EventLens is deliberately not a SIEM, a full Windows Event Viewer replacement, a cloud platform or an AI product. It has no database, authentication, telemetry, background worker, cloud account or LLM requirement. It focuses on one compact job: reconstructing a bounded incident story from Windows event records.

v1.0.6 capabilities

Parses real EVTX in memory with the Rust-backed evtx engine.
Enforces a 50 MiB file cap plus a receive-level request cap, 100,000-event cap, cooperative 8-second parse budget and bounded normalized output.
Reports complete, partial or failed parser status with stable issue codes, retained/skipped metrics and export metadata.
Normalizes System, EventData and UserData into a stable evidence contract; unreliable timestamps remain explicit and are never converted to epoch evidence.
Correlates provider/channel-scoped startup, shutdown, service, DNS, authentication and crash patterns using stable rule IDs, incident IDs and evidence event IDs.
Keeps unmatched warning/error evidence visible and compresses repeated signatures without deleting source events.
Supports drag/drop, search, category/level/provider filters, informational-noise suppression, incident focus and ±1/5/15/60-minute evidence windows.
Shows the rule, reason, time window and exact evidence IDs behind each incident.
Exports semantically equivalent JSON and Markdown in the browser. Redaction is enabled by default and previews host, identity, e-mail, IP, path and source-name replacement counts before export.
Uses no-store responses, security headers, bounded parse concurrency, sanitized source names and no intentional upload persistence.
Virtualizes large timelines so a 100,000-event analysis does not create 100,000 DOM rows.
Includes a deterministic demo fixture plus a pinned-hash public real-EVTX qualification fixture in CI and Playwright.
Provides five functional workspaces over the same in-memory analysis: Analysis overview, Timeline investigation, Hunting facets, Reports/export and local-only Settings.
Preserves workspace navigation and browser hash history without persisting event data; each workspace has an explicit empty state when no analysis is loaded.
Uses a responsive, keyboard-accessible shell with shared event filters, a virtualized timeline and an evidence inspector that remains available from Hunting results.
Ships one local, canonical evidence-lens mark across the top bar, browser favicon, touch/app icons and web manifest; it makes no network request and carries no tracking.
Keeps investigation orientation visible across Analysis, Timeline, Hunting and Reports with a compact source/completeness/evidence context strip and export-readiness summary.
Gives the existing browser-local preferences a dedicated, keyboard-accessible Settings workspace: native radio-backed option cards, a semantic export-redaction switch, explicit autosave feedback, a privacy boundary and a one-click preference reset.
Keeps source identity in one shared context strip, promotes parser completeness/skipped-record metrics in Analysis and reserves first-use guidance for the deterministic demo.

Privacy and security

Event logs can contain usernames, hostnames, IP addresses, e-mail addresses, executable paths and application-specific data. EventLens:

processes uploads only for the current request and closes the multipart handle;
never renders raw XML as markup and escapes untrusted values through React rendering;
bounds input size, parser records, fields, strings, normalized output and parse time;
bounds request bytes independently of Content-Length and admits only a small number of concurrent parses;
does not log event contents or write an application database;
previews best-effort redaction of hosts, identities (including domain accounts, SIDs and machine accounts), e-mails, IPv4/IPv6, Windows/UNC paths and source filenames before export.

Redaction is a privacy aid, not a formal DLP engine. Review an export before sharing it. See SECURITY.md and docs/PRIVACY.md.

Portfolio walkthrough

Open the deployed instance or start EventLens locally.
Select Load demo for a deterministic six-event walkthrough.
Review the source/completeness summary in Analysis and select an incident.
Investigate the linked evidence in Timeline with search, facets, focus and time windows.
Use Hunting for combined event-ID, provider, category, level, host and incident-membership searches.
Review the redaction preview and download JSON or Markdown from Reports.
Adjust UTC/local timestamps, density and default local preferences in Settings.

Run locally

Backend (locked dependencies):

cd backend
python -m pip install uv==0.10.0
python -m uv sync --locked --extra dev
python -m uv run --locked --extra dev uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm ci
npm test
npm run lint
npm run build
npm run dev

The development UI uses http://127.0.0.1:8000 for the API. Set VITE_API_BASE_URL when the API runs elsewhere. In a production image the UI and API are same-origin.

Docker

docker compose up --build

Open http://localhost:1252. The production image uses digest-pinned base images, npm ci, backend/uv.lock, a non-root runtime user, dropped Linux capabilities, a read-only root filesystem and a bounded /tmp tmpfs. The health endpoint is http://localhost:1252/health; its revision is the exact injected build SHA (local for an unlabelled development build).

For an Unraid DockerMan-managed Compose deployment, the compose metadata publishes the WebUI URL and serves the durable canonical icon locally at /eventlens-icon-512.png through net.unraid.docker.webui and net.unraid.docker.icon. A broker-managed deployment must preserve those service labels for DockerMan to import them; EventLens does not claim DockerMan lifecycle ownership.

Validation

The release gates are reproducible from a clean checkout:

cd backend
python -m uv sync --locked --extra dev
python -m uv run --locked --extra dev pytest -q -W error::DeprecationWarning
python -m uv run --locked --extra dev ruff check .
python -m uv run --locked --extra dev pip-audit --strict

cd ../frontend
npm ci
npm test
npm run lint
npm run build
npx playwright install chromium
npm run test:e2e
npm audit --audit-level=moderate

The private canonical repository maintains its own validation and deployment workflows. This public snapshot includes the application and reproducible tests; it does not include private infrastructure automation or deployment evidence.

Deployment and access

Compose publishes port 1252 on all host interfaces. For local use, change the mapping to 127.0.0.1:1252:8000. There is no built-in authentication; use network isolation and an authenticated HTTPS reverse proxy before allowing other users to upload sensitive evidence. Configure the build revision via GITEA_COMMIT_SHA when reproducible deployment identity is needed.

The screenshots show the deterministic bundled demo, not a real incident or an uploaded customer log.

Limitations

Correlation describes temporal/semantic relationships supported by evidence; it does not prove causality.
Rules are intentionally small and Windows-focused. Custom rules, hunting queries, alerting and retention are outside the product boundary.
The EVTX parser and browser analysis are bounded for safety; partial parses surface issues instead of pretending completeness.
Redaction is best-effort and application-specific values may still contain sensitive data.
A real Windows EVTX file is required for parser analysis; the bundled demo intentionally bypasses only the raw parser step.

License

No project-wide license file is included in this repository. Publishing the source does not grant an open-source license. Normal copyright restrictions and the applicable terms for individual third-party components remain in effect.

Public source distribution

The private canonical repository remains the development source. Reviewed snapshots are synchronized automatically to EventLens-Public after changes reach its default branch. The public export contains application source, dependency locks, generic deployment examples and selected demo visuals; private Git history, infrastructure workflows and operational records are excluded. PUBLIC_SOURCE_MANIFEST.json identifies the exact source revision and file hashes.