OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
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.pyindex 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[strcontinue_remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))for field in ("dataFlow", "data_flow", "dataflow", "reachability"):- if field not in attack_path:- continuedetail = 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.pyindex 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_outcomeselse 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 linesdef _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_presentationelse [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.pyindex 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()),