umbermark-cli 1.0.0__py3-none-any.whl

umbermark/core/fleet.py

@@ -0,0 +1,92 @@
+"""Fleet roll-up for one account: every saved server, worst score first, with its trend (UMBR-66).
+
+Pure functions over rows the caller already loaded (the owner's servers and their recent scans), so the route
+stays a thin shell and the ordering rules are unit-testable.
+
+Ordering ("worst first"):
+  1. servers whose latest scan has a full, comparable score, lowest score first; on a tie the bigger drop first;
+  2. servers whose latest scan is not a full score (incomplete coverage or an outside-in partial);
+  3. servers never scanned.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from umbermark.core.history import Scan, delta, signed
+
+
+@dataclass(frozen=True, slots=True)
+class FleetRow:
+    server: object  # SavedServer; typed loosely so this module needs no DB import
+    latest: Scan | None
+    change: int | None  # latest minus the scan before it, when both are full scores
+    adjusted: object | None = None  # core.accepted.Adjusted for the latest scan, when accepted risks apply
+
+    @property
+    def effective_score(self) -> int | None:
+        """The score the fleet ranks by: with accepted risks when there are any, else the measured one."""
+        if self.latest is None or not self.latest.comparable:
+            return None
+        return self.adjusted.score if self.adjusted is not None else self.latest.score
+
+    @property
+    def trend(self) -> str:
+        """One word a screen reader can say: rising, falling, steady, or '' when there is nothing to compare."""
+        if self.change is None:
+            return ""
+        return "rising" if self.change > 0 else "falling" if self.change < 0 else "steady"
+
+    @property
+    def arrow(self) -> str:
+        return {"rising": "▲", "falling": "▼", "steady": "="}.get(self.trend, "")
+
+    @property
+    def change_text(self) -> str:
+        return signed(self.change)
+
+    @property
+    def rank_key(self) -> tuple:
+        if self.latest is None:
+            return (2, 0, 0)
+        if not self.latest.comparable:
+            return (1, 0, 0)
+        return (0, self.effective_score, self.change if self.change is not None else 0)
+
+
+@dataclass(slots=True)
+class FleetSummary:
+    rows: list[FleetRow]
+    total: int = 0
+    scored: int = 0
+    average: int | None = None
+    dropped: int = 0
+    rising: int = 0
+    bands: dict[str, int] = field(default_factory=dict)
+
+
+def build(servers: list, scans_by_server: dict[int, list[Scan]], adjusted_by_server: dict | None = None) -> FleetSummary:
+    """`scans_by_server` maps server id to that server's recent scans, oldest first (the dashboard query).
+    `adjusted_by_server` maps server id to the latest scan's score with accepted risks (UMBR-66), when any apply.
+    The trend stays measured-vs-measured so an acceptance never shows up as an improvement."""
+    adjusted_by_server = adjusted_by_server or {}
+    rows = []
+    for s in servers:
+        scans = scans_by_server.get(s.id, [])
+        latest = scans[-1] if scans else None
+        prev = scans[-2] if len(scans) > 1 else None
+        rows.append(FleetRow(s, latest, delta(latest, prev), adjusted_by_server.get(s.id)))
+    rows.sort(key=lambda r: r.rank_key)
+    full = [r for r in rows if r.effective_score is not None]
+    bands: dict[str, int] = {}
+    for r in full:
+        b = r.adjusted.band if r.adjusted is not None else r.latest.band
+        bands[b] = bands.get(b, 0) + 1
+    return FleetSummary(
+        rows=rows,
+        total=len(rows),
+        scored=len(full),
+        average=round(sum(r.effective_score for r in full) / len(full)) if full else None,
+        dropped=sum(1 for r in rows if r.trend == "falling"),
+        rising=sum(1 for r in rows if r.trend == "rising"),
+        bands=bands,
+    )

umbermark/core/history.py

@@ -0,0 +1,235 @@
+"""Score history and before/after comparison for a saved server (UMBR-66).
+
+Pure functions over stored scan rows: no I/O beyond what the caller hands in.
+Nothing here is public. The routes that call it only serve the server's owner.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from html import escape
+from typing import Any
+
+from markupsafe import Markup
+
+BAD = ("fail", "warn")  # a finding that costs (or flags) something
+INCOMPLETE = "incomplete"  # band whose score is not a trustworthy number
+CHART_MAX_POINTS = 60  # the chart shows the latest scans; the table lists them all
+
+
+@dataclass(frozen=True, slots=True)
+class Scan:
+    """One stored scan of a saved server, metadata only."""
+
+    id: int
+    short_id: str
+    created_at: str
+    score: int
+    band: str
+    coverage: float
+    pass_count: int
+    warn_count: int
+    fail_count: int
+    skip_count: int
+    partial: bool = False  # UMBR-67: outside-in score of an unverified external scan, not a full score
+
+    @property
+    def comparable(self) -> bool:
+        """A full, trustworthy score: the only kind that is plotted or used for a delta."""
+        return self.band != INCOMPLETE and not self.partial
+
+    @property
+    def score_text(self) -> str:
+        """What a table cell shows: the score, '?' when there is none, or a marked outside-in partial."""
+        if self.partial and self.pass_count + self.warn_count + self.fail_count > 0:
+            return f"{self.score} (outside-in, partial)"
+        return str(self.score) if self.band != INCOMPLETE else "?"
+
+
+def scan_from_row(row: Any) -> Scan:
+    """Build a Scan from a row that carries the json_extract count columns."""
+    keys = row.keys() if hasattr(row, "keys") else ()
+    return Scan(
+        id=row["id"], short_id=row["short_id"], created_at=row["created_at"], score=row["score"], band=row["band"],
+        coverage=row["coverage"], pass_count=row["pass_count"] or 0, warn_count=row["warn_count"] or 0,
+        fail_count=row["fail_count"] or 0, skip_count=row["skip_count"] or 0,
+        partial=bool(row["partial"]) if "partial" in keys else False,
+    )
+
+
+def delta(newer: Scan | None, older: Scan | None) -> int | None:
+    """Score change newer - older; None when either scan is missing or has no trustworthy score."""
+    if newer is None or older is None or not (newer.comparable and older.comparable):
+        return None
+    return newer.score - older.score
+
+
+def signed(n: int | None) -> str:
+    """'+12', '-3', '0' or an en-dash when there is no number."""
+    if n is None:
+        return "–"
+    return f"+{n}" if n > 0 else str(n)
+
+
+def when(iso: str) -> str:
+    """'2026-11-13 09:30 UTC' from a stored ISO timestamp (falls back to the raw text)."""
+    return (iso[:16].replace("T", " ") + " UTC") if len(iso) >= 16 else iso
+
+
+@dataclass(frozen=True, slots=True)
+class Summary:
+    """Headline numbers for one server's history (scans ordered oldest first)."""
+
+    scans: list[Scan]
+    latest: Scan | None
+    previous: Scan | None
+    first: Scan | None
+    since_previous: int | None
+    since_first: int | None
+
+
+def summarise(scans: list[Scan]) -> Summary:
+    latest = scans[-1] if scans else None
+    previous = scans[-2] if len(scans) > 1 else None
+    first = scans[0] if len(scans) > 1 else None  # "since first scan" needs a different first scan
+    return Summary(scans, latest, previous, first, delta(latest, previous), delta(latest, first))
+
+
+# --- diff -----------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True, slots=True)
+class Change:
+    check_id: str
+    title: str
+    before: str  # verdict in the earlier scan ("" when the check was not in it)
+    after: str  # verdict in the later scan ("" when the check was not in it)
+
+
+@dataclass(slots=True)
+class Diff:
+    fixed: list[Change] = field(default_factory=list)
+    regressed: list[Change] = field(default_factory=list)
+    new: list[Change] = field(default_factory=list)
+    other: list[Change] = field(default_factory=list)  # verdict changed, but neither fixed nor regressed
+    unchanged: int = 0
+
+
+def _verdicts(payload: dict) -> dict[str, tuple[str, str]]:
+    out: dict[str, tuple[str, str]] = {}
+    for f in payload.get("findings", []):
+        v = f.get("verdict", "")
+        out[f.get("check_id", "")] = (str(getattr(v, "value", v)), f.get("title", ""))
+    out.pop("", None)
+    return out
+
+
+def diff_payloads(before: dict, after: dict) -> Diff:
+    """Classify every check by what happened between two scans of the same server.
+
+    fixed:     fail/warn -> pass            regressed: pass -> fail/warn
+    new:       a check that only the later scan ran
+    other:     any other verdict change (fail <-> warn, to or from skip)
+    unchanged: same verdict in both. Checks only the earlier scan ran are not counted.
+    """
+    b, a = _verdicts(before), _verdicts(after)
+    d = Diff()
+    for cid, (verdict, title) in a.items():
+        if cid not in b:
+            d.new.append(Change(cid, title, "", verdict))
+            continue
+        old = b[cid][0]
+        change = Change(cid, title or b[cid][1], old, verdict)
+        if old == verdict:
+            d.unchanged += 1
+        elif old in BAD and verdict == "pass":
+            d.fixed.append(change)
+        elif old == "pass" and verdict in BAD:
+            d.regressed.append(change)
+        else:
+            d.other.append(change)
+    return d
+
+
+def diff_payload_json(before_json: str, after_json: str) -> Diff:
+    def load(s: str) -> dict:
+        try:
+            v = json.loads(s)
+        except ValueError:
+            return {}
+        return v if isinstance(v, dict) else {}
+
+    return diff_payloads(load(before_json), load(after_json))
+
+
+def summary_line(d: Diff, before: Scan, after: Scan) -> str:
+    """'3 fixed, 1 regressed, score 71 -> 78' (the score part is dropped when either score is not comparable)."""
+    parts = [f"{len(d.fixed)} fixed", f"{len(d.regressed)} regressed"]
+    if d.new:
+        parts.append(f"{len(d.new)} new")
+    if before.comparable and after.comparable:
+        parts.append(f"score {before.score} → {after.score}")
+    return ", ".join(parts)
+
+
+# --- SVG ------------------------------------------------------------------------------------------------------
+
+_W, _H = 640, 200
+_PAD_L, _PAD_R, _PAD_T, _PAD_B = 34, 12, 12, 24
+
+
+def _points(scans: list[Scan], width: int, height: int, pl: int, pr: int, pt: int, pb: int) -> list[tuple[float, float, Scan]]:
+    shown = [s for s in scans if s.comparable][-CHART_MAX_POINTS:]
+    n = len(shown)
+    inner_w, inner_h = width - pl - pr, height - pt - pb
+    pts = []
+    for i, s in enumerate(shown):
+        x = pl + (inner_w / 2 if n == 1 else inner_w * i / (n - 1))
+        y = pt + inner_h * (1 - max(0, min(100, s.score)) / 100)
+        pts.append((round(x, 1), round(y, 1), s))
+    return pts
+
+
+def chart_svg(scans: list[Scan], uid: str = "hist") -> Markup:
+    """Score-over-time line chart as inline SVG: no script, no external reference, labelled for screen readers.
+
+    The scans table on the page is the text equivalent. Scans with an incomplete band are left off the line.
+    """
+    pts = _points(scans, _W, _H, _PAD_L, _PAD_R, _PAD_T, _PAD_B)
+    uid = "".join(c for c in uid if c.isalnum() or c in "-_") or "hist"
+    if pts:
+        desc = (f"{len(pts)} scan{'s' if len(pts) != 1 else ''}, from {pts[0][2].score} on {when(pts[0][2].created_at)} "
+                f"to {pts[-1][2].score} on {when(pts[-1][2].created_at)}. The scans table below lists every value.")
+    else:
+        desc = "No scans with a complete score yet."
+    out = [
+        f'<svg class="hist-chart" viewBox="0 0 {_W} {_H}" role="img" aria-labelledby="{uid}-t {uid}-d" '
+        f'xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet">',
+        f'<title id="{uid}-t">Hardening score over time</title><desc id="{uid}-d">{escape(desc)}</desc>',
+    ]
+    for g in (0, 50, 100):
+        y = round(_PAD_T + (_H - _PAD_T - _PAD_B) * (1 - g / 100), 1)
+        out.append(f'<line class="hist-grid" x1="{_PAD_L}" y1="{y}" x2="{_W - _PAD_R}" y2="{y}"/>')
+        out.append(f'<text class="hist-axis" x="{_PAD_L - 6}" y="{y + 4}" text-anchor="end">{g}</text>')
+    if len(pts) > 1:
+        line = " ".join(f"{x},{y}" for x, y, _ in pts)
+        out.append(f'<polyline class="hist-line" fill="none" points="{line}"/>')
+    for x, y, s in pts:
+        out.append(f'<circle class="hist-dot" cx="{x}" cy="{y}" r="4"><title>{s.score} ({escape(s.band)}) on '
+                   f'{escape(when(s.created_at))}</title></circle>')
+    out.append("</svg>")
+    return Markup("".join(out))
+
+
+def sparkline_svg(scans: list[Scan], uid: str = "spark") -> Markup:
+    """A small trend line (latest 20 scans) for the dashboard. Decorative: the delta text beside it carries the meaning."""
+    w, h = 96, 24
+    pts = _points(scans[-20:], w, h, 3, 3, 3, 3)
+    if not pts:
+        return Markup("")
+    out = [f'<svg class="hist-spark" viewBox="0 0 {w} {h}" width="{w}" height="{h}" aria-hidden="true" focusable="false" '
+           f'xmlns="http://www.w3.org/2000/svg">']
+    if len(pts) > 1:
+        out.append('<polyline class="hist-line" fill="none" points="' + " ".join(f"{x},{y}" for x, y, _ in pts) + '"/>')
+    x, y, _ = pts[-1]
+    out.append(f'<circle class="hist-dot" cx="{x}" cy="{y}" r="2.5"/></svg>')
+    return Markup("".join(out))

