SKELETONKEY/docs/ARCHITECTURE.md

Architecture

Module model

Each CVE (or tightly-related family of CVEs sharing a primitive) is a module under modules/. A module is a self-contained exploit + detection + metadata bundle that exports a standard interface to the top-level dispatcher.

Module layout

modules/<module_name>/
├── MODULE.md                  # Human-readable writeup of the bug
├── NOTICE.md                  # Credits to original researcher
├── kernel-range.json          # Machine-readable affected kernels
├── module.c                   # Implements skeletonkey_module interface
├── module.h
├── detect/
│   ├── auditd.rules           # blue team detection
│   ├── sigma.yml
│   └── yara.yara
├── src/                       # exploit internals
└── tests/                     # per-module tests (run in CI matrix)

skeletonkey_module interface (planned, Phase 1)

struct skeletonkey_module {
    const char *name;           /* "copy_fail" */
    const char *cve;            /* "CVE-2026-31431" */
    const char *summary;        /* one-line description */

    /* Return 1 if host appears vulnerable, 0 if patched/immune,
     * -1 if probe couldn't run. May call entrybleed_leak_kbase()
     * etc. from core/ if a leak primitive is needed. */
    int (*detect)(struct skeletonkey_host *host);

    /* Run the exploit. Caller has already passed the
     * authorization gate. Returns 0 on root acquired,
     * nonzero on failure. */
    int (*exploit)(struct skeletonkey_host *host, struct skeletonkey_opts *opts);

    /* Apply a runtime mitigation for this CVE (sysctl, module
     * blacklist, etc.). Returns 0 on success. NULL if no
     * mitigation is offered. */
    int (*mitigate)(struct skeletonkey_host *host);

    /* Undo --exploit-backdoor or --mitigate side effects. */
    int (*cleanup)(struct skeletonkey_host *host);

    /* Affected kernel version range, distros covered, etc. */
    const struct skeletonkey_kernel_range *ranges;
    size_t n_ranges;
};

Modules register themselves at link time via a constructor-attribute table. The top-level skeletonkey binary iterates the registry on each invocation.

Shared core/

Code that more than one module needs lives in core/:

• core/common.c — fingerprinting (kernel version, distro, LSM, hardening flags), logging, error handling
• core/apparmor_bypass.c — Ubuntu's apparmor_restrict_unprivileged_userns=1 defeat via change_onexec("crun") re-exec
• core/exploit_su.c — once we have page-cache-write or /etc/passwd-overwrite, this is the shared "drop to root shell" helper
• core/fcrypt.c — file-encryption helpers used by multiple modules
• core/entrybleed.c (planned, Phase 3) — kbase leak primitive that any module needing KASLR-defeat can call

Top-level dispatcher

skeletonkey.c (planned, Phase 1) is the CLI entry point. Responsibilities:

1. Parse args (--scan, --exploit <name>, --mitigate, --detect-rules, --cleanup, etc.)
2. Fingerprint the host — core/host.c is called once at startup to populate struct skeletonkey_host (kernel version + arch + distro + capability gates + service presence). The result is handed to every module via ctx->host. See "Host fingerprint" below.
3. For --scan: iterate module registry, call each module's detect(), emit table of results
4. For --exploit <name>: locate module, gate behind --i-know, call its exploit()
5. For --detect-rules: walk module registry, concatenate detection files in the requested format

Host fingerprint (core/host.{h,c})

A single struct skeletonkey_host is populated once at startup and exposed to every module via ctx->host (a stable pointer for the process lifetime). It carries:

• Identity: struct kernel_version kernel + arch + nodename + distro id/version/pretty (parsed from /etc/os-release).
• Process state: euid, real_uid (defeats the userns illusion by reading /proc/self/uid_map), egid, username, is_root, is_ssh_session.
• Platform family: is_linux, is_debian_family, is_rpm_family, is_arch_family, is_suse_family.
• Capability gates (Linux): unprivileged_userns_allowed (live fork-probe), apparmor_restrict_userns, unprivileged_bpf_disabled, kpti_enabled, kernel_lockdown_active, selinux_enforcing, yama_ptrace_restricted.
• System services: has_systemd, has_dbus_system.

Modules that want to consult the fingerprint do:

#include "../../core/host.h"
/* ... */
if (ctx->host && !ctx->host->unprivileged_userns_allowed)
    return SKELETONKEY_PRECOND_FAIL;
if (ctx->host->kernel.major < 7)
    return SKELETONKEY_OK;   /* predates the bug */

The migration is opt-in per module — modules that don't #include host.h continue to do their own probes; modules that do save the duplicate work and get a consistent view across the whole scan.

--auto and --scan (in verbose mode) print a two-line banner of the fingerprint via skeletonkey_host_print_banner() so operators can see at a glance which gates are open.

CI matrix

.github/workflows/ci.yml (planned, Phase 4) runs each module's test against a matrix of distro × kernel VMs. Each test asserts:

• on a vulnerable VM: detect() returns 1, exploit() returns 0 and produces uid=0
• on a patched VM: detect() returns 0, exploit() either refuses or fails gracefully

Failures on a previously-working matrix entry open an issue automatically (likely cause: distro shipped a backport that broke the module).

Adding a new CVE

1. git checkout -b add-cve-XXXX-NNNN
2. cp -r modules/_stubs/_template modules/<module_name>
3. Fill in MODULE.md, NOTICE.md, kernel-range.json
4. Implement module.c exposing the skeletonkey_module interface
5. Ship at least one detection rule under detect/
6. Add tests under tests/
7. PR. CI runs the matrix. If it lands root on at least one vulnerable matched VM AND fails cleanly on a patched VM, it merges.

See docs/module-template.md (planned) for the per-module checklist.