bootproof 0.2.0__py3-none-any.whl

bootproof/cli.py

@@ -0,0 +1,322 @@
+"""bootproof CLI — pre-reboot boot verification, Linux-only v1.
+
+Commands:
+  check       boot a snapshot, run the checklist, print GO / NO-GO
+  snapshots   list available snapshots for the machine
+  validate    validate a checklist file without booting anything
+  init        write example checklist + snapshot + fixture files
+  capture     draft a checklist from this machine (never runs a check)
+  preflight   static host boot checks: fstab, initramfs, /boot, dkms
+
+Exit codes: 0 = GO, 1 = NO-GO, 2 = error (missing snapshot, bad
+checklist, boot timeout, unverified checks, usage error). A GO
+means every check passed; anything unverified can never be a GO.
+
+Boot modes: --boot simulated (default; fixture guest state, the
+only mode that runs without KVM/QEMU) or --boot qemu (real
+QEMU/KVM boot; needs a snapshot with a disk path and a host with
+qemu-system-x86_64 and /dev/kvm). --local skips booting entirely
+and probes the current machine — a checklist dry run, not a boot
+verification, and labelled as such.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from . import preflight
+from . import report as reportmod
+from .capture import capture
+from .checklist import load_checklist
+from .errors import BootproofError
+from .probes import LocalTarget
+from .runners import FixtureRunner, QemuRunner
+from .snapshots import (DirectorySnapshotSource, FixtureSnapshotSource,
+                        select)
+from .verdict import evaluate
+
+EXAMPLE_CHECKLIST = """# bootproof checklist: what "up" means for this machine.
+checks:
+  - type: port
+    port: 443
+  - type: port
+    port: 5432
+  - type: unit
+    name: nginx.service
+  - type: http
+    url: http://127.0.0.1:8080/health
+    expect_status: 200
+    body_contains: ok
+"""
+
+EXAMPLE_SNAPSHOTS = {
+    "snapshots": [
+        {"id": "snap-2026-10-27", "name": "pre-kernel-update snapshot",
+         "source": "fixture"},
+    ]
+}
+
+EXAMPLE_FIXTURE_GO = {
+    "ports": {"443": True, "5432": True},
+    "units": {"nginx.service": "active"},
+    "endpoints": {"http://127.0.0.1:8080/health":
+                  {"status": 200, "body": "ok"}},
+}
+
+EXAMPLE_FIXTURE_NOGO = {
+    "ports": {"443": True, "5432": False},
+    "units": {"nginx.service": "active"},
+    "endpoints": {"http://127.0.0.1:8080/health":
+                  {"status": 200, "body": "ok"}},
+}
+
+
+def _snapshot_source(args):
+    if getattr(args, "snapshot_dir", None):
+        return DirectorySnapshotSource(args.snapshot_dir)
+    if getattr(args, "snapshots", None):
+        return FixtureSnapshotSource(path=args.snapshots)
+    raise BootproofError("no snapshot source: pass --snapshots FILE "
+                         "or --snapshot-dir DIR")
+
+
+def _load_fixture(path: str | None) -> dict:
+    if path is None:
+        return {}
+    p = Path(path)
+    if not p.exists():
+        raise BootproofError(f"fixture file not found: {p}")
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise BootproofError(f"fixture file {p} is not valid JSON: {e}")
+    if not isinstance(data, dict):
+        raise BootproofError(f"fixture file {p} must hold a JSON object")
+    return data
+
+
+def cmd_check(args) -> int:
+    try:
+        checklist = load_checklist(args.checklist)
+    except BootproofError as e:
+        print(reportmod.render_error(str(e), args.json))
+        return 2
+    if args.local:
+        verdict = evaluate(checklist, LocalTarget())
+        if args.json:
+            print(reportmod.render_json(verdict, "(local, no snapshot)",
+                                        "local"))
+        else:
+            print(reportmod.render_text(verdict, "(local, no snapshot)",
+                                        "local"))
+        return verdict.exit_code
+    try:
+        source = _snapshot_source(args)
+        snapshots = source.list_snapshots()
+        snapshot = select(snapshots, args.snapshot)
+    except BootproofError as e:
+        print(reportmod.render_error(str(e), args.json))
+        return 2
+    try:
+        if args.boot == "qemu":
+            runner = QemuRunner(
+                checklist=checklist,
+                ssh_user=getattr(args, "ssh_user", None),
+                ssh_key=getattr(args, "ssh_key", None),
+                ssh_host_port=getattr(args, "ssh_port", 2222))
+            boot_mode = runner.boot_mode
+        else:
+            fixture = _load_fixture(args.fixture)
+            boot_delay = fixture.pop("boot_delay", 0.0) \
+                if isinstance(fixture, dict) else 0.0
+            runner = FixtureRunner(fixture_data=fixture,
+                                   boot_delay=float(boot_delay))
+            boot_mode = runner.boot_mode
+        try:
+            target = runner.boot(snapshot, timeout=args.timeout)
+            verdict = evaluate(checklist, target)
+        finally:
+            runner.close()
+    except BootproofError as e:
+        print(reportmod.render_error(str(e), args.json))
+        return 2
+    if args.json:
+        print(reportmod.render_json(verdict, snapshot.id, boot_mode,
+                                    snapshot.path))
+    else:
+        print(reportmod.render_text(verdict, snapshot.id, boot_mode,
+                                    snapshot.path))
+    return verdict.exit_code
+
+
+def cmd_snapshots(args) -> int:
+    try:
+        source = _snapshot_source(args)
+        snapshots = source.list_snapshots()
+    except BootproofError as e:
+        print(reportmod.render_error(str(e), args.json))
+        return 2
+    print(reportmod.render_snapshots(snapshots, args.json))
+    return 0
+
+
+def cmd_validate(args) -> int:
+    try:
+        checklist = load_checklist(args.checklist)
+    except BootproofError as e:
+        print(reportmod.render_error(str(e), args.json))
+        return 2
+    if args.json:
+        print(json.dumps({"ok": True, "checks": len(checklist),
+                          "detail": [c.describe()
+                                     for c in checklist.checks]},
+                         indent=2))
+    else:
+        print(f"checklist valid: {len(checklist)} checks")
+        for c in checklist.checks:
+            print(f"  - {c.describe()}")
+    return 0
+
+
+def cmd_init(args) -> int:
+    out = Path(args.output)
+    out.mkdir(parents=True, exist_ok=True)
+    files = {
+        "bootproof-checklist.yaml": EXAMPLE_CHECKLIST,
+        "snapshots.json": json.dumps(EXAMPLE_SNAPSHOTS, indent=2) + "\n",
+        "fixture-go.json": json.dumps(EXAMPLE_FIXTURE_GO, indent=2) + "\n",
+        "fixture-nogo.json": json.dumps(EXAMPLE_FIXTURE_NOGO,
+                                        indent=2) + "\n",
+    }
+    for name, content in files.items():
+        (out / name).write_text(content, encoding="utf-8")
+        print(f"wrote {out / name}")
+    print("try: bootproof check --checklist "
+          f"{out / 'bootproof-checklist.yaml'} --snapshots "
+          f"{out / 'snapshots.json'} --snapshot snap-2026-10-27 "
+          f"--fixture {out / 'fixture-go.json'}")
+    return 0
+
+
+def cmd_capture(args) -> int:
+    try:
+        capture(args.output, force=args.force)
+    except BootproofError as e:
+        print(reportmod.render_error(str(e)))
+        return 2
+    print(f"wrote DRAFT {args.output} — review it, then: bootproof "
+          f"validate --checklist {args.output}")
+    return 0
+
+
+def cmd_preflight(args) -> int:
+    findings = preflight.run(args.root)
+    print(preflight.render(findings, args.json))
+    return preflight.EXIT[preflight.verdict_of(findings)]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bootproof",
+        description="Pre-reboot boot verification: boot a snapshot in "
+                    "an isolated VM, run the service-up checklist, "
+                    "print GO or NO-GO before you reboot the real box.")
+    parser.add_argument("--version", action="version",
+                        version=f"bootproof {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def snapshot_args(p):
+        p.add_argument("--snapshots",
+                       help="JSON snapshots file (fixture source)")
+        p.add_argument("--snapshot-dir",
+                       help="directory of disk images "
+                            "(*.qcow2/*.img/*.raw)")
+
+    def json_arg(p):
+        p.add_argument("--json", action="store_true",
+                       help="machine-readable JSON output")
+
+    p_check = sub.add_parser(
+        "check", help="boot a snapshot, run the checklist, print the "
+                      "verdict")
+    p_check.add_argument("--checklist", required=True,
+                         help="checklist file (JSON or YAML)")
+    p_check.add_argument("--snapshot",
+                         help="snapshot id (auto-selected when the "
+                              "source holds exactly one)")
+    snapshot_args(p_check)
+    p_check.add_argument("--fixture",
+                         help="fixture guest-state JSON (simulated "
+                              "boot only)")
+    p_check.add_argument("--boot", choices=["simulated", "qemu"],
+                         default="simulated",
+                         help="boot mode (default: simulated)")
+    p_check.add_argument("--ssh-user",
+                         help="guest SSH user for unit checks in qemu "
+                              "mode (units ERROR without it)")
+    p_check.add_argument("--ssh-key",
+                         help="guest SSH private key for unit checks "
+                              "in qemu mode")
+    p_check.add_argument("--ssh-port", type=int, default=2222,
+                         help="host port forwarded to guest SSH "
+                              "(default: 2222)")
+    p_check.add_argument("--local", action="store_true",
+                         help="probe the current machine instead of "
+                              "booting a snapshot (checklist dry run)")
+    p_check.add_argument("--timeout", type=float, default=120,
+                         help="boot timeout in seconds (default: 120)")
+    json_arg(p_check)
+    p_check.set_defaults(func=cmd_check)
+
+    p_snaps = sub.add_parser("snapshots",
+                             help="list available snapshots")
+    snapshot_args(p_snaps)
+    json_arg(p_snaps)
+    p_snaps.set_defaults(func=cmd_snapshots)
+
+    p_val = sub.add_parser("validate",
+                           help="validate a checklist file without "
+                                "booting")
+    p_val.add_argument("--checklist", required=True)
+    json_arg(p_val)
+    p_val.set_defaults(func=cmd_validate)
+
+    p_init = sub.add_parser("init",
+                            help="write example checklist, snapshots, "
+                                 "and fixture files")
+    p_init.add_argument("--output", default="bootproof-examples",
+                        help="directory to write into (default: "
+                             "bootproof-examples)")
+    p_init.set_defaults(func=cmd_init)
+
+    p_cap = sub.add_parser(
+        "capture", help="draft a checklist from this machine's "
+                        "listening ports and running services")
+    p_cap.add_argument("--output", default="bootproof-checklist.yaml",
+                       help="file to write (default: "
+                            "bootproof-checklist.yaml)")
+    p_cap.add_argument("--force", action="store_true",
+                       help="overwrite an existing file")
+    p_cap.set_defaults(func=cmd_capture)
+
+    p_pre = sub.add_parser(
+        "preflight", help="static host boot checks (fstab, initramfs, "
+                          "/boot space, dkms) — read-only, no VM")
+    p_pre.add_argument("--root", default="/",
+                       help="filesystem root to inspect (default: /)")
+    json_arg(p_pre)
+    p_pre.set_defaults(func=cmd_preflight)
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bootproof/errors.py

@@ -0,0 +1,38 @@
+"""Error types. Every failure mode has a distinct, specific error —
+never a silent pass, never a GO on an unverified check."""
+
+
+class BootproofError(Exception):
+    """Base class; CLI maps these to exit code 2."""
+
+
+class ChecklistError(BootproofError):
+    """Checklist file missing, malformed, or invalid (bad check type,
+    missing field, empty checklist)."""
+
+
+class SnapshotError(BootproofError):
+    """Snapshot inventory problem."""
+
+
+class SnapshotNotFound(SnapshotError):
+    """No snapshot with the requested id exists in the source."""
+
+
+class AmbiguousSnapshot(SnapshotError):
+    """No snapshot id given and the source holds more than one."""
+
+
+class BootError(BootproofError):
+    """The boot itself failed (e.g. QEMU binary missing, guest disk
+    unreadable)."""
+
+
+class BootTimeout(BootError):
+    """The guest did not become reachable within the boot timeout."""
+
+
+class ProbeError(BootproofError):
+    """A check could not be determined at all (e.g. systemctl missing,
+    target not booted). Probe errors are verdict errors, not passes
+    and not plain failures: the check is unverified."""

bootproof/preflight.py

@@ -0,0 +1,185 @@
+"""``bootproof preflight``: static, read-only host boot checks.
+
+No VM, no reboot. Four checks against a root directory (``/`` by
+default; injectable for tests):
+
+1. fstab: every ``UUID=`` / ``LABEL=`` / ``PARTUUID=`` entry resolves
+   under ``/dev/disk/by-*``, unless its options say ``nofail`` or
+   ``noauto``. An unresolved entry drops a real boot into emergency
+   mode, so it is FAIL.
+2. initramfs: every ``/boot/vmlinuz-<v>`` has an ``initrd.img-<v>``,
+   ``initramfs-<v>.img`` or ``initrd-<v>`` beside it. Missing is FAIL.
+3. /boot space: under 50 MB free is WARN (does not block GO).
+4. dkms: when ``dkms`` is installed, every module must be
+   ``installed`` for the newest /boot kernel (version-sorted), else
+   FAIL naming the module. No dkms binary is SKIP, never a pass.
+
+Same verdict rules and exit codes as ``check``: any error is ERROR
+(2), else any fail is NO-GO (1), else GO (0).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .verdict import ERROR, EXIT_ERROR, EXIT_GO, EXIT_NO_GO, GO, NO_GO
+
+BOOT_MODE = "preflight (static host checks — not a boot)"
+MIN_BOOT_FREE_MB = 50
+BY_DIR = {"UUID": "by-uuid", "LABEL": "by-label",
+          "PARTUUID": "by-partuuid"}
+INITRD_NAMES = ("initrd.img-{v}", "initramfs-{v}.img", "initrd-{v}")
+EXIT = {GO: EXIT_GO, NO_GO: EXIT_NO_GO, ERROR: EXIT_ERROR}
+
+
+@dataclass
+class Finding:
+    check: str
+    status: str  # "pass" | "fail" | "warn" | "skip" | "error"
+    observed: str
+
+
+def check_fstab(root: Path) -> Finding:
+    try:
+        lines = (root / "etc" / "fstab").read_text().splitlines()
+    except OSError as e:
+        return Finding("fstab", "error", f"cannot read /etc/fstab ({e})")
+    bad, tolerated, checked = [], [], 0
+    for line in lines:
+        fields = line.split("#", 1)[0].split()
+        if len(fields) < 2 or "=" not in fields[0]:
+            continue
+        kind, _, value = fields[0].partition("=")
+        if kind not in BY_DIR:
+            continue
+        checked += 1
+        if (root / "dev" / "disk" / BY_DIR[kind] / value).exists():
+            continue
+        opts = fields[3].split(",") if len(fields) > 3 else []
+        if "nofail" in opts or "noauto" in opts:
+            tolerated.append(f"{fields[0]} ({fields[1]})")
+        else:
+            bad.append(f"{fields[0]} ({fields[1]})")
+    if bad:
+        return Finding("fstab", "fail",
+                       "not found under /dev/disk/by-*, no nofail/noauto "
+                       "— boot would stop in emergency mode: "
+                       + ", ".join(bad))
+    note = (f"; missing but nofail/noauto: {', '.join(tolerated)}"
+            if tolerated else "")
+    return Finding("fstab", "pass",
+                   f"{checked} UUID/LABEL/PARTUUID entries checked{note}")
+
+
+def _version_key(v: str) -> list:
+    # "6.8.0-9" < "6.8.0-50": compare digit runs as numbers.
+    return [int(x) if x.isdigit() else x for x in re.split(r"(\d+)", v)]
+
+
+def kernel_versions(root: Path) -> list[str]:
+    return sorted((p.name[len("vmlinuz-"):]
+                   for p in (root / "boot").glob("vmlinuz-*")),
+                  key=_version_key)
+
+
+def check_initramfs(root: Path) -> Finding:
+    versions = kernel_versions(root)
+    if not versions:
+        return Finding("initramfs", "error",
+                       "no /boot/vmlinuz-* found — cannot check")
+    missing = [v for v in versions
+               if not any((root / "boot" / n.format(v=v)).exists()
+                          for n in INITRD_NAMES)]
+    if missing:
+        return Finding("initramfs", "fail",
+                       "no initramfs for kernel " + ", ".join(missing))
+    return Finding("initramfs", "pass",
+                   f"initramfs present for {len(versions)} kernel(s)")
+
+
+def check_boot_space(root: Path) -> Finding:
+    try:
+        free_mb = shutil.disk_usage(root / "boot").free // (1024 * 1024)
+    except OSError as e:
+        return Finding("/boot space", "error", f"cannot stat /boot ({e})")
+    if free_mb < MIN_BOOT_FREE_MB:
+        return Finding("/boot space", "warn",
+                       f"{free_mb} MB free on /boot (under "
+                       f"{MIN_BOOT_FREE_MB} MB)")
+    return Finding("/boot space", "pass", f"{free_mb} MB free on /boot")
+
+
+def check_dkms(root: Path) -> Finding:
+    exe = shutil.which("dkms")
+    if exe is None:
+        return Finding("dkms", "skip",
+                       "dkms not installed — not checked")
+    versions = kernel_versions(root)
+    if not versions:
+        return Finding("dkms", "error",
+                       "no /boot/vmlinuz-* found — no newest kernel")
+    newest = versions[-1]
+    try:
+        proc = subprocess.run([exe, "status"], capture_output=True,
+                              text=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return Finding("dkms", "error", f"dkms status failed ({e})")
+    if proc.returncode != 0:
+        return Finding("dkms", "error", f"dkms status exited "
+                       f"{proc.returncode}: {proc.stderr.strip()}")
+    out = proc.stdout
+    modules, ok = set(), set()
+    for line in out.splitlines():
+        left, sep, state = line.rpartition(": ")
+        if not sep:
+            continue
+        parts = [x.strip() for x in left.split(",")]
+        # new format "mod/ver, kernel, arch"; old "mod, ver, kernel, arch"
+        if "/" not in parts[0] and len(parts) > 1:
+            parts = [f"{parts[0]}/{parts[1]}"] + parts[2:]
+        modules.add(parts[0])
+        if len(parts) > 1 and parts[1] == newest                 and state.strip().startswith("installed"):
+            ok.add(parts[0])
+    missing = sorted(modules - ok)
+    if missing:
+        return Finding("dkms", "fail",
+                       f"not installed for newest kernel {newest}: "
+                       + ", ".join(missing))
+    return Finding("dkms", "pass",
+                   f"{len(modules)} module(s) installed for {newest}")
+
+
+def run(root: str = "/") -> list[Finding]:
+    r = Path(root)
+    return [check_fstab(r), check_initramfs(r), check_boot_space(r),
+            check_dkms(r)]
+
+
+def verdict_of(findings: list[Finding]) -> str:
+    statuses = {f.status for f in findings}
+    if "error" in statuses:
+        return ERROR
+    if "fail" in statuses:
+        return NO_GO
+    return GO
+
+
+def render(findings: list[Finding], as_json: bool) -> str:
+    verdict = verdict_of(findings)
+    if as_json:
+        return json.dumps({"verdict": verdict, "boot_mode": BOOT_MODE,
+                           "checks": [asdict(f) for f in findings]},
+                          indent=2)
+    lines = [f"bootproof verdict: {verdict}", f"boot: {BOOT_MODE}"]
+    if verdict == GO:
+        lines.append("GO — static boot checks passed. This is not a "
+                     "boot test.")
+    order = ("error", "fail", "warn", "skip", "pass")
+    for f in sorted(findings, key=lambda f: order.index(f.status)):
+        lines.append(f"  {f.status.upper()}: {f.check} — {f.observed}")
+    return "\n".join(lines)