Add event-driven eBPF execve layer with a Snort-style rule engine
Closes polling's blind spot (processes that exit between sweeps) with a real
eBPF probe and a declarative, data-driven detection engine — inspired by Snort
(rule language, signature IDs) and OSSEC (host-IDS framing).
New events/ subpackage:
- bcc_source.py : eBPF C tracing execve (filename, argv[1..2], ppid, uid,
parent comm) over a perf buffer, loaded via bcc; lazy import
+ available()/try-except so it fails closed to poll-only when
bcc/root/BTF are absent — a broken probe never downs the daemon
- exec_event.py : the ExecEvent type
- rules.py : ExecRule (sid/msg/severity/classtype + path/exec/parent/argv
conditions) and ExecRuleEngine; 4 shipped rules (fileless exec
100001, reverse-shell argv 100002, web/DB→shell RCE 100003,
curl|sh 100004); operators add more via exec_rules_file TOML
- monitor.py : runs the source on a thread, routes events through the engine
Integration:
- daemon starts the monitor, shares a lock-guarded cooldown with the sweep
loop, and feeds event alerts into the same snapshot pipeline
- Alert gains Snort-style sid + classtype; retrofitted onto all 7 poll
detectors; snapshots and JSON now carry them
- config: ebpf_exec_monitor (default on, degrades), exec_rules_file
- systemd: opt-in ebpf.conf drop-in (relaxes MemoryDenyWriteExecute + widens
caps for bcc's JIT) so the base unit stays hardened for poll-only
- sentinel-redteam: ebpf_exec drill (short-lived /tmp exec + /dev/tcp argv the
poller can't see); footer now uses the Python CLI
Tests: +14 cases for the rule engine (each default rule match/non-match, rule
validation, parent-exclude). 39/39 pass. Graceful non-root degradation verified.
NOTE: the eBPF C follows bcc's execsnoop pattern but could not be run here
(BPF needs root); it wants a root smoke-test on a real host.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Luna
parent
586f74b929
commit
0eb5077551
24 changed files with 734 additions and 38 deletions
98
README.md
98
README.md
|
|
@ -32,6 +32,35 @@ EDRs are built on:
|
|||
| `persistence` | Changes to cron, systemd units, `authorized_keys`, rc files | Persistence has to write somewhere that survives reboot |
|
||||
| `egress` | An interpreter with an established connection to a public IP | C2 beacons and exfil have to phone home |
|
||||
|
||||
Every detection carries a stable **`sid`** and a **`classtype`** (à la
|
||||
Snort/Suricata), so it can be referenced, tuned, and tracked across revisions.
|
||||
|
||||
## Event-driven detection (eBPF + a Snort-style rule engine)
|
||||
|
||||
Polling has a blind spot: a process that runs and exits between two sweeps is
|
||||
invisible to it. The event layer closes that gap. An eBPF probe (loaded with
|
||||
`bcc`) fires on every `execve` and hands each event to a **declarative rule
|
||||
engine** — the host-event analogue of Snort matching packets:
|
||||
|
||||
```toml
|
||||
# a rule is data, not code — sid, msg, classtype, severity + conditions
|
||||
sid = 100002
|
||||
msg = "Reverse-shell command pattern in execve arguments"
|
||||
severity = "CRITICAL"
|
||||
classtype = "c2-reverse-shell"
|
||||
argv_regex = "/dev/(tcp|udp)/| -i\\b| -e\\b| pty\\.spawn"
|
||||
```
|
||||
|
||||
Shipped rules cover fileless execution from world-writable dirs (`sid 100001`),
|
||||
reverse-shell argv patterns (`100002`), web/DB services spawning a shell —
|
||||
webshell/RCE (`100003`), and `curl|sh`-style ingress tool transfer (`100004`).
|
||||
Operators add their own via `exec_rules_file` without touching code.
|
||||
|
||||
The layer is **fail-safe**: if `bcc`/root/BTF aren't available it logs the
|
||||
reason and the daemon runs poll-only — a broken probe can never take detection
|
||||
down. Lineage: the rule-driven engine + SIDs come from **Snort**; the host-IDS
|
||||
framing (and the queued FIM / hidden-process checks) from **OSSEC**.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
|
|
@ -42,11 +71,22 @@ enodia_sentinel/
|
|||
├── snapshot.py forensic text+JSON capture · response guidance · retention
|
||||
├── config.py dataclass config (TOML + env overrides)
|
||||
├── netutil.py public-IP / CIDR logic (stdlib ipaddress)
|
||||
├── alert.py Alert / Severity
|
||||
└── detectors/ one module per signature, each a pure function:
|
||||
detect(state, cfg) -> Iterable[Alert]
|
||||
├── alert.py Alert / Severity (with Snort-style sid + classtype)
|
||||
├── detectors/ poll detectors — one module per signature, each a pure
|
||||
│ function: detect(state, cfg) -> Iterable[Alert]
|
||||
└── events/ event-driven layer (eBPF)
|
||||
├── bcc_source.py real eBPF execve probe loaded via bcc
|
||||
├── exec_event.py the ExecEvent type
|
||||
├── rules.py Snort-style ExecRule engine + default rules
|
||||
└── monitor.py runs the probe on a thread, routes events → rules
|
||||
```
|
||||
|
||||
Two complementary detection paths feed one Alert → snapshot pipeline:
|
||||
|
||||
- **Poll** — every few seconds, sweep `/proc`/`ss` (catches anything lingering).
|
||||
- **Event** — eBPF fires on every `execve`, matched against the rule engine
|
||||
(catches processes that exit *between* sweeps).
|
||||
|
||||
The loop is deliberately the same control flow as the bash prototype, but the
|
||||
state lives in real objects:
|
||||
|
||||
|
|
@ -161,28 +201,48 @@ writable path, `ProtectHome=read-only`, `NoNewPrivileges`,
|
|||
(`CAP_SYS_PTRACE`, `CAP_DAC_READ_SEARCH`). It only ever **reads** the system and
|
||||
**writes** to its own log directory.
|
||||
|
||||
## Roadmap — from polling to eBPF
|
||||
## Enabling the eBPF monitor
|
||||
|
||||
This is **poll-based**: it sweeps `/proc` and `ss` every few seconds. Robust,
|
||||
dependency-light, and catches anything that lingers — but it can miss sub-second
|
||||
processes. The planned evolution:
|
||||
The event layer needs `python-bpfcc` and privileges the hardened unit
|
||||
deliberately withholds (bcc JIT-compiles its programs, so it needs write+exec
|
||||
memory and `CAP_BPF`/`CAP_PERFMON`/`CAP_SYS_ADMIN`). Under the default unit the
|
||||
monitor simply fails closed and the daemon runs poll-only. To turn it on:
|
||||
|
||||
1. **bpftrace tracepoints (now, optional)** — `capture_execve_bpftrace = true`
|
||||
adds a live `execve` trace to each snapshot. The gentle on-ramp to kernel
|
||||
tracing.
|
||||
2. **Event-driven detection** — `bpftrace`/BCC probes on `sys_enter_execve`,
|
||||
`security_bprm_check`, and `tcp_connect`, streamed to the daemon so a
|
||||
short-lived reverse shell can't slip between sweeps.
|
||||
3. **A libbpf + CO-RE agent (Go or Rust userland)** — the production EDR core:
|
||||
LSM hooks, ring-buffer event streaming, per-process lineage, tamper
|
||||
resistance.
|
||||
```bash
|
||||
sudo pacman -S python-bpfcc
|
||||
sudo install -Dm644 systemd/enodia-sentinel-ebpf.conf \
|
||||
/etc/systemd/system/enodia-sentinel.service.d/ebpf.conf
|
||||
sudo systemctl daemon-reload && sudo systemctl restart enodia-sentinel
|
||||
# confirm: grep 'eBPF exec monitor' /var/log/enodia-sentinel/events.log
|
||||
```
|
||||
|
||||
The polling daemon isn't throwaway — it's the **oracle**: every signature here
|
||||
is a test case the eBPF agent must reproduce, and `sentinel-redteam` is the
|
||||
shared regression suite.
|
||||
The drop-in relaxes `MemoryDenyWriteExecute` and widens the capability set — a
|
||||
conscious tradeoff documented in the file itself.
|
||||
|
||||
## Roadmap
|
||||
|
||||
1. **bpftrace tracepoints (optional)** — `capture_execve_bpftrace = true` adds a
|
||||
live `execve` trace to each snapshot.
|
||||
2. ✅ **Event-driven `execve` detection (done)** — a real eBPF probe via bcc,
|
||||
feeding a Snort-style rule engine, so a short-lived process can't slip
|
||||
between sweeps.
|
||||
3. **More event sources** — `tcp_connect` (event-driven egress) and
|
||||
`security_bprm_check` (LSM) probes, plus per-process lineage tracking.
|
||||
4. **A libbpf + CO-RE agent (Go or Rust)** — the production EDR core: ring-buffer
|
||||
event streaming, tamper resistance, no runtime compiler.
|
||||
|
||||
The polling daemon isn't throwaway — it's the **oracle**: every signature is a
|
||||
test case the event layer must reproduce, and `sentinel-redteam` is the shared
|
||||
regression suite for both.
|
||||
|
||||
## Project status
|
||||
|
||||
v0.3 — adds the event-driven **eBPF layer**: a real `bcc` execve probe feeding a
|
||||
Snort-style declarative rule engine (4 default rules), stable signature IDs +
|
||||
classtypes on every detection, fail-safe degradation to poll-only, and an
|
||||
opt-in hardening drop-in. Inspired by Snort (rule engine, SIDs) and OSSEC (HIDS
|
||||
framing; FIM + hidden-process checks are next).
|
||||
|
||||
v0.2 — Python re-architecture of the bash prototype: 7 detectors, text+JSON
|
||||
forensic snapshots, backgrounded SUID scanning, 25-test unit suite, red-team
|
||||
harness, hardened systemd unit, Arch packaging. Zero runtime dependencies.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue