umbermark-cli 1.0.0__py3-none-any.whl

umbermark/core/tiers.py

@@ -0,0 +1,138 @@
+"""The one tier table (UMBR-19): what each plan allows. Every limit in Umbermark reads from here.
+
+Prices are display-only (what a buyer pays is set at Starship / the payment provider). Starship's catalog.yaml
+carries the same numbers for the three paid plans; tests/unit/test_tiers.py pins both to the operator-approved table.
+
+Limits
+  max_servers      saved servers the plan may hold (0 = none can be saved).
+  min_rescan_days  shortest allowed gap between scheduled re-scans (None = no scheduled re-scans at all).
+
+Enterprise is a contact-only plan sized by hand; it is not a tier here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Tier:
+    name: str
+    price_cents: int
+    max_servers: int
+    min_rescan_days: int | None
+
+    @property
+    def label(self) -> str:
+        return self.name.capitalize()
+
+
+TIERS: dict[str, Tier] = {
+    "free": Tier("free", 0, 0, None),
+    "solo": Tier("solo", 900, 7, 7),
+    "pro": Tier("pro", 1900, 15, 1),
+    "agency": Tier("agency", 4900, 50, 1),
+}
+PAID_TIERS: tuple[str, ...] = ("solo", "pro", "agency")
+RANK: dict[str, int] = {"free": 0, "solo": 1, "pro": 2, "agency": 3}  # best one wins
+
+# Schedule names the forms accept, and the gap each one means. "manual" has no gap.
+SCHEDULE_DAYS: dict[str, int] = {"daily": 1, "weekly": 7, "monthly": 30}
+SCHEDULES: tuple[str, ...] = ("manual", "daily", "weekly", "monthly")
+
+
+# UMBR-66: features beyond saved servers and re-scans, and the cheapest plan that includes each one.
+# The pricing page prints FEATURE_LABELS for every plan that has the feature, so only list what is built.
+FEATURES: dict[str, str] = {
+    "accepted_risk": "solo",
+    "checkin": "solo",
+    "subscriber_pdf": "solo",
+    "fleet": "pro",
+    "alert_channels": "pro",
+    "api": "pro",
+    "evidence_pack": "pro",
+    "remediation_bundle": "pro",
+    "white_label": "agency",
+}
+FEATURE_LABELS: dict[str, str] = {
+    "accepted_risk": "Accepted risks: mark a finding as accepted with a reason and an expiry; your score shows both",
+    "checkin": "Scheduled check-ins without SSH access: a cron job on your server uploads a scan; alert if one is missed",
+    "subscriber_pdf": "PDF download of every report in your account",
+    "fleet": "Fleet view: every server on one page, worst score first, with trend",
+    "alert_channels": "Score-drop alerts to your own webhook, Slack or Discord, as well as email",
+    "api": "Read API with scoped tokens: scores, history and reports as JSON or CSV, and start scans",
+    "evidence_pack": "Evidence pack per report: every finding with its CIS Controls v8 safeguards and accepted risks, as CSV and JSON",
+    "remediation_bundle": "Remediation bundle per server: one shell file with the fix steps for its open findings; nothing runs until you name a fix",
+    "white_label": "White-label: your name, logo and colour on PDFs and on live client links (read-only, revocable, one per client)",
+}
+
+
+def has_feature(tier: Tier, feature: str) -> bool:
+    """True when the tier includes `feature`. An unknown feature is never included (fail closed)."""
+    need = FEATURES.get(feature)
+    return need is not None and RANK.get(tier.name, 0) >= RANK[need]
+
+
+def plan_features(tier: Tier) -> list[str]:
+    """Pricing-card lines for the gated features this tier includes, in FEATURES order."""
+    return [FEATURE_LABELS[f] for f in FEATURES if has_feature(tier, f)]
+
+
+def feature_message(tier: Tier, feature: str) -> str:
+    """Why a gated page is not available on this plan, and which plan has it."""
+    need = TIERS[FEATURES[feature]].label
+    return f"This comes with the {need} plan and up. Your plan is {tier.label}."
+
+
+def tier_of(name: str | None) -> Tier:
+    """The tier for a stored name; anything unknown is treated as free (fail closed)."""
+    return TIERS.get(name or "free", TIERS["free"])
+
+
+def allowed_schedules(tier: Tier) -> list[str]:
+    """Schedule choices the tier may use, fastest first ("manual" is always allowed)."""
+    if tier.min_rescan_days is None:
+        return ["manual"]
+    ok = [s for s, d in SCHEDULE_DAYS.items() if d >= tier.min_rescan_days]
+    return ok + ["manual"]
+
+
+def schedule_allowed(tier: Tier, schedule: str | None) -> bool:
+    return (schedule or "manual") in allowed_schedules(tier)
+
+
+def fastest_schedule(tier: Tier) -> str | None:
+    """The fastest scheduled re-scan the tier may use (None when it may not schedule)."""
+    ok = allowed_schedules(tier)
+    return ok[0] if ok[0] != "manual" else None
+
+
+def server_limit_message(tier: Tier, count: int) -> str:
+    n = tier.max_servers
+    msg = f"Your {tier.label} plan allows {n} saved server{'' if n == 1 else 's'}; you have {count}."
+    if n == 0:
+        return msg + " Saved servers come with a paid plan; see /pricing."
+    return msg + " Delete one, or move to a bigger plan at /pricing."
+
+
+def paused_message(tier: Tier) -> str:
+    """Why a saved server over the plan's limit is paused, and the way back (UMBR-66)."""
+    if tier.max_servers == 0:
+        return (f"Paused: your {tier.label} plan has no saved servers. Nothing is deleted; "
+                "a paid plan resumes it.")
+    return (f"Paused: your {tier.label} plan allows {tier.max_servers} saved servers and this one is over the limit. "
+            "Nothing is deleted; delete another server or move to a bigger plan and it resumes.")
+
+
+def start_offer() -> str:
+    """The cheapest plan that can hold saved servers, as one phrase: '7 servers for $9/month'."""
+    t = TIERS[PAID_TIERS[0]]
+    return f"{t.max_servers} servers for ${t.price_cents // 100}/month"
+
+
+def schedule_message(tier: Tier, schedule: str) -> str:
+    fastest = fastest_schedule(tier)
+    if fastest is None:
+        return f"Scheduled re-scans come with a paid plan. Your {tier.label} plan is manual only; see /pricing."
+    choices = ", ".join(s for s in allowed_schedules(tier) if s != "manual")
+    return (f"Your {tier.label} plan can re-scan {fastest} at most, so {schedule} is not available. "
+            f"Choose {choices} or manual.")

