Add stable v1 schema IDs and docs
This commit is contained in:
Luna
parent
bfef23fc4a
commit
7a176ea238
13 changed files with 409 additions and 8 deletions
|
|
@ -308,6 +308,10 @@ staleness, total alerts with per-severity counts, last alert time, and eBPF
|
|||
monitor state. `--json` emits the same data as the dashboard `/api/status`
|
||||
endpoint, for cron/monitoring.
|
||||
|
||||
Stable JSON contracts are documented in [SCHEMAS.md](SCHEMAS.md). Current v1
|
||||
IDs cover alert objects/snapshots, incident records/views/exports, status,
|
||||
response plans, and response audit JSONL records.
|
||||
|
||||
Exit code:
|
||||
|
||||
- `0`: daemon is running and the heartbeat is fresh.
|
||||
|
|
|
|||
|
|
@ -89,9 +89,9 @@ Exit criteria:
|
|||
|
||||
Purpose: define a stable single-host product.
|
||||
|
||||
- Commit to stable JSON schemas for alerts, incidents, status, and response
|
||||
- ✅ Commit to stable JSON schemas for alerts, incidents, status, and response
|
||||
audits.
|
||||
- Add compatibility tests for schema evolution.
|
||||
- ✅ Add compatibility tests for schema evolution.
|
||||
- Add documentation versioning and manpage-style command reference.
|
||||
- Harden packaging for Arch first, then document Debian/RPM install paths.
|
||||
- Add signed release artifacts and checksums.
|
||||
|
|
|
|||
126
docs/SCHEMAS.md
Normal file
126
docs/SCHEMAS.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
# Enodia Sentinel JSON Schemas
|
||||
|
||||
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.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. |
|
||||
|
||||
## `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. |
|
||||
|
||||
`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.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.
|
||||
|
||||
Required fields:
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `schema` | string | `enodia.response.audit.v1`. |
|
||||
| `time` | string | ISO-8601 audit time. |
|
||||
| `event` | string | Currently `response_plan_generated`. |
|
||||
| `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. |
|
||||
|
|
@ -190,6 +190,11 @@ schema. Grouping is process-lineage first, with a time-window fallback for
|
|||
PID-less alerts; see the [command reference](COMMAND_REFERENCE.md) and
|
||||
[roadmap](ROADMAP.md).
|
||||
|
||||
Operator-facing JSON contracts carry stable v1 schema IDs for alert snapshots,
|
||||
incident records/views/exports, status, response plans, and response audit
|
||||
records. The schema reference is [SCHEMAS.md](SCHEMAS.md); compatibility tests
|
||||
pin required v1 fields and allow additive evolution.
|
||||
|
||||
## Configuration Model
|
||||
|
||||
Configuration is a TOML file loaded at startup. Unknown keys are ignored so
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue