tools/verify-vm: turnkey Vagrant + Parallels verification scaffolding

Closes the gap between 'detect() compiles and passes unit tests' and
'exploit() actually works on a real vulnerable kernel'. One-time
setup + one command per module to verify against a known-vulnerable
guest, with results emitted as JSON verification records.

Files:
  setup.sh        — one-shot bootstrap. Installs Vagrant via brew if
                    missing, installs vagrant-parallels plugin, pre-
                    downloads 5 base boxes (~5 GB):
                      generic/ubuntu1804  (4.15.0)
                      generic/ubuntu2004  (5.4.0 + HWE)
                      generic/ubuntu2204  (5.15.0 + HWE)
                      generic/debian11    (5.10.0)
                      generic/debian12    (6.1.0)
                    Idempotent; can pass --boxes subset.
  Vagrantfile     — single parameterized config driven by SKK_VM_*
                    env vars. Provisioners: build-deps install,
                    kernel pin (apt + snapshot.debian.org fallback),
                    build-and-verify (kept run='never' so verify.sh
                    invokes explicitly after reboot if pin'd).
  targets.yaml    — module → (box, kernel_pkg, kernel_version,
                    expect_detect, notes) mapping for all 26 modules.
                    3 marked manual: true (vmwgfx needs VMware guest;
                    dirtydecrypt + fragnesia need Linux 7.0 not yet
                    shipping as distro kernel).
  verify.sh       — entrypoint. 'verify.sh <module>' provisions if
                    needed, pins kernel + reboots if needed, runs
                    'skeletonkey --explain --active' inside the VM,
                    parses VERDICT, compares to expect_detect, emits
                    JSON verification record. --list shows the full
                    target matrix. --keep / --destroy lifecycle flags.
  README.md       — workflow + extending the targets table.

Design notes:
  - Pure bash + awk targets.yaml parsing — no PyYAML dep (macOS Python
    is PEP-668 'externally managed' and refuses pip --user installs).
  - Sources of vulnerable kernel packages: stock distro kernels where
    they're below the fix backport, otherwise pinned via apt with
    snapshot.debian.org as last-resort fallback (the Debian apt
    snapshot archive is the canonical source for historical kernel .deb
    packages).
  - Repo mounted at /vagrant via rsync (not 9p — vagrant-parallels'
    9p is finicky on macOS Sequoia per the plugin issue tracker).
  - VM lifecycle defaults to suspend-after-verify so the next run
    resumes in ~5s instead of cold-booting.
  - kernel pin reboots are handled by checking 'uname -r' after the
    pin provisioner and triggering 'vagrant reload' if mismatched.

Verification records (JSON on stdout per run) are intended to feed a
per-module verified_on[] table in a follow-up commit — that's the
'permanent trust artifact' angle from the earlier roadmap discussion.

Smoke tests (no VM actually spun up):
  - 'verify.sh --list': renders the 26-module matrix correctly.
  - 'verify.sh nf_tables': dispatches to generic/ubuntu2204 + kernel
    5.15.0-43 + expect=VULNERABLE; fails cleanly at 'vagrant: command
    not found' (expected — user runs setup.sh first).
  - 'verify.sh vmwgfx': errors with 'is marked manual: true' + note.

.gitignore: tools/verify-vm/{logs,.vagrant}/ excluded.

Usage:
  ./tools/verify-vm/setup.sh                    # one time, ~5 min
  ./tools/verify-vm/verify.sh nf_tables         # ~5 min first run, ~1 min after
  ./tools/verify-vm/verify.sh --list            # show all targets
This commit is contained in:
2026-05-23 11:19:28 -04:00
parent 8ab49f36f6
commit 554a58757e
6 changed files with 742 additions and 0 deletions
+2
View File
@@ -18,3 +18,5 @@ modules/*/skeletonkey
.vscode/
.idea/
*.swp
/tools/verify-vm/logs/
/tools/verify-vm/.vagrant/