mcpprobe-scanner 0.1.0__py3-none-any.whl

mcpprobe/cli.py

@@ -0,0 +1,295 @@
+"""Command-line interface.
+
+``mcpprobe <target>`` is shorthand for ``mcpprobe scan <target>``.
+
+Exit codes: 0 = no findings at or above ``--fail-on``; 1 = findings at or
+above ``--fail-on``; 2 = error (unreachable target, opt-out, authorisation
+refused, bad arguments).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Sequence
+
+import click
+from rich.console import Console
+
+from mcpprobe import POLICY_URL, USER_AGENT, __version__
+from mcpprobe.authz import (
+    AuthorisationError,
+    authorise,
+    expected_txt_record,
+    generate_token,
+    save_token,
+    write_record,
+)
+from mcpprobe.checks import ALL_CHECKS, ScanOptions
+from mcpprobe.checks._util import host_of
+from mcpprobe.dnsutil import record_name
+from mcpprobe.models import CheckMode, Severity
+from mcpprobe.policy import DEFAULT_RATE, MAX_RATE, OptOutError
+from mcpprobe.report import render, write_json, write_sarif
+from mcpprobe.scanner import ScanConfig, run_scan
+from mcpprobe.transport import TransportError, ensure_url
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+SEVERITIES = [s.value for s in Severity]
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="mcpprobe")
+def cli() -> None:
+    """mcpprobe: security scanner for MCP servers. Scan only servers you own or are authorised to test."""
+
+
+def _parse_kv(values: Sequence[str], what: str, sep: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in values:
+        key, found, value = item.partition(sep)
+        if not found or not key.strip():
+            raise click.BadParameter(f"{what} must be KEY{sep}VALUE, got {item!r}")
+        out[key.strip()] = value.strip()
+    return out
+
+
+@cli.command("scan")
+@click.argument("target")
+@click.option("--stdio", is_flag=True, help="Treat TARGET as a local command to spawn (stdio transport).")
+@click.option(
+    "--env", "env_vars", multiple=True, help="Environment for the stdio server, KEY=VALUE (repeatable)."
+)
+@click.option(
+    "--header",
+    "headers",
+    multiple=True,
+    help="Extra HTTP header, 'Name: value' (repeatable), e.g. a bearer token you own.",
+)
+@click.option(
+    "--active", is_flag=True, help="Enable active checks. Requires --authorised-by, --scope and --verify."
+)
+@click.option("--authorised-by", help="Who authorised this scan (name/role/ticket). Required for --active.")
+@click.option(
+    "--scope",
+    help="Agreed scope statement, e.g. 'https://host/mcp, read-only tools only'. Required for --active.",
+)
+@click.option(
+    "--verify",
+    "verify_method",
+    type=click.Choice(["dns-txt", "local"]),
+    help="Ownership verification method for --active.",
+)
+@click.option(
+    "--token", help="Verification token for --verify dns-txt (default: the one saved by 'mcpprobe token')."
+)
+@click.option(
+    "--reference", help="Operator reference stored in the authorisation record (ticket, change number)."
+)
+@click.option(
+    "--exclude-tool",
+    "excluded_tools",
+    multiple=True,
+    help="Tool names that must never be called (repeatable).",
+)
+@click.option(
+    "--rate",
+    default=DEFAULT_RATE,
+    show_default=True,
+    type=click.FloatRange(min=0.1, max=MAX_RATE),
+    help=f"Maximum requests per second (hard ceiling {MAX_RATE:g}).",
+)
+@click.option("--timeout", default=15.0, show_default=True, help="Per-request timeout in seconds.")
+@click.option(
+    "--fail-on",
+    default="high",
+    type=click.Choice(SEVERITIES),
+    show_default=True,
+    help="Exit 1 if any finding is at or above this severity.",
+)
+@click.option(
+    "--json", "json_path", type=click.Path(dir_okay=False), help="Write the JSON report (with evidence) here."
+)
+@click.option(
+    "--sarif", "sarif_path", type=click.Path(dir_okay=False), help="Write a SARIF 2.1.0 report here."
+)
+@click.option(
+    "--sarif-location", help="Repository-relative file to anchor SARIF results to (default: the target URI)."
+)
+@click.option(
+    "--baseline",
+    "baseline_path",
+    type=click.Path(dir_okay=False),
+    help="META-02 baseline file to compare against and update.",
+)
+@click.option("--no-write-baseline", is_flag=True, help="Compare against --baseline but do not overwrite it.")
+@click.option(
+    "--no-follow-as",
+    is_flag=True,
+    help="AUTH-03: do not fetch authorization-server metadata on third-party hosts.",
+)
+@click.option("--only", multiple=True, help="Run only these check IDs (repeatable).")
+@click.option("--skip", multiple=True, help="Skip these check IDs (repeatable).")
+@click.option("--insecure", is_flag=True, help="Do not verify the target's TLS certificate.")
+@click.option("--verbose", "-v", is_flag=True, help="Show descriptions and fixes in the terminal summary.")
+@click.option("--quiet", "-q", is_flag=True, help="Suppress the terminal summary.")
+def scan_cmd(
+    target: str,
+    stdio: bool,
+    env_vars: Sequence[str],
+    headers: Sequence[str],
+    active: bool,
+    authorised_by: str | None,
+    scope: str | None,
+    verify_method: str | None,
+    token: str | None,
+    reference: str | None,
+    excluded_tools: Sequence[str],
+    rate: float,
+    timeout: float,
+    fail_on: str,
+    json_path: str | None,
+    sarif_path: str | None,
+    sarif_location: str | None,
+    baseline_path: str | None,
+    no_write_baseline: bool,
+    no_follow_as: bool,
+    only: Sequence[str],
+    skip: Sequence[str],
+    insecure: bool,
+    verbose: bool,
+    quiet: bool,
+) -> None:
+    """Scan TARGET (an http(s) URL, or a command with --stdio)."""
+    console = Console(stderr=True)
+    err = Console(stderr=True, style="bold red")
+    try:
+        if not stdio:
+            target = ensure_url(target)
+        transport_kind = "stdio" if stdio else "http"
+        host = "" if stdio else host_of(target)
+        try:
+            record = authorise(
+                target=target,
+                transport=transport_kind,
+                host=host,
+                active=active,
+                authorised_by=authorised_by,
+                scope=scope,
+                verify_method=verify_method,
+                token=token,
+                excluded_tools=excluded_tools,
+                rate_cap_rps=rate,
+                reference=reference,
+            )
+        except AuthorisationError as exc:
+            err.print(f"authorisation refused: {exc}", markup=False, highlight=False)
+            err.print("active mode was not started; no request was sent to the target.", markup=False)
+            sys.exit(EXIT_ERROR)
+        options = ScanOptions(
+            mode=CheckMode.ACTIVE if active else CheckMode.PASSIVE,
+            baseline_path=baseline_path,
+            write_baseline=not no_write_baseline,
+            excluded_tools=set(excluded_tools),
+            follow_authorization_server=not no_follow_as,
+            timeout=timeout,
+        )
+        config = ScanConfig(
+            target=target,
+            stdio=stdio,
+            stdio_env=_parse_kv(env_vars, "--env", "="),
+            headers=_parse_kv(headers, "--header", ":"),
+            timeout=timeout,
+            rate=rate,
+            options=options,
+            only=list(only) or None,
+            skip=list(skip) or None,
+            authorisation=record if active else None,
+            user_agent=USER_AGENT,
+            verify_tls=not insecure,
+        )
+        if not quiet:
+            console.print(
+                f"[dim]mcpprobe {__version__} | {('active' if active else 'passive')} mode | rate {rate}/s | "
+                f"scan only what you own or are authorised to test | {POLICY_URL}[/dim]"
+            )
+        report, evidence = asyncio.run(run_scan(config))
+    except OptOutError as exc:
+        err.print(f"aborted: {exc}", markup=False, highlight=False)
+        sys.exit(EXIT_ERROR)
+    except (TransportError, AuthorisationError) as exc:
+        err.print(f"error: {exc}", markup=False, highlight=False)
+        sys.exit(EXIT_ERROR)
+    except click.ClickException:
+        raise
+    except KeyError as exc:
+        err.print(f"error: {exc.args[0] if exc.args else exc}", markup=False, highlight=False)
+        sys.exit(EXIT_ERROR)
+
+    if active:
+        path = write_record(record, json_path or sarif_path)
+        report.authorisation_record = str(path)
+    if json_path:
+        write_json(report, json_path, evidence)
+    if sarif_path:
+        write_sarif(report, sarif_path, location_uri=sarif_location)
+    threshold = Severity(fail_on)
+    if not quiet:
+        render(report, Console(), verbose=verbose, show_evidence=True, fail_on=threshold)
+        outputs = (
+            ("JSON", json_path),
+            ("SARIF", sarif_path),
+            ("authorisation record", report.authorisation_record),
+        )
+        for label, out_path in outputs:
+            if out_path:
+                console.print(f"{label}: {out_path}", style="dim", markup=False, highlight=False)
+    worst = report.max_severity()
+    sys.exit(EXIT_FINDINGS if worst is not None and worst >= threshold else EXIT_CLEAN)
+
+
+@cli.command("checks")
+@click.option("--format", "fmt", type=click.Choice(["table", "markdown"]), default="table", show_default=True)
+def checks_cmd(fmt: str) -> None:
+    """List every check with its mode, default severity and standards mapping."""
+    if fmt == "markdown":
+        from mcpprobe.catalogue import checks_markdown
+
+        click.echo(checks_markdown(), nl=False)
+        return
+    from rich.table import Table
+
+    table = Table(title=f"mcpprobe {__version__} checks")
+    for col in ("ID", "Mode", "Severity", "Title", "Standards"):
+        table.add_column(col)
+    for c in ALL_CHECKS:
+        table.add_row(c.id, c.mode.value, c.severity.value, c.title, ", ".join(c.standards.as_tags()) or "-")
+    Console().print(table)
+
+
+@cli.command("token")
+@click.argument("host")
+def token_cmd(host: str) -> None:
+    """Generate and save an ownership-verification token for HOST and print the TXT record to publish."""
+    token = generate_token()
+    path = save_token(host, token)
+    click.echo(f"Saved token for {host} in {path}")
+    click.echo("Publish this DNS TXT record, then run with --active --verify dns-txt:")
+    click.echo(f'  {record_name(host)}.  TXT  "{expected_txt_record(token)}"')
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Entry point: default to the ``scan`` sub-command when the first argument is a target."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    known = {"scan", "checks", "token"}
+    group_options = {"-h", "--help", "--version"}
+    if args and args[0] not in known and args[0] not in group_options:
+        args.insert(0, "scan")
+    cli.main(args=args, prog_name="mcpprobe", standalone_mode=True)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

mcpprobe/dnsutil.py

@@ -0,0 +1,67 @@
+"""DNS TXT lookups shared by ownership verification and opt-out handling."""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Callable
+
+#: Resolver signature: name -> list of TXT strings ([] when the name has none).
+TxtLookup = Callable[[str], list[str]]
+
+#: Label under which both verification and opt-out records live: ``_mcpprobe.<host>``.
+RECORD_LABEL = "_mcpprobe"
+
+
+class DnsLookupError(Exception):
+    """The resolver failed for a reason other than 'no such record'."""
+
+
+def record_name(host: str) -> str:
+    return f"{RECORD_LABEL}.{host.rstrip('.').lower()}"
+
+
+def has_public_dns_name(host: str) -> bool:
+    """False for IP literals and loopback-only names, which have no public TXT records."""
+    h = host.strip("[]").rstrip(".").lower()
+    if not h:
+        return False
+    try:
+        ipaddress.ip_address(h)
+    except ValueError:
+        pass
+    else:
+        return False
+    if h in {"localhost", "ip6-localhost"} or h.endswith((".localhost", ".local", ".internal", ".invalid")):
+        return False
+    return "." in h
+
+
+def default_txt_lookup(name: str) -> list[str]:
+    """Resolve TXT records with dnspython; ``[]`` on NXDOMAIN / no answer."""
+    import dns.exception
+    import dns.resolver
+
+    try:
+        answers = dns.resolver.resolve(name, "TXT", lifetime=5.0)
+    except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
+        return []
+    except dns.exception.DNSException as exc:
+        raise DnsLookupError(f"DNS lookup failed for {name}: {exc}") from exc
+    out: list[str] = []
+    for rdata in answers:
+        strings = getattr(rdata, "strings", None)
+        if strings is None:
+            out.append(str(rdata).strip('"'))
+        else:
+            out.append(b"".join(strings).decode("utf-8", errors="replace"))
+    return out
+
+
+__all__ = [
+    "RECORD_LABEL",
+    "DnsLookupError",
+    "TxtLookup",
+    "default_txt_lookup",
+    "has_public_dns_name",
+    "record_name",
+]

mcpprobe/governance.py

@@ -0,0 +1,74 @@
+"""GOV-01..05: governance items that an automated scan cannot assess.
+
+They are listed in every report as *attestation only*, with a short checklist
+the operator can work through. mcpprobe never reports them as passed or failed.
+"""
+
+from __future__ import annotations
+
+from mcpprobe.models import AttestationItem, Standards
+
+GOVERNANCE_ITEMS: list[AttestationItem] = [
+    AttestationItem(
+        id="GOV-01",
+        title="Audit logging and telemetry for tool invocations",
+        standards=Standards(mcp=["MCP08:2025"]),
+        reason="Whether a server logs and alerts on tool calls is not observable from outside.",
+        checklist=[
+            "Every tools/call is logged with caller identity, tool name, arguments digest and outcome.",
+            "Logs are shipped off-host, retained, and reviewed or alerted on.",
+            "Authentication failures and authorisation denials are logged.",
+        ],
+    ),
+    AttestationItem(
+        id="GOV-02",
+        title="Shadow MCP servers (inventory of servers in use)",
+        standards=Standards(mcp=["MCP09:2025"]),
+        reason="An inventory problem across workstations and repositories, not an endpoint property.",
+        checklist=[
+            "Maintain an inventory of approved MCP servers and their owners.",
+            "Periodically review client configuration files (mcp.json and similar) for unapproved entries.",
+        ],
+    ),
+    AttestationItem(
+        id="GOV-03",
+        title="Data and model poisoning in training or fine-tuning pipelines",
+        standards=Standards(llm_2025=["LLM04:2025"], llm_2026=["LLM05:2026"]),
+        reason="Training-pipeline integrity is not black-box testable.",
+        checklist=[
+            "Training and retrieval data sources are provenance-tracked and access-controlled.",
+            "Data changes are reviewed before they reach a model or index.",
+        ],
+    ),
+    AttestationItem(
+        id="GOV-04",
+        title="Inter-agent communication, cascading failures, human trust, rogue agents",
+        standards=Standards(asi=["ASI07", "ASI08", "ASI09", "ASI10"]),
+        reason="Architecture and process items; multi-agent paths are not externally visible.",
+        checklist=[
+            "Agent-to-agent channels are authenticated (the AUTH checks apply to any exposed endpoint).",
+            "Failure of one tool or agent is contained (timeouts, circuit breakers, budgets).",
+            "High-impact actions require explicit human approval with the full action shown.",
+            "Agents can be stopped centrally and their credentials revoked.",
+        ],
+    ),
+    AttestationItem(
+        id="GOV-05",
+        title="Memory and context poisoning persistence",
+        standards=Standards(asi=["ASI06"]),
+        reason="Needs a customer-supplied test session across two conversations; not a server-side scan.",
+        checklist=[
+            "Persistent memory is scoped per user and per tenant.",
+            "Stored memories can be reviewed and deleted by the user.",
+            "Content from tool output is not written to long-term memory without review.",
+        ],
+    ),
+]
+
+
+def governance_items() -> list[AttestationItem]:
+    """Fresh copies, so a report can be mutated without touching the module constant."""
+    return [item.model_copy(deep=True) for item in GOVERNANCE_ITEMS]
+
+
+__all__ = ["GOVERNANCE_ITEMS", "governance_items"]

mcpprobe/models.py

@@ -0,0 +1,264 @@
+"""Core data models shared by the transport, checks and reporters.
+
+Everything a reporter needs to render is a pydantic model so that the JSON
+report is a faithful, schema-stable serialisation of what the scanner saw.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+#: Maximum number of body bytes retained per request/response in evidence.
+EVIDENCE_BODY_LIMIT = 4096
+
+
+class Severity(str, Enum):
+    """Finding severity, ordered from least to most severe."""
+
+    INFO = "info"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def rank(self) -> int:
+        """Numeric rank so severities can be compared (``info`` = 0)."""
+        return _SEVERITY_ORDER.index(self)
+
+    def __ge__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.rank >= other.rank
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.rank > other.rank
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.rank <= other.rank
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.rank < other.rank
+
+
+_SEVERITY_ORDER = [
+    Severity.INFO,
+    Severity.LOW,
+    Severity.MEDIUM,
+    Severity.HIGH,
+    Severity.CRITICAL,
+]
+
+
+class Confidence(str, Enum):
+    """How sure the scanner is that a finding is a true positive."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class CheckMode(str, Enum):
+    """Passive checks only send requests a client might send plus benign
+    malformed ones; active checks need explicit authorisation."""
+
+    PASSIVE = "passive"
+    ACTIVE = "active"
+
+
+class Standards(BaseModel):
+    """Mapping of a check onto the four OWASP artefacts.
+
+    IDs are kept verbatim as published. The OWASP MCP Top 10 is still a beta
+    list, so its IDs carry a ``(beta)`` suffix in rendered output.
+    """
+
+    mcp: list[str] = Field(default_factory=list, description="OWASP MCP Top 10, e.g. MCP07:2025")
+    asi: list[str] = Field(default_factory=list, description="OWASP Agentic Top 10, e.g. ASI03")
+    llm_2025: list[str] = Field(default_factory=list, description="OWASP LLM Top 10 2025")
+    llm_2026: list[str] = Field(default_factory=list, description="OWASP LLM Top 10 2026")
+
+    def as_tags(self) -> list[str]:
+        """Flatten to a list of strings suitable for SARIF ``tags``."""
+        tags = [f"{m} (beta)" for m in self.mcp]
+        tags += list(self.asi)
+        tags += list(self.llm_2026)
+        tags += list(self.llm_2025)
+        return tags
+
+
+class EvidenceRecord(BaseModel):
+    """One request/response pair observed by the transport.
+
+    Bodies are truncated to :data:`EVIDENCE_BODY_LIMIT` bytes; only a fixed
+    subset of headers is kept and ``Authorization`` values are redacted.
+    """
+
+    id: str
+    timestamp: dt.datetime
+    transport: str = Field(description="'http' or 'stdio'")
+    method: str = Field(description="JSON-RPC method, or HTTP verb for non-RPC requests")
+    url: str | None = None
+    status: int | None = Field(default=None, description="HTTP status; None for stdio")
+    request_headers: dict[str, str] = Field(default_factory=dict)
+    response_headers: dict[str, str] = Field(default_factory=dict)
+    request_body: str = ""
+    response_body: str = ""
+    request_truncated: bool = False
+    response_truncated: bool = False
+    elapsed_ms: float | None = None
+    note: str | None = None
+    error: str | None = Field(default=None, description="Transport-level error, if any")
+
+
+class Finding(BaseModel):
+    """A single security finding produced by a check."""
+
+    id: str = Field(description="Check ID, e.g. AUTH-01")
+    title: str
+    severity: Severity
+    confidence: Confidence
+    standards: Standards
+    description: str = Field(description="What was observed and why it matters")
+    fix: str = Field(description="Plain-English remediation")
+    evidence: list[EvidenceRecord] = Field(default_factory=list)
+    evidence_excerpt: str = Field(
+        default="",
+        description="Short human-readable excerpt of the evidence (request, status, body snippet)",
+    )
+    location: str | None = Field(
+        default=None,
+        description="Where in the target the issue lives (tool name, header, URL path...)",
+    )
+    details: dict[str, Any] = Field(default_factory=dict)
+    false_positive_notes: str | None = None
+
+    @property
+    def fingerprint(self) -> str:
+        """Stable identity for de-duplication across scans (used in SARIF)."""
+        return f"{self.id}:{self.location or '-'}"
+
+
+class CheckStatus(str, Enum):
+    """Outcome of running one check, independent of whether it found anything."""
+
+    RAN = "ran"
+    SKIPPED = "skipped"
+    NOT_IMPLEMENTED = "not_implemented"
+    ERROR = "error"
+
+
+class CheckResult(BaseModel):
+    """Coverage record for a check: what ran, what was skipped and why."""
+
+    check_id: str
+    title: str
+    mode: CheckMode
+    status: CheckStatus
+    reason: str | None = None
+    findings: list[Finding] = Field(default_factory=list)
+    duration_ms: float | None = None
+
+
+class Fingerprint(BaseModel):
+    """What the transport learned about the target during negotiation."""
+
+    transport: str
+    protocol_version: str | None = None
+    flavour: str = Field(
+        default="unknown",
+        description="'stateless-2026' | 'handshake' | 'legacy-sse' | 'unknown'",
+    )
+    auth_required: bool = False
+    www_authenticate: str | None = None
+    session_id_seen: bool = False
+    server_info: dict[str, Any] = Field(default_factory=dict)
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    instructions: str | None = None
+    attempts: list[dict[str, Any]] = Field(default_factory=list)
+    error: str | None = None
+
+
+class Inventory(BaseModel):
+    """Tools, prompts and resources listed by the server."""
+
+    tools: list[dict[str, Any]] = Field(default_factory=list)
+    prompts: list[dict[str, Any]] = Field(default_factory=list)
+    resources: list[dict[str, Any]] = Field(default_factory=list)
+    tools_error: str | None = None
+    prompts_error: str | None = None
+    resources_error: str | None = None
+    tools_evidence: EvidenceRecord | None = None
+    prompts_evidence: EvidenceRecord | None = None
+    resources_evidence: EvidenceRecord | None = None
+
+    def summary(self) -> dict[str, int]:
+        return {
+            "tools": len(self.tools),
+            "prompts": len(self.prompts),
+            "resources": len(self.resources),
+        }
+
+
+class AttestationItem(BaseModel):
+    """A governance item that cannot be assessed by an automated scan.
+
+    Reported honestly as "attestation only" with a short checklist, rather
+    than faking coverage.
+    """
+
+    id: str
+    title: str
+    standards: Standards
+    reason: str = Field(description="Why a black-box scan cannot assess this")
+    checklist: list[str] = Field(default_factory=list)
+    status: str = "attestation-only"
+
+
+class ScanReport(BaseModel):
+    """Top-level report document."""
+
+    scanner: str = "mcpprobe"
+    version: str
+    target: str
+    mode: CheckMode
+    started_at: dt.datetime
+    finished_at: dt.datetime | None = None
+    fingerprint: Fingerprint | None = None
+    inventory_summary: dict[str, int] = Field(default_factory=dict)
+    checks: list[CheckResult] = Field(default_factory=list)
+    findings: list[Finding] = Field(default_factory=list)
+    attestations: list[AttestationItem] = Field(default_factory=list)
+    evidence_count: int = 0
+    authorisation_record: str | None = Field(
+        default=None, description="Path of the authorisation record JSON, if active mode"
+    )
+    notes: list[str] = Field(default_factory=list)
+
+    def counts(self) -> dict[str, int]:
+        """Number of findings per severity (all five keys always present)."""
+        out = {s.value: 0 for s in _SEVERITY_ORDER}
+        for f in self.findings:
+            out[f.severity.value] += 1
+        return out
+
+    def max_severity(self) -> Severity | None:
+        """Highest severity present, or ``None`` when there are no findings."""
+        if not self.findings:
+            return None
+        return max((f.severity for f in self.findings), key=lambda s: s.rank)
+
+
+def utcnow() -> dt.datetime:
+    """Timezone-aware UTC now (kept here so tests can monkeypatch one place)."""
+    return dt.datetime.now(dt.UTC)