Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

refactor(reports): share finding formatting and finalization helpers (#1355)

mldangelo-oaie0bbdad6c2b5
diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.py
index d45871973..60a44238b 100644
--- a/plugins/codex-security/scripts/finalize_scan_contract.py
+++ b/plugins/codex-security/scripts/finalize_scan_contract.py
@@ -1493,17 +1493,6 @@ def _normalize_unsealed_open_questions(coverage: dict[str, Any]) -> None:
coverage["openQuestions"] = normalized
-def _normalize_unsealed_deep_repository_inventory_strategy(
- coverage: dict[str, Any],
- *,
- expected_coverage_mode: str | None,
-) -> None:
- """Label whole-repository Deep scans as using the repository inventory."""
-
- if expected_coverage_mode == "deep_repository":
- coverage["inventoryStrategy"] = "repository"
-
-
def _validate_completion_binding(
manifest: dict[str, Any],
findings: dict[str, Any],
@@ -2089,29 +2078,20 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
continue
_remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
- if field not in attack_path:
- continue
detail = attack_path.get(field)
- if detail is None:
- attack_path.pop(field)
- continue
- if not isinstance(detail, (str, dict)):
- attack_path.pop(field)
- continue
- if isinstance(detail, str):
- if detail == "":
- attack_path.pop(field)
- continue
- detail_scalar_fields = ("summary", "source", "sink", "outcome")
- if field == "reachability":
- detail_scalar_fields += ("attacker", "entrypoint")
- _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
- _normalize_legacy_string_list_fields(
- detail, ("evidenceRefs", "evidence_refs", "transformations")
- )
- _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
- if field == "reachability":
- _normalize_legacy_string_list_fields(detail, ("preconditions",))
+ if isinstance(detail, dict):
+ detail_scalar_fields = ("summary", "source", "sink", "outcome")
+ if field == "reachability":
+ detail_scalar_fields += ("attacker", "entrypoint")
+ _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
+ _normalize_legacy_string_list_fields(
+ detail, ("evidenceRefs", "evidence_refs", "transformations")
+ )
+ _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
+ if field == "reachability":
+ _normalize_legacy_string_list_fields(detail, ("preconditions",))
+ elif not isinstance(detail, str) or detail == "":
+ attack_path.pop(field, None)
for field in ("impact", "likelihood"):
detail = attack_path.get(field)
if isinstance(detail, dict):
@@ -2767,11 +2747,7 @@ def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) ->
)
writer.writerow(finding_csv_columns(deep_scan))
for finding in findings["findings"]:
- locations = finding["locations"]
- location = next(
- (candidate for candidate in locations if candidate.get("role") == "root_control"),
- locations[0],
- )
+ location = _sarif_primary_location(finding)
writer.writerow(
(
csv_cell(finding["occurrenceId"]),
@@ -2953,10 +2929,9 @@ def _prepare_scan_finalization(
findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
if not was_sealed:
_populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
- _normalize_unsealed_deep_repository_inventory_strategy(
- coverage,
- expected_coverage_mode=expected_coverage_mode,
- )
+ # Label whole-repository Deep scans as using the repository inventory.
+ if expected_coverage_mode == "deep_repository":
+ coverage["inventoryStrategy"] = "repository"
_normalize_unsealed_open_questions(coverage)
if manifest.get("schemaVersion") != SCHEMA_VERSION:
diff --git a/plugins/codex-security/scripts/report_projection.py b/plugins/codex-security/scripts/report_projection.py
index 196e4cb3c..25eff4c61 100644
--- a/plugins/codex-security/scripts/report_projection.py
+++ b/plugins/codex-security/scripts/report_projection.py
@@ -218,8 +218,8 @@ def _hardening_portfolio_path(scan: dict[str, Any]) -> str | None:
return portfolio_path
-def _bullets(items: list[str], fallback: str) -> list[str]:
- return [f"- {item}" for item in (items or [fallback])]
+def _bullet_section(heading: str, items: list[str]) -> list[str]:
+ return ["", heading, *(f"- {item}" for item in items)] if items else []
def _code_evidence_catalog(finding: dict[str, Any]) -> dict[str, dict[str, Any]]:
@@ -433,22 +433,9 @@ def _code_evidence_lines(evidence: list[dict[str, Any]]) -> list[str]:
return lines
-def _severity_mix(findings: list[dict[str, Any]]) -> str:
- counts = Counter(finding["severity"]["level"] for finding in findings)
- return (
- ", ".join(f"{level}: {counts[level]}" for level in SEVERITY_ORDER if counts[level])
- or "none"
- )
-
-
-def _confidence_mix(findings: list[dict[str, Any]]) -> str:
- counts = Counter(finding["confidence"]["level"] for finding in findings)
- return (
- ", ".join(
- f"{level}: {counts[level]}" for level in ("high", "medium", "low") if counts[level]
- )
- or "none"
- )
+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:
@@ -500,6 +487,25 @@ def _surface_notes(surface: dict[str, Any]) -> str:
return _cell(f"{notes} Evidence: {evidence}")
+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)} |",
+ f"| Affected lines | {_cell(_locations(finding))} |",
+ ]
+
+
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)
@@ -562,10 +568,6 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
if validation_outcomes
else f"{finding['confidence']['rationale']} Validation details were not recorded separately.",
)
- validation_evidence = _strings(validation.get("evidence"))
- validation_assertions = _strings(validation.get("assertions"))
- validation_counterevidence = _strings(validation.get("counterEvidence"))
- validation_limitations = _strings(validation.get("limitations"))
root_cause_summary = _text(
raw_root_cause if isinstance(raw_root_cause, str) else root_cause.get("summary"),
"",
@@ -593,24 +595,8 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
severity.get("changeConditions"),
"Additional runtime or deployment evidence could raise or lower this severity.",
)
- remediation_tests = _strings(finding.get("remediationTests"))
- preventive_controls = _strings(finding.get("preventiveControls"))
- attack_steps = _strings(attack_path.get("steps"))
- cwes = ", ".join(finding["taxonomy"]["cwe"]) or "none"
- title = _text(finding["title"], "Untitled finding")
lines = [
- f'<a id="finding-{number}"></a>',
- "",
- f"### [{number}] {title}",
- "",
- "| Field | Value |",
- "| --- | --- |",
- f"| Severity | {_cell(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)} |",
- f"| Affected lines | {_cell(_locations(finding))} |",
+ *_finding_header(number, finding),
"",
"#### Summary",
"",
@@ -627,29 +613,19 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
if validation_outcomes:
lines.extend(["", *(f"- **{label}:** {value}" for label, value in validation_outcomes)])
lines.extend(_code_evidence_lines(validation_code_evidence))
- if validation_assertions:
- lines.extend(["", "Assertions:", *_bullets(validation_assertions, "None recorded.")])
- if validation_evidence:
- lines.extend(["", "Evidence:", *_bullets(validation_evidence, "No evidence recorded.")])
- if validation_counterevidence:
- lines.extend(
- [
- "",
- "Counterevidence and remaining uncertainty:",
- *_bullets(validation_counterevidence, "None recorded."),
- ]
- )
- if validation_limitations:
- lines.extend(["", "Limitations:", *_bullets(validation_limitations, "None recorded.")])
+ 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])
- if attack_steps:
- lines.extend(["", "Attack steps:", *_bullets(attack_steps, "None recorded.")])
+ 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')}"])
- transformations = _strings(dataflow.get("transformations"))
- if transformations:
- lines.extend(["", "Transformations:", *_bullets(transformations, "None recorded.")])
+ lines.extend(_bullet_section("Transformations:", _strings(dataflow.get("transformations"))))
lines.extend(_code_evidence_lines(dataflow_code_evidence))
lines.extend(["", "#### Reachability", "", reachability_summary])
for label, key in (
@@ -669,17 +645,14 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
]
)
)
- if preconditions:
- lines.extend(["", "Preconditions:", *_bullets(preconditions, "None recorded.")])
+ lines.extend(_bullet_section("Preconditions:", preconditions))
for label, key in (
("Assumptions", "assumptions"),
("Existing controls", "controls"),
("Blind spots", "blindspots"),
("Limitations", "limitations"),
):
- values = _strings(attack_path.get(key))
- if values:
- lines.extend(["", f"{label}:", *_bullets(values, "None recorded.")])
+ lines.extend(_bullet_section(f"{label}:", _strings(attack_path.get(key))))
lines.extend(_code_evidence_lines(reachability_code_evidence))
lines.extend(
[
@@ -721,31 +694,16 @@ def _finding_section(number: int, finding: dict[str, Any]) -> list[str]:
_text(finding["remediation"], "No canonical remediation was recorded."),
]
)
- if remediation_tests:
- lines.extend(["", "Tests:", *_bullets(remediation_tests, "No tests recorded.")])
- if preventive_controls:
- lines.extend(["", "Preventive controls:", *_bullets(preventive_controls, "None recorded.")])
+ lines.extend(_bullet_section("Tests:", _strings(finding.get("remediationTests"))))
+ lines.extend(
+ _bullet_section("Preventive controls:", _strings(finding.get("preventiveControls")))
+ )
return lines
def _linked_finding_section(number: int, finding: dict[str, Any], report_path: str) -> list[str]:
- cwes = ", ".join(finding["taxonomy"]["cwe"]) or "none"
- title = _text(finding["title"], "Untitled finding")
link = f"[detailed technical write-up]({report_path})"
- lines = [
- 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)} |",
- f"| Affected lines | {_cell(_locations(finding))} |",
- ]
+ lines = _finding_header(number, finding)
for heading in ("Summary", "Validation", "Dataflow", "Reachability", "Severity", "Remediation"):
lines.extend(["", f"#### {heading}", "", f"See the {link}."])
return lines
@@ -812,20 +770,19 @@ def build_report_markdown(
f"Excluded {_text(exclusion.get('pattern'), 'unspecified')}: "
f"{_text(exclusion.get('reason'), 'reason not recorded')}"
)
- if limitations:
- lines.extend(["", "Limitations and exclusions:", *_bullets(limitations, "None 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 | {_severity_mix(findings)} |",
- f"| Report confidence mix | {_confidence_mix(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 | {_severity_mix(findings)} |",
- f"| Confidence mix | {_confidence_mix(findings)} |",
+ f"| Severity mix | {_level_mix(findings, 'severity', SEVERITY_ORDER)} |",
+ f"| Confidence mix | {_level_mix(findings, 'confidence', CONFIDENCE_ORDER)} |",
]
)
lines.extend(
@@ -856,20 +813,16 @@ def build_report_markdown(
"No explicit canonical threat-model summary was recorded.",
)
)
- for heading, key, fallback in (
- ("Assets", "assets", "No assets were recorded."),
- ("Trust Boundaries", "trustBoundaries", "No trust boundaries were recorded."),
- (
- "Attacker Capabilities",
- "attackerCapabilities",
- "No attacker capabilities were recorded.",
- ),
- ("Security Objectives", "securityObjectives", "No security objectives were recorded."),
- ("Assumptions", "assumptions", "No assumptions were recorded."),
+ for heading, key in (
+ ("Assets", "assets"),
+ ("Trust Boundaries", "trustBoundaries"),
+ ("Attacker Capabilities", "attackerCapabilities"),
+ ("Security Objectives", "securityObjectives"),
+ ("Assumptions", "assumptions"),
):
values = _strings(threat_model.get(key))
if values:
- lines.extend(["", f"### {heading}", "", *_bullets(values, fallback)])
+ lines.extend(["", f"### {heading}", "", *(f"- {value}" for value in values)])
lines.extend(["", "## Findings", ""])
if findings:
if deep_presentation:
diff --git a/plugins/codex-security/tests/test_finalize_scan_contract.py b/plugins/codex-security/tests/test_finalize_scan_contract.py
index b3c34021c..8f46e59da 100644
--- a/plugins/codex-security/tests/test_finalize_scan_contract.py
+++ b/plugins/codex-security/tests/test_finalize_scan_contract.py
@@ -2833,10 +2833,7 @@ The extraction root is not enforced.
def test_sarif_emits_github_line_hash_through_windows_backend(self) -> None:
source_root = self.write_line_hash_source()
sarif_finding = self.sarif_finding("semantic-fingerprint")
- backend = mock.Mock()
- backend.open_read_fd.side_effect = lambda root, relative_path, _context: os.open(
- root / relative_path, os.O_RDONLY
- )
+ backend = windows_file_backend()
with (
mock.patch.object(FINALIZER.os, "supports_dir_fd", set()),