umbermark-cli 1.0.0__py3-none-any.whl

umbermark/core/branding.py

@@ -0,0 +1,71 @@
+"""White-label branding and client links (UMBR-66; Agency).
+
+The brand (name, accent colour, optional PNG logo) goes on the owner PDF and on client links. The logo is checked
+here before it is stored: PNG signature, a well-formed IHDR, at most MAX_LOGO_BYTES and MAX_LOGO_SIDE pixels a side.
+Only PNG is accepted (no SVG: it can carry script). It is served inline as a data: URI, never fetched from a URL, so
+the PDF renderer makes no outbound request for it.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+import secrets
+import struct
+
+MAX_LOGO_BYTES = 100_000
+MAX_LOGO_SIDE = 1024
+NAME_MAX = 60
+DEFAULT_ACCENT = "#3b82f6"
+ACCENT_RE = re.compile(r"^#[0-9a-fA-F]{6}$")
+LINK_PREFIX = "umk_cl_"
+_PNG_SIG = b"\x89PNG\r\n\x1a\n"
+
+
+class BrandError(ValueError):
+    pass
+
+
+def check_png(data: bytes) -> tuple[int, int]:
+    """(width, height) of a valid PNG within the limits; BrandError otherwise."""
+    if not data:
+        raise BrandError("Choose a PNG file")
+    if len(data) > MAX_LOGO_BYTES:
+        raise BrandError(f"The logo must be at most {MAX_LOGO_BYTES // 1000} KB")
+    if len(data) < 33 or data[:8] != _PNG_SIG or data[12:16] != b"IHDR":
+        raise BrandError("The logo must be a PNG image")
+    w, h = struct.unpack(">II", data[16:24])
+    if not (0 < w <= MAX_LOGO_SIDE and 0 < h <= MAX_LOGO_SIDE):
+        raise BrandError(f"The logo must be at most {MAX_LOGO_SIDE} x {MAX_LOGO_SIDE} pixels")
+    return w, h
+
+
+def data_uri(png: bytes | None) -> str | None:
+    return ("data:image/png;base64," + base64.b64encode(bytes(png)).decode()) if png else None
+
+
+def clean_name(name: str) -> str:
+    return re.sub(r"\s+", " ", name or "").strip()[:NAME_MAX]
+
+
+def clean_accent(accent: str) -> str:
+    a = (accent or "").strip()
+    if not ACCENT_RE.match(a):
+        raise BrandError("The colour must look like #1a2b3c")
+    return a.lower()
+
+
+def new_link_token() -> tuple[str, str]:
+    t = LINK_PREFIX + secrets.token_urlsafe(24)
+    return t, hashlib.sha256(t.encode()).hexdigest()
+
+
+def hash_link_token(t: str) -> str:
+    return hashlib.sha256(t.encode()).hexdigest()
+
+
+def for_render(row) -> dict | None:
+    """The brand dict templates use ({name, accent, logo}), or None."""
+    if row is None:
+        return None
+    return {"name": row["name"], "accent": row["accent"], "logo": data_uri(row["logo_png"])}

umbermark/core/capture.py

@@ -0,0 +1,228 @@
+"""Tier-2 'run & upload' support.
+
+A client who won't grant SSH access can instead run a small, auditable,
+read-only script on their own box and upload its output. That output is a
+*command bundle* — a map of the exact shell commands the checks issue to the
+stdout/exit_code they produced. Replaying the bundle through the same checks
+(`engine.run_scan`) yields the identical report a live SSH scan would, with
+zero access granted.
+
+The command set is enumerated from the checks themselves (see
+`enumerate_commands`) so the generated script can never drift from the catalog.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+
+from umbermark.core.ssh import CommandResult, FakeRunner
+
+
+def _stdout_of(rec: dict[str, Any]) -> str:
+    """Resolve a captured command's stdout.
+
+    The generated script base64-encodes stdout (``stdout_b64``) so arbitrary
+    output survives JSON transport without escaping hazards; hand-written
+    bundles (and tests) may use a plain ``stdout`` instead.
+    """
+    if "stdout_b64" in rec:
+        try:
+            return base64.b64decode(rec["stdout_b64"]).decode("utf-8", "replace")
+        except (binascii.Error, ValueError):
+            return ""
+    return rec.get("stdout", "")
+
+
+class CollectingRunner:
+    """A runner that records every requested command and always reports failure.
+
+    Returning a failure result (exit 127) forces each check down its full
+    fallback chain, so a single pass over the catalog requests the *superset* of
+    commands any check could issue. Used only to enumerate the command set for
+    the capture script — it never executes anything.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, bool]] = []
+
+    def run(self, command: str, sudo: bool = False, timeout: float = 30.0) -> CommandResult:
+        self.calls.append((command, bool(sudo)))
+        return CommandResult(stdout="", stderr="", exit_code=127)
+
+
+def enumerate_commands() -> list[dict[str, Any]]:
+    """Enumerate every shell command a full scan issues, deduplicated, in order.
+
+    Drives directly off the live check catalog + platform detector, so the
+    generated capture script can never drift from what the checks actually run.
+    Each entry is ``{"command": str, "sudo": bool}`` where ``sudo`` is true if
+    *any* check issues that command with sudo.
+    """
+    from umbermark.checks import ALL_CHECKS
+    from umbermark.core.platform import detect_platform
+
+    collector = CollectingRunner()
+    detect_platform(collector)
+    for check in ALL_CHECKS:
+        try:
+            check.run(collector)
+        except Exception:
+            # A check raising under all-failure input still recorded its commands.
+            pass
+
+    ordered: dict[str, dict[str, Any]] = {}
+    for command, sudo in collector.calls:
+        if command in ordered:
+            ordered[command]["sudo"] = ordered[command]["sudo"] or sudo
+        else:
+            ordered[command] = {"command": command, "sudo": sudo}
+    return list(ordered.values())
+
+
+def build_replay_runner(bundle: dict[str, Any]) -> FakeRunner:
+    """Build a CommandRunner that serves captured output from a command bundle.
+
+    Bundle shape: ``{"commands": {"<bare cmd>": {"stdout": str, "exit_code": int,
+    "stderr": str?}}}``. Commands absent from the bundle resolve to a failure
+    result (exit 127), so the corresponding check degrades to SKIP — exactly as
+    `FakeRunner` does for an unregistered command.
+    """
+    commands = bundle.get("commands", {}) or {}
+    responses: dict[str, CommandResult] = {}
+    for cmd, rec in commands.items():
+        responses[cmd] = CommandResult(
+            stdout=_stdout_of(rec),
+            stderr=rec.get("stderr", ""),
+            exit_code=int(rec.get("exit_code", 0)),
+        )
+    return FakeRunner(responses=responses)
+
+
+def _sh_squote(s: str) -> str:
+    """POSIX single-quote a string for safe embedding as one shell word."""
+    return "'" + s.replace("'", "'\\''") + "'"
+
+
+_SCRIPT_TEMPLATE = """\
+#!/usr/bin/env bash
+# =============================================================================
+# Umbermark read-only scan collector  --  REVIEW THIS SCRIPT BEFORE RUNNING.
+#
+# It runs ONLY the read-only diagnostic commands listed below (each passed to
+# `_run`) and writes a JSON bundle of their output to stdout. It changes NOTHING
+# on this host: no installs, no config edits (the only write is a temp file
+# holding your bundle, and only if an upload fails). Upload the bundle to
+# Umbermark to get your hardening score -- we never touch your server.
+#
+# Run with sudo (or as root) for full coverage of privileged checks:
+#     sudo bash umbermark-collect.sh
+# =============================================================================
+set -u
+TARGET=${1:-@@TARGET@@}
+
+_jstr() { printf '"%s"' "$(printf '%s' "$1" | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g')"; }
+_run() {  # _run <command-string> <needs_sudo:0|1>
+  cmd="$1"; need="$2"
+  if [ "$need" = "1" ] && [ "$(id -u)" != "0" ]; then
+    out="$(sudo -n sh -c "$cmd" 2>/dev/null)"; rc=$?
+  else
+    out="$(sh -c "$cmd" 2>/dev/null)"; rc=$?
+  fi
+  printf '%s%s:{"exit_code":%s,"stdout_b64":"%s"}' \\
+    "$SEP" "$(_jstr "$cmd")" "$rc" "$(printf '%s' "$out" | base64 | tr -d '\\n')"
+  SEP=','
+}
+
+@@PROGRESS@@
+BUNDLE="$(
+  printf '{"schema_version":1,"target":%s,"commands":{' "$(_jstr "$TARGET")"
+  SEP=''
+@@RUNS@@
+  printf '}}'
+)"
+@@OUTPUT@@"""
+
+# Autoupload tail: POST the bundle, print the server's plain-text summary
+# (score/band + share URL) as the final lines. bash + curl + coreutils only.
+# `-w` appends the HTTP status after the body; curl exits non-zero on network
+# failure, in which case the status is 000. Bundle goes via stdin (`@-`) so a
+# large bundle can't hit the argv size limit.
+_AUTOUPLOAD_TEMPLATE = r"""RESP="$(printf '%s' "$BUNDLE" | curl -sS -X POST \
+  -H "Content-Type: application/json" -H "Accept: text/plain"@@AUTH@@ \
+  --data-binary @- -w '\n%{http_code}' @@URL@@ 2>&1)"
+CURL_RC=$?
+CODE="${RESP##*$'\n'}"
+BODY="${RESP%$'\n'*}"
+case "$CODE" in 2??) OK=1 ;; *) OK=0 ;; esac
+if [ "$CURL_RC" -eq 0 ] && [ "$OK" = "1" ]; then
+  printf '%s\n' "$BODY"
+elif [ "$CURL_RC" -eq 0 ] && [ "$CODE" = "429" ]; then
+  echo "[umbermark] $BODY" >&2
+  exit 1
+else
+  [ "$CURL_RC" -ne 0 ] && CODE="000 (network error: $BODY)"
+  echo "[umbermark] ERROR: upload failed, HTTP status $CODE" >&2
+  FALLBACK="$(mktemp 2>/dev/null || echo /tmp/umbermark-bundle.json)"
+  printf '%s\n' "$BUNDLE" > "$FALLBACK" 2>/dev/null
+  echo "[umbermark] Your bundle was saved to $FALLBACK" >&2
+  echo "[umbermark] Paste its contents at the upload page to get your report manually." >&2
+  exit 1
+fi
+"""
+
+
+def generate_capture_script(target: str | None = None, upload_url: str | None = None,
+                            header_file: str | None = None) -> str:
+    """Generate the auditable, read-only bash collector for Tier-2 'run & upload'.
+
+    The script runs exactly the commands `enumerate_commands` reports (so it
+    never drifts from the catalog), base64-encodes each stdout for escaping-safe
+    JSON transport. Without ``upload_url`` it prints the bundle to stdout (for
+    ``> file`` usage). With ``upload_url`` it does NOT print the bundle; it POSTs
+    it and prints the score, band and share URL instead (bundle is saved to a
+    temp file only if the upload fails).
+    """
+    commands = enumerate_commands()
+    runs = "\n".join(
+        "  _run {cmd} {sudo}".format(cmd=_sh_squote(c["command"]), sudo=1 if c["sudo"] else 0)
+        for c in commands
+    )
+    if upload_url:
+        # The announced check count is len(ALL_CHECKS): every check yields exactly
+        # one result row (PASS/WARN/FAIL/SKIP), so it equals the report's tally.
+        # Commands are a separate, larger number (checks share/fallback commands).
+        from umbermark.checks import ALL_CHECKS
+
+        progress = (
+            f'echo "[umbermark] Running {len(ALL_CHECKS)} read-only checks '
+            f'({len(commands)} commands)..." >&2'
+        )
+        # UMBR-66 check-ins: curl reads the Authorization header from a root-only file (-H @file), so the
+        # token never appears in a process list or in this script.
+        auth = f" -H @{_sh_squote(header_file)}" if header_file else ""
+        output = _AUTOUPLOAD_TEMPLATE.replace("@@URL@@", _sh_squote(upload_url)).replace("@@AUTH@@", auth)
+    else:
+        progress = ""
+        output = "printf '%s\\n' \"$BUNDLE\"\n"
+    return (
+        _SCRIPT_TEMPLATE
+        .replace("@@TARGET@@", _sh_squote(target or "uploaded"))
+        .replace("@@RUNS@@", runs)
+        .replace("@@PROGRESS@@", progress)
+        .replace("@@OUTPUT@@", output)
+    )
+
+
+def scan_from_bundle(bundle: dict[str, Any]):
+    """Run the full check catalog against a captured command bundle.
+
+    Returns the same `engine.ScanReport` a live SSH scan would — the bundle
+    simply stands in for the live runner. ``bundle["target"]`` labels the report.
+    """
+    from umbermark.checks import ALL_CHECKS
+    from umbermark.core.engine import run_scan
+
+    runner = build_replay_runner(bundle)
+    target = bundle.get("target") or "uploaded"
+    return run_scan(target, runner, ALL_CHECKS)

umbermark/core/check.py

@@ -0,0 +1,82 @@
+"""Check abstractions — base class, Finding dataclass, severity/verdict enums."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from umbermark.core.ssh import CommandRunner
+
+
+class Severity(Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class Verdict(Enum):
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+    SKIP = "skip"
+
+
+@dataclass
+class Finding:
+    check_id: str
+    title: str
+    category: str
+    severity: Severity
+    weight: int
+    verdict: Verdict
+    evidence: str = ""
+    remediation: str = ""
+    skip_reason: str = ""
+
+
+class Check(ABC):
+    id: str = ""
+    title: str = ""
+    category: str = ""
+    severity: Severity = Severity.MEDIUM
+    weight: int = 5
+    remediation: str = ""
+    # Distro families this check applies to. Empty tuple means universal.
+    # Values are 'debian' | 'rhel' | etc, matching PlatformFacts.distro_family.
+    applicable_distros: tuple[str, ...] = ()
+
+    @abstractmethod
+    def run(self, runner: "CommandRunner") -> Finding:
+        ...
+
+    def applies_to(self, distro_family: str) -> bool:
+        if not self.applicable_distros:
+            return True
+        return distro_family in self.applicable_distros
+
+    def _finding(
+        self,
+        verdict: Verdict,
+        evidence: str = "",
+        skip_reason: str = "",
+        severity: Severity | None = None,
+        weight: int | None = None,
+        remediation: str | None = None,
+    ) -> Finding:
+        """Build a Finding. ``severity`` / ``weight`` / ``remediation`` override the
+        class defaults for this finding only (exposure-aware checks scale them)."""
+        rem = self.remediation if remediation is None else remediation
+        return Finding(
+            check_id=self.id,
+            title=self.title,
+            category=self.category,
+            severity=self.severity if severity is None else severity,
+            weight=self.weight if weight is None else weight,
+            verdict=verdict,
+            evidence=evidence,
+            remediation=rem if verdict in (Verdict.FAIL, Verdict.WARN) else "",
+            skip_reason=skip_reason,
+        )

umbermark/core/checkin.py

@@ -0,0 +1,89 @@
+"""Scheduled check-ins for run-and-upload hosts (UMBR-66).
+
+A check-in server is a saved server with no SSH key. A cron job on the host runs the same read-only collector as
+the one-off upload and posts the bundle to POST /api/checkin with a per-server push token. Umbermark never connects
+to the host. If no check-in arrives within the expected gap plus GRACE, the owner is alerted once per gap.
+
+Token: `umk_ci_` + 32 random bytes (urlsafe). Only its SHA-256 is stored; it is shown once when the server is added
+or the token is rotated. On the host it lives in a root-only header file read by curl (`-H @file`), so it never
+appears in a process list.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import secrets
+
+TOKEN_PREFIX = "umk_ci_"
+HEADER_FILE = "/etc/umbermark/checkin.header"
+SCRIPT_PATH = "/usr/local/sbin/umbermark-checkin"
+CRON_FILE = "/etc/cron.d/umbermark-checkin"
+GRACE = dt.timedelta(hours=6)
+# A check-in arriving sooner than this share of the plan's minimum re-scan gap is refused (429), so a check-in
+# cannot be used to re-scan faster than the plan allows. 0.8 leaves room for cron jitter and clock drift.
+MIN_GAP_SHARE = 0.8
+
+
+def new_token() -> tuple[str, str]:
+    """(plaintext token, sha256 hex) for a new check-in server or a rotation."""
+    t = TOKEN_PREFIX + secrets.token_urlsafe(32)
+    return t, hash_token(t)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def _parse(iso: str | None) -> dt.datetime | None:
+    if not iso:
+        return None
+    try:
+        v = dt.datetime.fromisoformat(iso)
+    except ValueError:
+        return None
+    return v if v.tzinfo else v.replace(tzinfo=dt.UTC)
+
+
+def due_at(created_at: str, last_checkin_at: str | None, days: int) -> dt.datetime:
+    """When the next check-in is expected (late after this plus GRACE)."""
+    base = _parse(last_checkin_at) or _parse(created_at) or dt.datetime.now(dt.UTC)
+    return base + dt.timedelta(days=days)
+
+
+def is_missed(created_at: str, last_checkin_at: str | None, missed_alert_at: str | None, days: int,
+              now: dt.datetime | None = None) -> bool:
+    """True when the check-in is overdue by more than GRACE and no alert went out for this gap yet."""
+    now = now or dt.datetime.now(dt.UTC)
+    if now <= due_at(created_at, last_checkin_at, days) + GRACE:
+        return False
+    sent = _parse(missed_alert_at)
+    last = _parse(last_checkin_at) or _parse(created_at)
+    return sent is None or (last is not None and sent < last)
+
+
+def too_soon(last_checkin_at: str | None, min_rescan_days: int | None, now: dt.datetime | None = None) -> int:
+    """Seconds the caller must wait before the next check-in is accepted (0 = accept now)."""
+    last = _parse(last_checkin_at)
+    if last is None or not min_rescan_days:
+        return 0
+    now = now or dt.datetime.now(dt.UTC)
+    ready = last + dt.timedelta(days=min_rescan_days * MIN_GAP_SHARE)
+    return max(0, int((ready - now).total_seconds()))
+
+
+def cron_line(days: int, minute: int, hour: int) -> str:
+    """The /etc/cron.d line for the interval: daily, weekly (Mondays) or monthly (the 1st)."""
+    when = {1: f"{minute} {hour} * * *", 7: f"{minute} {hour} * * 1", 30: f"{minute} {hour} 1 * *"}[days]
+    return f"{when} root {SCRIPT_PATH} >/dev/null 2>&1"
+
+
+def setup_commands(base_url: str, token: str, days: int, seed: int) -> str:
+    """Copy-paste setup for the host (run as a sudo-capable user). `seed` spreads cron times across servers."""
+    minute, hour = seed % 60, (seed // 60) % 24
+    return "\n".join([
+        f"sudo install -d -m 700 {HEADER_FILE.rsplit('/', 1)[0]}",
+        f"echo 'Authorization: Bearer {token}' | sudo tee {HEADER_FILE} >/dev/null && sudo chmod 600 {HEADER_FILE}",
+        f"sudo curl -fsSo {SCRIPT_PATH} {base_url}/scan/checkin-script && sudo chmod 700 {SCRIPT_PATH}",
+        f"sudo {SCRIPT_PATH}   # first check-in now; read the script first if you like: less {SCRIPT_PATH}",
+        f"echo '{cron_line(days, minute, hour)}' | sudo tee {CRON_FILE} >/dev/null",
+    ])

umbermark/core/crypto.py

@@ -0,0 +1,15 @@
+"""Indexed, non-secret peppered SHA-256 hashes.
+
+Used for `abuse_log.ip_hash` and `target_host_hash` — deterministic enough to
+index for rate-limit lookups, but not reversible to the source value without
+the operator-only pepper. Not for password storage (use argon2 there).
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def hash_with_pepper(value: str, pepper: str) -> str:
+    if not pepper:
+        raise ValueError("pepper is required and must be non-empty")
+    return hashlib.sha256(f"{pepper}::{value}".encode("utf-8")).hexdigest()

umbermark/core/duration.py

@@ -0,0 +1,45 @@
+"""Human-readable link lifetime, derived from ANONYMOUS_REPORT_TTL_SECONDS.
+
+User-facing copy must follow the configured TTL, not a hard-coded number.
+"""
+from __future__ import annotations
+
+from umbermark.core.settings import (
+    DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS,
+    DEFAULT_SESSION_TTL_SECONDS,
+)
+
+
+def humanize_ttl(seconds: int, adjective: bool = False) -> str:
+    """Render a TTL in whole days when it divides evenly, else hours/minutes.
+
+    2592000 -> "30 days", 86400 -> "1 day", 3600 -> "1 hour".
+    With adjective=True the unit is hyphenated and singular, for use before a
+    noun: 2592000 -> "30-day" ("a 30-day shareable URL").
+    """
+    seconds = int(seconds)
+    for unit_seconds, name in ((86_400, "day"), (3_600, "hour"), (60, "minute")):
+        if seconds >= unit_seconds and seconds % unit_seconds == 0:
+            n = seconds // unit_seconds
+            if adjective:
+                return f"{n}-{name}"
+            return f"{n} {name}{'' if n == 1 else 's'}"
+    if adjective:
+        return f"{seconds}-second"
+    return f"{seconds} second{'' if seconds == 1 else 's'}"
+
+
+def link_lifetime(settings, adjective: bool = False) -> str:
+    """Lifetime text for the app's settings (30 days when settings are absent)."""
+    ttl = getattr(settings, "anonymous_report_ttl_seconds", None)
+    if ttl is None:
+        ttl = DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS
+    return humanize_ttl(ttl, adjective=adjective)
+
+
+def session_lifetime(settings) -> str:
+    """Sign-in session lifetime text (30 days when settings are absent)."""
+    ttl = getattr(settings, "session_ttl_seconds", None)
+    if ttl is None:
+        ttl = DEFAULT_SESSION_TTL_SECONDS
+    return humanize_ttl(ttl)

umbermark/core/engine.py

@@ -0,0 +1,74 @@
+"""Scan orchestrator — detects platform, runs checks, catches errors."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Iterable
+
+from umbermark.core.check import Check, Finding, Verdict
+from umbermark.core.platform import PlatformFacts, detect_platform
+from umbermark.core.scoring import ScoreResult, score
+from umbermark.core.ssh import CommandRunner
+
+
+@dataclass
+class ScanReport:
+    target: str
+    started_at: str
+    finished_at: str
+    findings: list[Finding]
+    result: ScoreResult
+    platform_facts: PlatformFacts = field(default_factory=PlatformFacts)
+
+
+def run_scan(
+    target: str,
+    runner: CommandRunner,
+    checks: Iterable[Check],
+    detect: bool = True,
+) -> ScanReport:
+    started = datetime.now(timezone.utc).isoformat()
+    platform_facts = detect_platform(runner) if detect else PlatformFacts()
+    findings: list[Finding] = []
+    for c in checks:
+        # Skip checks that don't apply to this distro family — but only if
+        # we successfully detected one. Unknown family means "best effort".
+        if (
+            platform_facts.distro_family != "unknown"
+            and not c.applies_to(platform_facts.distro_family)
+        ):
+            findings.append(
+                Finding(
+                    check_id=c.id,
+                    title=c.title,
+                    category=c.category,
+                    severity=c.severity,
+                    weight=c.weight,
+                    verdict=Verdict.SKIP,
+                    skip_reason=f"check not applicable on distro_family={platform_facts.distro_family}",
+                )
+            )
+            continue
+        try:
+            findings.append(c.run(runner))
+        except Exception as exc:
+            findings.append(
+                Finding(
+                    check_id=c.id,
+                    title=c.title,
+                    category=c.category,
+                    severity=c.severity,
+                    weight=c.weight,
+                    verdict=Verdict.SKIP,
+                    skip_reason=f"check raised: {exc!r}",
+                )
+            )
+    finished = datetime.now(timezone.utc).isoformat()
+    return ScanReport(
+        target=target,
+        started_at=started,
+        finished_at=finished,
+        findings=findings,
+        result=score(findings),
+        platform_facts=platform_facts,
+    )