Document current Sentinel project state

CLAUDE.md

@@ -21,6 +21,54 @@ Primary functions:
   logged, and tested.
 - Assure: heartbeat, watchdog, self-integrity, future external anchors.
 
+## Current State Snapshot
+
+As of 2026-06-13, the project is a local-first Linux IDS/IPS/EDR agent at
+package version `0.7.0`. The branch has a working stdlib-only daemon, CLI,
+HTTPS management console, incident model, response planner, rootcheck, posture
+checks, file/package integrity checks, push notification backends, and optional
+bcc/eBPF telemetry.
+
+Implemented detection coverage:
+
+- Poll detectors: `reverse_shell`, `ld_preload`, `deleted_exe`,
+  `input_snooper`, `credential_access`, `stealth_network`,
+  `memory_obfuscation`, `new_listener`, `new_suid`, `persistence`, and
+  `egress`.
+- eBPF exec rules: fileless execution from writable paths, reverse-shell argv,
+  web/database service spawning shells, and `curl|wget|sh` style staging.
+- eBPF syscall rules: RWX `mprotect`/`mmap`, `memfd_create`, sensitive
+  `ptrace`, seccomp changes, cross-process memory access, and memory locking.
+- Anti-rootkit checks: hidden PIDs, `/proc` vs `ps` mismatches, hidden modules,
+  hidden TCP/UDP/raw/special-protocol sockets, raw ICMP/SCTP-style channels,
+  promiscuous interfaces, known LKM rootkit names, module taint, and kernel
+  taint.
+
+Implemented investigation/response state:
+
+- Alert snapshots are written as text and JSON under `log_dir`.
+- Incident tracking groups snapshots by process lineage and time window and
+  exposes `incident list/show/export`.
+- The dashboard is HTTPS-only, token-protected off loopback, and read-only. It
+  shows status, incidents, timelines, alerts, posture findings, event tail, and
+  dry-run response plans.
+- `respond plan <incident-id>` builds read-only containment/recovery plans,
+  persists CLI-generated plans under `response-plans/`, and appends
+  `response-audit.log`. Dashboard/API plan previews do not write artifacts.
+- IPS behavior is currently explicit workflow: posture hardening plus reviewed
+  dry-run containment actions. There is no automatic inline blocking or silent
+  host mutation yet.
+
+Near-term open work:
+
+- Audited `--apply` response execution with tests and rollback notes.
+- Baseline reconciliation for legitimate FIM/package/listener/SUID drift.
+- Rule inspection/test commands and generated rule documentation.
+- More event sources and correlation across exec, network, persistence, FIM,
+  and rootcheck signals.
+- Stable schema compatibility tests for alerts, incidents, status, response
+  plans, and response audit records.
+
 Start with:
 
 - `README.md` for product overview and architecture.

README.md

@@ -26,11 +26,11 @@ behind reviewed response workflows rather than silent remediation.
 
 | Function | Current capability | Direction |
 |---|---|---|
-| Detect | Poll detectors + eBPF exec rules | More event sources and correlation |
+| Detect | Poll detectors + eBPF exec/syscall rules | More event sources and correlation |
 | Prevent | Posture checks + dry-run containment plans | Audited, explicit `--apply` workflows |
 | Verify | FIM, package DB anchor, signed-package checks | External anchors and signed evidence |
-| Investigate | Text/JSON snapshots, dashboard, triage | Incident timelines and evidence export |
-| Respond | Human guidance today | Dry-run response plans and audited containment |
+| Investigate | Text/JSON snapshots, incidents, dashboard, triage | Richer timelines and evidence export |
+| Respond | Persisted dry-run response plans | Audited containment and recovery execution |
 | Assure | Heartbeat, watchdog, self-integrity, rootcheck | Fleet health and attestation-ready anchors |
 
 Project docs:
@@ -127,16 +127,22 @@ enodia_sentinel/
 ├── notify/           outbound push — ntfy / Pushover / webhook backends
 └── events/           event-driven layer (eBPF)
     ├── bcc_source.py   real eBPF execve probe loaded via bcc
