mirror of
https://github.com/openai/codex-security.git
synced 2026-11-21 02:12:29 +08:00
1094 lines
42 KiB
Python
1094 lines
42 KiB
Python
#!/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", surface.get("reason", "No additional canonical notes were recorded.")
|
|
)
|
|
if "notes" in surface and "reason" in surface and surface["reason"] != notes:
|
|
notes += f" {surface['reason']}"
|
|
source = _coverage_source(surface)
|
|
if source:
|
|
notes = f"{source}. {notes}"
|
|
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 _coverage_source(item: dict[str, Any]) -> str:
|
|
provenance = item.get("provenance", {})
|
|
if not isinstance(provenance, dict) or not provenance.get("workerId"):
|
|
return ""
|
|
source = f"Review {provenance['workerId']}"
|
|
if provenance.get("attempt") is not None:
|
|
source += f", attempt {provenance['attempt']}"
|
|
return source
|
|
|
|
|
|
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})",
|
|
]
|
|
)
|
|
reviews = coverage.get("reviews", [])
|
|
if reviews:
|
|
lines.extend(
|
|
[
|
|
"",
|
|
"## Source Review Coverage",
|
|
"",
|
|
"| Review | Attempt | Coverage |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
)
|
|
for review in reviews:
|
|
if isinstance(review, dict):
|
|
lines.append(
|
|
f"| {_cell(review.get('workerId'))} | {_cell(str(review.get('attempt', 'unknown')))} | {_cell(review.get('completeness'))} |"
|
|
)
|
|
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."),
|
|
"provenance": item.get("provenance", {}),
|
|
"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.')}")
|
|
source = _coverage_source(question)
|
|
if source:
|
|
lines.append(f" - {_text(source, '')}.")
|
|
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)
|