enodia-sentinal/docs/SCHEMAS.md

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).

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.