10 KiB
Enodia Sentinel JSON Schemas
Applies to package version: 0.7.0
Docs version: 0.7
Schema generation: v1
Sentinel uses stable schema IDs for operator-facing JSON contracts. These IDs are lightweight compatibility markers, not external JSON Schema files. The v1 rule is additive: future releases may add fields, but required v1 fields should not be removed, renamed, or change type.
Schema IDs live in enodia_sentinel/schemas.py, and compatibility tests in
tests/test_schema_contracts.py pin the required v1 fields.
enodia.event.v1
Uniform envelope that wraps every emitted record with a typed discriminator.
This is the Python↔Go interoperability contract: any implementation must emit
the same envelope for the same input. Modeled on Suricata's EVE JSON — the
type-specific payload lives under a key named by event_type.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.event.v1. |
event_type |
string | Discriminator: alert, incident, or status (additive set). |
timestamp |
string | ISO-8601 emission time. |
host |
string | Hostname at emission time. |
<event_type> |
object | Payload, under a key equal to event_type (e.g. alert holds an enodia.alert.v1 object). |
The Python reference encoder lives in enodia_sentinel/event.py
(build_event, from_alert); tests/test_event_envelope.py pins the contract.
The experimental Go encoder lives in go-agent/internal/schema; the shared
fixture harness scripts/check-go-parity.py compares its alert envelopes with
the Python oracle.
enodia.alert.v1
Single detection object, used inside alert snapshots and by commands such as
posture check --json.
Required fields:
| Field | Type | Meaning |
|---|---|---|
sid |
integer | Stable signature/rule id. |
severity |
string | MEDIUM, HIGH, or CRITICAL. |
signature |
string | Stable machine-readable detection name. |
classtype |
string | Snort/Suricata-style category. |
key |
string | Cooldown/dedup identity. |
detail |
string | Human-readable finding detail. |
pids |
array | Process IDs tied to the finding. |
enodia.alert.snapshot.v1
Structured alert sidecar written beside each text snapshot under log_dir.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.alert.snapshot.v1. |
time |
string | ISO-8601 capture time. |
host |
string | Hostname at capture time. |
severity |
string | Highest severity in the snapshot. |
incident_id |
string or null | Incident grouping id, when enabled. |
alerts |
array | enodia.alert.v1 objects. |
processes |
array | Captured process context for alert PIDs. |
enrichment |
object | Best-effort post-alert context: package ownership, executable hashes, parent chain, remote IP classification, file metadata, recent watched writes, and local integrity/rootcheck anchor status. |
enodia.incident.v1
Incident index record stored in incidents.json.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.incident.v1. |
id |
string | Stable incident id. |
host |
string | Host that produced the incident. |
first_ts, last_ts |
number | Unix timestamps for first/last activity. |
first_seen, last_seen |
string | ISO-8601 first/last activity times. |
severity |
string | Highest incident severity. |
signatures |
array | Unique detection signatures in the incident. |
sids |
array | Unique SIDs in the incident. |
pids |
array | Alert PIDs observed in the incident. |
lineage |
array | Process-lineage IDs used for grouping. |
snapshots |
array | Member snapshot filenames. |
alert_count |
integer | Total alerts grouped into the incident. |
correlations |
array | Higher-confidence correlation records derived from the incident's raw alerts. Empty when no correlation rule matched. |
Each correlation record is additive evidence on the incident and keeps the raw
alerts visible. Current fields are sid, signature, classtype, severity,
summary, window_seconds, and matched_signatures.
incident show --json returns enodia.incident.view.v1 with schema,
incident, and timeline. The dashboard incident API returns the same schema
plus snapshots. incident export returns enodia.incident.bundle.v1 with
schema, incident, and inlined snapshots.
enodia.status.v1
Health/status object returned by status --json and /api/status.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.status.v1. |
version |
string | Sentinel package version. |
running |
boolean | Whether the daemon pid appears alive. |
total_alerts |
integer | Count of retained alert snapshots. |
counts |
object | Per-severity retained alert counts. |
last_alert |
string or null | Most recent retained alert time. |
ebpf, ebpf_exec, ebpf_syscall |
string | Last observed sensor states. |
host |
string | Hostname. |
heartbeat_age |
number or null | Seconds since heartbeat, if present. |
heartbeat_stale |
boolean | Whether heartbeat exceeds configured max age. |
enodia.integrity.v1
Integrity/watchdog object returned by /api/integrity. This is a read-only
summary of existing state; the dashboard endpoint does not run live FIM or
package verification work.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.integrity.v1. |
generated_at |
number | Unix timestamp when the report was built. |
status |
string | Overall state: ok, review, or critical. |
checks |
object | Compact per-check status map. |
watchdog |
object | Daemon running state, heartbeat age, stale flag, max age, and verdict message. |
anchors |
object | FIM baseline, package DB anchor, pacman keyring, and SigLevel summary. |
sentinel_footprint |
object | Configured Sentinel self-integrity paths and present/missing counts. |
hash_chain |
object | Local append-only hash-chain summary for snapshots and event logs: path, exists flag, record count, and last chain hash. |
read_only |
boolean | Always true for this dashboard API. |
enodia.hash_chain.v1
JSONL record appended to hash-chain.jsonl when Sentinel captures forensic
artifacts. This is a local tamper-evidence chain; future fleet/external anchors
can mirror the same records off-box.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.hash_chain.v1. |
time |
number | Unix timestamp when the chain record was appended. |
kind |
string | Artifact kind, such as snapshot-log, snapshot-json, or events-log. |
path |
string | Local artifact path that was hashed. |
size |
integer | Artifact size in bytes, or 0 if unavailable. |
sha256 |
string | SHA-256 of the artifact bytes, empty if unavailable. |
prev_hash |
string | Previous chain hash, empty for the first usable record. |
chain_hash |
string | SHA-256 over this record and prev_hash. |
enodia.first_seen.v1
Local detector state stored in first-seen.json. The first detector pass builds
a baseline silently; later passes alert on new public destinations per process
name and new listener ports per process name.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.first_seen.v1. |
initialized |
boolean | Whether the initial silent baseline pass has completed. |
public_destinations |
object | Process name to sorted host:port destinations. |
listener_ports |
object | Process name to sorted listener port strings. |
enodia.response.plan.v1
Dry-run response plan from respond plan <incident-id>.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.response.plan.v1. |
plan_id |
string | Stable plan id for the incident. |
incident_id |
string | Source incident. |
created_at |
string | ISO-8601 plan time. |
mode |
string | Currently dry-run. |
apply_supported |
boolean | Currently false. |
summary |
object | Severity, signatures, snapshot/action counts. |
actions |
array | Reviewable action proposals. |
notes |
array | Operator cautions. |
CLI-generated plans may also include artifacts with saved plan/audit paths.
enodia.response.audit.v1
JSONL record appended when the CLI persists a response plan or rehearses a
saved plan with respond apply --dry-run.
Required fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.response.audit.v1. |
time |
string | ISO-8601 audit time. |
event |
string | response_plan_generated or response_apply_rehearsed. |
actor |
string | Caller identity supplied by the CLI/workflow. |
plan_id |
string | Persisted plan id. |
incident_id |
string | Source incident id. |
mode |
string | Plan mode. |
apply_supported |
boolean | Whether the plan supports apply. |
action_count |
integer | Number of proposed actions. |
plan_path |
string | Persisted plan artifact path. |
Apply rehearsal records also include executed: false and a short reason.
enodia.reconcile.v1
Acknowledged-drift store written by baseline accept/revoke/list
(log_dir/reconciliation.json, overridable via reconcile_store) and emitted
by baseline list --json.
Top-level fields:
| Field | Type | Meaning |
|---|---|---|
schema |
string | enodia.reconcile.v1. |
records |
array | Acknowledgement records (below). |
Each record:
| Field | Type | Meaning |
|---|---|---|
kind |
string | fim, pkgfile, listener, or suid. |
target |
string | Path, or port/comm key for listeners. |
fingerprint |
object | Kind-specific identity compared each sweep. |
reason |
string | Mandatory operator justification. |
actor |
string | Who recorded the acceptance. |
accepted_at |
string | ISO-8601 UTC acceptance time. |
status |
string | ok or stale. |
expires_at |
string | ISO-8601 UTC TTL; absent when no TTL. |
The dashboard enodia.integrity.v1 payload also carries a reconciliation
summary object (total, ok, stale, stale_items) and a reconciliation
entry under checks.