← Files Codex SecurityARCHIVED FILE

scripts/report_projection.py

40.7 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

#!/usr/bin/env python3
"""Project canonical Codex Security scan JSON into the standard reports."""

from __future__ import annotations

import argparse
import json
import re
from collections import Counter
from collections.abc import Iterator
from itertools import chain
from typing import Any

SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}
CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
REPORTABLE_SEVERITIES = {"critical", "high", "medium", "low"}
THREAT_MODEL_SECTIONS = (
    ("Assets", "assets"),
    ("Trust Boundaries", "trustBoundaries"),
    ("Attacker Capabilities", "attackerCapabilities"),
    ("Security Objectives", "securityObjectives"),
    ("Assumptions", "assumptions"),
)
DISPOSITION_LABELS = {
    "reported": "Reported",
    "no_issue_found": "No issue found",
    "rejected": "Rejected",
    "not_applicable": "Not applicable",
    "needs_follow_up": "Needs follow-up",
}
WRITEUP_REPORT_PATH_RE = re.compile(r"^findings/([a-z0-9][a-z0-9._-]*)/\1\.md$")
INLINE_CODE_RE = r"(?<!`)`[^`\n]+`(?!`)"
ENTITY_AMP_RE = r"&(?=(?:#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]*);)"
WWW_LINK_RE = r"(?<![^\s*_~(])(?i:www)\.[^\s<>]+"


class ReportProjectionError(ValueError):
    """Raised when a canonical scan cannot be projected into a valid report."""


def markdown_threat_model_content(model: dict[str, Any]) -> str | None:
    """Return nonblank authored content for a Markdown model, otherwise None."""
    content = model.get("content")
    if model.get("format") == "markdown" and isinstance(content, str) and content.strip():
        return content
    return None


def _escape_markdown(value: str) -> str:
    # Locate whole URLs before matching code spans: a URL can contain backticks.
    urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]
    # Preserve protocol-relative and fuzzy links without a domain/TLD table.
    for match in re.finditer(r"[^\s<>]+", value):
        token = match[0]
        dot = token.split("/", 1)[0].find(".")
        if "//" in token or (dot >= 0 and re.search(r"[/?#]", token[dot + 1 :])):
            urls.append(match.span())
    punctuation = r"[\\`*_\[\]<>]|" + ENTITY_AMP_RE
    pattern = f"(?P<code>{INLINE_CODE_RE})|{punctuation}"

    def escape(match: re.Match[str]) -> str:
        if match.lastgroup == "code":
            return match[0]
        # GFM autolinks retain backslashes literally, including in query strings.
        if match[0] == "&" and any(start <= match.start() < end for start, end in urls):
            return "&"
        return "\\" + match[0]

    return re.sub(pattern, escape, value)


def _text(value: Any, fallback: str) -> str:
    candidate = value if isinstance(value, str) and value.strip() else fallback
    normalized = " ".join(candidate.split())
    if re.match(r"^(?:#{1,6}\s|[-*+]\s|>\s|```|~~~|\d+[.)]\s|\|)", normalized):
        normalized = f"Text: {normalized}"
    return _escape_markdown(normalized)


def _string_values(value: Any) -> Iterator[str]:
    if isinstance(value, str):
        yield value
    elif isinstance(value, list):
        yield from (item for item in value if isinstance(item, str))


def _strings(value: Any) -> list[str]:
    return [text for item in _string_values(value) if (text := _text(item, ""))]


def _path_label(value: str, *, ensure_ascii: bool = False) -> str:
    if "," in value or value != " ".join(value.split()) or any(ord(c) < 32 for c in value):
        quoted = json.dumps(value, ensure_ascii=ensure_ascii)
        return "".join(c if c.isprintable() else json.dumps(c)[1:-1] for c in quoted)
    return value


def _path_text(value: str, *, ensure_ascii: bool = False) -> str:
    label = _path_label(value, ensure_ascii=ensure_ascii)
    if label != value or re.search(ENTITY_AMP_RE, value):
        marker = _code_fence(label, minimum=1)
        padding = " " if label.startswith("`") or label.endswith("`") else ""
        return f"{marker}{padding}{label}{padding}{marker}"
    return re.sub(r"([\\`*_\[\]<>])", r"\\\1", value)


def _cell(value: Any) -> str:
    return _text(value, "none").replace("|", "\\|").replace("\n", "<br>")


def _deep_report_id(finding: dict[str, Any]) -> str:
    extensions = finding.get("extensions")
    if isinstance(extensions, dict):
        report_id = extensions.get("reportId")
        if isinstance(report_id, str) and report_id.strip():
            return report_id
        ledger_row_id = extensions.get("ledgerRowId")
        if isinstance(ledger_row_id, str) and ledger_row_id.strip():
            return ledger_row_id
    identity = finding.get("identity")
    if isinstance(identity, dict):
        instance = identity.get("instance")
        if isinstance(instance, str) and instance.strip():
            return instance
    occurrence_id = finding.get("occurrenceId")
    return (
        occurrence_id
        if isinstance(occurrence_id, str) and occurrence_id.strip()
        else "Unidentified report"
    )


