Adds .opsec_notes to every module's struct skeletonkey_module
(31 entries across 26 module files). One paragraph per exploit
describing the runtime footprint a defender/SOC would see:
- file artifacts created/modified (exact paths from source)
- syscall observables (the unshare / socket / setsockopt /
splice / msgsnd patterns the embedded detection rules look for)
- dmesg signatures (silent on success vs KASAN oops on miss)
- network activity (loopback-only vs none)
- persistence side-effects (/etc/passwd modification, dropped
setuid binaries, backdoors)
- cleanup behaviour (callback present? what it restores?)
Each note is grounded in the module's source code + its existing
auditd/sigma/yara/falco detection rules — the OPSEC notes are
literally the inverse of those rules (the rules describe what to
look for; the notes describe what the exploit triggers).
Three intelligence agents researched the modules in parallel,
reading source + MODULE.md, then their proposals were embedded
verbatim via tools/inject_opsec.py (one-shot script, not retained).
Where surfaced:
- --module-info <name>: '--- opsec notes ---' section between
detect-rules summary and the embedded auditd/sigma rule bodies.
- --module-info / --scan --json: 'opsec_notes' top-level string.
Audience uses:
- Red team: see what footprint each exploit leaves so they pick
chains that match the host's telemetry posture.
- Blue team: the notes mirror the existing detection rules from the
attacker side — easy diff to find gaps in their SIEM coverage.
- Researchers: per-exploit footprint catalog for technique analysis.
copy_fail_family gets one shared note across all 5 register entries
(copy_fail, copy_fail_gcm, dirty_frag_esp, dirty_frag_esp6,
dirty_frag_rxrpc) since they share exploit infrastructure.
Verification:
- macOS local: clean build, --module-info nf_tables shows full
opsec section + CWE + ATT&CK + KEV row from previous commit.
- Linux (docker gcc:latest): 33 + 54 = 87 passes, 0 fails.
Next: --explain mode (uses these notes + the triage metadata to
render a single 'why is this verdict, what would patch fix it, and
what would the SOC see' page per module).
Closes the 'rules in the box' gap — the README has claimed YARA +
Falco coverage but detect_yara and detect_falco were NULL on every
module. This commit lights up both formats for the 6 highest-value
modules (covering 10 of 31 registered modules via family-shared
rules), and the existing operational playbook gains the
format-specific deployment recipes + the cross-format correlation
table.
YARA rules (8 rules, 9 module-headers, 152 lines):
- copy_fail_family — etc_passwd_uid_flip + etc_passwd_root_no_password
(shared across copy_fail / copy_fail_gcm / dirty_frag_esp /
dirty_frag_esp6 / dirty_frag_rxrpc)
- dirty_pipe — passwd UID flip pattern, dirty-pipe-specific tag
- dirtydecrypt — 28-byte ELF prefix match on tiny_elf[] + setuid+execve
shellcode tail, detects the page-cache overlay landing
- fragnesia — 28-byte ELF prefix on shell_elf[] + setuid+setgid+seteuid
cascade, detects the 192-byte page-cache overlay
- pwnkit — gconv-modules cache file format (small text file with
module UTF-8// X// /tmp/...)
- pack2theroot — malicious .deb (ar archive + SUID-bash postinst) +
/tmp/.suid_bash artifact scan
Falco rules (13 rules, 9 module-headers, 219 lines):
- pwnkit — pkexec with empty argv + GCONV_PATH/CHARSET env from non-root
- copy_fail_family — AF_ALG socket from non-root + NETLINK_XFRM from
unprivileged userns + /etc/passwd modified by non-root
- dirty_pipe — splice() of setuid/credential file by non-root
- dirtydecrypt — AF_RXRPC socket + add_key(rxrpc) by non-root
- fragnesia — TCP_ULP=espintcp from non-root + splice of setuid binary
- pack2theroot — SUID bit set on /tmp/.suid_bash + dpkg invoked by
packagekitd with /tmp/.pk-*.deb + 2x InstallFiles on same transaction
Wiring: each module's .detect_yara and .detect_falco struct fields
now point at the embedded string. The dispatcher dedups by pointer,
so family-shared rules emit once across the 5 sub-modules.
docs/DETECTION_PLAYBOOK.md augmented (302 -> 456 lines):
- New 'YARA artifact scanning' subsection under SIEM integration
with scheduled-scan cron pattern + per-rule trigger table
- New 'Falco runtime detection' subsection with deploy + per-rule
trigger table
- New 'Per-module detection coverage' table — 4-format matrix
- New 'Correlation across formats' section — multi-format incident
signature per exploit (the 3-of-4 signal pattern)
- New 'Worked example: catching DirtyDecrypt end-to-end' walkthrough
from Falco page through yara confirmation, recovery, hunt + patch
The existing operational lifecycle / SIEM patterns / FP tuning
content is preserved unchanged — this commit only adds.
Final stats:
- auditd: 109 rule statements across 27 modules
- sigma: 16 sigma rules across 19 modules
- yara: 8 yara rules across 9 module headers (5 family + 4 distinct)
- falco: 13 falco rules across 9 module headers
The remaining 21 modules can gain YARA / Falco coverage incrementally
by populating their detect_yara / detect_falco struct fields.
The 4 dirty_frag siblings + the GCM variant all gate on unprivileged
user-namespace creation (the XFRM-ESP / AF_RXRPC paths are
unreachable without it). The inner DIRTYFAIL detect functions
already check this, but the check happened deep inside the legacy
code — invisible to the test harness, and the bridge wrappers would
delegate first and only short-circuit afterwards.
Move the check up to the bridge: a single cff_check_userns() helper
inspects ctx->host->unprivileged_userns_allowed and returns
PRECOND_FAIL (with a host-fingerprint-annotated message) BEFORE
calling the inner detect. The inner check stays in place as belt-
and-suspenders.
copy_fail itself uses AF_ALG (no userns needed) and bypasses the
gate — its inner detect still confirms the primitive empirically
via the active probe.
modules/copy_fail_family/skeletonkey_modules.c:
- #include "../../core/host.h" alongside the existing includes.
- new static cff_check_userns(modname, ctx) helper.
- copy_fail_gcm_detect_wrap, dirty_frag_esp_detect_wrap,
dirty_frag_esp6_detect_wrap, dirty_frag_rxrpc_detect_wrap all
call cff_check_userns before delegating.
- copy_fail_detect_wrap is intentionally untouched.
tests/test_detect.c: 4 new EXPECT_DETECT cases assert that all 4
gated bridge wrappers return PRECOND_FAIL when
unprivileged_userns_allowed=false, using the existing
h_kernel_5_14_no_userns fingerprint.
29 → 33 tests, all pass on Linux.
The vendored DIRTYFAIL exploits call typed_confirm("DIRTYFAIL"), which
reads stdin interactively. SKELETONKEY already gates --exploit/--auto
behind --i-know, so the prompt is redundant and deadlocks non-interactive
runs like `skeletonkey --auto --i-know`.
Add a dirtyfail_assume_yes flag, forwarded from skeletonkey_ctx.authorized
by the bridge layer's apply_ctx(). When set, typed_confirm() auto-satisfies
its gate and logs that it did so.
The YES_BREAK_SSH self-lockout guard is exempt — it protects the
operator's own access rather than gating authorization, so it still
requires an interactive answer.
Standalone DIRTYFAIL builds are unchanged: the flag defaults false.
leviathan