Hunt Ledger

Continuous hunting and proof of work. Each run records what was checked in a time window, what was found, what was proposed for human follow-up, and what was clear — including mornings where nothing fired. If the control plane is down, the page says unavailable and does not invent a synthetic overnight run.

Why this surface exists

A quiet incident queue can mean two opposite things: we are safe, or we are not looking. Traditional SOC UIs punish quiet with doubt and reward noise with false confidence. Hunt Ledger exists so the second interpretation is harder to hide.

Scheduled deterministic jobs walk checks over tenant telemetry and case state, then leave a durable morning record: what ran, how many events were inspected, which checks were clear, which produced findings, and which proposed human follow-up. The ledger is a record of work — not a wall of new alerts and not a SOAR playbook runner.

Run lifecycle in detail

Celery beat schedules beacons_worker.tasks.run_nightly_hunts every 86400 seconds on the risk queue. The task discovers tenants from tenant settings or telemetry (or accepts an explicit tenant_id) and calls run_hunt_for_tenant for each. Operators with detections:manage — or an admin baseline — can also POST a run via Run hunt now in the UI (API: POST /v1/hunt-ledger/runs).

Each run stores windowStart/windowEnd (default last 24 hours), status, startedAt/completedAt, checksPlanned/checksCompleted, findingsCount/proposedCount/clearCount, a human-readable summary, the per-check summaries, initiatedBy, and an optional error string.

Status meanings matter. running means the job is in flight. completed means checks finished with at least some non-clear outcome path as defined by the service. empty means the checks ran and recorded clear dispositions without findings — the job was not skipped. failed means the run errored; the error remains visible in History. GET /v1/hunt-ledger returns source live when a usable latest run exists, empty when no runs exist yet, and unavailable when the latest run failed (or when the UI cannot reach the control plane).

Dispositions: clear, found, proposed

clear means the check inspected its window and did not raise a finding. That is still proof of work — it belongs on the ledger.

found means the check raised something noteworthy that should be visible, but the automation path did not (or should not) open a pending ticket from that path alone as currently implemented for lower-confidence matches.

proposed means the check believes human follow-up is warranted. For proposed findings, Hunt Ledger may open or link an incident and create a create_ticket response action in requested status. It does not isolate hosts or disable accounts. Deduplication uses fingerprints over a seven-day window so the same primary key does not spam tickets every night.

Current deterministic checks

Checks are identified by stable check ids and recorded on every run even when clear.

checkId	Name	What it does	Typical outcome path
ioc_ip_match	IOC IP Match	Compare recent real telemetry IPs against cached bad IPv4 indicators (URLhaus-backed feed path)	clear if none; found or proposed based on confidence / repeat observations
stale_open_high	Stale High-Severity Incidents	Find high/critical incidents still in new, triaged, or investigating beyond 24 hours	proposed with create_ticket for follow-up when stale cases exist
privilege_signal_cluster	Privilege Signal Cluster	Cluster privilege/admin/elevation-related telemetry by entity; threshold is 3 events in-window	clear below threshold; found or proposed when cluster fires

UI layout and operator workflow

The header states continuous hunting / proof of work and links to Automation so the boundary stays visible. A posture strip shows source health, latest status, window, and checked/found/proposed/clear counts without metric cards.

Checks tab lists each check summary with disposition and detail text. Findings tab lists findings with severity, confidence, entity ids, and links: open the incident when incidentId exists, or review pending work when disposition is proposed. History tab lists recent runs for the tenant.

Morning workflow: open Hunt Ledger → read the summary sentence → scan Checks for anything not clear → open Findings that are proposed → work the case in Incidents → only then consider Automation if a multi-step response is required.

Permissions, API, and honesty rules

Viewing: tenant console operators with normal read access
Run hunt now: detections:manage or admin role baseline
GET /v1/hunt-ledger — latest run, findings, recent runs, source
GET /v1/hunt-ledger/runs — history
POST /v1/hunt-ledger/runs — start a run
When the control plane is unreachable, the UI shows unavailable and does not substitute synthetic runs

Hunt Ledger is not Automation, not Detection Engineering, and not silent containment. Those jobs belong to /automation, /detection-engineering, and the response approval model respectively.