# Contributing to SKELETONKEY

SKELETONKEY is a curated corpus. PRs welcome for the things below.
For everything else, open an issue first to discuss scope.

## What we accept

### 1. Kernel offsets for the `--full-chain` table

The 11 🟡 PRIMITIVE modules use the shared finisher in
`core/finisher.c` to convert their primitive into a root pop via
`modprobe_path` overwrite. That needs `&modprobe_path` (and friends)
at runtime — resolved via env vars / `/proc/kallsyms` /
`/boot/System.map` / the embedded `kernel_table[]` in
`core/offsets.c`.

The embedded table is **empty by default** to honor the
no-fabricated-offsets rule. Every entry must come from a real kernel
you have root on.

**Workflow:**

```bash
sudo skeletonkey --dump-offsets   # on the target kernel build
# Paste the printed C struct entry into core/offsets.c kernel_table[]
# Open a PR titled "offsets: <distro> <kernel_release>"
```

Include in the PR body:
- Distro + kernel version (`uname -a`, `cat /etc/os-release`)
- How you verified the offsets (kallsyms / System.map / debuginfo)
- Whether `--full-chain` succeeds end-to-end against any 🟡 module
  on that kernel (if you can test on a vulnerable build)

### 2. New modules

A new CVE module is welcome if:

- The bug is **patched in upstream mainline** (no 0days here)
- It has a public CVE assignment or clear advisory
- The kernel range it affects has realistic deployment footprint
- You can include a working detect() with branch-backport ranges
- You ship matching detection rules (auditd at minimum)

Use any existing module as a template. Lightest-weight reference:
`modules/ptrace_traceme_cve_2019_13272/skeletonkey_modules.c`.

Mandatory:
- Detect short-circuits cleanly on patched kernels (we test this)
- `--i-know` gate on exploit
- Honest scope: `SKELETONKEY_EXPLOIT_OK` only after empirical root,
  otherwise `EXPLOIT_FAIL` with diagnostic
- `NOTICE.md` crediting the original CVE reporter + PoC author

After the module file exists, wire it into:
- `core/registry.h` (extern declaration)
- `skeletonkey.c` main() (register call)
- `Makefile` (new objects + ALL_OBJS)
- `CVES.md` (inventory entry)

### 3. Detection rules

If you're adding only detection coverage (no exploit) for an
existing or new CVE, that's fine. Drop a sigma rule into the module
or a new auditd rule file.

### 4. Bug reports + CVE-status corrections

Distro backports that patched a CVE without bumping the upstream
version → file an issue. Same for kernels we mis-classify as
vulnerable.

## What we don't accept

- Untested code paths claiming `SKELETONKEY_EXPLOIT_OK`
- Per-kernel offsets fabricated without verification
- Modules without detection rules
- 0day disclosures (responsible disclosure first; bundle here
  after upstream patch ships)
- Container escapes that don't chain to host root

## Code style

C99. Match the surrounding file. Run `make` and the existing
CI build (`.github/workflows/build.yml`) before opening the PR.

## License

By contributing you agree your work is MIT-licensed.