51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
|
|
# Enodia Sentinel — Behavioral Specification
|
|
|
|
This directory documents the **observable behavior of the current Python
|
|
production agent** at reimplementation fidelity: the inputs each subsystem
|
|
reads, the algorithm it applies, the outputs it produces (SIDs, severities,
|
|
dedup keys, JSON schemas), the files it writes, and its edge-case / fail-open
|
|
rules.
|
|
|
|
## Why this exists
|
|
|
|
Python is the production agent and the **parity oracle** for the Go rewrite
|
|
that will ship as Enodia Sentinel **2.0** (see `docs/ROADMAP.md`, Active
|
|
Migration Track). "Match the oracle" was previously tribal knowledge encoded
|
|
only in the parity fixture and the source itself. These documents make the
|
|
contract reviewable: a Go port of any subsystem is correct when it reproduces
|
|
the behavior described here.
|
|
|
|
This is deliberately distinct from `docs/SPECIFICATION.md`, which defines the
|
|
*product* (what Sentinel is, design principles, acceptance criteria). This set
|
|
defines *mechanism* (what the code does, precisely enough to re-derive).
|
|
|
|
## Conventions
|
|
|
|
- **Source anchors** are written as `module.py:function` — the authority is
|
|
always the code, and these documents must be updated when the code changes.
|
|
- **SIDs / severities / keys** quoted here are the stable contract; a port that
|
|
emits a different value for the same condition is a parity break.
|
|
- "Fail-open" means a collection or read error degrades to an empty/absent
|
|
value and never raises — detection continues on partial data.
|
|
- Defaults quoted are the `config.py` dataclass defaults as of package version
|
|
`0.7.0`; operators may override them.
|
|
|
|
## Sections
|
|
|
|
Written in port-priority order. Status reflects which documents exist.
|
|
|
|
| # | File | Covers | Status |
|
|
|---|------|--------|--------|
|
|
| 1 | [`01-sweep-and-state.md`](01-sweep-and-state.md) | `system.py` capture, `daemon.py` sweep loop + baseline lifecycle, `alert.py`, detector registry, `config.py` timing knobs | **written** |
|
|
| 2 | [`02-poll-detectors.md`](02-poll-detectors.md) | the twelve `detectors/*` — per-detector input → match → output contract | **written** |
|
|
| 3 | [`03-event-detection.md`](03-event-detection.md) | `event.py`, exec/syscall/host rule engines, `ruleops.py`, `sids.py` | **written** |
|
|
| 4 | `04-integrity.md` | `fim.py`, `pkgdb.py`, `selfprotect.py`, `assurance.py` | planned |
|
|
| 5 | `05-rootcheck.md` | `rootcheck.py` anti-rootkit cross-view checks | planned |
|
|
| 6 | `06-posture.md` | `posture.py` advisory host-hygiene checks | planned |
|
|
| 7 | `07-investigation.md` | `snapshot.py`, `incident.py`, `correlation.py`, `enrich.py`, `triage.py` | planned |
|
|
| 8 | `08-response.md` | `respond.py` plans, `reconcile.py` acknowledged-drift store | planned |
|
|
| 9 | `09-interfaces.md` | `cli.py`, `web.py`, `tui.py` operator-visible contracts | planned |
|
|
|
|
Shared helpers (`netutil.py`, `provenance.py`) are documented inline in whatever
|
|
section first depends on them.
|