def _deep_candidate_id(finding: dict[str, Any]) -> str:
    extensions = finding.get("extensions")
    if isinstance(extensions, dict):
        candidate_id = extensions.get("candidateId")
        if isinstance(candidate_id, str) and candidate_id.strip():
            return candidate_id
    return _deep_report_id(finding)


def _has_deep_child_metadata(finding: dict[str, Any]) -> bool:
    extensions = finding.get("extensions")
    if not isinstance(extensions, dict):
        return False
    return any(
        isinstance(extensions.get(field), str) and extensions[field].strip()
        for field in ("candidateId", "reportId")
    )


def uses_deep_presentation(coverage: dict[str, Any], findings: list[dict[str, Any]]) -> bool:
    """Select deep-report formatting for repository scans in deep mode and scoped scans with deep-child metadata."""
    if coverage.get("mode") == "deep_repository":
        return True
    if coverage.get("mode") != "scoped_path":
        return False
    # Scoped deep scans can arrive as scoped_path artifacts. The child ids are
    # the stable deep-scan signal; ordinary scoped scans do not emit them.
    return any(_has_deep_child_metadata(finding) for finding in findings)


def _deep_title_parts(finding: dict[str, Any], report_id: str) -> tuple[str, str | None]:
    title = finding.get("title")
    if not isinstance(title, str):
        return "Untitled finding", None
    normalized = " ".join(title.split())
    match = re.fullmatch(r"(.+?)\s+\[([^\[\]\n]+)\]", normalized)
    if match is None:
        return normalized, None
    annotation = match.group(2)
    extensions = finding.get("extensions")
    recognized_ids = [report_id]
    if isinstance(extensions, dict):
        ledger_row_id = extensions.get("ledgerRowId")
        if isinstance(ledger_row_id, str) and ledger_row_id.strip():
            recognized_ids.append(ledger_row_id)
    if any(
        annotation == report_id or annotation.startswith(f"{report_id};")
        for report_id in recognized_ids
    ):
        return match.group(1), annotation
    return normalized, None


def _deep_group_levels(
    group: list[tuple[int, dict[str, Any], str | None]],
    field: str,
    order: dict[str, int],
) -> str:
    levels = {finding[field]["level"] for _, finding, _ in group}
    return "<br>".join(sorted(levels, key=lambda level: order.get(level, len(order))))


def _deep_group_row(group: list[tuple[int, dict[str, Any], str | None]]) -> str:
    report_ids = [_deep_report_id(finding) for _, finding, _ in group]
    report_counts = Counter(report_ids)
    titles = []
    labels = []
    for report_id, (_, finding, _) in zip(report_ids, group, strict=True):
        title, annotation = _deep_title_parts(finding, report_id)
        titles.append(_cell(title))
        labels.append(annotation if report_counts[report_id] > 1 and annotation else report_id)

    label_counts = Counter(labels)
    report_links = []
    writeup_links = []
    for report_id, label, (number, finding, path) in zip(report_ids, labels, group, strict=True):
        identity = finding.get("identity")
        if label_counts[label] > 1 and isinstance(identity, dict):
            label = identity.get("instance") or report_id
        label = _cell(label)
        report_links.append(f"[{label}](#finding-{number})")
        writeup_links.append(f"[Open {label}]({path})" if path else f"{label}: inline below")
    return (
        f"| {'<br>'.join(dict.fromkeys(titles))} | {'<br>'.join(report_links)} "
        f"| {_deep_group_levels(group, 'severity', SEVERITY_ORDER)} "
        f"| {_deep_group_levels(group, 'confidence', CONFIDENCE_ORDER)} "
        f"| {'<br>'.join(writeup_links)} |"
    )


def _writeup_report_path(finding: dict[str, Any]) -> str | None:
    writeup = finding.get("writeup")
    if writeup is None:
        return None
    if not isinstance(writeup, dict):
        raise ReportProjectionError("finding writeup must be an object")
    report_path = writeup.get("reportPath")
    if not isinstance(report_path, str) or not WRITEUP_REPORT_PATH_RE.fullmatch(report_path):
        raise ReportProjectionError("finding writeup has an invalid reportPath")
    return report_path


def _hardening_portfolio_path(scan: dict[str, Any]) -> str | None:
    hardening = scan.get("hardening")
    if hardening is None:
        return None
    if not isinstance(hardening, dict):
        raise ReportProjectionError("scan hardening must be an object")
    portfolio_path = hardening.get("portfolioPath")
    if portfolio_path != "hardening/hardening.md":
        raise ReportProjectionError("scan hardening has an invalid portfolioPath")
    return portfolio_path


