leviathan/SKELETONKEY
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity
98 Commits 1 Branch 20 Tags
6e0f811a2c0c242bb552daa910605073fa338750
Commit Graph

5 Commits

Author SHA1 Message Date
leviathan 39ce4dff09 modules: per-module OPSEC notes — telemetry footprint per exploit 
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).
 2026-05-23 10:45:38 -04:00
leviathan 8938a74d04 detection rules: YARA + Falco for the 6 highest-rank modules + playbook 
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.
 2026-05-23 00:47:13 -04:00
leviathan 150f16bc97 pwnkit + sudoedit_editor: ctx->host migration + 4 more tests (39 total) 
pwnkit: migrate detect() to consult ctx->host->polkit_version with
the same graceful-fallback pattern as the sudo modules. The version
is populated once at startup by core/host.c (via pkexec --version);
detect() skips the per-scan popen when the host fingerprint has the
version. Falls back to the inline popen path when ctx->host is
missing the version (degenerate test contexts).

sudoedit_editor: already migrated; this commit adds direct test
coverage.

tests/test_detect.c expansion (35 → 39):
- pwnkit: polkit_version='0.105'  -> VULNERABLE (pre-0.121 fix)
- pwnkit: polkit_version='0.121'  -> OK (fix release)
- sudoedit_editor: vuln sudo + no sudoers grant -> PRECOND_FAIL
  (documented behaviour: vulnerable version, but the dispatcher
   has no usable sudoedit grant on the host)
- sudoedit_editor: fixed sudo (1.9.13p1) -> OK

The sudoedit_editor 'vuln + no grant' case is the first test to
exercise the second-level precondition gate AFTER the version
check passes — proves the version-pinned detect logic AND the
sudo -ln target-discovery short-circuit both work as intended.

The h_vuln_sudo / h_fixed_sudo synthetic fingerprints gained the
.polkit_version field alongside .sudo_version so a single fingerprint
exercises both pwnkit and the sudo modules.

Verification: 39/39 pass on Linux (docker gcc:latest + libglib2.0-dev
+ sudo, non-root user skeletonkeyci). macOS dev box still reports
'skipped — Linux-only' as designed.
 2026-05-23 00:15:01 -04:00
leviathan 36814f272d modules: migrate remaining 22 modules to ctx->host fingerprint 
Completes the host-fingerprint refactor that started in c00c3b4. Every
module now consults the shared ctx->host (populated once at startup
by core/host.c) instead of re-doing uname / geteuid / /etc/os-release
parsing / fork+unshare(CLONE_NEWUSER) probes per detect().

Migrations applied per module (mechanical, no exploit logic touched):

1. #include "../../core/host.h" inside each module's #ifdef __linux__.
2. kernel_version_current(&v) -> ctx->host->kernel (with the
   v -> v-> arrow-vs-dot fix for all later usage). Drops ~20 redundant
   uname() calls across the corpus.
3. geteuid() == 0 (the 'already root, nothing to escalate' gate) ->
   bool is_root = ctx->host ? ctx->host->is_root : (geteuid() == 0);
   This is the key change that lets the unit test suite construct
   non-root fingerprints regardless of the test process's actual euid.
4. Per-detect fork+unshare(CLONE_NEWUSER) probe helpers (named
   can_unshare_userns / can_unshare_userns_mount across the corpus)
   are removed wholesale; their call sites now consult
   ctx->host->unprivileged_userns_allowed, which was probed once at
   startup. Removes ~10 per-scan fork()s.

Modules touched by this commit (22):

  Batch A (7): dirty_pipe, dirty_cow, ptrace_traceme, pwnkit,
               cgroup_release_agent, overlayfs_setuid, and entrybleed
               (no migration target — KPTI gate stays as direct sysfs
               read; documented as 'no applicable pattern').

  Batch B (7): nf_tables, cls_route4, netfilter_xtcompat, af_packet,
               af_packet2, af_unix_gc, fuse_legacy.

  Batch C (8): stackrot, nft_set_uaf, nft_fwd_dup, nft_payload,
               sudo_samedit, sequoia, sudoedit_editor, vmwgfx.

Combined with the 4 modules already migrated (dirtydecrypt, fragnesia,
pack2theroot, overlayfs) and the 5-module copy_fail_family bridge,
the entire registered corpus now goes through ctx->host. The 4
'fork+unshare per detect()' helpers that existed across nf_tables,
cls_route4, netfilter_xtcompat, af_packet, af_packet2, fuse_legacy,
nft_set_uaf, nft_fwd_dup, nft_payload, sequoia,
cgroup_release_agent, and overlayfs_setuid are now gone — replaced by
the single startup probe in core/host.c.

Verification:
- Linux (docker gcc:latest + libglib2.0-dev): full clean build links
  31 modules; tests/test_detect.c: 8/8 pass.
- macOS (local): full clean build links 31 modules (Mach-O, 172KB);
  test suite reports skipped as designed on non-Linux.

Subsequent commits can add more EXPECT_DETECT cases in
tests/test_detect.c — the host-fingerprint paths in every module are
now uniformly testable via synthetic struct skeletonkey_host instances.
 2026-05-22 23:43:20 -04:00
leviathan 9593d90385 rename: IAMROOT → SKELETONKEY across the entire project
release / build (arm64) (push) Waiting to run
Details
release / build (x86_64) (push) Waiting to run
Details
release / release (push) Blocked by required conditions
Details 
Breaking change. Tool name, binary name, function/type names,
constant names, env vars, header guards, file paths, and GitHub
repo URL all rebrand IAMROOT → SKELETONKEY.

Changes:
  - All "IAMROOT" → "SKELETONKEY" (constants, env vars, enum
    values, docs, comments)
  - All "iamroot" → "skeletonkey" (functions, types, paths, CLI)
  - iamroot.c → skeletonkey.c
  - modules/*/iamroot_modules.{c,h} → modules/*/skeletonkey_modules.{c,h}
  - tools/iamroot-fleet-scan.sh → tools/skeletonkey-fleet-scan.sh
  - Binary "iamroot" → "skeletonkey"
  - GitHub URL KaraZajac/IAMROOT → KaraZajac/SKELETONKEY
  - .gitignore now expects build output named "skeletonkey"
  - /tmp/iamroot-* tmpfiles → /tmp/skeletonkey-*
  - Env vars IAMROOT_MODPROBE_PATH etc. → SKELETONKEY_*

New ASCII skeleton-key banner (horizontal key icon + ANSI Shadow
SKELETONKEY block letters) replaces the IAMROOT banner in
skeletonkey.c and README.md.

VERSION: 0.3.1 → 0.4.0 (breaking).

Build clean on Debian 6.12.86. `skeletonkey --version` → 0.4.0.
All 24 modules still register; no functional code changes — pure
rename + banner refresh.
 2026-05-16 22:43:49 -04:00