From 1f05923e0f180ab354576704ace773bd6dfcb21e Mon Sep 17 00:00:00 2001 From: Luna Date: Sat, 13 Jun 2026 06:46:33 -0700 Subject: [PATCH] Document current Sentinel project state --- CLAUDE.md | 48 +++++++++++++++++++++++++++++++++++++++++++ README.md | 14 +++++++++---- docs/ROADMAP.md | 8 +++++--- docs/SPECIFICATION.md | 13 +++++++++--- 4 files changed, 73 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a7d97c3..3d8a0ef 100644 --- a/CLAUDE.md +++ b/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 ` 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. diff --git a/README.md b/README.md index 692211b..2ee0b59 100644 --- a/README.md +++ b/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: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 5760bc6..05d268e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -64,9 +64,11 @@ Purpose: move from "tell me" to "help me act" without unsafe automation. `enodia-sentinel respond plan `. - ✅ 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: diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md index 51cb845..89660b4 100644 --- a/docs/SPECIFICATION.md +++ b/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