def _bullet_section(heading: str, items: list[str]) -> list[str]:
    return ["", heading, *(f"- {item}" for item in items)] if items else []


def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:
    """Yield evidence objects with nonblank code in their original order."""
    for items in catalogs:
        if isinstance(items, list):
            yield from (
                item
                for item in items
                if isinstance(item, dict)
                and isinstance(item.get("code"), str)
                and item["code"].strip()
            )


def embedded_code_evidence(section: dict[str, Any]) -> Iterator[dict[str, Any]]:
    """Collect code evidence from both supported field spellings."""
    return code_evidence_rows(section.get("codeEvidence"), section.get("code_evidence"))


def _code_evidence_catalog(finding: dict[str, Any]) -> dict[str, dict[str, Any]]:
    catalog = {}
    for item in embedded_code_evidence(finding):
        if isinstance(item.get("id"), str):
            catalog.setdefault(item["id"], item)
    return catalog


def _section_code_evidence(
    catalog: dict[str, dict[str, Any]], *sections: dict[str, Any]
) -> list[dict[str, Any]]:
    unique: dict[tuple[str, str], dict[str, Any]] = {}
    for section in sections:
        referenced = (
            catalog[ref]
            for key in ("evidenceRefs", "evidence_refs")
            for ref in _string_values(section.get(key))
            if ref in catalog
        )
        for item in chain(referenced, embedded_code_evidence(section)):
            unique.setdefault((str(item.get("id", "")), item["code"]), item)
    return list(unique.values())


def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:
    """Return the first recorded root-cause field name and its merged detail, or (None, None) if absent."""
    keys = [key for key in ("rootCause", "root_cause") if key in value]
    if not keys:
        return None, None
    if len(keys) == 1:
        detail = value[keys[0]]
        return keys[0], detail if isinstance(detail, (str, dict)) else None
    details: list[dict[str, Any]] = []
    for key in keys:
        detail = value[key]
        if isinstance(detail, str):
            details.append({"summary": detail})
        elif isinstance(detail, dict):
            details.append(detail)
    if not details:
        return keys[0], None

    merged: dict[str, Any] = {}
    text_fields = {
        "cause",
        "code",
        "description",
        "detail",
        "explanation",
        "rationale",
        "summary",
        "why",
    }
    for detail in details:
        for field, item in detail.items():
            if field in (
                "evidenceRefs",
                "evidence_refs",
                "codeEvidence",
                "code_evidence",
                "language",
            ):
                continue
            if field in text_fields and (not isinstance(item, str) or not item.strip()):
                continue
            current = merged.get(field)
            if (
                field not in merged
                or current in (None, "", [], {})
                or (isinstance(current, str) and not current.strip())
            ):
                merged[field] = item

    evidence_values = [
        detail[field]
        for detail in details
        for field in ("evidenceRefs", "evidence_refs")
        if field in detail
    ]
    if evidence_values:
        merged["evidenceRefs"] = list(
            dict.fromkeys(item for evidence in evidence_values for item in _string_values(evidence))
        )

    embedded_evidence = [
        item
        for detail in details
        for field in ("codeEvidence", "code_evidence")
        for item in (detail.get(field, []) if isinstance(detail.get(field), list) else [])
    ]
    if embedded_evidence:
        merged["codeEvidence"] = embedded_evidence

    code = merged.get("code")
    matching_details = (
        details
        if not isinstance(code, str) or not code.strip()
        else [detail for detail in details if detail.get("code") == code]
    )
    language = next(
        (
            detail["language"]
            for detail in matching_details
            if isinstance(detail.get("language"), str) and detail["language"].strip()
        ),
        None,
    )
    if language is not None:
        merged["language"] = language
    return keys[0], merged


def _root_cause_code_evidence(
    finding: dict[str, Any], root_cause: dict[str, Any], catalog: dict[str, dict[str, Any]]
) -> list[dict[str, Any]]:
    evidence = _section_code_evidence(catalog, root_cause)
    legacy_code = root_cause.get("code")
    if not isinstance(legacy_code, str) or not legacy_code.strip():
        return evidence
    if any(item["code"] == legacy_code for item in evidence):
        return evidence
    root_location = next(
        (
            location
            for location in finding.get("locations", [])
            if isinstance(location, dict) and location.get("role") == "root_control"
        ),
        {},
    )
    return [
        *evidence,
        {
            "code": legacy_code,
            "label": "Broken control",
            "language": root_cause.get("language", ""),
            "location": root_location,
        },
    ]


