bootproof 0.2.0__py3-none-any.whl

bootproof/__init__.py

@@ -0,0 +1,15 @@
+"""bootproof — pre-reboot boot verification.
+
+Snapshot the machine, boot the snapshot in an isolated VM, run a
+service-up checklist (ports listening, systemd units active, health
+endpoints green), and print one verdict — GO or NO-GO — before you
+reboot the real box.
+
+v1 is Linux-only. The verdict and checklist engines are fully
+implemented; the VM-boot layer is a runner abstraction with a real
+QEMU/KVM implementation path and a fixture (simulated) implementation
+for hosts without KVM. A simulated boot is never presented as a real
+boot: every report labels its boot_mode.
+"""
+
+__version__ = "0.2.0"

bootproof/__main__.py

@@ -0,0 +1,8 @@
+"""Allow `python -m bootproof`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bootproof/capture.py

@@ -0,0 +1,120 @@
+"""``bootproof capture``: draft a checklist from this machine.
+
+Reads listening TCP ports from /proc/net/tcp and /proc/net/tcp6
+(state 0A) and running services from systemctl, then writes a
+DRAFT checklist for a human to review. It never runs a check.
+
+Ports bound to 0.0.0.0, ::, or a loopback address are written
+with host 127.0.0.1. A port bound only to one specific non-loopback
+address is written with that address. Running services that
+``systemctl is-enabled`` says will not start at boot are left out
+and listed as comments.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .errors import BootproofError, ProbeError
+from .probes import BOOT_ENABLED_STATES, systemctl
+
+PROC_NET_TCP = ("/proc/net/tcp", "/proc/net/tcp6")
+LISTEN = "0A"
+SYSTEMCTL_TIMEOUT = 10
+
+
+def _addr(hexaddr: str) -> str:
+    raw = bytes.fromhex(hexaddr)
+    # /proc stores each 32-bit word in host (little-endian) order.
+    fixed = b"".join(raw[i:i + 4][::-1] for i in range(0, len(raw), 4))
+    ip = ipaddress.ip_address(fixed)
+    if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped:
+        ip = ip.ipv4_mapped
+    return str(ip)
+
+
+def listening_ports(paths=None) -> set[tuple[str, int]]:
+    """(host, port) pairs in LISTEN state. Wildcard and loopback
+    binds map to 127.0.0.1. Raises if no /proc/net/tcp* is readable."""
+    found: set[tuple[str, int]] = set()
+    read_any = False
+    for path in paths or PROC_NET_TCP:
+        try:
+            lines = Path(path).read_text().splitlines()[1:]
+        except OSError:
+            continue
+        read_any = True
+        for line in lines:
+            fields = line.split()
+            if len(fields) < 4 or fields[3] != LISTEN:
+                continue
+            hexaddr, _, hexport = fields[1].partition(":")
+            host = _addr(hexaddr)
+            ip = ipaddress.ip_address(host)
+            if ip.is_unspecified or ip.is_loopback:
+                host = "127.0.0.1"
+            found.add((host, int(hexport, 16)))
+    if not read_any:
+        raise BootproofError("cannot read /proc/net/tcp or /proc/net/tcp6 "
+                             "— capture needs a Linux host")
+    return found
+
+
+def running_services() -> tuple[list[str], list[str]]:
+    """(units to check, comment lines). Raises ProbeError when
+    systemctl is missing."""
+    proc = systemctl(["list-units", "--type=service", "--state=running",
+                      "--no-legend"], SYSTEMCTL_TIMEOUT)
+    keep: list[str] = []
+    notes: list[str] = []
+    for line in proc.stdout.splitlines():
+        fields = line.replace("●", " ").split()
+        if not fields:
+            continue
+        unit = fields[0]
+        state = systemctl(["is-enabled", unit],
+                          SYSTEMCTL_TIMEOUT).stdout.strip() or "unknown"
+        if state in BOOT_ENABLED_STATES:
+            keep.append(unit)
+        else:
+            notes.append(f"# skipped {unit}: running now but is-enabled "
+                         f"says {state} (will not start at boot)")
+    return sorted(keep), notes
+
+
+def render(host: str, when: str, ports, units, notes) -> str:
+    lines = [f"# DRAFT captured from {host} at {when}; review before use. "
+             "Ports bound to non-loopback addresses are listed with host "
+             "127.0.0.1 only if also bound to 0.0.0.0/::",
+             *notes, "checks:"]
+    for h, port in sorted(ports, key=lambda p: (p[0] != "127.0.0.1",
+                                                p[0], p[1])):
+        lines.append("  - type: port")
+        if h != "127.0.0.1":
+            lines.append(f"    host: {h}")
+        lines.append(f"    port: {port}")
+    for unit in units:
+        lines += ["  - type: unit", f"    name: {unit}"]
+    return "\n".join(lines) + "\n"
+
+
+def capture(output: str, force: bool = False) -> str:
+    out = Path(output)
+    if out.exists() and not force:
+        raise BootproofError(f"{out} exists — pass --force to overwrite")
+    ports = listening_ports()
+    try:
+        units, notes = running_services()
+    except ProbeError:
+        units, notes = [], ["# systemctl not found — no unit checks "
+                            "captured"]
+    if not ports and not units:
+        raise BootproofError("nothing captured: no listening TCP ports "
+                             "and no running enabled services")
+    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    text = render(socket.gethostname(), when, ports, units, notes)
+    out.write_text(text, encoding="utf-8")
+    return text