umbermark/core/html_report.py

@@ -0,0 +1,308 @@
+"""HTML report rendering — owner view (full) and public view (scrubbed).
+
+The public view is the shareable artifact: same score and findings list,
+but target identifier and per-finding evidence are scrubbed. Remediation
+snippets are kept since they're already generic. v0.1 errs on the side of
+hiding more rather than less.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from jinja2 import Environment, select_autoescape
+
+from umbermark.core.engine import ScanReport
+from umbermark.core.partial import outside_in
+from umbermark.core.report import _to_dict
+from umbermark.core.wording import present_payload
+
+Mode = Literal["owner", "public"]
+
+
+_TEMPLATE = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Hardening report — {{ target_display }}</title>
+<style>
+  :root {
+    --bg: #0f1419;
+    --panel: #181d24;
+    --panel-2: #1f2530;
+    --text: #e6e9ef;
+    --muted: #9aa3b2;
+    --gold: #f5c451;
+    --green: #6ec97a;
+    --yellow: #e4b15c;
+    --red: #ef6b6b;
+    --incomplete: #8a90a0;
+    --critical: #ef6b6b;
+    --high: #f0a050;
+    --medium: #e0c060;
+    --low: #8bd0c0;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 2rem;
+    font: 14px/1.5 -apple-system, "Segoe UI", system-ui, sans-serif;
+    background: var(--bg); color: var(--text);
+  }
+  .wrap { max-width: 900px; margin: 0 auto; }
+  header { display: flex; align-items: center; gap: 1.5rem; margin-bottom: 2rem; }
+  .score {
+    width: 7rem; height: 7rem; border-radius: 50%;
+    display: flex; align-items: center; justify-content: center;
+    flex-direction: column; flex-shrink: 0;
+    border: 4px solid var(--{{ band }});
+    background: var(--panel);
+  }
+  .score.partial { border: 3px dashed var(--incomplete); }
+  .score .n { font-size: 2.3rem; font-weight: 700; line-height: 1; }
+  .score .b { font-size: 0.75rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; margin-top: 0.2rem; }
+  .meta h1 { margin: 0 0 0.4rem; font-size: 1.25rem; font-weight: 600; }
+  .meta .target { color: var(--muted); font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+  .meta .timestamp { color: var(--muted); font-size: 0.85rem; margin-top: 0.2rem; }
+  .coverage-banner {
+    background: rgba(138, 144, 160, 0.15);
+    border-left: 4px solid var(--incomplete);
+    padding: 0.85rem 1.25rem;
+    border-radius: 4px;
+    margin: 1rem 0 1.5rem;
+    color: var(--text);
+  }
+  .coverage-banner b { color: var(--incomplete); }
+  .counts { display: flex; gap: 1rem; margin: 1.5rem 0 2rem; }
+  .count {
+    background: var(--panel); padding: 0.75rem 1rem; border-radius: 6px;
+    flex: 1; text-align: center;
+  }
+  .count .n { font-size: 1.5rem; font-weight: 700; display: block; }
+  .count .l { font-size: 0.75rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; }
+  .count.pass .n { color: var(--green); }
+  .count.warn .n { color: var(--yellow); }
+  .count.fail .n { color: var(--red); }
+  .count.skip .n { color: var(--muted); }
+  h2 { font-size: 1.05rem; font-weight: 600; margin: 2rem 0 0.75rem; }
+  .deductions, .findings { background: var(--panel); border-radius: 8px; overflow: hidden; }
+  .row {
+    display: grid; grid-template-columns: auto 1fr auto;
+    gap: 1rem; align-items: start;
+    padding: 1rem 1.25rem;
+    border-bottom: 1px solid var(--panel-2);
+  }
+  .row:last-child { border-bottom: 0; }
+  .row .badge {
+    display: inline-block; padding: 0.15rem 0.55rem; border-radius: 999px;
+    font-size: 0.7rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em;
+    background: var(--panel-2);
+  }
+  .row .badge.critical { background: var(--critical); color: #0f1419; }
+  .row .badge.high { background: var(--high); color: #0f1419; }
+  .row .badge.medium { background: var(--medium); color: #0f1419; }
+  .row .badge.low { background: var(--low); color: #0f1419; }
+  .row .verdict { font-size: 0.7rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; }
+  .row .verdict.pass { color: var(--green); }
+  .row .verdict.fail { color: var(--red); }
+  .row .verdict.warn { color: var(--yellow); }
+  .row .title { font-weight: 600; }
+  .row .evidence, .row .remediation, .row .skip-reason {
+    margin-top: 0.4rem; color: var(--muted); font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.85rem;
+    white-space: pre-wrap;
+  }
+  .row .remediation { color: var(--text); font-family: inherit; white-space: normal; }
+  .row .remediation p, .row .remediation ul { margin: 0.3rem 0; }
+  .row .remediation pre { margin: 0.3rem 0; padding: 0.5rem 0.75rem; background: var(--panel-2); border-radius: 4px; white-space: pre-wrap; }
+  .row .remediation code { font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+  .row .control { margin-top: 0.2rem; color: var(--muted); font-size: 0.8rem; }
+  .points { text-align: right; font-weight: 700; color: var(--red); white-space: nowrap; }
+  footer { margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid var(--panel); color: var(--muted); font-size: 0.8rem; text-align: center; }
+  footer .cta { color: var(--text); }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <header>
+    <div class="score{% if partial %} partial{% endif %}">
+      {% if partial %}
+      <span class="n">{{ partial.score }}</span>
+      <span class="b">outside-in</span>
+      {% else %}
+      {% if band == "incomplete" %}
+      <span class="n">?</span>
+      {% else %}
+      <span class="n">{{ result.score }}</span>
+      {% endif %}
+      <span class="b">{{ band }}</span>
+      {% endif %}
+    </div>
+    <div class="meta">
+      {% if brand %}<div class="brand" style="border-left: 4px solid {{ brand.accent }}; padding-left: 8px; margin-bottom: 6px;">{% if brand.logo %}<img src="{{ brand.logo }}" alt="" style="max-height: 40px; vertical-align: middle; margin-right: 8px;">{% endif %}<strong>Prepared by {{ brand.name }}</strong></div>{% endif %}
+      <h1>Linux hardening report</h1>
+      <div class="target">{{ target_display }}</div>
+      <div class="timestamp">Scanned {{ scanned_at_display }}</div>
+    </div>
+  </header>
+
+  {% if partial %}
+  <div class="coverage-banner">
+    <b>Outside-in score: {{ partial.score }} (partial, {{ partial.ran }} of {{ partial.total }} checks).</b>
+    This scan was run from outside without proof of ownership, so only the
+    passive checks ran. The number is scored on those checks alone and is not
+    the full hardening score. Verify you own the host to run the other
+    {{ partial.gated }} check{% if partial.gated != 1 %}s{% endif %}.
+  </div>
+  {% elif band == "incomplete" %}
+  <div class="coverage-banner">
+    <b>Incomplete scan.</b>
+    Only {{ result.pass_count + result.warn_count + result.fail_count }} of
+    {{ result.pass_count + result.warn_count + result.fail_count + result.skip_count }}
+    checks were able to run on this target ({{ coverage_pct }}% coverage). The
+    score is hidden because there isn't enough signal to call this a clean
+    result. See "All findings" below for what got skipped and why.
+  </div>
+  {% elif result.skip_count > 0 %}
+  <div class="coverage-banner" style="border-left-color: var(--muted);">
+    {{ coverage_pct }}% scan coverage — {{ result.skip_count }} check{% if result.skip_count != 1 %}s{% endif %} skipped (see findings for reasons).
+  </div>
+  {% endif %}
+
+  <section class="counts">
+    <div class="count pass"><span class="n">{{ result.pass_count }}</span><span class="l">pass</span></div>
+    <div class="count warn"><span class="n">{{ result.warn_count }}</span><span class="l">warn</span></div>
+    <div class="count fail"><span class="n">{{ result.fail_count }}</span><span class="l">fail</span></div>
+    <div class="count skip"><span class="n">{{ result.skip_count }}</span><span class="l">skip</span></div>
+  </section>
+
+  {% if cost_deductions %}
+  <h2>What cost you points</h2>
+  <section class="deductions">
+    {% for d in cost_deductions %}
+    <div class="row">
+      <span class="badge {{ d.severity }}">{{ d.severity }}</span>
+      <div>
+        <div class="title">{{ d.text }}</div>
+        <div class="verdict {{ d.verdict }}">{{ d.verdict }}</div>
+      </div>
+      <div class="points">-{{ d.points_lost }}</div>
+    </div>
+    {% endfor %}
+  </section>
+  {% endif %}
+  {% if info_deductions %}
+  <h2>Informational (no points lost)</h2>
+  <section class="deductions">
+    {% for d in info_deductions %}
+    <div class="row">
+      <span class="badge">info</span>
+      <div><div class="title">{{ d.text }}</div></div>
+      <div></div>
+    </div>
+    {% endfor %}
+  </section>
+  {% endif %}
+
+  <h2>All findings</h2>
+  <section class="findings">
+    {% for f in findings %}
+    <div class="row">
+      <span class="badge {{ f.severity }}">{{ f.severity }}</span>
+      <div>
+        <div class="title">{{ f.text }}</div>
+        <div class="verdict {{ f.verdict }}">{{ "info" if f.informational else f.verdict }}</div>
+        <div class="control">Check: {{ f.control }}</div>
+        {% if mode == 'owner' and f.evidence %}
+        <div class="evidence">{{ f.evidence }}</div>
+        {% endif %}
+        {% if f.remediation %}
+        <div class="remediation">{{ f.remediation_html }}</div>
+        {% endif %}
+        {% if f.verdict == 'skip' %}
+        <div class="skip-reason">{{ f.skip_note }}{% if mode == 'owner' and f.skip_reason %} ({{ f.skip_reason }}){% endif %}</div>
+        {% endif %}
+      </div>
+      <div></div>
+    </div>
+    {% endfor %}
+  </section>
+
+  <footer>
+    <span class="cta">Scanned with Umbermark</span>
+    {% if mode == 'public' %}
+    &nbsp;·&nbsp; Want your own score? Free scan at <tbd-domain>
+    {% endif %}
+  </footer>
+
+</div>
+</body>
+</html>
+"""
+
+
+@dataclass
+class _Ctx:
+    target_display: str
+    scanned_at_display: str
+    band: str
+    result: object
+    findings: list
+    mode: Mode
+
+
+def _format_timestamp(iso: str) -> str:
+    # 2026-05-14T06:58:45.123456+00:00 → 2026-05-14 06:58 UTC
+    return iso.split(".")[0].replace("T", " ") + " UTC"
+
+
+def to_html(report: ScanReport, mode: Mode = "owner") -> str:
+    env = Environment(autoescape=select_autoescape(["html", "xml"]))
+    tmpl = env.from_string(_TEMPLATE)
+    payload = present_payload(_to_dict(report))
+
+    target = report.target if mode == "owner" else "<redacted>"
+    coverage_pct = int(round(report.result.coverage * 100))
+    return tmpl.render(
+        target_display=target,
+        scanned_at_display=_format_timestamp(report.finished_at),
+        band=report.result.band,
+        partial=None,  # a ScanReport rendered here is an on-box scan: always the full score
+        coverage_pct=coverage_pct,
+        result=payload["result"],
+        findings=payload["findings"],
+        cost_deductions=payload["cost_deductions"],
+        info_deductions=payload["info_deductions"],
+        mode=mode,
+    )
+
+
+def render_owner_html_from_payload(
+    payload: dict, target: str, mode: Mode = "owner", brand: dict | None = None
+) -> str:
+    """Render the owner-view HTML from the persisted Report v1.0 JSON dict.
+
+    Used by the PDF render worker, which loads the payload_json from the
+    reports table and produces a self-contained HTML document for PDF
+    conversion. The template handles dict-shaped values (Jinja falls
+    back from .attr to ['attr']) so no reconstruction of dataclasses
+    is needed.
+    """
+    env = Environment(autoescape=select_autoescape(["html", "xml"]))
+    tmpl = env.from_string(_TEMPLATE)
+    payload = present_payload(payload)
+    result = payload.get("result", {})
+    coverage_pct = int(round(float(result.get("coverage", 0.0)) * 100))
+    finished = payload.get("finished_at", "")
+    return tmpl.render(
+        target_display=target,
+        scanned_at_display=_format_timestamp(finished) if finished else "",
+        band=result.get("band", "incomplete"),
+        partial=outside_in(payload),  # UMBR-67: unverified outside-in scan -> labelled partial score
+        coverage_pct=coverage_pct,
+        result=result,
+        findings=payload.get("findings", []),
+        cost_deductions=payload["cost_deductions"],
+        info_deductions=payload["info_deductions"],
+        mode=mode,
+        brand=brand,  # UMBR-66 white-label (Agency): {name, accent (#rrggbb, validated), logo (PNG data: URI)}
+    )