def _code_evidence_location(item: dict[str, Any]) -> str:
    location = item.get("location")
    if isinstance(location, str):
        return " ".join(location.split())
    if isinstance(location, dict):
        item = location
    path = item.get("path")
    start = item.get("startLine")
    end = item.get("endLine")
    if not isinstance(path, str) or not path:
        return ""
    path = _path_label(path)
    if not isinstance(start, int) or isinstance(start, bool) or start < 1:
        return path
    if not isinstance(end, int) or isinstance(end, bool) or end <= start:
        return f"{path}:{start}"
    return f"{path}:{start}-{end}"


def _code_fence(code: str, minimum: int = 3) -> str:
    longest_run = max((len(match.group(0)) for match in re.finditer(r"`+", code)), default=0)
    return "`" * max(minimum, longest_run + 1)


def _code_evidence_lines(evidence: list[dict[str, Any]]) -> list[str]:
    lines: list[str] = []
    for index, item in enumerate(evidence):
        label = _text(item.get("label"), f"Code evidence {index + 1}")
        location = _code_evidence_location(item)
        explanation = _text(item.get("explanation"), "")
        language = item.get("language") if isinstance(item.get("language"), str) else ""
        language = language if re.fullmatch(r"[A-Za-z0-9_+.-]*", language) else ""
        code = item["code"]
        fence = _code_fence(code)
        heading = f"**{label}**"
        if location:
            marker = _code_fence(location, minimum=1)
            padding = " " if location.startswith("`") or location.endswith("`") else ""
            heading += f" — {marker}{padding}{location}{padding}{marker}"
        lines.extend(["", heading])
        if explanation:
            lines.extend(["", explanation])
        lines.extend(["", f"{fence}{language}", code, fence])
    return lines


def _level_mix(findings: list[dict[str, Any]], field: str, order: dict[str, int]) -> str:
    counts = Counter(finding[field]["level"] for finding in findings)
    return ", ".join(f"{level}: {counts[level]}" for level in order if counts[level]) or "none"


def _locations(finding: dict[str, Any]) -> str:
    rendered = []
    for location in finding["locations"]:
        start = location["startLine"]
        end = location.get("endLine", start)
        suffix = f":{start}" if end == start else f":{start}-{end}"
        rendered.append(f"{_path_text(location['path'])}{suffix}")
    return ", ".join(rendered)


def _finding_sort_key(finding: dict[str, Any]) -> tuple[int, str, str]:
    return (
        SEVERITY_ORDER.get(finding["severity"]["level"], len(SEVERITY_ORDER)),
        finding.get("occurrenceId", ""),
        finding["title"],
    )


def _target_scope_lines(target: dict[str, Any]) -> list[str]:
    lines = [
        f"- Target kind: {_text(target.get('kind'), 'not recorded')}",
        f"- Target ID: {_text(target.get('targetId'), 'not recorded')}",
    ]
    base_revision = _text(target.get("baseRevision"), "")
    head_revision = _text(target.get("headRevision"), "")
    if base_revision or head_revision:
        lines.append(
            f"- Revision range: {base_revision or 'unknown'}...{head_revision or 'unknown'}"
        )
    revision = _text(target.get("revision"), "")
    if revision:
        lines.append(f"- Revision: {revision}")
    snapshot_digest = _text(target.get("snapshotDigest"), "")
    if snapshot_digest:
        lines.append(f"- Snapshot digest: {snapshot_digest}")
    return lines


def _surface_notes(surface: dict[str, Any]) -> str:
    notes = surface.get("notes", "No additional canonical notes were recorded.")
    receipt_refs = surface.get("receiptRefs", [])
    if not isinstance(receipt_refs, list) or not receipt_refs:
        return _cell(notes)
    evidence = ", ".join(item for item in receipt_refs if isinstance(item, str))
    if not evidence:
        return _cell(notes)
    return _cell(f"{notes} Evidence: {evidence}")


def _remediation_section(finding: dict[str, Any]) -> list[str]:
    remediation = _text(finding.get("remediation"), "No canonical remediation was recorded.")
    lines = ["", "#### Remediation", "", remediation]
    seen = {remediation}
    originals: list[tuple[str, dict[str, Any]]] = []
    pending = [("finding", finding)]
    seen_findings: set[int] = set()
    while pending:
        source_id, original = pending.pop()
        if id(original) in seen_findings:
            continue
        seen_findings.add(id(original))
        originals.append((source_id, original))
        provenance = original.get("provenance")
        if not isinstance(provenance, dict):
            continue
        previous = provenance.get("previousFindings")
        if isinstance(previous, list):
            pending.extend(
                (source_id, item) for item in reversed(previous) if isinstance(item, dict)
            )
        sources = provenance.get("sourceFindings")
        if isinstance(sources, list):
            pending.extend(
                (_text(source.get("id"), "finding"), source["finding"])
                for source in reversed(sources)
                if isinstance(source, dict) and isinstance(source.get("finding"), dict)
            )
    for source_id, original in originals[1:]:
        text = _text(original.get("remediation"), "")
        if text and text not in seen:
            seen.add(text)
            lines.extend(["", f"Source {source_id}: {text}"])
    for field, label in (
        ("remediationTests", "Tests"),
        ("preventiveControls", "Preventive controls"),
    ):
        values = list(
            dict.fromkeys(
                value for _, original in originals for value in _strings(original.get(field))
            )
        )
        lines.extend(_bullet_section(f"{label}:", values))
    return lines