umbermark/core/webhooks.py

@@ -0,0 +1,177 @@
+"""Outbound alert webhooks: URL validation, SSRF-safe delivery, message bodies (UMBR-66 alert channels).
+
+Three kinds of destination, all customer-configured:
+  webhook  any https URL; gets JSON, signed with HMAC-SHA256 (X-Umbermark-Signature: sha256=<hex>)
+  slack    https://hooks.slack.com/services/...      ({"text": ...})
+  discord  https://discord.com/api/webhooks/...      ({"content": ...}; discordapp.com accepted)
+
+SSRF rules (every send, not only on save):
+  * https only, port 443 only for generic webhooks, no credentials in the URL, no IP-literal hosts;
+  * the host must resolve and EVERY address must be public (core.external.ownership.resolve_public_ips refuses
+    loopback, RFC1918, CGNAT/tailnet, link-local/metadata, multicast and the rest);
+  * the TCP connection goes to the address that was checked (pinned), with SNI and certificate checks against
+    the hostname, so a DNS answer cannot change between the check and the connect;
+  * redirects are never followed (a 3xx counts as a failed delivery);
+  * short timeouts and a capped response read.
+The host's egress firewall (deploy/umk-egress.nft) blocks the same ranges for the app's uid as a second layer.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import http.client
+import json
+import socket
+import ssl
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+KINDS: tuple[str, ...] = ("webhook", "slack", "discord")
+KIND_LABELS = {"webhook": "Webhook (JSON)", "slack": "Slack", "discord": "Discord"}
+MAX_URL_LEN = 500
+TIMEOUT_SECONDS = 8
+_SLACK_HOSTS = {"hooks.slack.com"}
+_DISCORD_HOSTS = {"discord.com", "discordapp.com", "ptb.discord.com", "canary.discord.com"}
+
+
+class WebhookError(ValueError):
+    """The URL is not acceptable, or delivery was refused before any bytes were sent."""
+
+
+@dataclass(frozen=True, slots=True)
+class Target:
+    host: str
+    port: int
+    path: str  # path + query, as sent
+
+
+def validate(kind: str, url: str) -> Target:
+    """Shape checks only (no DNS). Raises WebhookError with a message fit for the form."""
+    if kind not in KINDS:
+        raise WebhookError("Choose webhook, Slack or Discord")
+    url = (url or "").strip()
+    if not url or len(url) > MAX_URL_LEN:
+        raise WebhookError(f"Paste the full https URL (at most {MAX_URL_LEN} characters)")
+    try:
+        u = urlsplit(url)
+        port = u.port or 443
+    except ValueError as exc:
+        raise WebhookError("That is not a valid URL") from exc
+    host = (u.hostname or "").lower().rstrip(".")
+    if u.scheme != "https" or not host:
+        raise WebhookError("The URL must start with https://")
+    if u.username or u.password:
+        raise WebhookError("The URL must not contain a user name or password")
+    if port != 443:
+        raise WebhookError("Only the standard https port (443) is allowed")
+    if _is_ip_literal(host):
+        raise WebhookError("Use a host name, not an IP address")
+    path = (u.path or "/") + (f"?{u.query}" if u.query else "")
+    if kind == "slack" and (host not in _SLACK_HOSTS or not u.path.startswith("/services/")):
+        raise WebhookError("A Slack incoming-webhook URL starts with https://hooks.slack.com/services/")
+    if kind == "discord" and (host not in _DISCORD_HOSTS or not u.path.startswith("/api/webhooks/")):
+        raise WebhookError("A Discord webhook URL starts with https://discord.com/api/webhooks/")
+    return Target(host, port, path)
+
+
+def masked(url: str) -> str:
+    """What the page shows: scheme, host and the last 4 characters (the rest of a Slack/Discord URL is a secret)."""
+    try:
+        u = urlsplit(url)
+        tail = url[-4:] if len(url) > 12 else ""
+        return f"https://{u.hostname}/…{tail}"
+    except ValueError:
+        return "(invalid URL)"
+
+
+def _is_ip_literal(host: str) -> bool:
+    import ipaddress
+
+    try:
+        ipaddress.ip_address(host.strip("[]"))
+        return True
+    except ValueError:
+        return False
+
+
+def _resolve(host: str) -> str:
+    """The first public address of `host`; WebhookError unless every address is public."""
+    from umbermark.core.external.ownership import BlockedTarget, resolve_public_ips
+
+    try:
+        return resolve_public_ips(host)[0]
+    except BlockedTarget as exc:
+        raise WebhookError("That host does not resolve to a public address") from exc
+
+
+class _PinnedHTTPS(http.client.HTTPSConnection):
+    """HTTPS to a fixed IP while SNI and the certificate check use the hostname."""
+
+    def __init__(self, host: str, ip: str, port: int, timeout: float):
+        super().__init__(host, port, timeout=timeout, context=ssl.create_default_context())
+        self._ip = ip
+
+    def connect(self):  # noqa: D401 - http.client hook
+        sock = socket.create_connection((self._ip, self.port), self.timeout)
+        self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
+
+
+def body_for(kind: str, event: dict) -> bytes:
+    """The request body for one alert event (see `drop_event`)."""
+    text = event["text"]
+    if kind == "slack":
+        return json.dumps({"text": text}).encode()
+    if kind == "discord":
+        return json.dumps({"content": text[:1900], "allowed_mentions": {"parse": []}}).encode()
+    return json.dumps({k: v for k, v in event.items() if k != "text"} | {"text": text}, sort_keys=True).encode()
+
+
+def signature(secret: str, body: bytes) -> str:
+    return "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+
+
+def send(kind: str, url: str, event: dict, *, secret: str | None = None, resolve=None,
+         connection_factory=None) -> int:
+    """Deliver one event. Returns the HTTP status (2xx = delivered). Raises WebhookError before sending when the
+    URL or its addresses are not acceptable; OSError/ssl errors propagate for the caller to record."""
+    t = validate(kind, url)
+    ip = (resolve or _resolve)(t.host)
+    connection_factory = connection_factory or _PinnedHTTPS
+    body = body_for(kind, event)
+    headers = {"Content-Type": "application/json", "User-Agent": "Umbermark-Alerts/1"}
+    if kind == "webhook" and secret:
+        headers["X-Umbermark-Signature"] = signature(secret, body)
+    conn = connection_factory(t.host, ip, t.port, TIMEOUT_SECONDS)
+    try:
+        conn.request("POST", t.path, body=body, headers=headers)
+        resp = conn.getresponse()
+        resp.read(4096)  # capped; never kept
+        return resp.status
+    finally:
+        conn.close()
+
+
+def drop_event(*, label: str, server_id: int, previous: int, current: int, threshold: int, report_url: str) -> dict:
+    """The one alert Umbermark sends today: a score drop at or past the server's threshold."""
+    delta = previous - current
+    return {
+        "event": "score_drop", "server": {"id": server_id, "label": label},
+        "score": {"previous": previous, "current": current, "drop": delta, "threshold": threshold},
+        "report_url": report_url,
+        "text": f"Umbermark: {label} score dropped {delta} points ({previous} -> {current}). {report_url}",
+    }
+
+
+def missed_event(*, label: str, server_id: int, last_checkin_at: str | None, server_url: str) -> dict:
+    """A check-in server did not check in within its interval plus grace (UMBR-66)."""
+    last = (last_checkin_at or "never")[:16].replace("T", " ")
+    return {
+        "event": "missed_checkin", "server": {"id": server_id, "label": label}, "score": None,
+        "last_checkin_at": last_checkin_at, "report_url": server_url,
+        "text": f"Umbermark: {label} missed its scheduled check-in (last check-in: {last} UTC). {server_url}",
+    }
+
+
+def sample_event(label: str = "test") -> dict:
+    return {"event": "test", "server": None, "score": None, "report_url": None,
+            "text": f"Umbermark: test alert for channel '{label}'. If you can read this, alerts reach you."}

