# 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-16, 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, dry-run response plans, and a local Settings menu with
  persistent themes. Web tests cover the theme registry and core text/status
  contrast checks.
- `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 v1 schema IDs and compatibility tests for alerts, incidents, status,
  response plans, and response audit records.

Start with:

- `README.md` for product overview and architecture.
- `docs/INDEX.md` for the versioned documentation entry point.
- `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/PACKAGING.md` for package layout and distro install paths.
- `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

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

```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.
- `docs/SCHEMAS.md` for stable JSON contracts.
- `docs/PACKAGING.md` for package/install behavior.
- `packaging/release-artifacts.sh` for release tarballs, checksums, and optional
  GPG signatures.
- `docs/VERSION.json` and `docs/INDEX.md` for documentation versioning.
- `config/enodia-sentinel.toml` for config knobs.