def _finding_header(number: int, finding: dict[str, Any]) -> list[str]:
    cwes = ", ".join(finding["taxonomy"]["cwe"]) or "none"
    title = _text(finding["title"], "Untitled finding")
    return [
        f'<a id="finding-{number}"></a>',
        "",
        f"### [{number}] {title}",
        "",
        "| Field | Value |",
        "| --- | --- |",
        f"| Severity | {_cell(finding['severity']['level'])} |",
        f"| Confidence | {_cell(finding['confidence']['level'])} |",
        f"| Confidence rationale | {_cell(finding['confidence']['rationale'])} |",
        f"| Category | {_cell(finding['taxonomy']['category'])} |",
        f"| CWE | {_cell(cwes)} |",
        "| Affected lines | " + _locations(finding).replace("|", "\\|") + " |",
    ]


def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
    validation = finding.get("validation") if isinstance(finding.get("validation"), dict) else {}
    _, raw_root_cause = merged_root_cause(finding)
    root_cause = raw_root_cause if isinstance(raw_root_cause, dict) else {}
    attack_path = finding.get("attackPath") if isinstance(finding.get("attackPath"), dict) else {}
    dataflow_sections = [
        {"summary": value} if isinstance(value, str) else value
        for key in ("dataFlow", "dataflow", "data_flow")
        if isinstance((value := attack_path.get(key)), (str, dict))
    ]
    dataflow: dict[str, Any] = {}
    for section in dataflow_sections:
        for key in ("summary", "source", "sink", "outcome"):
            value = section.get(key)
            if isinstance(value, str) and value.strip():
                dataflow.setdefault(key, value)
    transformations = dict.fromkeys(
        value
        for section in dataflow_sections
        for value in _string_values(section.get("transformations"))
        if value.strip()
    )
    raw_reachability = attack_path.get("reachability")
    reachability = (
        {"summary": raw_reachability}
        if isinstance(raw_reachability, str)
        else raw_reachability
        if isinstance(raw_reachability, dict)
        else {}
    )
    severity = finding["severity"]
    validation_outcomes = [
        (label, text)
        for label, key in (
            ("Status", "status"),
            ("Disposition", "disposition"),
            ("Result", "result"),
        )
        if (text := _text(validation.get(key), ""))
    ]
    validation_summary = _text(
        validation.get("summary"),
        "Validation outcomes are recorded below."
        if validation_outcomes
        else f"{finding['confidence']['rationale']} Validation details were not recorded separately.",
    )
    root_cause_summary = _text(
        raw_root_cause if isinstance(raw_root_cause, str) else root_cause.get("summary"),
        "",
    )
    catalog = _code_evidence_catalog(finding)
    root_cause_code_evidence = _root_cause_code_evidence(finding, root_cause, catalog)
    validation_code_evidence = _section_code_evidence(catalog, validation)
    dataflow_code_evidence = _section_code_evidence(catalog, attack_path, *dataflow_sections)
    reachability_code_evidence = _section_code_evidence(catalog, reachability)
    dataflow_summary = _text(dataflow.get("summary"), "") or (
        f"The canonical finding records the affected path at {_locations(finding)}, "
        "but no expanded source-to-sink narrative was recorded."
    )
    reachability_summary = _text(reachability.get("summary"), "") or _text(
        attack_path.get("summary"),
        "Reachability was not recorded beyond the canonical finding summary and affected locations.",
    )
    severity_rationale = _text(
        severity.get("rationale"),
        f"The scan assigned {severity['level']} severity; no separate canonical severity rationale was recorded.",
    )
    severity_change = _text(
        severity.get("changeConditions"),
        "Additional runtime or deployment evidence could raise or lower this severity.",
    )
    lines = [
        *_finding_header(number, finding),
        "",
        "#### Summary",
        "",
        _text(finding["summary"], "No canonical finding summary was recorded."),
    ]
    if root_cause_summary or root_cause_code_evidence:
        lines.extend(["", "#### Root Cause", ""])
        if root_cause_summary:
            lines.append(root_cause_summary)
        lines.extend(_code_evidence_lines(root_cause_code_evidence))
    lines.extend(["", "#### Validation", "", validation_summary])
    if validation.get("method"):
        lines.extend(["", f"Validation method: {_text(validation['method'], 'not recorded')}"])
    if validation_outcomes:
        lines.extend(["", *(f"- **{label}:** {value}" for label, value in validation_outcomes)])
    lines.extend(_code_evidence_lines(validation_code_evidence))
    for label, key in (
        ("Assertions", "assertions"),
        ("Evidence", "evidence"),
        ("Counterevidence and remaining uncertainty", "counterEvidence"),
        ("Limitations", "limitations"),
    ):
        lines.extend(_bullet_section(f"{label}:", _strings(validation.get(key))))
    lines.extend(["", "#### Dataflow", "", dataflow_summary])
    lines.extend(_bullet_section("Attack steps:", _strings(attack_path.get("steps"))))
    for label, key in (("Source", "source"), ("Sink", "sink"), ("Outcome", "outcome")):
        if dataflow.get(key):
            lines.extend(["", f"- **{label}:** {_text(dataflow[key], 'not recorded')}"])
    lines.extend(
        _bullet_section("Transformations:", [_text(value, "") for value in transformations])
    )
    lines.extend(_code_evidence_lines(dataflow_code_evidence))
    lines.extend(["", "#### Reachability", "", reachability_summary])
    for label, key in (
        ("Attacker", "attacker"),
        ("Entry point", "entrypoint"),
        ("Source", "source"),
        ("Sink", "sink"),
        ("Outcome", "outcome"),
    ):
        if reachability.get(key):
            lines.extend(["", f"- **{label}:** {_text(reachability[key], 'not recorded')}"])
    preconditions = list(
        dict.fromkeys(
            _strings(attack_path.get("preconditions")) + _strings(reachability.get("preconditions"))
        )
    )
    lines.extend(_bullet_section("Preconditions:", preconditions))
    for label, key in (
        ("Assumptions", "assumptions"),
        ("Existing controls", "controls"),
        ("Blind spots", "blindspots"),
        ("Limitations", "limitations"),
    ):
        lines.extend(_bullet_section(f"{label}:", _strings(attack_path.get(key))))
    lines.extend(_code_evidence_lines(reachability_code_evidence))
    lines.extend(
        [
            "",
            "#### Severity",
            "",
            f"**{severity['level'].capitalize()}** — {severity_rationale}",
            "",
            severity_change,
        ]
    )
    for label, key in (("Impact", "impact"), ("Likelihood", "likelihood")):
        assessment = attack_path.get(key)
        if isinstance(assessment, str):
            rendered = _text(assessment, "")
            if rendered:
                lines.extend(["", f"**{label} assessment:** {rendered}"])
            continue
        if not isinstance(assessment, dict):
            continue
        details = [
            (detail_label, text)
            for detail_label, detail_key in (
                ("Level", "level"),
                ("Rationale", "rationale"),
                ("Why", "why"),
            )
            if (text := _text(assessment.get(detail_key), ""))
        ]
        if details:
            lines.extend(
                ["", f"{label} assessment:", *(f"- **{name}:** {value}" for name, value in details)]
            )
    lines.extend(_remediation_section(finding))
    return lines


