ecdat 0.2.0__tar.gz → 0.3.0__tar.gz

{ecdat-0.2.0/ecdat.egg-info → ecdat-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecdat
-Version: 0.2.0
+Version: 0.3.0
 Summary: Cryptographic discovery and post-quantum readiness scanner — CLI with a gradient ASCII banner and an animated 3D globe (CBOM, CycloneDX 1.6)
 Author: ECDAT Team
 License-Expression: MIT
@@ -8,36 +8,42 @@ Project-URL: Homepage, https://github.com/profm0r14rty/ecdat
 Project-URL: Repository, https://github.com/profm0r14rty/ecdat
 Project-URL: Issues, https://github.com/profm0r14rty/ecdat/issues
 Project-URL: Changelog, https://github.com/profm0r14rty/ecdat/blob/main/CHANGELOG.md
-Keywords: cbom,cli,cryptography,cyclonedx,post-quantum,pqc,quantum,sbom,security
+Keywords: cbom,cli,cryptography,cyclonedx,post-quantum,pqc,quantum,sbom,security,tui
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Security
 Classifier: Topic :: Security :: Cryptography
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic>=2
 Requires-Dist: rich>=13.7
+Requires-Dist: textual<9,>=8.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: jsonschema; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Dynamic: license-file
 
 # ecdat
 
+[![PyPI](https://img.shields.io/pypi/v/ecdat?color=3ddc97&label=PyPI)](https://pypi.org/project/ecdat/)
+[![Python](https://img.shields.io/pypi/pyversions/ecdat?color=3ddc97)](https://pypi.org/project/ecdat/)
+[![Downloads](https://img.shields.io/pypi/dm/ecdat?color=3ddc97&label=downloads)](https://pypi.org/project/ecdat/)
+[![License: MIT](https://img.shields.io/github/license/profm0r14rty/ECDAT?color=3ddc97)](https://github.com/profm0r14rty/ECDAT/blob/main/LICENSE)
+[![SIH 2026](https://img.shields.io/badge/SIH%202026%20Internals-1st%20Place%20🏆-gold)](https://github.com/profm0r14rty/ECDAT)
+
 **ECDAT** is a [CycloneDX](https://cyclonedx.org/) **Cryptography Bill of
 Materials (CBOM) scanner for post-quantum readiness**. One command finds the
 cryptographic artefacts in a codebase — RSA, ECC, DH, DSA, MD5, SHA-1, DES,

{ecdat-0.2.0 → ecdat-0.3.0}/PYPI_README.md

@@ -1,5 +1,11 @@
 # ecdat
 
+[![PyPI](https://img.shields.io/pypi/v/ecdat?color=3ddc97&label=PyPI)](https://pypi.org/project/ecdat/)
+[![Python](https://img.shields.io/pypi/pyversions/ecdat?color=3ddc97)](https://pypi.org/project/ecdat/)
+[![Downloads](https://img.shields.io/pypi/dm/ecdat?color=3ddc97&label=downloads)](https://pypi.org/project/ecdat/)
+[![License: MIT](https://img.shields.io/github/license/profm0r14rty/ECDAT?color=3ddc97)](https://github.com/profm0r14rty/ECDAT/blob/main/LICENSE)
+[![SIH 2026](https://img.shields.io/badge/SIH%202026%20Internals-1st%20Place%20🏆-gold)](https://github.com/profm0r14rty/ECDAT)
+
 **ECDAT** is a [CycloneDX](https://cyclonedx.org/) **Cryptography Bill of
 Materials (CBOM) scanner for post-quantum readiness**. One command finds the
 cryptographic artefacts in a codebase — RSA, ECC, DH, DSA, MD5, SHA-1, DES,

{ecdat-0.2.0 → ecdat-0.3.0}/README.md

@@ -1,5 +1,12 @@
 # ECDAT - Enterprise Cryptographic Discovery & Analysis Tool
 
+[![PyPI](https://img.shields.io/pypi/v/ecdat?color=3ddc97&label=PyPI)](https://pypi.org/project/ecdat/)
+[![Python](https://img.shields.io/pypi/pyversions/ecdat?color=3ddc97)](https://pypi.org/project/ecdat/)
+[![Downloads](https://img.shields.io/pypi/dm/ecdat?color=3ddc97&label=downloads)](https://pypi.org/project/ecdat/)
+[![License: MIT](https://img.shields.io/github/license/profm0r14rty/ECDAT?color=3ddc97)](https://github.com/profm0r14rty/ECDAT/blob/main/LICENSE)
+[![CI](https://github.com/profm0r14rty/ECDAT/actions/workflows/ecdat-ci.yml/badge.svg)](https://github.com/profm0r14rty/ECDAT/actions/workflows/ecdat-ci.yml)
+[![SIH 2026](https://img.shields.io/badge/SIH%202026%20Internals-1st%20Place%20🏆-gold)](https://github.com/profm0r14rty/ECDAT)
+
 ECDAT is a Cryptography Bill of Materials (CBOM) scanner for post-quantum readiness assessment. It discovers cryptographic artefacts in source code, assesses their quantum-computing risk using Mosca's algorithm, and recommends NIST post-quantum replacements, outputting a CycloneDX 1.6 CBOM report.
 
 ## Install the CLI

{ecdat-0.2.0 → ecdat-0.3.0}/ecdat/__init__.py

@@ -1,4 +1,4 @@
-"""ECDAT — Enterprise Cryptographic Discovery & Analysis Tool."""
+"""ECDAT — Enterprise Cryptographic Discovery & Analysis Tool (app layer)."""
 
 import importlib.metadata
 
@@ -7,4 +7,4 @@ DIST_NAME = "ecdat"
 try:
     __version__ = importlib.metadata.version(DIST_NAME)
 except importlib.metadata.PackageNotFoundError:
-    __version__ = "0+unknown"
+    __version__ = "0+unknown"

ecdat-0.3.0/ecdat/cli/__init__.py

@@ -0,0 +1,14 @@
+"""ECDAT command-line interface.
+
+The :func:`main` entry point (wired as the ``ecdat`` console script and used by
+``python -m ecdat``) lives in :mod:`ecdat.cli.main`; it is re-exported here so
+both ``from ecdat.cli import main`` and ``from ecdat.cli.main import main``
+resolve to the same callable.  Importing this package stays cheap — Rich, the
+scanner engine, and Textual are all imported lazily by the command modules.
+"""
+
+from __future__ import annotations
+
+from ecdat.cli.main import main
+
+__all__ = ["main"]

ecdat-0.3.0/ecdat/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""ECDAT CLI subcommands."""

{ecdat-0.2.0 → ecdat-0.3.0}/ecdat/cli/commands/demo.py

@@ -51,6 +51,11 @@ def register(subparsers: "argparse._SubParsersAction") -> None:
         action="store_true",
         help="Copy the sample under ECDAT_HOME/demo and print its path",
     )
+    parser.add_argument(
+        "--tui",
+        action="store_true",
+        help="Open the animated TUI straight into the demo scan",
+    )
 
 
 def run(args) -> int:
@@ -66,6 +71,11 @@ def run(args) -> int:
     out_console = make_console(no_color=no_color)
     err_console = make_console(stderr=True, no_color=no_color)
 
+    if getattr(args, "tui", False):
+        from ecdat.tui import run_tui
+
+        return run_tui(auto_start=True, demo=True)
+
     if getattr(args, "path", False):
         from ecdat.services.demo import materialize_demo
 

ecdat-0.3.0/ecdat/cli/commands/explain.py

@@ -0,0 +1,204 @@
+"""``ecdat explain`` — explain an algorithm in plain English.
+
+Looks up a signature entry by name (or family) and renders a panel describing
+what it is, its quantum status, whether it is classically broken, how ECDAT
+scores it with Mosca's inequality, the recommended NIST replacement, and the
+languages ECDAT detects it in.
+
+The knowledge base is read through the public
+:mod:`ecdat_core.signature_loader` API.  Every dynamic value is wrapped in
+:class:`rich.text.Text` so knowledge-base text is never parsed as markup.
+
+Note:
+    :class:`~ecdat_core.signature_loader.SignatureEntry` has no ``aliases``
+    field, so the lookup covers ``name`` and ``family`` — the fields the real
+    model actually exposes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+from typing import List
+
+from rich.panel import Panel
+from rich.text import Text
+
+from ecdat.ui.theme import PALETTE, make_console
+from ecdat_core.signature_loader import SignatureEntry, get_all_signatures
+
+NAME = "explain"
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``explain`` subcommand to *subparsers*."""
+    parser = subparsers.add_parser(
+        "explain",
+        help="Explain an algorithm in plain English",
+        description=(
+            "Explain a signature by name or family: what it is, its quantum "
+            "status, how Mosca's inequality scores it, and what replaces it."
+        ),
+    )
+    parser.add_argument(
+        "name",
+        help="Signature name or family to explain (case-insensitive)",
+    )
+
+
+# One-paragraph, static explanation of the scoring model.  Kept as a module
+# constant so the wording is consistent across every explained algorithm.
+_MOSCA_PARAGRAPH = (
+    "ECDAT scores this with Mosca's inequality, X + Y > Z: X is the time to "
+    "migrate away from the algorithm, Y is how long the protected data must "
+    "stay secret, and Z is the estimated arrival of a cryptographically "
+    "relevant quantum computer. When X + Y exceeds Z the artefact is already "
+    "exposed, and the urgency ratio (X + Y) / Z classifies it from low through "
+    "critical."
+)
+
+
+def _find_matches(name: str) -> List[SignatureEntry]:
+    """Return entries whose name or family matches *name* case-insensitively."""
+    needle = name.strip().lower()
+    return [
+        entry
+        for entry in get_all_signatures()
+        if entry.name.lower() == needle or entry.family.lower() == needle
+    ]
+
+
+def _quantum_status(entry: SignatureEntry) -> str:
+    """Return the plain-English quantum status for *entry*.
+
+    - Symmetric families with a ``min_quantum_safe_key_bits`` threshold are
+      described as weakened by Grover's algorithm up to that key size.
+    - Otherwise quantum-vulnerable entries are broken by Shor's algorithm.
+    - Everything else is not affected.
+    """
+    if entry.min_quantum_safe_key_bits is not None:
+        return (
+            "weakened by Grover's algorithm \u2014 needs at least "
+            f"{entry.min_quantum_safe_key_bits}-bit keys"
+        )
+    if entry.quantum_vulnerable:
+        return "broken by Shor's algorithm"
+    return "not affected by quantum algorithms (quantum-safe)"
+
+
+def _build_body(entry: SignatureEntry) -> Text:
+    """Build the panel body as a :class:`~rich.text.Text` (markup-safe).
+
+    Args:
+        entry: The matched signature entry.
+
+    Returns:
+        A styled :class:`~rich.text.Text` ready to place inside a panel.
+    """
+    body = Text()
+
+    def section(title: str) -> None:
+        body.append(f"{title}\n", style=f"bold {PALETTE.accent}")
+
+    def field(label: str, value: str) -> None:
+        body.append(f"{label}: ", style=f"bold {PALETTE.text}")
+        body.append(f"{value}\n")
+
+    # What it is.
+    section("What it is")
+    field("Family", entry.family)
+    body.append("\n")
+
+    # Quantum status.
+    section("Quantum status")
+    field("Status", _quantum_status(entry))
+    if entry.classically_broken:
+        body.append("Warning: ", style=f"bold {PALETTE.critical}")
+        body.append(
+            "already broken today by classical attacks, independent of "
+            "quantum computing \u2014 do not treat it as quantum-safe.\n",
+            style=PALETTE.critical,
+        )
+    body.append("\n")
+
+    # How ECDAT scores it.
+    section("How ECDAT scores it")
+    body.append(_MOSCA_PARAGRAPH + "\n")
+    body.append("\n")
+
+    # Recommended replacement.
+    section("Recommended replacement")
+    field("Algorithm", entry.pqc_recommendation.algorithm)
+    field("FIPS reference", entry.pqc_recommendation.fips_reference)
+    body.append("\n")
+
+    # Detection coverage.
+    section("Detected in languages")
+    body.append(", ".join(sorted(entry.patterns)) + "\n")
+
+    return body
+
+
+def _render_panel(entry: SignatureEntry) -> Panel:
+    """Render the explanation panel for a single matched entry."""
+    return Panel(
+        _build_body(entry),
+        title=Text(f"ecdat explain \u00b7 {entry.name}"),
+        title_align="left",
+        border_style=PALETTE.border,
+        padding=(1, 2),
+    )
+
+
+def run(args: object) -> int:
+    """Execute the ``explain`` subcommand.
+
+    Args:
+        args: Parsed arguments with attribute ``name``.
+
+    Returns:
+        Exit code: 0 when exactly one entry matched; 2 when several or none
+        matched (several → the candidates are listed; none → close matches are
+        suggested).
+    """
+    name: str = getattr(args, "name", "")
+    out = make_console()
+
+    matches = _find_matches(name)
+
+    if len(matches) == 1:
+        out.print(_render_panel(matches[0]))
+        return 0
+
+    if len(matches) > 1:
+        out.print(
+            Text(
+                f"{len(matches)} signatures match {name!r}; "
+                f"be more specific:"
+            )
+        )
+        for entry in sorted(matches, key=lambda e: e.name):
+            out.print(Text(f"  {entry.name} \u2014 {entry.family}"))
+        return 2
+
+    # No match — offer close suggestions from the real knowledge base.
+    names = [entry.name for entry in get_all_signatures()]
+    suggestions = difflib.get_close_matches(
+        name.strip().lower(), [n.lower() for n in names], n=3
+    )
+    # Map lowercased suggestions back to their canonical names.
+    by_lower = {n.lower(): n for n in names}
+    canonical = [by_lower[s] for s in suggestions]
+
+    if canonical:
+        out.print(Text(f"No signature named {name!r}. Did you mean:"))
+        for suggestion in canonical:
+            out.print(Text(f"  {suggestion}"))
+    else:
+        out.print(
+            Text(
+                f"No signature named {name!r} "
+                f"(0 of {len(names)} signatures)."
+            )
+        )
+    return 2

ecdat-0.3.0/ecdat/cli/commands/history_cmd.py

@@ -0,0 +1,51 @@
+"""``ecdat history`` — list saved scan records."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ecdat.services.history import load_history
+
+NAME = "history"
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``history`` subcommand to *subparsers*."""
+    subparsers.add_parser(
+        "history",
+        help="Show scan history",
+        description="List the scans saved to the local ECDAT history store.",
+    )
+
+
+def run(args: object) -> int:
+    """Execute the ``history`` subcommand.
+
+    Args:
+        args: Parsed arguments (unused for history — no options).
+
+    Returns:
+        Exit code (always 0).
+    """
+    records = load_history()
+
+    if not records:
+        print("No scan history found.", file=sys.stderr)
+        return 0
+
+    # Header
+    header = f"{'#':<4} {'Scan ID':<38} {'Target':<36} {'Detections':>10} {'Scanned at'}"
+    print(header)
+    print("-" * len(header))
+
+    for i, rec in enumerate(records, start=1):
+        # Truncate long fields.
+        scan_id = rec.scan_id[:36]
+        target = rec.target[:34] + ".." if len(rec.target) > 36 else rec.target
+        detections = str(len(rec.detections))
+        scanned = rec.scanned_at[:19]  # ISO datetime (no TZ offset detail)
+
+        print(f"{i:<4} {scan_id:<38} {target:<36} {detections:>10} {scanned}")
+
+    return 0

ecdat-0.3.0/ecdat/cli/commands/mosca.py

@@ -0,0 +1,222 @@
+"""``ecdat mosca`` — Mosca's-inequality calculator with a visual timeline.
+
+Given X (data lifetime), Y (migration time) and Z (quantum arrival horizon),
+this computes the urgency ratio ``(X + Y) / Z``, classifies it with the engine's
+own :func:`ecdat_core.risk_engine.classify_urgency` (the exact thresholds the
+scanner uses — no duplicated constants), and draws the timeline from
+:func:`ecdat.ui.render.mosca_timeline`.
+
+Variable naming follows the Phase 77 spec: ``-x``/``--shelf-life`` is the data
+lifetime, ``-y``/``--migration`` is the migration time, ``-z``/``--threat`` is
+the quantum arrival horizon.
+
+Exit codes:
+    - 0 — computed successfully.
+    - 2 — usage/validation error (missing/invalid arguments).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional
+
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.text import Text
+
+from ecdat.ui.render import mosca_timeline
+from ecdat.ui.theme import PALETTE, RISK_COLORS, RISK_LABELS, make_console
+from ecdat_core.risk_engine import classify_urgency
+
+NAME = "mosca"
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``mosca`` subcommand to *subparsers*."""
+    parser = subparsers.add_parser(
+        "mosca",
+        help="Mosca's-inequality calculator with a visual timeline",
+        description=(
+            "Compute the Mosca urgency ratio (X + Y) / Z from a data "
+            "lifetime (X), migration time (Y) and quantum horizon (Z) and "
+            "draw the exposure timeline."
+        ),
+    )
+    parser.add_argument(
+        "-x",
+        "--shelf-life",
+        type=float,
+        default=None,
+        dest="x",
+        help="X — data lifetime in years (data must stay secret)",
+    )
+    parser.add_argument(
+        "-y",
+        "--migration",
+        type=float,
+        default=None,
+        dest="y",
+        help="Y — migration time in years",
+    )
+    parser.add_argument(
+        "-z",
+        "--threat",
+        type=float,
+        default=None,
+        dest="z",
+        help="Z — quantum threat horizon in years",
+    )
+
+
+def _is_interactive() -> bool:
+    """Return whether we may prompt the user for missing values.
+
+    Interactive means both stdin and stdout are TTYs — prompting into a pipe or
+    a redirected stream would either hang or corrupt the payload.
+    """
+    try:
+        return bool(sys.stdin.isatty() and sys.stdout.isatty())
+    except (AttributeError, ValueError):
+        return False
+
+
+def _fmt(value: float) -> str:
+    """Format a year value without a trailing ``.0`` for whole numbers."""
+    return str(int(value)) if float(value).is_integer() else f"{value:g}"
+
+
+def _risk_chip(level: str) -> Text:
+    """Return a coloured uppercase risk chip for *level*."""
+    color = RISK_COLORS.get(level, PALETTE.text)
+    label = RISK_LABELS.get(level, level.upper())
+    return Text(label, style=f"bold {color}")
+
+
+def _resolve(
+    raw: Optional[float],
+    *,
+    label: str,
+    flag: str,
+    out,
+) -> Optional[float]:
+    """Resolve a possibly-missing value, prompting only when interactive.
+
+    Args:
+        raw: The parsed value, or ``None`` when the flag was omitted.
+        label: Human-readable name used in the prompt ("data lifetime").
+        flag: The CLI flag spelling used in the prompt (``-x/--shelf-life``).
+        out: The console used for the interactive prompt.
+
+    Returns:
+        The resolved float value, or ``None`` when a value is required but the
+        session is non-interactive (the caller then returns a usage error).
+    """
+    if raw is not None:
+        return raw
+    if not _is_interactive():
+        return None
+    entered = Prompt.ask(
+        Text(f"{label} ({flag})", style=PALETTE.accent),
+        console=out,
+    )
+    try:
+        return float(entered)
+    except (TypeError, ValueError):
+        return None
+
+
+def run(args: object) -> int:
+    """Execute the ``mosca`` subcommand.
+
+    Args:
+        args: Parsed arguments with attributes ``x`` (data lifetime),
+            ``y`` (migration time) and ``z`` (threat horizon), any of which may
+            be ``None``.
+
+    Returns:
+        Exit code (0 on success, 2 on usage/validation error).
+    """
+    out = make_console()
+
+    raw_x: Optional[float] = getattr(args, "x", None)
+    raw_y: Optional[float] = getattr(args, "y", None)
+    raw_z: Optional[float] = getattr(args, "z", None)
+
+    x = _resolve(raw_x, label="Data lifetime", flag="-x/--shelf-life", out=out)
+    if x is None:
+        print(
+            "Error: data lifetime (-x/--shelf-life) is required and must be a "
+            "number.",
+            file=sys.stderr,
+        )
+        return 2
+
+    y = _resolve(raw_y, label="Migration time", flag="-y/--migration", out=out)
+    if y is None:
+        print(
+            "Error: migration time (-y/--migration) is required and must be a "
+            "number.",
+            file=sys.stderr,
+        )
+        return 2
+
+    z = _resolve(raw_z, label="Quantum arrival", flag="-z/--threat", out=out)
+    if z is None:
+        print(
+            "Error: quantum arrival (-z/--threat) is required and must be a "
+            "number.",
+            file=sys.stderr,
+        )
+        return 2
+
+    if x < 0 or y < 0:
+        print(
+            "Error: data lifetime (X) and migration time (Y) must be >= 0.",
+            file=sys.stderr,
+        )
+        return 2
+    if z <= 0:
+        print("Error: quantum arrival (Z) must be > 0.", file=sys.stderr)
+        return 2
+
+    total = x + y
+    urgency = total / z
+    level = classify_urgency(urgency)
+    violation = total > z
+
+    # --- headline numbers + risk chip -------------------------------------
+    line = Text()
+    line.append(f"X + Y = {_fmt(total)} vs Z = {_fmt(z)}")
+    line.append("    urgency ratio ")
+    line.append(_fmt(round(urgency, 2)))
+    line.append("    ")
+    line.append(_risk_chip(level))
+
+    # --- plain-English verdict -------------------------------------------
+    if violation:
+        verdict = Text(
+            f"You would be exposed for {_fmt(total - z)} years.",
+            style=f"bold {PALETTE.critical}",
+        )
+    else:
+        verdict = Text(
+            f"You have a {_fmt(z - total)}-year safety margin.",
+            style=PALETTE.safe,
+        )
+
+    out.print(
+        Panel(
+            Text.assemble(
+                line,
+                "\n\n",
+                verdict,
+            ),
+            title="ecdat mosca",
+            title_align="left",
+            border_style=PALETTE.border,
+            padding=(1, 2),
+        )
+    )
+    out.print(mosca_timeline(x, y, z))
+    return 0

ecdat-0.3.0/ecdat/cli/commands/report.py

@@ -0,0 +1,67 @@
+"""``ecdat report`` — show a Markdown or HTML report for a scan."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ecdat.services.exporters import export_html, export_markdown
+from ecdat.services.history import get_by_id, get_latest
+
+NAME = "report"
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    """Attach the ``report`` subcommand to *subparsers*."""
+    parser = subparsers.add_parser(
+        "report",
+        help="Show a report for a scan",
+        description="Re-render a saved scan as Markdown or HTML.",
+    )
+    parser.add_argument(
+        "scan_ref",
+        help="'latest' or a scan ID",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["markdown", "html"],
+        default="markdown",
+        dest="format",
+        help="Output format (default: markdown)",
+    )
+
+
+def run(args: object) -> int:
+    """Execute the ``report`` subcommand.
+
+    Args:
+        args: Parsed arguments with attributes ``scan_ref`` and ``format``.
+
+    Returns:
+        Exit code (0 on success, 1 if scan not found, 2 on usage error).
+    """
+    scan_ref: str = args.scan_ref  # type: ignore[union-attr]
+    fmt: str = args.format  # type: ignore[union-attr]
+
+    if scan_ref == "latest":
+        result = get_latest()
+    else:
+        result = get_by_id(scan_ref)
+
+    if result is None:
+        if scan_ref == "latest":
+            print("Error: no scan history found", file=sys.stderr)
+        else:
+            print(f"Error: scan {scan_ref!r} not found in history", file=sys.stderr)
+        return 1
+
+    if fmt == "markdown":
+        sys.stdout.write(export_markdown(result))
+    elif fmt == "html":
+        sys.stdout.write(export_html(result))
+    else:
+        print(f"Error: unknown format {fmt!r}", file=sys.stderr)
+        return 2
+
+    return 0