backupproof 0.2.0__py3-none-any.whl

backupproof/__init__.py

@@ -0,0 +1,23 @@
+"""backupproof — backup restore-testing CLI.
+
+Pick the latest restic/borg/Proxmox backup, restore it into a
+throwaway target, verify it, and report PASS or FAIL with proof.
+
+What "verify" means depends on the source, and the report says
+which: restic/borg backups are file-level — the restored files are
+content-checked (web pack served from the restored tree, DB and
+file checks against the restored files); there is no disk image to
+boot, and the report says so. Proxmox backups restore into a
+throwaway VMID on the Proxmox host and are probed there (web pack
+via a probe URL; db/files packs cannot verify a VM from the host
+and are refused, not silently dropped). Fixture sources are
+labelled simulated in every output.
+
+Exit codes: 0 = PASS, 1 = FAIL (a check failed), 2 = ERROR
+(no backup found, restore failure, boot timeout, bad config,
+missing tool, stale backup with --fail-on-stale, unsupported pack
+for Proxmox). A PASS is only ever issued when every check was
+actually run and passed; unverified checks never pass silently.
+"""
+
+__version__ = "0.2.0"

backupproof/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

backupproof/cli.py

@@ -0,0 +1,420 @@
+"""backupproof CLI.
+
+Commands:
+  run       the verdict: latest backup -> restore -> boot -> smoke -> PASS/FAIL
+  list      list backups for a source (newest first)
+  validate  validate a config file (no restore, no boot)
+
+Exit codes: 0 PASS, 1 FAIL, 2 ERROR (no backup, restore/boot
+failure, bad config, missing tool). --json on all commands.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+from dataclasses import replace
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__
+from . import config as configmod
+from . import discovery, smoke, verdict as verdictmod
+from .errors import (BackupProofError, StaleBackupError,
+                     UnsupportedPackError)
+from .runners import FixtureRunner, RealRunner
+
+
+def _backup_datetime(backup):
+    """Backup timestamp as an aware datetime, or None when missing/
+    unparseable."""
+    ts = (backup.timestamp or "").strip()
+    if not ts:
+        return None
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _backup_age_days(backup):
+    """Age of a backup in days, or None when the timestamp is
+    missing/unparseable (staleness then warns, never fails)."""
+    dt = _backup_datetime(backup)
+    if dt is None:
+        return None
+    return (datetime.now(timezone.utc) - dt).total_seconds() / 86400.0
+
+
+def _verified_against(source, mode, boot_kind, probe_url):
+    """What the packs actually verified, in one honest line. Web
+    checks hit an HTTP target; db/files checks always hit restored
+    files — the report must never imply otherwise."""
+    if mode == "simulated":
+        return ("restored fixture tree (web pack served over real HTTP "
+                "from the restored webroot)")
+    if boot_kind == "file-level":
+        return ("restored files (web pack served from serve_dir where "
+                "configured, else explicit URLs)")
+    if probe_url:
+        return ("booted VM via probe URL (web pack only; db/files not "
+                "verifiable from host)")
+    return ("booted VM, unprobed (web pack only — no probe URL "
+            "configured)")
+
+
+def _runner_for(source: dict, include: list[str] | None = None):
+    if source["type"] == "fixture":
+        return FixtureRunner(source["dir"]), "simulated"
+    return RealRunner(source, include), "real"
+
+
+def _source_from_args(args) -> dict:
+    if getattr(args, "config", None):
+        return configmod.load_config(args.config)["source"]
+    stype = args.source_type
+    src: dict = {"type": stype}
+    if stype in ("restic", "borg"):
+        src["repo"] = args.repo
+    elif stype == "proxmox":
+        src["dump_dir"] = args.dump_dir
+    elif stype == "fixture":
+        src["dir"] = args.fixture_dir
+    if stype in ("restic", "borg") and not src.get("repo"):
+        raise configmod.ConfigError(f"{stype} source requires --repo")
+    if stype == "proxmox" and not src.get("dump_dir"):
+        raise configmod.ConfigError("proxmox source requires --dump-dir")
+    if stype == "fixture" and not src.get("dir"):
+        raise configmod.ConfigError("fixture source requires --fixture-dir")
+    return src
+
+
+def cmd_list(args) -> int:
+    try:
+        source = _source_from_args(args)
+        runner, _mode = _runner_for(source)
+        backups = runner.list_backups()
+        latest = discovery.latest(backups)
+    except BackupProofError as e:
+        if args.json:
+            print(json.dumps({"ok": False, "error": e.code,
+                              "detail": str(e)}, indent=2))
+        else:
+            print(f"error: {e.code}: {e}")
+        return 2
+    if args.json:
+        print(json.dumps({"ok": True, "latest": latest.to_dict(),
+                          "backups": [b.to_dict() for b in backups]}, indent=2))
+    else:
+        if not backups:
+            print("no backups found")
+        for b in backups:
+            mark = " (latest)" if b is latest or b.snapshot_id == latest.snapshot_id else ""
+            print(f"  {b.source_type} {b.snapshot_id} {b.timestamp}{mark}")
+    return 0
+
+
+def cmd_validate(args) -> int:
+    try:
+        cfg = configmod.load_config(args.config)
+    except BackupProofError as e:
+        if args.json:
+            print(json.dumps({"ok": False, "error": e.code,
+                              "detail": str(e)}, indent=2))
+        else:
+            print(f"error: {e.code}: {e}")
+        return 2
+    n = sum(len(v) for v in cfg["checks"].values())
+    if args.json:
+        print(json.dumps({"ok": True, "source": cfg["source"],
+                          "packs": sorted(cfg["checks"]),
+                          "check_count": n}, indent=2))
+    else:
+        print(f"config valid: source={cfg['source']['type']}, "
+              f"{n} check(s) across packs {sorted(cfg['checks'])}")
+    return 0
+
+
+PING_TIMEOUT_SECONDS = 10
+
+
+def cmd_run(args) -> int:
+    code = _run_verdict(args)
+    if getattr(args, "ping_url", None):
+        _ping(args.ping_url, code)
+    return code
+
+
+def _ping(url: str, code: int) -> None:
+    """healthchecks.io convention: GET URL on PASS, URL/fail on FAIL
+    or ERROR. A ping failure warns and never changes the exit code."""
+    import urllib.request
+
+    if code != 0:
+        url = url.rstrip("/") + "/fail"
+    try:
+        urllib.request.urlopen(url, timeout=PING_TIMEOUT_SECONDS).close()
+    except Exception as e:
+        print(f"warning: ping {url} failed: {type(e).__name__}: {e}",
+              file=sys.stderr)
+
+
+def _run_verdict(args) -> int:
+    try:
+        cfg = configmod.load_config(args.config)
+    except BackupProofError as e:
+        return _emit_error(None, "simulated", e, args)
+    source = cfg["source"]
+    try:
+        include = (configmod.checked_paths(cfg)
+                   if source.get("restore") == "checked-paths" else None)
+        runner, mode = _runner_for(source, include)
+        backups = runner.list_backups()
+        backup = discovery.latest(backups)
+    except BackupProofError as e:
+        return _emit_error(None, "simulated" if source["type"] == "fixture" else "real",
+                           e, args)
+    # Staleness gate: a PASS on an ancient "latest" backup proves an
+    # old backup, not a current one. Warn by default; --fail-on-stale
+    # refuses the run outright (before touching anything).
+    warnings: list[str] = []
+    max_age = getattr(args, "max_age_days", None)
+    if max_age is None:
+        max_age = cfg.get("max_age_days")
+    if max_age is not None:
+        age = _backup_age_days(backup)
+        if age is None:
+            warnings.append(
+                f"could not determine backup age (timestamp "
+                f"{backup.timestamp!r} unparseable); staleness not checked")
+        elif age > float(max_age):
+            msg = (f"latest backup is {age:.1f} days old "
+                   f"(max {max_age})")
+            if getattr(args, "fail_on_stale", False):
+                return _emit_error(backup, mode,
+                                   StaleBackupError(msg), args)
+            warnings.append(msg)
+    # Proxmox pack guard: a host cannot verify a VM's filesystem
+    # without guest access, so db/files packs can never verify a
+    # Proxmox VM from here. Fail fast instead of running a partial
+    # verdict that silently drops packs.
+    if source["type"] == "proxmox" and mode == "real":
+        unsupported = [p for p in ("db", "files") if cfg["checks"].get(p)]
+        if unsupported:
+            return _emit_error(
+                backup, mode,
+                UnsupportedPackError(
+                    f"packs {', '.join(unsupported)} cannot verify a "
+                    f"Proxmox VM's filesystem from the host — use web "
+                    f"checks with --probe-url, or drop those packs"),
+                args)
+    integrity = None
+    if getattr(args, "integrity", False):
+        try:
+            if not isinstance(runner, RealRunner):
+                raise configmod.ConfigError(
+                    "--integrity supports restic/borg sources only")
+            integrity = runner.check_integrity(args.read_data_subset,
+                                               args.verify_data)
+        except BackupProofError as e:
+            return _emit_error(backup, mode, e, args)
+    tmp = tempfile.TemporaryDirectory(prefix="backupproof-")
+    try:
+        try:
+            target = runner.restore_and_boot(
+                backup, Path(tmp.name), boot_timeout=args.boot_timeout,
+                probe_url=getattr(args, "probe_url", None))
+        except BackupProofError as e:
+            return _emit_error(backup, mode, e, args)
+        try:
+            smoke_target = smoke.Target(target.root, target.base_url,
+                                        _backup_datetime(backup))
+            results = smoke.run_smoke(cfg["checks"], smoke_target)
+            v = verdictmod.build_verdict(
+                backup, mode, results,
+                target.boot_evidence,
+                _restore_evidence(runner, target),
+                boot_kind=target.boot_kind,
+                boot_probed=target.boot_probed,
+                verified_against=_verified_against(
+                    source, mode, target.boot_kind,
+                    getattr(args, "probe_url", None)),
+                warnings=warnings)
+            v = replace(v, restore_partial=len(include or []),
+                        integrity=integrity,
+                        restore_seconds=target.restore_seconds)
+        finally:
+            target.close()
+    finally:
+        tmp.cleanup()
+    if args.report:
+        Path(args.report).write_text(verdictmod.render_json(v) + "\n")
+    print(verdictmod.render_json(v) if args.json else verdictmod.render_text(v))
+    return v.exit_code
+
+
+def _restore_evidence(runner, target) -> str:
+    text = _restore_evidence_base(runner, target)
+    if target.restore_seconds is not None:
+        text += f" in {target.restore_seconds:.1f}s"
+        if isinstance(runner, FixtureRunner):
+            text += " (simulated)"
+    return text
+
+
+def _restore_evidence_base(runner, target) -> str:
+    n_files = sum(1 for _ in target.root.rglob("*") if _.is_file())
+    if getattr(runner, "include", None):
+        return (f"partial ({len(runner.include)} paths) — only checked "
+                f"paths restored; the rest of the backup was not "
+                f"restore-tested; restored into {target.root} "
+                f"({n_files} files)")
+    if isinstance(runner, FixtureRunner):
+        return (f"SIMULATED restore into {target.root} ({n_files} files "
+                f"copied from fixture)")
+    return f"restored into {target.root} ({n_files} files)"
+
+
+def _emit_error(backup, mode, err: BackupProofError, args) -> int:
+    v = verdictmod.error_verdict(backup, mode, err.code, str(err))
+    if getattr(args, "report", None):
+        Path(args.report).write_text(verdictmod.render_json(v) + "\n")
+    print(verdictmod.render_json(v) if args.json else verdictmod.render_text(v))
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="backupproof",
+        description="Backup restore testing: restore the latest backup "
+                    "into a throwaway target, boot it, run smoke checks, "
+                    "report PASS or FAIL with proof.")
+    p.add_argument("--version", action="version",
+                   version=f"backupproof {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def json_arg(x):
+        x.add_argument("--json", action="store_true",
+                       help="machine-readable JSON output")
+
+    p_run = sub.add_parser("run", help="run the restore/boot/smoke verdict")
+    p_run.add_argument("--config", required=True, help="config JSON file")
+    p_run.add_argument("--boot-timeout", type=int, default=300,
+                       help="seconds to wait for boot (default: 300)")
+    p_run.add_argument("--probe-url",
+                       help="HTTP URL to poll for boot readiness (real runner)")
+    p_run.add_argument("--max-age-days", type=float, default=None,
+                       help="warn when the latest backup is older than "
+                            "this (overrides config max_age_days)")
+    p_run.add_argument("--fail-on-stale", action="store_true",
+                       help="refuse the run when the latest backup "
+                            "exceeds --max-age-days (default: warn only)")
+    p_run.add_argument("--integrity", action="store_true",
+                       help="run restic check / borg check "
+                            "--repository-only before restoring")
+    p_run.add_argument("--read-data-subset", metavar="PCT",
+                       help="with --integrity on restic: also read this "
+                            "subset of pack data (e.g. 5%%)")
+    p_run.add_argument("--verify-data", action="store_true",
+                       help="with --integrity on borg: borg check "
+                            "--verify-data instead of --repository-only")
+    p_run.add_argument("--ping-url",
+                       help="after the verdict, GET this URL on PASS or "
+                            "URL/fail on FAIL/ERROR (healthchecks.io "
+                            "convention); off unless given")
+    p_run.add_argument("--report", help="write the proof report JSON to this file")
+    json_arg(p_run)
+    p_run.set_defaults(func=cmd_run)
+
+    p_list = sub.add_parser("list", help="list backups, newest first")
+    p_list.add_argument("--config", help="config JSON file (source is read from it)")
+    p_list.add_argument("--source-type", choices=list(discovery.SUPPORTED),
+                        default="fixture")
+    p_list.add_argument("--repo", help="restic/borg repository path")
+    p_list.add_argument("--dump-dir", help="proxmox dump directory")
+    p_list.add_argument("--fixture-dir", help="fixture directory")
+    json_arg(p_list)
+    p_list.set_defaults(func=cmd_list)
+
+    p_val = sub.add_parser("validate", help="validate a config file")
+    p_val.add_argument("--config", required=True, help="config JSON file")
+    json_arg(p_val)
+    p_val.set_defaults(func=cmd_validate)
+
+    p_init = sub.add_parser("init", help="write example config + fixture "
+                            "files (try: backupproof run --config "
+                            "<dir>/config.json)")
+    p_init.add_argument("--output", default="backupproof-examples",
+                        help="directory to write into (default: "
+                             "backupproof-examples)")
+    p_init.set_defaults(func=cmd_init)
+    return p
+
+
+def cmd_init(args) -> int:
+    """Write a runnable fixture example: config + fixture tree with
+    a real SQLite DB and a webroot. The files-check sha256 is
+    computed from the written app.conf, so the example PASSES."""
+    import hashlib
+    import sqlite3
+
+    out = Path(args.output)
+    fixture = out / "fixture"
+    restored = fixture / "restored"
+    webroot = restored / "webroot"
+    webroot.mkdir(parents=True, exist_ok=True)
+    app_conf = "port=8080\nmode=production\n"
+    # bytes, not text: Windows newline translation would break the sha256
+    (restored / "app.conf").write_bytes(app_conf.encode("utf-8"))
+    (webroot / "index.html").write_text(
+        "<html><body>Welcome to the restored app</body></html>\n",
+        encoding="utf-8")
+    db_path = restored / "app.db"
+    if db_path.exists():
+        db_path.unlink()
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.execute("CREATE TABLE users (name TEXT)")
+        conn.execute("INSERT INTO users VALUES ('alice')")
+        conn.commit()
+    finally:
+        conn.close()
+    (fixture / "backups.json").write_text(json.dumps(
+        [{"id": "snap-example", "time": "2026-10-28T03:00:00Z",
+          "size": 1234}], indent=2) + "\n", encoding="utf-8")
+    (fixture / "boot.json").write_text(json.dumps(
+        {"ok": True, "seconds": 0, "webroot": "webroot"},
+        indent=2) + "\n", encoding="utf-8")
+    sha = hashlib.sha256(app_conf.encode("utf-8")).hexdigest()
+    config = {
+        # Absolute fixture dir so the example runs from any cwd.
+        "source": {"type": "fixture", "dir": str(fixture.resolve())},
+        "checks": {
+            "web": [{"name": "homepage", "path": "/index.html",
+                     "expect_status": 200, "expect_contains": "Welcome"}],
+            "db": [{"name": "users", "db_file": "app.db",
+                    "query": "SELECT name FROM users",
+                    "expect_rows_min": 1}],
+            "files": [{"name": "config", "path": "app.conf",
+                       "sha256": sha}],
+        },
+    }
+    (out / "config.json").write_text(json.dumps(config, indent=2) + "\n",
+                                     encoding="utf-8")
+    print(f"wrote {out / 'config.json'} + {fixture}/")
+    print(f"try: backupproof run --config {out / 'config.json'}")
+    return 0
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

backupproof/config.py

@@ -0,0 +1,121 @@
+"""Config loading and validation.
+
+Config is a JSON file (stdlib only, no YAML dependency):
+
+  {
+    "source": {"type": "restic", "repo": "/srv/backups"},
+    "checks": {
+      "web":   [{"name": "homepage", "path": "/",
+                 "expect_status": 200, "expect_contains": "Welcome"}],
+      "db":    [{"name": "users table", "db_file": "app.db",
+                 "query": "SELECT count(*) FROM users",
+                 "expect_rows_min": 1}],
+      "files": [{"name": "config", "path": "etc/app.conf",
+                 "sha256": "<hex>", "size_min": 10}]
+    }
+  }
+
+For fixture runs the source is {"type": "fixture", "dir": "<dir>"}.
+Validation is strict: unknown packs, unknown check keys, and empty
+check sets are CONFIG_ERROR, because a run with no checks to run
+must never report PASS.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .discovery import SUPPORTED
+from .errors import ConfigError
+
+PACKS = ("web", "db", "files")
+WEB_KEYS = {"name", "path", "expect_status", "expect_contains", "url"}
+DB_KEYS = {"name", "db_file", "query", "expect_contains", "expect_rows_min",
+           "command"}
+FILE_KEYS = {"name", "path", "sha256", "size_min", "size_max", "size_exact",
+             "max_age_days", "mode", "owner"}
+
+
+def load_config(path: str | Path) -> dict:
+    p = Path(path)
+    if not p.is_file():
+        raise ConfigError(f"config file not found: {path}")
+    try:
+        data = json.loads(p.read_text())
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"config is not valid JSON: {e}")
+    return validate_config(data)
+
+
+def validate_config(data: dict) -> dict:
+    if not isinstance(data, dict):
+        raise ConfigError("config must be a JSON object")
+    source = data.get("source")
+    if not isinstance(source, dict) or source.get("type") not in SUPPORTED:
+        raise ConfigError(f"source.type must be one of {list(SUPPORTED)}")
+    if source["type"] in ("restic", "borg") and not source.get("repo"):
+        raise ConfigError(f"{source['type']} source requires 'repo'")
+    if source["type"] == "proxmox" and not source.get("dump_dir"):
+        raise ConfigError("proxmox source requires 'dump_dir'")
+    if source["type"] == "fixture" and not source.get("dir"):
+        raise ConfigError("fixture source requires 'dir'")
+    max_age = data.get("max_age_days")
+    if max_age is not None:
+        if not isinstance(max_age, (int, float)) \
+                or isinstance(max_age, bool) or max_age <= 0:
+            raise ConfigError("max_age_days must be a positive number")
+    checks = data.get("checks")
+    if not isinstance(checks, dict) or not checks:
+        raise ConfigError("checks must be a non-empty object "
+                          "(at least one of web/db/files)")
+    for pack, items in checks.items():
+        if pack not in PACKS:
+            raise ConfigError(f"unknown smoke pack: {pack!r} "
+                              f"(expected one of {list(PACKS)})")
+        if not isinstance(items, list) or not items:
+            raise ConfigError(f"pack {pack!r} must be a non-empty list")
+        allowed = {"web": WEB_KEYS, "db": DB_KEYS, "files": FILE_KEYS}[pack]
+        for item in items:
+            if not isinstance(item, dict) or not item.get("name"):
+                raise ConfigError(f"pack {pack!r}: each check needs a 'name'")
+            unknown = set(item) - allowed
+            if unknown:
+                raise ConfigError(f"pack {pack!r} check {item['name']!r}: "
+                                  f"unknown keys {sorted(unknown)}")
+            if pack == "web" and "path" not in item and "url" not in item:
+                raise ConfigError(f"web check {item['name']!r} needs 'path' or 'url'")
+            if pack == "db" and "query" not in item and "command" not in item:
+                raise ConfigError(f"db check {item['name']!r} needs 'query' or 'command'")
+            if pack == "db" and "query" in item and "db_file" not in item:
+                raise ConfigError(f"db check {item['name']!r} needs 'db_file' with 'query'")
+            if pack == "files" and "path" not in item:
+                raise ConfigError(f"files check {item['name']!r} needs 'path'")
+            if pack == "files" and "mode" in item:
+                try:
+                    int(str(item["mode"]), 8)
+                except ValueError:
+                    raise ConfigError(f"files check {item['name']!r}: mode "
+                                      f"must be an octal string like '0640'")
+    restore = source.get("restore", "full")
+    if restore not in ("full", "checked-paths"):
+        raise ConfigError("source.restore must be 'full' or 'checked-paths'")
+    if restore == "checked-paths":
+        if source["type"] not in ("restic", "borg"):
+            raise ConfigError("restore 'checked-paths' is restic/borg only")
+        if not checked_paths(data):
+            raise ConfigError("restore 'checked-paths' needs at least one "
+                              "path-bearing check (files path, db db_file) "
+                              "or serve_dir")
+    return data
+
+
+def checked_paths(cfg: dict) -> list[str]:
+    """Restored-tree paths the checks read: files paths, db files,
+    serve_dir. Web URLs and db commands name no restorable path."""
+    checks = cfg["checks"]
+    paths = [c["path"] for c in checks.get("files", [])]
+    paths += [c["db_file"] for c in checks.get("db", []) if "db_file" in c]
+    if cfg["source"].get("serve_dir"):
+        paths.append(cfg["source"]["serve_dir"])
+    return sorted({p.strip("/") for p in paths})