umbermark/core/keyenc.py

@@ -0,0 +1,42 @@
+"""Authenticated encryption for saved-server SSH private keys.
+
+Implements spec §17 — saved-server scans:
+
+1. The plaintext key never lives on disk.
+2. Encryption key is derived per user via PBKDF2(KEY_PEPPER || user_id, salt).
+3. SecretBox is XSalsa20-Poly1305 — AEAD; tampering raises on decrypt.
+4. The 16-byte salt is stored in the DB next to the ciphertext.
+
+DB-only compromise (no `KEY_PEPPER`) does not yield plaintext keys.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+
+from nacl.secret import SecretBox
+
+_SALT_BYTES = 16
+_KDF_ROUNDS = 200_000
+_KEY_BYTES = SecretBox.KEY_SIZE  # 32
+
+
+def _derive_key(key_pepper: str, user_id: int, salt: bytes) -> bytes:
+    if not key_pepper:
+        raise ValueError("key_pepper must be non-empty")
+    if len(salt) != _SALT_BYTES:
+        raise ValueError(f"salt must be {_SALT_BYTES} bytes")
+    secret_material = f"{key_pepper}::{user_id}".encode("utf-8")
+    return hashlib.pbkdf2_hmac("sha256", secret_material, salt, _KDF_ROUNDS, _KEY_BYTES)
+
+
+def encrypt(plaintext: bytes, *, key_pepper: str, user_id: int) -> tuple[bytes, bytes]:
+    """Returns (ciphertext, salt)."""
+    salt = os.urandom(_SALT_BYTES)
+    key = _derive_key(key_pepper, user_id, salt)
+    return SecretBox(key).encrypt(plaintext), salt
+
+
+def decrypt(ciphertext: bytes, salt: bytes, *, key_pepper: str, user_id: int) -> bytes:
+    key = _derive_key(key_pepper, user_id, salt)
+    return SecretBox(key).decrypt(ciphertext)