bootproof/checklist.py

@@ -0,0 +1,263 @@
+"""Checklist definition: what "up" means for this machine.
+
+Format: JSON, or a small YAML subset (no PyYAML dependency —
+stdlib only). A checklist is a mapping with a ``checks`` list. Each
+check is one of:
+
+  port:  {"type": "port", "host": "127.0.0.1", "port": 443}
+  unit:  {"type": "unit", "name": "nginx.service",
+          "require_enabled": true}
+  http:  {"type": "http", "url": "http://127.0.0.1:8080/health",
+          "expect_status": 200, "body_contains": "ok"}
+
+Defaults: port host 127.0.0.1, http expect_status 200, per-check
+timeout 5 seconds. An empty checklist is an error, not a GO: a
+verdict over zero checks would verify nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import ChecklistError
+
+CHECK_TYPES = ("port", "unit", "http")
+
+
+@dataclass(frozen=True)
+class Check:
+    type: str
+    # port
+    host: str = "127.0.0.1"
+    port: int | None = None
+    # unit
+    name: str | None = None
+    require_enabled: bool = True  # --local only: must start at boot
+    # http
+    url: str | None = None
+    expect_status: int = 200
+    body_contains: str | None = None
+    timeout: float = 5.0
+
+    def describe(self) -> str:
+        if self.type == "port":
+            return f"port {self.port} listening on {self.host}"
+        if self.type == "unit":
+            return f"unit {self.name} active"
+        return (f"endpoint {self.url} returns {self.expect_status}"
+                + (f" containing {self.body_contains!r}"
+                   if self.body_contains else ""))
+
+
+@dataclass
+class Checklist:
+    checks: list[Check] = field(default_factory=list)
+
+    def __len__(self) -> int:
+        return len(self.checks)
+
+
+def _validate(raw: object, source: str) -> Checklist:
+    if not isinstance(raw, dict):
+        raise ChecklistError(f"{source}: top level must be a mapping "
+                             f"with a 'checks' list")
+    raw_checks = raw.get("checks")
+    if not isinstance(raw_checks, list):
+        raise ChecklistError(f"{source}: missing or non-list 'checks'")
+    if not raw_checks:
+        raise ChecklistError(f"{source}: checklist is empty — a verdict "
+                             f"over zero checks would verify nothing")
+    checks: list[Check] = []
+    for i, item in enumerate(raw_checks):
+        where = f"{source}: check #{i + 1}"
+        if not isinstance(item, dict):
+            raise ChecklistError(f"{where}: each check must be a mapping")
+        ctype = item.get("type")
+        if ctype not in CHECK_TYPES:
+            raise ChecklistError(
+                f"{where}: unknown check type {ctype!r} "
+                f"(expected one of: {', '.join(CHECK_TYPES)})")
+        try:
+            timeout = float(item.get("timeout", 5.0))
+        except (TypeError, ValueError):
+            raise ChecklistError(f"{where}: timeout must be a number")
+        if timeout <= 0:
+            raise ChecklistError(f"{where}: timeout must be positive")
+        if ctype == "port":
+            port = item.get("port")
+            if not isinstance(port, int) or isinstance(port, bool) \
+                    or not 1 <= port <= 65535:
+                raise ChecklistError(
+                    f"{where}: port check needs an integer 'port' "
+                    f"in 1..65535")
+            host = item.get("host", "127.0.0.1")
+            if not isinstance(host, str) or not host:
+                raise ChecklistError(f"{where}: 'host' must be a "
+                                     f"non-empty string")
+            checks.append(Check(type="port", host=host, port=port,
+                                timeout=timeout))
+        elif ctype == "unit":
+            name = item.get("name")
+            if not isinstance(name, str) or not name:
+                raise ChecklistError(f"{where}: unit check needs a "
+                                     f"non-empty 'name'")
+            req = item.get("require_enabled", True)
+            if not isinstance(req, bool):
+                raise ChecklistError(f"{where}: require_enabled must be "
+                                     f"true or false")
+            checks.append(Check(type="unit", name=name,
+                                require_enabled=req, timeout=timeout))
+        else:
+            url = item.get("url")
+            if not isinstance(url, str) or not url:
+                raise ChecklistError(f"{where}: http check needs a "
+                                     f"non-empty 'url'")
+            if not (url.startswith("http://")
+                    or url.startswith("https://")):
+                raise ChecklistError(f"{where}: url must start with "
+                                     f"http:// or https://")
+            status = item.get("expect_status", 200)
+            if not isinstance(status, int) or isinstance(status, bool) \
+                    or not 100 <= status <= 599:
+                raise ChecklistError(f"{where}: expect_status must be "
+                                     f"an HTTP status code")
+            body = item.get("body_contains")
+            if body is not None and not isinstance(body, str):
+                raise ChecklistError(f"{where}: body_contains must be a "
+                                     f"string")
+            checks.append(Check(type="http", url=url,
+                                expect_status=status, body_contains=body,
+                                timeout=timeout))
+    return Checklist(checks=checks)
+
+
+def _strip_comment(line: str) -> str:
+    """Strip a YAML ``#`` comment, but only when ``#`` starts the
+    line or is preceded by whitespace AND is not inside quotes. A
+    ``#`` inside a value (URL fragments, ``body_contains: "a #b"``)
+    is data, not a comment — the old rule (cut at the first ``#``)
+    silently mangled those."""
+    quote: str | None = None
+    for i, ch in enumerate(line):
+        if quote is not None:
+            if ch == quote:
+                quote = None
+        elif ch in "\"'":
+            quote = ch
+        elif ch == "#" and (i == 0 or line[i - 1] in " \t"):
+            return line[:i]
+    return line
+
+
+def _parse_yaml_subset(text: str, source: str) -> dict:
+    """Minimal YAML subset parser, just enough for checklists.
+
+    Supports: top-level ``key: value`` pairs, a ``checks:`` list of
+    ``- key: value`` mappings with scalar values (strings, ints,
+    quoted strings), ``#`` comments, and blank lines. Anything else
+    raises ChecklistError naming the line. This is deliberately not
+    a general YAML parser — use JSON for anything fancier.
+    """
+    data: dict = {}
+    checks: list[dict] = []
+    current: dict | None = None
+    in_checks = False
+    for lineno, raw_line in enumerate(text.splitlines(), 1):
+        line = _strip_comment(raw_line).rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip())
+        stripped = line.strip()
+        if indent == 0:
+            if ":" not in stripped:
+                raise ChecklistError(f"{source}:{lineno}: expected "
+                                     f"'key: value'")
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = value.strip()
+            if key == "checks":
+                if value:
+                    raise ChecklistError(f"{source}:{lineno}: 'checks' "
+                                         f"must be followed by a list")
+                in_checks = True
+                data["checks"] = checks
+            else:
+                in_checks = False
+                data[key] = _scalar(value, source, lineno)
+            current = None
+            continue
+        if not in_checks:
+            raise ChecklistError(f"{source}:{lineno}: unexpected "
+                                 f"indented line outside 'checks'")
+        if stripped.startswith("- "):
+            current = {}
+            checks.append(current)
+            stripped = stripped[2:].strip()
+            if not stripped:
+                continue
+        if current is None:
+            raise ChecklistError(f"{source}:{lineno}: list item must "
+                                 f"start with '- '")
+        if ":" not in stripped:
+            raise ChecklistError(f"{source}:{lineno}: expected "
+                                 f"'key: value'")
+        key, _, value = stripped.partition(":")
+        current[key.strip()] = _scalar(value.strip(), source, lineno)
+    if "checks" not in data:
+        raise ChecklistError(f"{source}: missing 'checks' list")
+    return data
+
+
+def _scalar(value: str, source: str, lineno: int) -> object:
+    if value == "":
+        return None
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    if value in ("true", "True"):
+        return True
+    if value in ("false", "False"):
+        return False
+    if value in ("null", "Null", "~"):
+        return None
+    # ": " (colon-space) is a YAML mapping indicator; a bare colon
+    # is fine — URLs like http://127.0.0.1:8080 need it.
+    if ": " in value or value.startswith(("- ", "[", "{")):
+        raise ChecklistError(f"{source}:{lineno}: unsupported YAML "
+                             f"construct {value!r} — use JSON for "
+                             f"complex values")
+    return value
+
+
+def load_checklist(path: str | Path) -> Checklist:
+    """Load a checklist from a JSON file or the YAML subset above.
+    JSON is tried first when the file parses as JSON; otherwise the
+    YAML subset parser runs. Missing files raise ChecklistError."""
+    p = Path(path)
+    if not p.exists():
+        raise ChecklistError(f"checklist file not found: {p}")
+    text = p.read_text(encoding="utf-8")
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError:
+        raw = _parse_yaml_subset(text, str(p))
+    return _validate(raw, str(p))
+
+
+def parse_checklist_text(text: str, source: str = "<text>") -> Checklist:
+    """Parse checklist text (JSON or YAML subset), for tests and
+    embedding."""
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError:
+        raw = _parse_yaml_subset(text, source)
+    return _validate(raw, source)