CLAUDE.md

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

Project Shape

Enodia Sentinel is a zero-runtime-dependency Linux host security 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.

Primary functions:

Detect: poll detectors plus optional eBPF exec rules.
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.

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 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.
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 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.

4.8 KiB Raw Blame History