def _linked_finding_section(number: int, finding: dict[str, Any], report_path: str) -> list[str]:
    link = f"[detailed technical write-up]({report_path})"
    lines = _finding_header(number, finding)
    for heading in ("Summary", "Validation", "Dataflow", "Reachability", "Severity"):
        lines.extend(["", f"#### {heading}", "", f"See the {link}."])
    if any(
        finding.get("provenance", {}).get(field) for field in ("sourceFindings", "previousFindings")
    ):
        lines.extend(_remediation_section(finding))
    else:
        lines.extend(["", "#### Remediation", "", f"See the {link}."])
    return lines


def build_report_markdown(
    manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
) -> str:
    """Render findings and review coverage as a Markdown report ending in a newline.

    Args:
        manifest: Scan metadata, target, and scope.
        findings_document: Canonical findings for the scan.
        coverage: Review coverage for older manifests. Newer scans supply review state inline.

    Raises:
        ReportProjectionError: Reportable findings share a writeup path.
    """
    scan = manifest["scan"]
    if "review" in scan and "coverageRef" not in scan:
        from review_state import review_state

        coverage = review_state(scan)
    target = scan["target"]
    scope = scan["scope"]
    threat_model = scan.get("threatModel") if isinstance(scan.get("threatModel"), dict) else {}
    findings = sorted(
        (
            finding
            for finding in findings_document["findings"]
            if finding["severity"]["level"] in REPORTABLE_SEVERITIES
        ),
        key=_finding_sort_key,
    )
    numbered_findings = [
        (number, finding, _writeup_report_path(finding))
        for number, finding in enumerate(findings, 1)
    ]
    writeup_counts = Counter(path for _, _, path in numbered_findings if path is not None)
    duplicate_writeup_paths = sorted(path for path, count in writeup_counts.items() if count > 1)
    if duplicate_writeup_paths:
        raise ReportProjectionError(
            "reportable findings have duplicate writeup reportPath values: "
            + ", ".join(duplicate_writeup_paths)
        )
    deep_presentation = uses_deep_presentation(coverage, findings)
    deep_finding_groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
    if deep_presentation:
        for entry in numbered_findings:
            _, finding, _ = entry
            deep_finding_groups.setdefault(_deep_candidate_id(finding), []).append(entry)
    hardening_portfolio_path = _hardening_portfolio_path(scan)
    include_paths = [
        _path_text(path) for path in coverage.get("includePaths", scope.get("includePaths", []))
    ]
    exclude_paths = [
        _path_text(path) for path in coverage.get("excludePaths", scope.get("excludePaths", []))
    ]
    limitations = _strings(scope.get("limitations"))
    explicit_exclusions = coverage.get("explicitExclusions", [])
    lines = [
        f"# Security Review: {_text(target['displayName'], 'Unknown target')}",
        "",
        "## Scope",
        "",
        _text(
            scope.get("summary"),
            "The scan was configured for the include paths and exclusions listed below.",
        ),
        "",
        f"- Scan mode: {coverage['mode']}",
        *_target_scope_lines(target),
        f"- Included paths: {', '.join(include_paths) or 'none'}",
        f"- Excluded paths: {', '.join(exclude_paths) or 'none'}",
    ]
    artifacts_reviewed = _strings(scope.get("artifactsReviewed"))
    if artifacts_reviewed:
        lines.extend(["- Artifacts reviewed: " + ", ".join(artifacts_reviewed)])
    context = _text(scope.get("context"), "")
    if context:
        lines.extend([f"- Scan context: {context}"])
    for exclusion in explicit_exclusions:
        if isinstance(exclusion, dict):
            limitations.append(
                f"Excluded {_text(exclusion.get('pattern'), 'unspecified')}: "
                f"{_text(exclusion.get('reason'), 'reason not recorded')}"
            )
    lines.extend(_bullet_section("Limitations and exclusions:", limitations))
    summary_count_lines = (
        [
            f"| Reportable DSS findings | {len(deep_finding_groups)} |",
            f"| Report instances | {len(findings)} |",
            f"| Report severity mix | {_level_mix(findings, 'severity', SEVERITY_ORDER)} |",
            f"| Report confidence mix | {_level_mix(findings, 'confidence', CONFIDENCE_ORDER)} |",
        ]
        if deep_presentation
        else [
            f"| Reportable findings | {len(findings)} |",
            f"| Severity mix | {_level_mix(findings, 'severity', SEVERITY_ORDER)} |",
            f"| Confidence mix | {_level_mix(findings, 'confidence', CONFIDENCE_ORDER)} |",
        ]
    )
    lines.extend(
        [
            "",
            "### Scan Summary",
            "",
            "| Field | Value |",
            "| --- | --- |",
            f"| Scan outcome | {scan.get('status', 'completed')} |",
            *summary_count_lines,
            f"| Validation mode | {_cell(scope.get('validationMode', 'not recorded'))} |",
            "",
            "Canonical artifacts: `scan-manifest.json` and `findings.json`. This report is a deterministic projection of those files.",
            "",
            "## Threat Model",
            "",
        ]
    )
    content = markdown_threat_model_content(threat_model)
    if content is not None:
        lines.append(content)
    else:
        lines.append(
            _text(
                threat_model.get("summary"),
                "No explicit canonical threat-model summary was recorded.",
            )
        )
        for heading, key in THREAT_MODEL_SECTIONS:
            values = _strings(threat_model.get(key))
            if values:
                lines.extend(["", f"### {heading}", "", *(f"- {value}" for value in values)])
    reviews = scan.get("reviewState", {}).get("reviews")
    if isinstance(reviews, list) and any(
        isinstance(review, dict) and isinstance(review.get("threatModel"), dict)
        for review in reviews
    ):
        lines.extend(
            [
                "",
                (
                    "Other reviews recorded different threat models. See the `threatModel` fields "
                    "in `scan.reviewState.reviews` in the [scan manifest](scan-manifest.json)."
                ),
            ]
        )
    lines.extend(["", "## Findings", ""])
    informational_count = sum(
        finding["severity"]["level"] == "informational" for finding in findings_document["findings"]
    )
    informational_note = ""
    if informational_count:
        noun = "finding" if informational_count == 1 else "findings"
        informational_note = (
            f"This report omits details for {informational_count} informational {noun}. "
            "See `findings.json` or export the findings as SARIF or CSV."
        )
    if findings:
        if informational_note:
            lines.extend([informational_note, ""])
        if deep_presentation:
            lines.extend(
                [
                    "| Findings | Reports | Severity | Confidence | Detailed write-up |",
                    "| --- | --- | --- | --- | --- |",
                ]
            )
            lines.extend(_deep_group_row(group) for group in deep_finding_groups.values())
        else:
            lines.extend(
                [
                    "| Finding | Severity | Confidence | Detailed write-up |",
                    "| --- | --- | --- | --- |",
                ]
            )
            for number, finding, report_path in numbered_findings:
                title = _cell(finding["title"])
                finding_link = f"[{title}](#finding-{number})"
                writeup_link = f"[Open report]({report_path})" if report_path else "inline below"
                lines.append(
                    f"| {finding_link} | {finding['severity']['level']} "
                    f"| {finding['confidence']['level']} | {writeup_link} |"
                )
        lines.extend(
            [
                "",
                "### Confidence Scale",
                "",
                "| Label | Meaning |",
                "| --- | --- |",
                "| high | Direct evidence supports the finding with no material unresolved blocker. |",
                "| medium | Evidence supports a plausible issue, but material runtime or reachability proof remains. |",
                "| low | Evidence is incomplete and the item is retained only for explicit follow-up. |",
            ]
        )
        for number, finding, report_path in numbered_findings:
            if report_path is not None:
                lines.extend(["", *_linked_finding_section(number, finding, report_path)])
            else:
                lines.extend(["", *_finding_section(number, finding)])
    else:
        stopped = manifest.get("scan", {}).get("status") in {
            "failed",
            "canceled",
            "interrupted",
        }
        heading = "### No reportable findings" if informational_note else "### No findings"
        message = informational_note or (
            "No findings were retained before the scan stopped."
            if stopped
            else "No findings were reported."
        )
        if stopped:
            message += " The scan did not complete. No vulnerability conclusion can be drawn."
        lines.extend([heading, "", message])
    if hardening_portfolio_path is not None:
        lines.extend(
            [
                "",
                "## Structural Hardening",
                "",
                "The scan also produced derived, unsealed design guidance based on the complete finding collection. These proposals describe options and tradeoffs; they do not indicate that any finding has been remediated.",
                "",
                f"[Open the structural hardening portfolio]({hardening_portfolio_path})",
            ]
        )
    surfaces = coverage.get("surfaces", [])
    if surfaces:
        lines.extend(
            [
                "",
                "## Reviewed Surfaces",
                "",
                "| Surface | Risk Area | Outcome | Notes |",
                "| --- | --- | --- | --- |",
            ]
        )
        for surface in surfaces:
            if not isinstance(surface, dict):
                continue
            lines.append(
                "| "
                + " | ".join(
                    (
                        _cell(surface.get("label", surface.get("id"))),
                        _cell(surface.get("riskArea", "not recorded")),
                        _cell(
                            DISPOSITION_LABELS.get(
                                surface.get("disposition"), surface.get("disposition")
                            )
                        ),
                        _surface_notes(surface),
                    )
                )
                + " |"
            )
    open_questions = coverage.get("openQuestions", [])
    deferred_questions = []
    deferred = coverage.get("deferred", [])
    if isinstance(deferred, list):
        deferred_questions = [
            {
                "question": item.get("reason", "Deferred review requires follow-up."),
                "followUpPrompt": " ".join(
                    (
                        f"Review deferred unit {item.get('id', 'unknown')} and close its stated proof gap.",
                        f"Paths: {', '.join(item.get('paths', []))}." if item.get("paths") else "",
                        (
                            f"Surfaces: {', '.join(item.get('surfaceIds', []))}."
                            if item.get("surfaceIds")
                            else ""
                        ),
                    )
                ).strip(),
            }
            for item in deferred
            if isinstance(item, dict)
        ]
    for heading, questions in (
        ("Deferred Requested Work", deferred_questions),
        ("Open Questions And Follow Up", open_questions),
    ):
        if not isinstance(questions, list) or not questions:
            continue
        lines.extend(["", f"## {heading}", ""])
        for question in questions:
            if not isinstance(question, dict):
                continue
            lines.append(f"- {_text(question.get('question'), 'Unspecified open question.')}")
            prompt = _text(question.get("followUpPrompt"), "")
            if prompt:
                lines.append(f"  - Follow-up prompt: {prompt}")
    return "\n".join(lines).rstrip() + "\n"


def generate_report_markdown(
    manifest: dict[str, Any],
    findings: dict[str, Any],
    coverage: dict[str, Any],
) -> bytes:
    """Return the Markdown report for the scan as UTF-8 bytes ready to write."""
    return build_report_markdown(manifest, findings, coverage).encode("utf-8")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.parse_args()
    raise SystemExit(0)

SHA-256: 6e950c378fece395b7cb648425a814ae6a45211abade77b96ddeca1e743f65e5