6ff2087329
Add docs/ (SPECIFICATION, ROADMAP, OPERATIONS, COMMAND_REFERENCE, THREAT_MODEL) describing the current v0.7 agent and the phased path from local HIDS to a host security platform. Reframe README, package metadata, and CLI/module descriptions from "intrusion-detection daemon" to "Linux host security platform", and surface the v0.7 signed-package verify (pkgdb_pkgverify*) and anti-rootkit (rootcheck_*) knobs in the sample config. Also wrap the pacman.conf read in pkgdb.siglevel_alert in a context manager to avoid a leaked file handle. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
226 lines
5.2 KiB
Markdown
226 lines
5.2 KiB
Markdown
# Enodia Sentinel Command Reference
|
|
|
|
This is the operator-facing command contract for the current local agent. Commands
|
|
are intentionally plain: they either inspect state, manage baselines, run the
|
|
daemon, or expose existing evidence.
|
|
|
|
Global options:
|
|
|
|
```bash
|
|
enodia-sentinel --version
|
|
enodia-sentinel -c /path/to/config.toml <command>
|
|
```
|
|
|
|
If no command is provided, `run` is used.
|
|
|
|
## Service Commands
|
|
|
|
### `run`
|
|
|
|
```bash
|
|
enodia-sentinel run
|
|
```
|
|
|
|
Starts the daemon loop. This is the command used by the systemd service. It
|
|
builds or loads baselines, starts optional event monitoring, writes heartbeats,
|
|
runs detector sweeps, captures snapshots, and sends notifications.
|
|
|
|
Expected use: systemd, not an interactive shell.
|
|
|
|
### `check`
|
|
|
|
```bash
|
|
enodia-sentinel check
|
|
```
|
|
|
|
Runs the enabled detector set once and prints alerts. This forces the SUID scan
|
|
and arms baseline-gated detectors immediately, so it is useful for health checks
|
|
and debugging.
|
|
|
|
Exit code:
|
|
|
|
- `0`: no alerts.
|
|
- `0`: alerts may still print today; this command is currently human-oriented,
|
|
not a strict CI gate.
|
|
|
|
### `baseline`
|
|
|
|
```bash
|
|
enodia-sentinel baseline
|
|
```
|
|
|
|
Rebuilds listener and SUID baselines under `log_dir`. Use after installing on a
|
|
known-good host or after intentionally adding persistent services or privileged
|
|
helpers.
|
|
|
|
Do not run this to silence unexplained findings.
|
|
|
|
## Detection and Integrity Commands
|
|
|
|
### `list-detectors`
|
|
|
|
```bash
|
|
enodia-sentinel list-detectors
|
|
```
|
|
|
|
Prints the poll detectors and whether each is enabled by config.
|
|
|
|
### `rootcheck`
|
|
|
|
```bash
|
|
enodia-sentinel rootcheck
|
|
```
|
|
|
|
Runs anti-rootkit cross-view checks once:
|
|
|
|
- PIDs alive via `kill(pid, 0)` but missing from `/proc`.
|
|
- Live modules in `/sys/module` but missing from `/proc/modules`.
|
|
- Listening TCP ports in `/proc/net/tcp*` but missing from `ss`.
|
|
- Network interfaces in promiscuous mode.
|
|
|
|
Exit code:
|
|
|
|
- `0`: no rootcheck findings.
|
|
- `1`: one or more rootcheck alerts.
|
|
|
|
### `fim-baseline`
|
|
|
|
```bash
|
|
enodia-sentinel fim-baseline
|
|
```
|
|
|
|
Builds the SHA-256 file integrity baseline for configured critical paths plus
|
|
Sentinel's own footprint.
|
|
|
|
Use on a known-good host. The package hook also calls `fim-update` after normal
|
|
package transactions.
|
|
|
|
### `fim-update`
|
|
|
|
```bash
|
|
enodia-sentinel fim-update
|
|
```
|
|
|
|
Refreshes the FIM baseline. This exists primarily for the package manager hook.
|
|
Manual use should be treated as an acknowledgement that the current file state
|
|
is legitimate.
|
|
|
|
### `fim-check`
|
|
|
|
```bash
|
|
enodia-sentinel fim-check
|
|
enodia-sentinel fim-check --packages
|
|
```
|
|
|
|
Diffs current file state against the FIM baseline. With `--packages`, also runs
|
|
package-owned file verification through the package manager (`pacman -Qkk` on
|
|
Arch).
|
|
|
|
Exit code:
|
|
|
|
- `0`: no baseline changes.
|
|
- `1`: one or more added, removed, or modified files.
|
|
|
|
### `pkgdb-check`
|
|
|
|
```bash
|
|
enodia-sentinel pkgdb-check
|
|
```
|
|
|
|
Checks whether the local package database fingerprint changed outside a logged
|
|
package transaction. This catches an attacker rewriting stored package checksums
|
|
to hide a modified binary.
|
|
|
|
Exit code:
|
|
|
|
- `0`: package DB matches the anchor or was legitimately re-anchored.
|
|
- `1`: out-of-band DB tampering suspected.
|
|
|
|
### `pkgdb-verify`
|
|
|
|
```bash
|
|
enodia-sentinel pkgdb-verify
|
|
enodia-sentinel pkgdb-verify --sample 200
|
|
```
|
|
|
|
Compares on-disk package-owned files to SHA-256 hashes from `.MTREE` manifests
|
|
inside cached signed packages. This is independent of the mutable local package
|
|
database.
|
|
|
|
The command also flags insecure global `SigLevel` settings and warns if the
|
|
pacman keyring is missing.
|
|
|
|
Exit code:
|
|
|
|
- `0`: sampled files match and signature policy is not downgraded.
|
|
- `1`: a signed-package mismatch or insecure signature setting was found.
|
|
|
|
## Evidence and Operator Commands
|
|
|
|
### `web`
|
|
|
|
```bash
|
|
enodia-sentinel web
|
|
```
|
|
|
|
Starts the read-only dashboard. By default it binds to the Tailscale interface
|
|
when available and uses bearer-token authentication for non-loopback binds.
|
|
|
|
Expected use: `enodia-sentinel-web.service`.
|
|
|
|
### `triage`
|
|
|
|
```bash
|
|
enodia-sentinel triage
|
|
```
|
|
|
|
Reads captured alert JSON snapshots and classifies distinct findings as likely
|
|
false positive or review-needed. It suggests config snippets for known benign
|
|
noise but never edits config automatically.
|
|
|
|
### `watchdog`
|
|
|
|
```bash
|
|
enodia-sentinel watchdog --url http://100.x.y.z:8787 --token <token> --max-age 120
|
|
```
|
|
|
|
Polls a remote dashboard and alerts if the sensor is down, unreachable, or has a
|
|
stale heartbeat. Run this from a separate host. A watchdog on the same machine
|
|
does not prove the protected host is alive.
|
|
|
|
Exit code:
|
|
|
|
- `0`: remote sensor is reachable and fresh.
|
|
- `1`: remote sensor is stale, down, or unreachable.
|
|
|
|
## Development Shortcuts
|
|
|
|
The Makefile wraps common local tasks:
|
|
|
|
```bash
|
|
make test
|
|
make check
|
|
make baseline
|
|
make web
|
|
make drill
|
|
```
|
|
|
|
`make install` installs a plain package directory plus a launcher wrapper. It
|
|
does not require pip or a virtualenv.
|
|
|
|
## Future Command Contracts
|
|
|
|
The roadmap reserves these command shapes:
|
|
|
|
```bash
|
|
enodia-sentinel status --json
|
|
enodia-sentinel incident list
|
|
enodia-sentinel incident show <incident-id>
|
|
enodia-sentinel incident export <incident-id>
|
|
enodia-sentinel posture check
|
|
enodia-sentinel respond plan <incident-id>
|
|
enodia-sentinel respond apply <plan-id>
|
|
```
|
|
|
|
These should be introduced with stable JSON schemas and tests before they are
|
|
documented as supported.
|