# 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/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.
- `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

```bash
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:

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