skeletonkey: --explain MODULE — single-page operator briefing

One command that answers 'should we worry about this CVE here,
what would patch it, and what would the SOC see if someone tried
it'. Renders, for the specified module:

  - Header: name + CVE + summary
  - WEAKNESS: CWE id and MITRE ATT&CK technique (from CVE metadata)
  - THREAT INTEL: CISA KEV status (with date_added if listed) and
    the upstream-curated kernel_range
  - HOST FINGERPRINT: kernel + arch + distro from ctx->host plus
    every relevant capability gate (userns / apparmor / selinux /
    lockdown)
  - DETECT() TRACE (live): runs the module's detect() with verbose
    stderr enabled so the operator sees the gates fire in real
    time — 'kernel X is patched', 'userns blocked by AppArmor',
    'no readable setuid binary', etc.
  - VERDICT: the result_t with a one-line operator interpretation
    that varies by outcome (OK / VULNERABLE / PRECOND_FAIL /
    TEST_ERROR each get their own framing)
  - OPSEC FOOTPRINT: word-wrapped .opsec_notes paragraph (from
    last commit) showing what an exploit would leave behind on
    this host
  - DETECTION COVERAGE: which of auditd/sigma/yara/falco have
    embedded rules for this module, with pointers to the
    --module-info / --detect-rules commands that dump the bodies

Targeted at every audience the project is meant to serve:
  - Red team: opsec footprint + 'would this even reach' verdict
    in one screen
  - Blue team: paste-ready triage ticket with CVE / CWE / ATT&CK /
    KEV header and detection-coverage matrix
  - Researchers: the live trace shows the reasoning chain
    (predates check, kernel_range_is_patched lookup, userns gate)
    that drove the verdict — auditable without reading source
  - SOC analysts / students: a single self-contained briefing per
    CVE, no cross-referencing needed

Implementation:
  - New mode MODE_EXPLAIN, new flag --explain MODULE
  - cmd_explain() composes the page from the existing module
    struct, cve_metadata_lookup() (federal-source triage data),
    ctx->host (cached fingerprint), and a live detect() call
  - print_wrapped() helper word-wraps the long .opsec_notes
    paragraph at 76 cols / 2-space indent
  - Help text + README quickstart + DETECTION_PLAYBOOK single-host
    recipe all updated to mention --explain

Smoke tests:
  - macOS: --explain nf_tables shows full briefing; trace says
    'Linux-only module — not applicable here'; verdict
    PRECOND_FAIL with the generic-precondition interpretation
  - Linux (docker gcc:latest): --explain nf_tables on a 6.12 host
    fires '[+] nf_tables: kernel 6.12.76-linuxkit is patched';
    verdict OK with the 'this host is patched' interpretation
  - Both: --explain nope (unknown module) returns 1 with a clear
    'no module ... Try --list' error
  - Both: 87 tests still pass (33 kernel_range + 54 detect on Linux,
    33 + 0 stubbed on macOS)

Closes the metadata + opsec + explain trio. The three together
answer the 'best tool for red team, blue team, researchers, and
more' framing.
This commit is contained in:
2026-05-23 10:49:46 -04:00
parent 39ce4dff09
commit ee3e7dd9a7
3 changed files with 181 additions and 0 deletions
+11
View File
@@ -41,12 +41,23 @@ make it part of your daily ops" guide.
# Daily/weekly hygiene check
sudo skeletonkey --scan
# Investigate a specific finding (one-page operator briefing)
sudo skeletonkey --explain nf_tables # whichever module came back VULNERABLE
# Shows: CVE / CWE / MITRE ATT&CK / CISA KEV status, live detect() trace,
# OPSEC footprint (what an exploit would leave behind), detection-rule
# coverage, mitigation. Paste into the triage ticket.
# If anything's VULNERABLE, deploy detections + apply mitigation
sudo skeletonkey --detect-rules --format=auditd | sudo tee /etc/audit/rules.d/99-skeletonkey.rules
sudo augenrules --load
sudo skeletonkey --mitigate copy_fail # or whichever module fired
```
The `--explain` output is also useful as a learning artifact: each
module's `--explain` block is a self-contained CVE briefing with the
reasoning chain the detect() function walked, so analysts can verify
SKELETONKEY's verdict against their own understanding of the bug.
### Small fleet (~10-100 hosts, SSH-reachable)
Use `tools/skeletonkey-fleet-scan.sh`: