bootproof 0.2.0__py3-none-any.whl

bootproof/probes.py

@@ -0,0 +1,399 @@
+"""Probe targets: the thing a checklist is evaluated against.
+
+A target answers three questions: is this port listening, is this
+systemd unit active, does this endpoint answer green? Two targets
+ship in v1:
+
+* LocalTarget — probes the machine bootproof runs on, with real
+  sockets, real HTTP (urllib), and real ``systemctl``. Used for
+  live-testing the checklist engine and for checking the current
+  box itself (a dry run of what the checklist would say).
+* FixtureTarget — answers from a fixed data structure (ports,
+  units, endpoints). This is what a simulated boot returns: fully
+  deterministic, and it labels itself simulated everywhere.
+
+Probe outcomes: ``pass`` (observed matches), ``fail`` (observed
+does not match — port closed, unit failed, status 500), or
+``error`` (could not be determined — systemctl missing, target not
+booted). Errors are never passes.
+"""
+
+from __future__ import annotations
+
+import shutil
+import socket
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, replace
+
+from .checklist import Check
+from .errors import ProbeError
+
+LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1")
+
+
+# `systemctl is-enabled` states that mean the unit starts at boot.
+BOOT_ENABLED_STATES = ("enabled", "static", "indirect", "generated",
+                       "alias", "enabled-runtime")
+
+
+def is_loopback(host: str) -> bool:
+    return host in LOOPBACK_HOSTS
+
+
+def systemctl(args: list[str], timeout: float
+              ) -> subprocess.CompletedProcess:
+    """Run local ``systemctl``, resolved via PATH/PATHEXT. A missing
+    binary is a ProbeError (unverifiable, never a pass)."""
+    exe = shutil.which("systemctl")
+    if exe is None:
+        raise ProbeError("systemctl not found — unit state cannot "
+                         "be verified on this host")
+    return subprocess.run([exe, *args], capture_output=True, text=True,
+                          timeout=timeout)
+
+
+@dataclass
+class ProbeOutcome:
+    status: str  # "pass" | "fail" | "error"
+    observed: str
+    seconds: float = 0.0
+
+
+class Target:
+    """Interface every boot target implements."""
+
+    kind: str = "target"
+
+    def probe_port(self, check: Check) -> ProbeOutcome:
+        raise NotImplementedError
+
+    def probe_unit(self, check: Check) -> ProbeOutcome:
+        raise NotImplementedError
+
+    def probe_http(self, check: Check) -> ProbeOutcome:
+        raise NotImplementedError
+
+    def probe(self, check: Check) -> ProbeOutcome:
+        if check.type == "port":
+            return self.probe_port(check)
+        if check.type == "unit":
+            return self.probe_unit(check)
+        return self.probe_http(check)
+
+
+class LocalTarget(Target):
+    """Probe the local machine. Real sockets, real HTTP, real
+    systemctl. A missing systemctl binary is an error, not a pass:
+    unit state cannot be verified without it."""
+
+    kind = "local"
+
+    def probe_port(self, check: Check) -> ProbeOutcome:
+        start = time.monotonic()
+        try:
+            with socket.create_connection((check.host, check.port),
+                                          timeout=check.timeout):
+                pass
+        except socket.timeout:
+            return ProbeOutcome("fail",
+                                f"port {check.port} on {check.host} "
+                                f"did not answer within {check.timeout}s",
+                                time.monotonic() - start)
+        except OSError as e:
+            return ProbeOutcome("fail",
+                                f"port {check.port} on {check.host} "
+                                f"closed ({e.strerror or e})",
+                                time.monotonic() - start)
+        return ProbeOutcome("pass",
+                            f"port {check.port} on {check.host} "
+                            f"listening",
+                            time.monotonic() - start)
+
+    def probe_unit(self, check: Check) -> ProbeOutcome:
+        """Active now AND (unless require_enabled is false) set to
+        start at boot: a unit running by hand but disabled passes
+        is-active today and is gone after the reboot."""
+        start = time.monotonic()
+        try:
+            proc = systemctl(["is-active", check.name], check.timeout)
+            if proc.returncode == 0 and check.require_enabled:
+                enabled = systemctl(["is-enabled", check.name],
+                                    check.timeout)
+        except subprocess.TimeoutExpired:
+            return ProbeOutcome("error",
+                                f"systemctl on {check.name} "
+                                f"timed out after {check.timeout}s",
+                                time.monotonic() - start)
+        state = proc.stdout.strip() or proc.stderr.strip() or "unknown"
+        elapsed = time.monotonic() - start
+        if not (proc.returncode == 0 and state == "active"):
+            return ProbeOutcome("fail", f"unit {check.name} {state}",
+                                elapsed)
+        if not check.require_enabled:
+            return ProbeOutcome("pass", f"unit {check.name} active",
+                                elapsed)
+        en = enabled.stdout.strip() or enabled.stderr.strip() or "unknown"
+        if en in BOOT_ENABLED_STATES:
+            return ProbeOutcome("pass", f"unit {check.name} active, "
+                                f"{en}", elapsed)
+        if en in ("disabled", "masked", "linked", "linked-runtime",
+                  "masked-runtime"):
+            return ProbeOutcome(
+                "fail", f"unit {check.name} active now but {en} — will "
+                f"not start at boot unless pulled in by another unit",
+                elapsed)
+        return ProbeOutcome("error", f"unit {check.name} active, but "
+                            f"is-enabled said {en!r} — cannot tell if it "
+                            f"starts at boot", elapsed)
+
+    def probe_http(self, check: Check) -> ProbeOutcome:
+        start = time.monotonic()
+        req = urllib.request.Request(check.url, method="GET")
+        try:
+            with urllib.request.urlopen(req, timeout=check.timeout) as resp:
+                status = resp.status
+                body = resp.read(65536).decode("utf-8", "replace")
+        except urllib.error.HTTPError as e:
+            body = e.read(65536).decode("utf-8", "replace") \
+                if e.fp is not None else ""
+            return ProbeOutcome(
+                "fail", f"{check.url} returned HTTP {e.code}"
+                        + (f" (expected {check.expect_status})"
+                           if e.code != check.expect_status else "")
+                        + (f", body did not contain "
+                           f"{check.body_contains!r}"
+                           if check.body_contains
+                           and check.body_contains not in body else ""),
+                time.monotonic() - start)
+        except urllib.error.URLError as e:
+            return ProbeOutcome("fail", f"{check.url} unreachable "
+                                f"({e.reason})",
+                                time.monotonic() - start)
+        except (TimeoutError, socket.timeout):
+            return ProbeOutcome("fail", f"{check.url} timed out after "
+                                f"{check.timeout}s",
+                                time.monotonic() - start)
+        except ValueError as e:
+            raise ProbeError(f"invalid url {check.url}: {e}")
+        elapsed = time.monotonic() - start
+        if status != check.expect_status:
+            return ProbeOutcome("fail", f"{check.url} returned HTTP "
+                                f"{status} (expected "
+                                f"{check.expect_status})", elapsed)
+        if check.body_contains is not None \
+                and check.body_contains not in body:
+            return ProbeOutcome("fail", f"{check.url} returned HTTP "
+                                f"{status} but body did not contain "
+                                f"{check.body_contains!r}", elapsed)
+        detail = f"HTTP {status}"
+        if check.body_contains:
+            detail += f", body contains {check.body_contains!r}"
+        return ProbeOutcome("pass", f"{check.url} {detail}", elapsed)
+
+
+def ssh_systemctl_is_active(user: str, key: str, host_port: int,
+                            unit: str, timeout: float) -> ProbeOutcome:
+    """Run ``systemctl is-active`` inside a guest over SSH.
+
+    BatchMode=yes so a failed key never hangs on a password prompt;
+    LogLevel=ERROR keeps host-key chatter out of the evidence.
+    A missing ssh binary is a ProbeError (unverifiable, never a
+    pass); a failed command is a fail with the observed state."""
+    start = time.monotonic()
+    # Resolve via PATH/PATHEXT so .cmd/.bat wrappers work on Windows too.
+    ssh = shutil.which("ssh")
+    if ssh is None:
+        raise ProbeError("ssh not found — guest unit state cannot be "
+                         "verified without it")
+    cmd = [ssh, "-i", key, "-o", "BatchMode=yes",
+           "-o", "StrictHostKeyChecking=no",
+           "-o", "UserKnownHostsFile=/dev/null",
+           "-o", "LogLevel=ERROR",
+           "-o", f"ConnectTimeout={int(max(1, timeout))}",
+           "-p", str(host_port), f"{user}@127.0.0.1",
+           "systemctl", "is-active", unit]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True,
+                              timeout=timeout + 5)
+    except FileNotFoundError:
+        raise ProbeError("ssh not found — guest unit state cannot be "
+                         "verified without it")
+    except subprocess.TimeoutExpired:
+        return ProbeOutcome("error",
+                            f"ssh systemctl is-active {unit} timed out "
+                            f"after {timeout}s",
+                            time.monotonic() - start)
+    state = proc.stdout.strip() or proc.stderr.strip() or "unknown"
+    elapsed = time.monotonic() - start
+    if proc.returncode == 0 and state == "active":
+        return ProbeOutcome("pass", f"unit {unit} active (guest)", elapsed)
+    return ProbeOutcome("fail", f"unit {unit} {state} (guest)", elapsed)
+
+
+class GuestTarget(Target):
+    """Probe a QEMU guest through forwarded host ports.
+
+    ``port_map`` maps guest port -> host port (built by QemuRunner
+    from the checklist). Port and HTTP checks are remapped to the
+    forwarded host port; the observed text names the GUEST port, so
+    a report never confuses host and guest.
+
+    Only loopback hosts/URLs are forwarded. A non-loopback host
+    (e.g. the machine's LAN IP) is not reachable from the host
+    without bridging, so it becomes an ERROR — unverified, never a
+    pass, and never silently probed against the host. HTTPS URLs
+    are likewise ERROR: TLS to a forwarded port cannot present the
+    guest's hostname certificate. Unit checks run over SSH when
+    credentials are given, and ERROR without them — units must
+    never be probed against the host and mistaken for the guest.
+    """
+
+    kind = "guest"
+
+    def __init__(self, port_map: dict[int, int],
+                 ssh_user: str | None = None,
+                 ssh_key: str | None = None,
+                 ssh_host_port: int = 2222):
+        self.port_map = dict(port_map)
+        self.ssh_user = ssh_user
+        self.ssh_key = ssh_key
+        self.ssh_host_port = ssh_host_port
+        self._local = LocalTarget()
+
+    def _remap_port_observed(self, outcome: ProbeOutcome,
+                             guest_port: int, host_port: int
+                             ) -> ProbeOutcome:
+        if guest_port == host_port:
+            return outcome
+        return ProbeOutcome(outcome.status,
+                            outcome.observed.replace(
+                                f"port {host_port} ", f"port {guest_port} "),
+                            outcome.seconds)
+
+    def probe_port(self, check: Check) -> ProbeOutcome:
+        if not is_loopback(check.host):
+            return ProbeOutcome(
+                "error",
+                f"cannot probe host {check.host} against a QEMU guest "
+                f"— only loopback hosts are forwarded (use 127.0.0.1 "
+                f"for guest-local services)")
+        host_port = self.port_map.get(check.port)
+        if host_port is None:
+            return ProbeOutcome(
+                "error",
+                f"port {check.port} was not forwarded to the guest — "
+                f"checklist port missing from the forward map")
+        outcome = self._local.probe_port(
+            replace(check, host="127.0.0.1", port=host_port))
+        return self._remap_port_observed(outcome, check.port, host_port)
+
+    def probe_unit(self, check: Check) -> ProbeOutcome:
+        if self.ssh_user and self.ssh_key:
+            return ssh_systemctl_is_active(
+                self.ssh_user, self.ssh_key, self.ssh_host_port,
+                check.name, check.timeout)
+        return ProbeOutcome(
+            "error",
+            f"unit {check.name} cannot be verified against a QEMU "
+            f"guest without SSH credentials — pass --ssh-user and "
+            f"--ssh-key, or drop the unit check (host units are never "
+            f"substituted for guest units)")
+
+    def probe_http(self, check: Check) -> ProbeOutcome:
+        parsed = urllib.parse.urlparse(check.url)
+        if parsed.scheme == "https":
+            return ProbeOutcome(
+                "error",
+                f"cannot probe {check.url} against a QEMU guest — "
+                f"HTTPS over a forwarded port cannot present the "
+                f"guest's certificate (use an http loopback URL)")
+        if not is_loopback(parsed.hostname or ""):
+            return ProbeOutcome(
+                "error",
+                f"cannot probe {check.url} against a QEMU guest — "
+                f"only loopback URLs are forwarded")
+        guest_port = parsed.port or 80
+        host_port = self.port_map.get(guest_port)
+        if host_port is None:
+            return ProbeOutcome(
+                "error",
+                f"port {guest_port} was not forwarded to the guest — "
+                f"checklist URL port missing from the forward map")
+        rewritten = urllib.parse.urlunparse(
+            ("http", f"127.0.0.1:{host_port}", parsed.path or "/",
+             parsed.params, parsed.query, parsed.fragment))
+        outcome = self._local.probe_http(replace(check, url=rewritten))
+        if guest_port != host_port:
+            outcome = ProbeOutcome(
+                outcome.status,
+                outcome.observed.replace(
+                    rewritten, check.url),
+                outcome.seconds)
+        return outcome
+
+
+class FixtureTarget(Target):
+    """Deterministic answers from fixture data. Shape:
+
+    {"ports": {"443": true, "80": false},
+     "units": {"nginx.service": "active", "db.service": "failed"},
+     "endpoints": {"http://127.0.0.1:8080/health":
+                   {"status": 200, "body": "ok"}}}
+
+    Anything not listed is observed as absent: a port not listed is
+    closed, a unit not listed is inactive, an endpoint not listed
+    is unreachable. That keeps fixtures honest — an unlisted check
+    fails loudly instead of passing by default.
+    """
+
+    kind = "fixture"
+
+    def __init__(self, data: dict):
+        self.data = data or {}
+        ports = self.data.get("ports", {})
+        self.ports = {str(k): bool(v) for k, v in ports.items()}
+        self.units = {str(k): str(v)
+                      for k, v in self.data.get("units", {}).items()}
+        self.endpoints = {str(k): v
+                          for k, v in self.data.get("endpoints", {}).items()}
+
+    def probe_port(self, check: Check) -> ProbeOutcome:
+        if self.ports.get(str(check.port), False):
+            return ProbeOutcome("pass", f"port {check.port} on "
+                                f"{check.host} listening")
+        return ProbeOutcome("fail", f"port {check.port} on {check.host} "
+                            f"closed")
+
+    def probe_unit(self, check: Check) -> ProbeOutcome:
+        state = self.units.get(check.name)
+        if state == "active":
+            return ProbeOutcome("pass", f"unit {check.name} active")
+        if state is None:
+            return ProbeOutcome("fail", f"unit {check.name} inactive "
+                                f"(not present in booted snapshot)")
+        return ProbeOutcome("fail", f"unit {check.name} {state}")
+
+    def probe_http(self, check: Check) -> ProbeOutcome:
+        entry = self.endpoints.get(check.url)
+        if entry is None:
+            return ProbeOutcome("fail", f"{check.url} unreachable "
+                                f"(not present in booted snapshot)")
+        if isinstance(entry, int):
+            status, body = entry, ""
+        else:
+            status = entry.get("status", 0)
+            body = entry.get("body", "")
+        if status != check.expect_status:
+            return ProbeOutcome("fail", f"{check.url} returned HTTP "
+                                f"{status} (expected "
+                                f"{check.expect_status})")
+        if check.body_contains is not None \
+                and check.body_contains not in body:
+            return ProbeOutcome("fail", f"{check.url} returned HTTP "
+                                f"{status} but body did not contain "
+                                f"{check.body_contains!r}")
+        return ProbeOutcome("pass", f"{check.url} HTTP {status}")

bootproof/report.py

@@ -0,0 +1,79 @@
+"""Report rendering: text for humans, JSON for CI.
+
+Text form leads with the verdict on its own line — GO or NO-GO —
+then names every failing check exactly (which port, which unit,
+which endpoint, what was observed). The boot_mode line is always
+present: a simulated boot says so, in the report itself, not just
+in the README.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .verdict import ERROR, GO, NO_GO, Verdict
+
+
+def render_text(verdict: Verdict, snapshot_id: str,
+                boot_mode: str, snapshot_path: str | None = None) -> str:
+    lines = [f"bootproof verdict: {verdict.verdict}",
+             f"snapshot: {snapshot_id}",
+             f"boot: {boot_mode}"]
+    if snapshot_path:
+        lines.append(f"disk: {snapshot_path}")
+    lines.append(f"checks: {len(verdict.passed)} passed, "
+                 f"{len(verdict.failed)} failed, "
+                 f"{len(verdict.errored)} errored, "
+                 f"{len(verdict.results)} total")
+    slowest = sorted(verdict.results, key=lambda r: r.seconds,
+                     reverse=True)[:3]
+    if slowest and slowest[0].seconds > 0:
+        lines.append("slowest: " + "; ".join(
+            f"{r.check.describe()} ({r.seconds:.2f}s)" for r in slowest))
+    if verdict.verdict == GO:
+        lines.append("GO — every service-up check passed. "
+                     "Safe to reboot.")
+    elif verdict.verdict == NO_GO:
+        lines.append("NO-GO — the following checks failed:")
+        for r in verdict.failed:
+            lines.append(f"  FAIL: {r.check.describe()} — "
+                         f"{r.observed}")
+    else:
+        lines.append("ERROR — the run could not verify the checklist:")
+        for r in verdict.errored:
+            lines.append(f"  ERROR: {r.check.describe()} — "
+                         f"{r.observed}")
+        for r in verdict.failed:
+            lines.append(f"  FAIL: {r.check.describe()} — "
+                         f"{r.observed}")
+    for r in verdict.passed:
+        lines.append(f"  PASS: {r.check.describe()} — {r.observed}")
+    return "\n".join(lines)
+
+
+def render_json(verdict: Verdict, snapshot_id: str,
+                boot_mode: str, snapshot_path: str | None = None) -> str:
+    payload = verdict.to_dict()
+    payload["snapshot"] = snapshot_id
+    payload["boot_mode"] = boot_mode
+    if snapshot_path:
+        payload["snapshot_path"] = snapshot_path
+    return json.dumps(payload, indent=2)
+
+
+def render_error(message: str, as_json: bool = False) -> str:
+    if as_json:
+        return json.dumps({"verdict": ERROR, "error": message}, indent=2)
+    return f"error: {message}"
+
+
+def render_snapshots(snapshots, as_json: bool = False) -> str:
+    if as_json:
+        return json.dumps({"snapshots": [s.to_dict() for s in snapshots]},
+                          indent=2)
+    if not snapshots:
+        return "no snapshots available"
+    lines = [f"{s.id}  {s.name}  [{s.source}]"
+             + (f"  {s.path}" if s.path else "")
+             for s in snapshots]
+    return "\n".join(lines)