umbermark/core/wording.py

@@ -0,0 +1,371 @@
+"""Report wording: how a check's result reads to a human.
+
+A check has three strings, kept apart from the check classes so existing
+stored reports (which only carry ``check_id`` + the old ``title``) pick up new
+wording at render time with no migration:
+
+* ``control``   neutral name of the thing being checked ("SSH cipher strength").
+                Used on SEO pages, the checks index and anywhere no verdict is
+                implied.
+* ``pass_text`` what is right on the server (shown on PASS rows).
+* ``fail_text`` what is wrong on the server (shown on FAIL / WARN rows and in
+                "What cost you points"). Present tense, no "should".
+
+Rule of thumb: ``fail_text`` is a finding, never a control name. A reader who
+only sees the fail text must never think the *good* thing is the problem.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import html
+import re
+from dataclasses import dataclass
+
+from markupsafe import Markup
+
+
+@dataclass(frozen=True)
+class Wording:
+    control: str
+    pass_text: str
+    fail_text: str
+
+
+WORDING: dict[str, Wording] = {
+    # --- identity / auth ---------------------------------------------------
+    "ssh_permit_root_login": Wording(
+        "SSH root login",
+        "SSH does not allow direct root login",
+        "SSH allows direct root login",
+    ),
+    "ssh_password_authentication": Wording(
+        "SSH password login",
+        "SSH only accepts keys; password login is off",
+        "SSH still accepts password logins",
+    ),
+    "ssh_weak_ciphers": Wording(
+        "SSH cipher strength",
+        "SSH only accepts strong ciphers, MACs and key exchange",
+        "SSH still accepts weak ciphers, MACs or key exchange",
+    ),
+    "ssh_non_default_port": Wording(
+        "SSH port",
+        "SSH listens on a non-default port",
+        "SSH listens on the default port 22",
+    ),
+    "sudoers_nopasswd": Wording(
+        "Passwordless sudo rules",
+        "No risky passwordless sudo rules",
+        "Passwordless sudo (NOPASSWD) rules are in place",
+    ),
+    "sudo_requires_authentication": Wording(
+        "sudo authentication",
+        "sudo asks users to authenticate",
+        "sudo lets users in without authenticating",
+    ),
+    "user_password_aging": Wording(
+        "Password aging policy",
+        "Account passwords have an expiry policy",
+        "Some accounts have passwords that never expire",
+    ),
+    "failed_login_anomaly": Wording(
+        "Failed SSH logins (7 days)",
+        "Few failed SSH logins in the last 7 days",
+        "Many failed SSH login attempts in the last 7 days",
+    ),
+    "fail2ban_enabled": Wording(
+        "fail2ban brute-force protection",
+        "fail2ban is running with active jails",
+        "fail2ban is missing, stopped or has no active jails",
+    ),
+    # --- patching ----------------------------------------------------------
+    "kernel_age": Wording(
+        "Kernel age",
+        "The running kernel is recent",
+        "The running kernel is more than 6 months old",
+    ),
+    "pending_security_updates": Wording(
+        "Security updates",
+        "No security updates are waiting",
+        "Security updates are waiting to be installed",
+    ),
+    "reboot_pending": Wording(
+        "Pending reboot",
+        "No reboot is pending",
+        "A reboot is pending, so updates are not active yet",
+    ),
+    "auto_updates_configured": Wording(
+        "Automatic security updates",
+        "Automatic security updates are turned on",
+        "Automatic security updates are not set up",
+    ),
+    "repo_gpg_trust": Wording(
+        "Package signing keys",
+        "Package repositories have signing keys configured",
+        "Package repositories have no signing keys configured",
+    ),
+    # --- network -----------------------------------------------------------
+    "firewall_protective": Wording(
+        "Host firewall",
+        "The host firewall blocks unsolicited inbound traffic",
+        "The host firewall is off or lets inbound traffic through",
+    ),
+    "time_sync": Wording(
+        "Clock synchronisation",
+        "The clock is synced and an NTP service is running",
+        "The clock is not synced or no NTP service is running",
+    ),
+    "dns_resolver_sanity": Wording(
+        "DNS resolver",
+        "DNS is configured and answering",
+        "DNS is misconfigured or not answering",
+    ),
+    # --- filesystem / services / logging / hardening -----------------------
+    "root_disk_free": Wording(
+        "Root disk space",
+        "The root disk has plenty of free space",
+        "The root disk is nearly full",
+    ),
+    "tmp_hardening": Wording(
+        "/tmp mount options",
+        "/tmp is mounted noexec and nosuid",
+        "/tmp allows running programs or setuid files",
+    ),
+    "failed_systemd_units": Wording(
+        "Failed systemd units",
+        "No systemd units have failed",
+        "One or more systemd units have failed",
+    ),
+    "swap_pressure": Wording(
+        "Swap pressure",
+        "The server is not swapping memory to disk",
+        "The server is swapping memory to disk",
+    ),
+    "journald_persistence": Wording(
+        "Persistent system logs",
+        "System logs survive a reboot",
+        "System logs are lost on reboot",
+    ),
+    "mac_framework_enforcing": Wording(
+        "AppArmor / SELinux",
+        "AppArmor or SELinux is enforcing",
+        "AppArmor or SELinux is off or not enforcing",
+    ),
+    "public_listen_anomalies": Wording(
+        "Public listening ports",
+        "Only expected ports listen on public addresses",
+        "Unexpected ports listen on public addresses",
+    ),
+    "listen_vs_firewall_delta": Wording(
+        "Firewall cover for listening ports",
+        "Public listening ports are covered by a deny-by-default firewall",
+        "Public ports are reachable only because the firewall allows everything by default",
+    ),
+    "world_writable_suid_audit": Wording(
+        "World-writable files and SUID binaries",
+        "No unexpected world-writable files or SUID binaries",
+        "Unexpected world-writable files or SUID binaries exist",
+    ),
+    # --- external (outside-in) --------------------------------------------
+    "external_exposed_datastores": Wording(
+        "Exposed data stores",
+        "No database or cache is reachable from the internet",
+        "A database or cache is reachable from the internet",
+    ),
+    "external_legacy_plaintext_services": Wording(
+        "Legacy plaintext services",
+        "No telnet, FTP or r-services are reachable from the internet",
+        "A plaintext service (telnet, FTP or r-service) is reachable from the internet",
+    ),
+    "external_open_management_ports": Wording(
+        "Remote-management ports",
+        "No remote-management ports are reachable from the internet",
+        "Remote-management ports (RDP, VNC, Docker, etcd...) are reachable from the internet",
+    ),
+    "external_ssh_weak_algorithms": Wording(
+        "SSH algorithms (outside view)",
+        "SSH offers only modern algorithms to the internet",
+        "SSH offers weak or deprecated algorithms to the internet",
+    ),
+    "external_ssh_alt_ports": Wording(
+        "SSH algorithms on alternate ports (outside view)",
+        "SSH on alternate ports offers only modern algorithms to the internet",
+        "SSH on an alternate port offers weak or deprecated algorithms to the internet",
+    ),
+    "external_tls_hygiene": Wording(
+        "TLS and certificate",
+        "TLS is modern and the certificate is valid",
+        "TLS uses old protocols or the certificate has a problem",
+    ),
+    "external_http_security_headers": Wording(
+        "HTTP security headers",
+        "HTTPS responses set the core security headers",
+        "HTTPS responses are missing or weakly set core security headers",
+    ),
+}
+
+
+def wording_for(check_id: str, fallback_title: str = "") -> Wording:
+    """Wording for a check; unknown ids (old/foreign payloads) fall back to the
+    stored title for all three strings."""
+    w = WORDING.get(check_id)
+    if w is not None:
+        return w
+    t = fallback_title or check_id
+    return Wording(t, t, t)
+
+
+def control_name(check_id: str, fallback_title: str = "") -> str:
+    return wording_for(check_id, fallback_title).control
+
+
+# --- skip reasons -----------------------------------------------------------
+
+def skip_note(reason: str) -> str:
+    """Public-safe, human reason a check was skipped (no raw command output)."""
+    r = (reason or "").lower()
+    if not r:
+        return "Skipped: no data was available for this check."
+    if "ownership" in r or "re-verify" in r or "not probed (unverified)" in r:
+        return "Skipped: this check only runs after you verify you own the server."
+    if "not applicable" in r or "no protective firewall" in r or "non-systemd" in r:
+        return "Skipped: not applicable to this server."
+    if "check raised" in r:
+        return "Skipped: the check hit an internal error."
+    if "requires root" in r or "needs root" in r:
+        return "Skipped: needs root access, which this scan did not have."
+    if "no tls service" in r or "no https service" in r or "kexinit" in r:
+        return "Skipped: the service did not answer on the expected port."
+    return "Skipped: the data was not available on this server."
+
+
+# --- presentation -------------------------------------------------------------
+
+def points_lost(verdict: str, weight: int) -> int:
+    if verdict == "fail":
+        return int(weight)
+    if verdict == "warn":
+        return int(weight) // 2
+    return 0
+
+
+def _val(x):
+    return x.value if hasattr(x, "value") else x
+
+
+def annotate_finding(f: dict) -> dict:
+    """Add display fields to a finding dict (in place) and return it."""
+    verdict = str(_val(f.get("verdict", "")))
+    w = wording_for(f.get("check_id", ""), f.get("title", ""))
+    f["control"] = w.control
+    if verdict == "pass":
+        f["text"] = w.pass_text
+    elif verdict in ("fail", "warn"):
+        f["text"] = w.fail_text
+    else:
+        f["text"] = w.control
+    lost = points_lost(verdict, f.get("weight", 0))
+    f["points_lost"] = lost
+    f["informational"] = verdict == "warn" and lost == 0
+    if verdict == "skip":
+        f["skip_note"] = f.get("skip_note") or skip_note(f.get("skip_reason", ""))
+    f["remediation_html"] = remediation_html(f.get("remediation", ""))
+    return f
+
+
+def present_payload(payload: dict) -> dict:
+    """Return the payload with display fields added to findings and the
+    deduction list split into points-costing vs informational (0-point) rows."""
+    findings = [annotate_finding(dict(f)) for f in payload.get("findings", [])]
+    out = dict(payload)
+    out["findings"] = findings
+    by_id = {f.get("check_id"): f for f in findings}
+    cost, info = [], []
+    for d in payload.get("result", {}).get("deductions", []):
+        d = dict(d)
+        f = by_id.get(d.get("check_id"))
+        d["text"] = f["text"] if f else wording_for(d.get("check_id", ""), d.get("title", "")).fail_text
+        (cost if d.get("points_lost", 0) > 0 else info).append(d)
+    # Zero-point findings that never produced a Deduction row (e.g. weight 0).
+    seen = {d.get("check_id") for d in cost + info}
+    for f in findings:
+        if f["informational"] and f.get("check_id") not in seen:
+            info.append({"check_id": f.get("check_id"), "severity": _val(f.get("severity", "")),
+                         "verdict": "warn", "points_lost": 0, "text": f["text"]})
+    out["cost_deductions"] = cost
+    out["info_deductions"] = info
+    return out
+
+
+# --- remediation text -> safe HTML -------------------------------------------
+
+_BULLET = re.compile(r"^\s{1,3}(?:-|\d+\.)\s+(.*)$")
+_BACKTICK = re.compile(r"`([^`]+)`")
+
+
+def _inline(s: str) -> str:
+    return _BACKTICK.sub(lambda m: "<code>" + m.group(1) + "</code>", html.escape(s, quote=False))
+
+
+def remediation_html(text: str) -> Markup:
+    """Render a remediation string: indented (4+ spaces) lines become <pre><code>
+    blocks, "  - " / "  1. " lines become list items, hard-wrapped prose lines
+    are joined into paragraphs, `x` becomes <code>x</code>. Everything is
+    HTML-escaped first."""
+    if not text:
+        return Markup("")
+    out: list[str] = []
+    para: list[str] = []
+    code: list[str] = []
+    items: list[str] = []
+
+    def flush() -> None:
+        if para:
+            out.append("<p>" + _inline(" ".join(para)) + "</p>")
+            para.clear()
+        if code:
+            out.append("<pre><code>" + html.escape("\n".join(code), quote=False) + "</code></pre>")
+            code.clear()
+        if items:
+            out.append("<ul>" + "".join("<li>" + _inline(i) + "</li>" for i in items) + "</ul>")
+            items.clear()
+
+    for raw in text.split("\n"):
+        line = raw.rstrip()
+        if not line.strip():
+            flush()
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        b = _BULLET.match(line) if indent < 4 else None
+        if b:
+            if para or code:
+                flush()
+            items.append(b.group(1))
+            continue
+        if items and indent >= 2:  # wrapped continuation of a bullet
+            items[-1] += " " + line.strip()
+            continue
+        if indent >= 4:
+            if para or items:
+                flush()
+            code.append(line[4:])
+            continue
+        if code or items:
+            flush()
+        para.append(line.strip())
+    flush()
+    return Markup("".join(out))
+
+
+# --- dates ----------------------------------------------------------------
+
+def human_date(iso: str | None) -> str:
+    """'2026-11-21T10:00:00.123456+00:00' -> '21 Nov 2026'. Unparseable input is
+    returned unchanged so we never hide a value."""
+    if not iso:
+        return ""
+    try:
+        d = dt.datetime.fromisoformat(iso)
+    except ValueError:
+        return iso
+    return f"{d.day} {d.strftime('%b %Y')}"