enodia-sentinal/docs/behavior/index.md

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	system.py capture, daemon.py sweep loop + baseline lifecycle, alert.py, detector registry, config.py timing knobs	written
2	02-poll-detectors.md	the twelve detectors/* — per-detector input → match → output contract	written
3	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.