119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```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.
|