Three zones, one-way boundaries
Managed endpoints send telemetry to the Manager control plane. The Manager runs detection, stages responses and dispatches only what has been authorized. Analysts work through the console. Nothing in the detection path can execute anything on a host.
Running components and trust boundaries
Ingest fast, detect asynchronously, act only on authorization
An agent posts a batch to POST /api/v1/ingest (or a v2 endpoint-record route). The Manager commits it to its SQLite WAL store and answers immediately; it never makes the agent wait for detection.
A detection worker claims pending events in bounded batches under a lease, runs them through the vendored detection engine, writes alerts and incidents, and stages any response recommendation as PENDING.
An analyst authorizes or rejects the staged action through the console. Authorized commands are queued; the agent picks them up on its next poll, optionally acknowledges, executes after verifying the target, and posts a typed result.
Two read-only collections are the only actions that may skip analyst approval.
Seven actions, two tiers, no exceptions
The vocabulary is closed in the contracts, the response engine and the Manager. An action outside it is rejected, and anything unrecognized falls to the stricter tier — never to auto-run.
| Action | What it does | Tier |
|---|---|---|
COLLECT_PROCESS_INFO | Collect details of a target process. | AUTO_SAFE |
COLLECT_NETWORK_CONNECTIONS | Collect the endpoint's current network connections. | AUTO_SAFE |
COLLECT_FILE | Collect approved file evidence. No path allowlist exists yet, so it is not auto-safe. | ANALYST_APPROVAL |
QUARANTINE_FILE | Move a file out of reach on the endpoint. | ANALYST_APPROVAL |
KILL_PROCESS | Terminate a process identified by PID and start time, so a recycled PID is refused. | ANALYST_APPROVAL |
ISOLATE_HOST | Block network traffic except the Manager channel (Windows Filtering Platform on Windows, a privileged isolation helper on Linux). | ANALYST_APPROVAL |
RELEASE_HOST_ISOLATION | Lift a previous isolation. | ANALYST_APPROVAL |
Source: response_engine/policy.py. Kill, isolate and release are locked decisions that never auto-fire, regardless of severity.
Every response is a state machine
Legal transitions are enforced in one place, the response engine. Terminal states have no way out, and any non-terminal state can expire if its window lapses.
Also: CANCELLED (from pending or authorized) and EXPIRED (from any non-terminal state). An agent may skip the optional accept step and report an outcome directly from DISPATCHED.
The control plane's surface
A FastAPI application. Endpoints authenticate with enrolled identities; analysts with individual enrollment and explicit artifact-access grants.
| Area | Representative routes |
|---|---|
| Enrollment | POST /api/v1/agents/enrollment-challenge, POST /api/v1/agents/enroll, POST /api/v1/analysts/enroll |
| Telemetry | POST /api/v1/ingest, POST /api/v2/endpoint/records, POST /api/v2/endpoint/freshness-challenge, POST /api/v2/linux-endpoint/records |
| Commands | GET /api/v1/agents/{id}/commands, POST …/commands/{cid}/accept, POST /api/v1/agents/{id}/command-results |
| Detections | GET /api/v1/alerts, GET /api/v1/incidents, POST /api/v1/incidents/{id}/status |
| Response | GET /api/v1/response-actions, …/catalog, …/{id}/preflight, …/{id}/authorize, …/{id}/reject, …/{id}/cancel, …/{id}/export, /api/v1/response-campaigns |
| Evidence | POST …/commands/{cid}/artifacts/signed, …/artifact-transfers, GET /api/v1/response-artifacts/{id}/content, …/custody, artifact key rotation and revocation |
| Audit | GET /api/v1/response-audit, GET /api/v1/response-audit/verify, POST /api/v1/response-audit/checkpoints |
| Operations | /healthz, /readyz, /metrics, /api/v1/status, /api/v2/linux-endpoint/hosts/{id}/health |
Versioned envelopes, shared fixtures
Legacy telemetry 0.2 – 0.4
The original process, network, file, registry and image-load event schema. Officer keeps a compatibility mirror; the canonical copy lives in contracts.
Endpoint record 1.0
Windows canonical endpoint records with enrolled identity, epochs and sequence numbers. Linux has its own linux-endpoint/1.0 envelope preserving boot, PID and start-time identity.
Command / CommandResult
Typed envelopes for the seven actions. Version "1" for legacy commands; "2" for Windows boot-bound process commands and durable results.
Implementers are checked against the golden fixtures in panopticon-contracts; see its compatibility matrix.
A polyrepo on purpose
Agents never import engine code, and engines never read agent source. The detection and response engines are vendored into the Manager as pinned submodules and run in-process; they have no network surface of their own.
The detection engine knows nothing about the response engine — its recommendation is just a shape the response engine knows how to translate.
