CLAUDE.md

Guidance for Claude or Claude Code agents working on Enodia Sentinel.

Project Shape

Enodia Sentinel is a zero-runtime-dependency Linux IDS/IPS/EDR platform. The core agent is pure Python standard library and should stay that way unless a dependency has clear security/operator value that cannot reasonably be achieved with stdlib. Its IPS scope is explicit prevention workflow: posture hardening, containment planning, and future reviewed --apply actions, not silent inline network blocking or automatic host mutation.

Primary functions:

Detect: poll detectors plus optional eBPF exec/syscall rules.
Prevent: posture findings plus reviewed containment/recovery plans.
Verify: FIM, package DB anchor, signed-package verification, rootcheck.
Investigate: text/JSON snapshots, incidents, HTTPS management console.
Respond: dry-run plans first; any state-changing action must be explicit, 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-rule metadata, 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.
rules list/show/test exposes built-in and configured event rules and lets operators test exec/syscall event JSON fixtures against the rule engines.
rules docs emits generated Markdown rule docs; docs/RULES.md is the checked-in built-in rule reference with match fields, false positives, and drill guidance.
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.
Fixture or red-team drill coverage for every built-in SID, including event-only and future correlation SIDs.
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.
docs/SPECIFICATION.md for the product model and acceptance criteria.
docs/ROADMAP.md for sequenced work.
docs/COMMAND_REFERENCE.md for CLI contracts.
docs/OPERATIONS.md and docs/RUNBOOKS.md for operator workflows.
docs/THREAT_MODEL.md for security boundaries and non-goals.

Engineering Rules

Keep the daemon stdlib-only and useful without a dashboard, collector, or network.
Prefer read-only detection and dry-run response until schemas and audit logs are tested and documented.
Every new detector, rootcheck, response action, or event rule needs a stable sid, signature, classtype, tests, and operator documentation.
Do not add stealth, self-hiding, persistence tricks, or automatic destructive remediation.
Preserve the bash prototype/red-team harness as the behavioral oracle for core signatures.
If you add config keys, update config/enodia-sentinel.toml, README, and the relevant docs.

Current Architecture

enodia_sentinel/cli.py is the command entry point.
daemon.py runs sweep/cooldown/background tasks.
system.py builds one cached injectable view of processes and sockets.
detectors/ contains pure poll detectors.
events/ contains optional eBPF exec/syscall monitoring and declarative rules.
snapshot.py writes forensic .log and .json evidence.
incident.py groups snapshots by process lineage and time window.
respond.py builds read-only response plans from incident evidence; the CLI persists reviewed dry-run plans under response-plans/ and appends response-audit.log, while dashboard/API previews stay write-free.
web.py serves the HTTPS-only management console and JSON APIs.
rootcheck.py performs anti-rootkit cross-view checks: hidden processes, processes hidden from ps, hidden modules, hidden TCP/UDP/raw/special-protocol sockets, raw ICMP/SCTP-style channels, promiscuous interfaces, known LKM rootkit module names, and kernel/module taint.
posture.py performs advisory host hygiene checks.

Current Threat Mapping

Recent local sample families used for defensive coverage:

Gonzalo-style implant/rootkit behavior: direct input-event keylogging, credential harvesting, LD_PRELOAD/tool tampering, persistence writes, raw ICMP and SCTP-style knock/listener paths, deleted/fileless execution, and hidden sockets/modules, plus heap/string obfuscation and mapped process-hiding libraries.
Peopleswar-style C2 behavior: TLS C2 listener/check-in traffic, command queue responses, and API/listener ports. Sentinel should prefer behavior coverage (new_listener, egress, stealth_network, memory_obfuscation, rootcheck, credential/input detectors) over brittle sample-name matching unless adding explicit IOCs.

Development Commands

python3 -m unittest discover -s tests -v
python3 -m enodia_sentinel.cli check
python3 -m enodia_sentinel.cli rootcheck
python3 -m enodia_sentinel.cli posture check --json
python3 -m enodia_sentinel.cli incident list
python3 -m enodia_sentinel.cli respond plan <incident-id> --json
python3 -m enodia_sentinel.cli rules list
python3 -m enodia_sentinel.cli web

The web dashboard is HTTPS-only. In development it auto-generates a self-signed certificate under log_dir; tests use an unverified TLS context for that local certificate.

Testing Notes

Unit tests are stdlib unittest; pytest is optional, not required.
Most detectors are pure functions over injectable SystemState.
Rootcheck tests monkeypatch system views instead of depending on live /proc, /sys, or ss.
Web tests bind a local HTTPS socket and may require permission in sandboxed environments.
Run the full suite before committing:

python3 -m unittest discover -s tests -v

Documentation Checklist

When changing behavior, update the relevant set:

README.md for visible product/architecture behavior.
docs/COMMAND_REFERENCE.md for CLI/API-visible commands.
docs/OPERATIONS.md for routine operator workflow.
docs/RUNBOOKS.md for alert response guidance.
docs/SPECIFICATION.md for product/data-model changes.
docs/THREAT_MODEL.md for trust-boundary/security-model changes.
docs/ROADMAP.md for planned or completed roadmap movement.
config/enodia-sentinel.toml for config knobs.

8 KiB Raw Blame History