+    ├── bcc_syscall_source.py  real eBPF syscall telemetry probe
     ├── exec_event.py   the ExecEvent type
+    ├── syscall_event.py  the SyscallEvent type
     ├── rules.py        Snort-style ExecRule engine + default rules
+    ├── syscall_rules.py  memory/anti-analysis SyscallRule engine
     └── monitor.py      runs the probe on a thread, routes events → rules
 ```
 
-Two complementary detection paths feed one Alert → snapshot pipeline:
+Three complementary detection paths feed one Alert → snapshot pipeline:
 
 - **Poll** — every few seconds, sweep `/proc`/`ss` (catches anything lingering).
 - **Event** — eBPF fires on every `execve`, matched against the rule engine
   (catches processes that exit *between* sweeps).
+- **Syscall event** — optional eBPF telemetry catches short-lived memory and
+  anti-analysis actions such as RWX mappings, `memfd_create`, `ptrace`,
+  seccomp, cross-process memory access, and memory locking.
 
 The loop is deliberately the same control flow as the bash prototype, but the
 state lives in real objects:

docs/ROADMAP.md

@@ -64,9 +64,11 @@ Purpose: move from "tell me" to "help me act" without unsafe automation.
   `enodia-sentinel respond plan <incident-id>`.
 - ✅ Persist CLI-generated dry-run plans under `response-plans/` and append
   `response-audit.log` records for review/handoff.
-- Add dry-run first actions:
-  kill process, stop/disable service, block remote IP, quarantine file, restore
-  package-owned file by reinstalling its package, and freeze evidence.
+- ✅ Add dry-run first actions for evidence freeze, process freeze/terminate,
+  outbound IP block, systemd stop/disable, suspicious-file quarantine,
+  package-owner lookup, and follow-up verification.
+- Add package reinstall/restore planning after trusted-media and package-manager
+  semantics are designed for pacman, dpkg, and rpm.
 - Require explicit `--apply` for changes; default to read-only plans.
 - Extend response audit logs to any future state-changing `--apply` workflow.
 - Add baseline reconciliation:

docs/SPECIFICATION.md

@@ -43,7 +43,7 @@ The long-term product should combine six functions:
 6. **Bash prototype remains the oracle.** The original shell implementation and
    red-team harness preserve behavioral compatibility for core signatures.
 
-## Current Scope: v0.8-dev
+## Current Scope: Local IDS/IPS/EDR
 
 ### Poll Detectors
 
@@ -100,9 +100,9 @@ When a fresh alert survives cooldown, Sentinel writes:
 
 | Interface | Role |
 |---|---|
-| CLI | Run daemon, one-shot checks, baseline management, FIM checks, package DB checks, rootcheck, posture audit, incident review, triage, watchdog. |
+| CLI | Run daemon, one-shot checks, baseline management, FIM checks, package DB checks, rootcheck, posture audit, incident review/export, triage, status/watchdog, and response planning. |
 | Logs | Durable local evidence under `/var/log/enodia-sentinel`. |
-| Dashboard | Read-only web view for status, alert browsing, and snapshot inspection. |
+| Dashboard | HTTPS-only read-only web view for status, incidents, timelines, alert browsing, posture findings, event tail, and response-plan previews. |
 | Push | ntfy, Pushover, and generic webhook notifications. |
 | Red-team harness | Safe drills for testing signatures and demos. |
 
@@ -111,6 +111,13 @@ reviewed dry-run plan under `response-plans/` and appends a JSONL
 `response-audit.log` record. Dashboard/API previews remain read-only and do not
 create artifacts.
 
+Current IPS scope is explicit prevention workflow, not transparent inline
+enforcement. Sentinel can recommend evidence preservation, process
+freeze/termination, outbound IP blocks, systemd unit disablement, suspicious-file
+quarantine, package-owner lookup, and follow-up verification. It does not
+execute those commands until a future audited `--apply` workflow is designed,
+tested, and documented.
+
 ## Target Scope: Host Security Platform
 
 The next product shape should make Enodia useful before, during, and after an