@openai/codex-security 0.1.14 → 0.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.md +94 -19
  2. package/_bundled_plugin/.app.json +5 -0
  3. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  4. package/_bundled_plugin/examples/completed-scan/report.md +96 -0
  5. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  6. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  7. package/_bundled_plugin/references/config-preflight.md +5 -1
  8. package/_bundled_plugin/references/core-scan.md +6 -15
  9. package/_bundled_plugin/references/final-report.md +1 -1
  10. package/_bundled_plugin/references/sarif-adapter.md +3 -1
  11. package/_bundled_plugin/references/scan-artifacts.md +1 -1
  12. package/_bundled_plugin/references/threat-model.md +64 -0
  13. package/_bundled_plugin/schemas/findings.schema.json +327 -2
  14. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +286 -4
  15. package/_bundled_plugin/scripts/config_preflight.py +20 -1
  16. package/_bundled_plugin/scripts/deep_scan_workbench.py +12 -6
  17. package/_bundled_plugin/scripts/finalize_scan_contract.py +389 -39
  18. package/_bundled_plugin/scripts/finding_preview.py +81 -19
  19. package/_bundled_plugin/scripts/report_projection.py +253 -33
  20. package/_bundled_plugin/scripts/validate_scan_contract.py +5 -2
  21. package/_bundled_plugin/scripts/workbench_cli.py +7 -1
  22. package/_bundled_plugin/scripts/workbench_remediation.py +2 -0
  23. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +4 -0
  24. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +2 -2
  25. package/_bundled_plugin/skills/security-scan/SKILL.md +1 -1
  26. package/_bundled_plugin/skills/threat-model/SKILL.md +6 -49
  27. package/_bundled_plugin/skills/verify-fix/SKILL.md +44 -0
  28. package/_bundled_plugin/skills/verify-fix/agents/openai.yaml +4 -0
  29. package/dist/api.d.ts +5 -73
  30. package/dist/api.d.ts.map +1 -1
  31. package/dist/api.js +259 -209
  32. package/dist/api.js.map +1 -1
  33. package/dist/bulk-scan-discovery.d.ts +3 -3
  34. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  35. package/dist/bulk-scan-discovery.js +8 -7
  36. package/dist/bulk-scan-discovery.js.map +1 -1
  37. package/dist/cli.d.ts +25 -4
  38. package/dist/cli.d.ts.map +1 -1
  39. package/dist/cli.js +1212 -123
  40. package/dist/cli.js.map +1 -1
  41. package/dist/codex-prompt.d.ts +4 -0
  42. package/dist/codex-prompt.d.ts.map +1 -0
  43. package/dist/codex-prompt.js +14 -0
  44. package/dist/codex-prompt.js.map +1 -0
  45. package/dist/contract.d.ts.map +1 -1
  46. package/dist/contract.js +198 -2
  47. package/dist/contract.js.map +1 -1
  48. package/dist/cost.d.ts +7 -0
  49. package/dist/cost.d.ts.map +1 -1
  50. package/dist/cost.js +71 -47
  51. package/dist/cost.js.map +1 -1
  52. package/dist/errors.d.ts +4 -0
  53. package/dist/errors.d.ts.map +1 -1
  54. package/dist/errors.js +9 -0
  55. package/dist/errors.js.map +1 -1
  56. package/dist/index.d.ts +2 -2
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +1 -1
  59. package/dist/index.js.map +1 -1
  60. package/dist/linear.d.ts +19 -0
  61. package/dist/linear.d.ts.map +1 -0
  62. package/dist/linear.js +106 -0
  63. package/dist/linear.js.map +1 -0
  64. package/dist/models.d.ts +89 -2
  65. package/dist/models.d.ts.map +1 -1
  66. package/dist/models.js.map +1 -1
  67. package/dist/multiscan.d.ts.map +1 -1
  68. package/dist/multiscan.js +7 -6
  69. package/dist/multiscan.js.map +1 -1
  70. package/dist/patch-tui.d.ts +28 -0
  71. package/dist/patch-tui.d.ts.map +1 -0
  72. package/dist/patch-tui.js +384 -0
  73. package/dist/patch-tui.js.map +1 -0
  74. package/dist/publish.d.ts +2 -2
  75. package/dist/publish.d.ts.map +1 -1
  76. package/dist/publish.js +4 -8
  77. package/dist/publish.js.map +1 -1
  78. package/dist/runtime.d.ts +10 -7
  79. package/dist/runtime.d.ts.map +1 -1
  80. package/dist/runtime.js +63 -35
  81. package/dist/runtime.js.map +1 -1
  82. package/dist/scan-comparison.d.ts +2 -1
  83. package/dist/scan-comparison.d.ts.map +1 -1
  84. package/dist/scan-comparison.js +17 -15
  85. package/dist/scan-comparison.js.map +1 -1
  86. package/dist/scan-dashboard.d.ts +3 -2
  87. package/dist/scan-dashboard.d.ts.map +1 -1
  88. package/dist/scan-dashboard.js +223 -12
  89. package/dist/scan-dashboard.js.map +1 -1
  90. package/dist/targets.d.ts +1 -0
  91. package/dist/targets.d.ts.map +1 -1
  92. package/dist/targets.js +4 -2
  93. package/dist/targets.js.map +1 -1
  94. package/dist/trusted-executable.d.ts.map +1 -1
  95. package/dist/trusted-executable.js +26 -11
  96. package/dist/trusted-executable.js.map +1 -1
  97. package/dist/version.d.ts +1 -1
  98. package/dist/version.js +1 -1
  99. package/dist/version.js.map +1 -1
  100. package/package.json +7 -3
  101. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +0 -48
@@ -20,7 +20,16 @@ except ModuleNotFoundError: # pragma: no cover - Python 3.10 only
20
20
  PLUGIN_ROOT = Path(__file__).resolve().parents[1]
21
21
  DEFAULT_REGISTRY = PLUGIN_ROOT / "preflight" / "capability-profiles.toml"
22
22
  DEFAULT_CODEX_HOME = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
23
- SYSTEM_CONFIG = Path("/etc/codex/config.toml")
23
+
24
+
25
+ def default_system_config() -> Path:
26
+ if os.name == "nt":
27
+ program_data = os.environ.get("ProgramData", r"C:\ProgramData")
28
+ return Path(program_data) / "OpenAI" / "Codex" / "config.toml"
29
+ return Path("/etc/codex/config.toml")
30
+
31
+
32
+ SYSTEM_CONFIG = default_system_config()
24
33
  DEFAULT_CONFIG = DEFAULT_CODEX_HOME / "config.toml"
25
34
  VALID_SEVERITIES = {"block", "warn", "suggest"}
26
35
  VALID_MULTI_AGENT_OWNERS = {"native", "codex-bridge"}
@@ -244,6 +253,16 @@ def project_trust_level(
244
253
  if not isinstance(projects, dict):
245
254
  continue
246
255
  project = projects.get(str(project_root))
256
+ if not isinstance(project, dict) and os.name == "nt":
257
+ project_key = os.path.normcase(os.path.realpath(project_root))
258
+ project = next(
259
+ (
260
+ value
261
+ for path, value in projects.items()
262
+ if os.path.normcase(os.path.realpath(path)) == project_key
263
+ ),
264
+ None,
265
+ )
247
266
  if not isinstance(project, dict):
248
267
  continue
249
268
  trust_level = project.get("trust_level")
@@ -160,6 +160,12 @@ def now() -> str:
160
160
  return dependencies().now()
161
161
 
162
162
 
163
+ def _parse_timestamp(value: str) -> datetime:
164
+ if isinstance(value, str) and value.endswith(("Z", "z")):
165
+ value = value[:-1] + "+00:00"
166
+ return datetime.fromisoformat(value)
167
+
168
+
163
169
  def state_dir() -> Path:
164
170
  return dependencies().state_dir()
165
171
 
@@ -219,7 +225,7 @@ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlit
219
225
 
220
226
 
221
227
  def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
222
- elapsed = datetime.fromisoformat(now()) - datetime.fromisoformat(str(run["created_at"]))
228
+ elapsed = _parse_timestamp(now()) - _parse_timestamp(str(run["created_at"]))
223
229
  return elapsed.total_seconds() / 3600 >= run["max_time_hours"]
224
230
 
225
231
 
@@ -880,12 +886,12 @@ def coordinator_lease_is_live(
880
886
  """,
881
887
  (run["scan_id"],),
882
888
  ).fetchone()
883
- return active_worker is not None and datetime.fromisoformat(
889
+ return active_worker is not None and _parse_timestamp(
884
890
  str(run["updated_at"])
885
- ) > datetime.fromisoformat(timestamp) - timedelta(
891
+ ) > _parse_timestamp(timestamp) - timedelta(
886
892
  seconds=DEEP_SCAN_LEGACY_COORDINATOR_GRACE_SECONDS
887
893
  )
888
- heartbeat_time = datetime.fromisoformat(str(run["updated_at"]))
894
+ heartbeat_time = _parse_timestamp(str(run["updated_at"]))
889
895
  heartbeat_path = (
890
896
  Path(scan["scan_dir"])
891
897
  / "artifacts"
@@ -895,10 +901,10 @@ def coordinator_lease_is_live(
895
901
  try:
896
902
  heartbeat = json.loads(heartbeat_path.read_text(encoding="utf-8"))
897
903
  if heartbeat["coordinatorGeneration"] == run["coordinator_generation"]:
898
- heartbeat_time = max(heartbeat_time, datetime.fromisoformat(heartbeat["updatedAt"]))
904
+ heartbeat_time = max(heartbeat_time, _parse_timestamp(heartbeat["updatedAt"]))
899
905
  except (OSError, KeyError, TypeError, ValueError):
900
906
  pass
901
- current_time = datetime.fromisoformat(timestamp)
907
+ current_time = _parse_timestamp(timestamp)
902
908
  return heartbeat_time > current_time - timedelta(seconds=DEEP_SCAN_COORDINATOR_LEASE_SECONDS)
903
909
 
904
910
 
@@ -51,6 +51,13 @@ SARIF_LEVELS = {
51
51
  "low": "note",
52
52
  "informational": "note",
53
53
  }
54
+ SARIF_SECURITY_SCORES = {
55
+ "critical": 9.5,
56
+ "high": 8.0,
57
+ "medium": 5.0,
58
+ "low": 2.0,
59
+ "informational": 0.0,
60
+ }
54
61
  SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9._/-]*$")
55
62
  RFC3339_RE = re.compile(
56
63
  r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$"
@@ -694,7 +701,7 @@ def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
694
701
  return (
695
702
  ("informational", "low", "medium", "high", "critical").index(finding["severity"]["level"]),
696
703
  ("low", "medium", "high").index(finding["confidence"]["level"]),
697
- len(finding.get("codeEvidence") or []),
704
+ _finding_evidence_strength(finding),
698
705
  )
699
706
 
700
707
 
@@ -735,6 +742,12 @@ def _recover_unsealed_findings(
735
742
  try:
736
743
  if not isinstance(finding, dict):
737
744
  raise ContractError(f"{context}: expected an object")
745
+ compatible_findings = _legacy_sealed_findings_for_validation(
746
+ {"findings": [finding]}
747
+ )["findings"]
748
+ compatible_finding = compatible_findings[0]
749
+ normalized_legacy_details = compatible_finding != finding
750
+ finding = compatible_finding
738
751
  identity = _require_dict(finding, "identity", context)
739
752
  fields: list[tuple[dict[str, Any], str, str, str]] = [
740
753
  (finding, "ruleId", context, "rule identifier"),
@@ -742,7 +755,9 @@ def _recover_unsealed_findings(
742
755
  ]
743
756
  if "instance" in identity:
744
757
  fields.append((identity, "instance", f"{context}.identity", "instance"))
745
- normalized_fields = []
758
+ normalized_fields = (
759
+ ["legacy finding details"] if normalized_legacy_details else []
760
+ )
746
761
  for parent, field, field_context, label in fields:
747
762
  value = _require_str(parent, field, field_context)
748
763
  if SLUG_RE.fullmatch(value):
@@ -1222,12 +1237,14 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1222
1237
  _validate_location(location, f"{context}.locations[{index}]")
1223
1238
 
1224
1239
  evidence_ids: set[str] = set()
1225
- code_evidence = finding.get("codeEvidence")
1226
- if code_evidence is not None:
1240
+ for evidence_key in ("codeEvidence", "code_evidence"):
1241
+ if evidence_key not in finding:
1242
+ continue
1243
+ code_evidence = finding[evidence_key]
1227
1244
  if not isinstance(code_evidence, list):
1228
- raise ContractError(f"{context}.codeEvidence: expected an array")
1245
+ raise ContractError(f"{context}.{evidence_key}: expected an array")
1229
1246
  for index, evidence in enumerate(code_evidence):
1230
- evidence_context = f"{context}.codeEvidence[{index}]"
1247
+ evidence_context = f"{context}.{evidence_key}[{index}]"
1231
1248
  if not isinstance(evidence, dict):
1232
1249
  raise ContractError(f"{evidence_context}: expected an object")
1233
1250
  evidence_id = _require_str(evidence, "id", evidence_context)
@@ -1236,19 +1253,33 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1236
1253
  evidence_ids.add(evidence_id)
1237
1254
  _require_str(evidence, "code", evidence_context)
1238
1255
 
1239
- for section_name in ("rootCause", "validation", "attackPath"):
1240
- section = finding.get(section_name)
1241
- if not isinstance(section, dict) or "evidenceRefs" not in section:
1256
+ referenced_sections = [
1257
+ (section_name, finding.get(section_name))
1258
+ for section_name in ("rootCause", "root_cause", "validation", "attackPath")
1259
+ ]
1260
+ attack_path = finding.get("attackPath")
1261
+ if isinstance(attack_path, dict):
1262
+ referenced_sections.extend(
1263
+ (f"attackPath.{section_name}", attack_path.get(section_name))
1264
+ for section_name in ("dataFlow", "dataflow", "data_flow", "reachability")
1265
+ )
1266
+ for section_name, section in referenced_sections:
1267
+ if not isinstance(section, dict):
1242
1268
  continue
1243
- refs = section["evidenceRefs"]
1244
- if not isinstance(refs, list) or any(not isinstance(ref, str) or not ref for ref in refs):
1245
- raise ContractError(f"{context}.{section_name}.evidenceRefs: expected strings")
1246
- unknown_refs = sorted(set(refs) - evidence_ids)
1247
- if unknown_refs:
1248
- raise ContractError(
1249
- f"{context}.{section_name}.evidenceRefs: unknown code-evidence ids: "
1250
- + ", ".join(unknown_refs)
1251
- )
1269
+ for refs_key in ("evidenceRefs", "evidence_refs"):
1270
+ if refs_key not in section:
1271
+ continue
1272
+ refs = section[refs_key]
1273
+ if not isinstance(refs, list) or any(
1274
+ not isinstance(ref, str) or not ref for ref in refs
1275
+ ):
1276
+ raise ContractError(f"{context}.{section_name}.{refs_key}: expected strings")
1277
+ unknown_refs = sorted(set(refs) - evidence_ids)
1278
+ if unknown_refs:
1279
+ raise ContractError(
1280
+ f"{context}.{section_name}.{refs_key}: unknown code-evidence ids: "
1281
+ + ", ".join(unknown_refs)
1282
+ )
1252
1283
 
1253
1284
  provenance = _require_dict(finding, "provenance", context)
1254
1285
  _require_str(provenance, "source", f"{context}.provenance")
@@ -1466,6 +1497,190 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1466
1497
  _validate_schema_node(payload, schema, schema_path.stem)
1467
1498
 
1468
1499
 
1500
+ def _filter_unknown_legacy_evidence_refs(
1501
+ section: dict[str, Any], evidence_ids: set[str]
1502
+ ) -> None:
1503
+ for refs_field in ("evidenceRefs", "evidence_refs"):
1504
+ refs = section.get(refs_field)
1505
+ if isinstance(refs, list):
1506
+ section[refs_field] = [
1507
+ ref
1508
+ for ref in refs
1509
+ if isinstance(ref, str) and ref.strip() and ref in evidence_ids
1510
+ ]
1511
+
1512
+
1513
+ def _normalize_legacy_string_list_fields(
1514
+ section: dict[str, Any], fields: tuple[str, ...]
1515
+ ) -> None:
1516
+ for field in fields:
1517
+ if field not in section:
1518
+ continue
1519
+ value = section[field]
1520
+ if isinstance(value, str):
1521
+ normalized = [value] if value.strip() else []
1522
+ elif isinstance(value, list):
1523
+ normalized = [
1524
+ item for item in value if isinstance(item, str) and item.strip()
1525
+ ]
1526
+ else:
1527
+ normalized = []
1528
+ if normalized:
1529
+ section[field] = normalized
1530
+ else:
1531
+ section.pop(field)
1532
+
1533
+
1534
+ def _remove_unsupported_legacy_scalar_fields(
1535
+ section: dict[str, Any], fields: tuple[str, ...]
1536
+ ) -> None:
1537
+ for field in fields:
1538
+ if field in section and (
1539
+ not isinstance(section[field], str) or section[field] == ""
1540
+ ):
1541
+ section.pop(field)
1542
+
1543
+
1544
+ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str, Any]:
1545
+ compatible = copy.deepcopy(findings)
1546
+ finding_items = compatible.get("findings")
1547
+ if not isinstance(finding_items, list):
1548
+ return compatible
1549
+ for finding in finding_items:
1550
+ if not isinstance(finding, dict):
1551
+ continue
1552
+ canonical_evidence = finding.get("codeEvidence")
1553
+ canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
1554
+ canonical_evidence_ids = {
1555
+ evidence["id"]
1556
+ for evidence in canonical_evidence
1557
+ if isinstance(evidence, dict)
1558
+ and isinstance(evidence.get("id"), str)
1559
+ and evidence["id"]
1560
+ }
1561
+ legacy_evidence = finding.get("code_evidence")
1562
+ if isinstance(legacy_evidence, list):
1563
+ compatible_legacy_evidence = []
1564
+ seen_evidence_ids = set(canonical_evidence_ids)
1565
+ for evidence in legacy_evidence:
1566
+ if not isinstance(evidence, dict):
1567
+ continue
1568
+ evidence_id = evidence.get("id")
1569
+ evidence_code = evidence.get("code")
1570
+ if (
1571
+ not isinstance(evidence_id, str)
1572
+ or not evidence_id.strip()
1573
+ or not isinstance(evidence_code, str)
1574
+ or not evidence_code.strip()
1575
+ ):
1576
+ continue
1577
+ if evidence_id in seen_evidence_ids:
1578
+ continue
1579
+ seen_evidence_ids.add(evidence_id)
1580
+ compatible_legacy_evidence.append(evidence)
1581
+ finding["code_evidence"] = compatible_legacy_evidence
1582
+ elif "code_evidence" in finding:
1583
+ finding.pop("code_evidence")
1584
+ compatible_legacy_evidence = finding.get("code_evidence")
1585
+ compatible_legacy_evidence = (
1586
+ compatible_legacy_evidence if isinstance(compatible_legacy_evidence, list) else []
1587
+ )
1588
+ evidence_ids = canonical_evidence_ids | {
1589
+ evidence["id"]
1590
+ for evidence in compatible_legacy_evidence
1591
+ if isinstance(evidence, dict)
1592
+ and isinstance(evidence.get("id"), str)
1593
+ and evidence["id"]
1594
+ }
1595
+ for section_name, list_fields in (
1596
+ ("root_cause", ("evidenceRefs", "evidence_refs")),
1597
+ (
1598
+ "validation",
1599
+ (
1600
+ "assertions",
1601
+ "counterEvidence",
1602
+ "evidence",
1603
+ "evidenceRefs",
1604
+ "evidence_refs",
1605
+ "limitations",
1606
+ ),
1607
+ ),
1608
+ (
1609
+ "attackPath",
1610
+ (
1611
+ "assumptions",
1612
+ "blindspots",
1613
+ "controls",
1614
+ "evidenceRefs",
1615
+ "evidence_refs",
1616
+ "limitations",
1617
+ "preconditions",
1618
+ "steps",
1619
+ ),
1620
+ ),
1621
+ ):
1622
+ section = finding.get(section_name)
1623
+ if not isinstance(section, dict):
1624
+ continue
1625
+ _normalize_legacy_string_list_fields(section, list_fields)
1626
+ _filter_unknown_legacy_evidence_refs(section, evidence_ids)
1627
+ legacy_root_cause = finding.get("root_cause")
1628
+ if isinstance(legacy_root_cause, dict):
1629
+ _remove_unsupported_legacy_scalar_fields(
1630
+ legacy_root_cause, ("summary", "code", "language")
1631
+ )
1632
+ elif (
1633
+ "root_cause" in finding
1634
+ and legacy_root_cause is not None
1635
+ and (not isinstance(legacy_root_cause, str) or legacy_root_cause == "")
1636
+ ):
1637
+ finding.pop("root_cause")
1638
+ validation = finding.get("validation")
1639
+ if isinstance(validation, dict):
1640
+ _remove_unsupported_legacy_scalar_fields(
1641
+ validation, ("method", "status", "summary", "disposition", "result")
1642
+ )
1643
+ attack_path = finding.get("attackPath")
1644
+ if not isinstance(attack_path, dict):
1645
+ continue
1646
+ _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
1647
+ for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
1648
+ if field not in attack_path:
1649
+ continue
1650
+ detail = attack_path.get(field)
1651
+ if detail is None:
1652
+ attack_path.pop(field)
1653
+ continue
1654
+ if not isinstance(detail, (str, dict)):
1655
+ attack_path.pop(field)
1656
+ continue
1657
+ if isinstance(detail, str):
1658
+ if detail == "":
1659
+ attack_path.pop(field)
1660
+ continue
1661
+ detail_scalar_fields = ("summary", "source", "sink", "outcome")
1662
+ if field == "reachability":
1663
+ detail_scalar_fields += ("attacker", "entrypoint")
1664
+ _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
1665
+ _normalize_legacy_string_list_fields(
1666
+ detail, ("evidenceRefs", "evidence_refs", "transformations")
1667
+ )
1668
+ _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
1669
+ if field == "reachability":
1670
+ _normalize_legacy_string_list_fields(detail, ("preconditions",))
1671
+ for field in ("impact", "likelihood"):
1672
+ detail = attack_path.get(field)
1673
+ if isinstance(detail, dict):
1674
+ _remove_unsupported_legacy_scalar_fields(
1675
+ detail, ("level", "rationale", "why")
1676
+ )
1677
+ elif detail is not None and (
1678
+ not isinstance(detail, str) or detail == ""
1679
+ ):
1680
+ attack_path.pop(field)
1681
+ return compatible
1682
+
1683
+
1469
1684
  def _validate_canonical_schemas_before_projection(
1470
1685
  manifest: dict[str, Any],
1471
1686
  findings: dict[str, Any],
@@ -1493,15 +1708,67 @@ def _validate_contract_refs(scan: dict[str, Any]) -> None:
1493
1708
  raise ContractError(f"manifest.scan.{field}: expected {expected!r}")
1494
1709
 
1495
1710
 
1496
- def _sarif_rule(rule_id: str) -> dict[str, Any]:
1711
+ def _sarif_label(value: str) -> str:
1712
+ words = re.sub(r"[-_./]+", " ", value).split()
1713
+ acronyms = {"api", "csrf", "html", "http", "id", "rce", "sql", "ssrf", "url", "xml", "xss"}
1714
+ label = " ".join(word.upper() if word.lower() in acronyms else word for word in words)
1715
+ return label[:1].upper() + label[1:]
1716
+
1717
+
1718
+ def _sarif_rule(rule_id: str, findings: list[dict[str, Any]]) -> dict[str, Any]:
1719
+ name = ": ".join(_sarif_label(part) for part in rule_id.split("."))
1720
+ categories = sorted({finding["taxonomy"]["category"] for finding in findings})
1721
+ cwes = sorted({cwe for finding in findings for cwe in finding["taxonomy"]["cwe"]})
1722
+ tags = {"security", *categories}
1723
+ for cwe in cwes:
1724
+ match = re.fullmatch(r"CWE-([0-9]+)", cwe, re.IGNORECASE)
1725
+ if match and int(match[1]) > 0:
1726
+ tags.add(f"external/cwe/cwe-{int(match[1]):03d}")
1727
+ description = f"{name}. Categories: {', '.join(map(_sarif_label, categories))}."
1728
+ if cwes:
1729
+ description += f" Weaknesses: {', '.join(cwes)}."
1730
+ remediation = "\n\n".join(sorted({finding["remediation"] for finding in findings}))
1731
+ properties: dict[str, Any] = {"tags": sorted(tags)}
1732
+ # GitHub assigns security severity to the shared rule, not each result.
1733
+ score = max(
1734
+ finding["severity"].get("score", SARIF_SECURITY_SCORES[finding["severity"]["level"]])
1735
+ for finding in findings
1736
+ )
1737
+ if score > 0:
1738
+ properties["security-severity"] = str(score)
1497
1739
  return {
1498
1740
  "id": rule_id,
1499
- "name": rule_id,
1500
- "shortDescription": {"text": rule_id},
1501
- "properties": {"tags": ["security"]},
1741
+ "name": name,
1742
+ "shortDescription": {"text": name},
1743
+ "fullDescription": {"text": description},
1744
+ "help": {
1745
+ "text": f"{description}\n\nRemediation:\n\n{remediation}",
1746
+ "markdown": f"{description}\n\n## Remediation\n\n{remediation}",
1747
+ },
1748
+ "properties": properties,
1502
1749
  }
1503
1750
 
1504
1751
 
1752
+ def _sarif_finding_message(finding: dict[str, Any]) -> str:
1753
+ taxonomy = finding["taxonomy"]
1754
+ details = [
1755
+ finding["title"],
1756
+ finding["summary"],
1757
+ f"Severity: {finding['severity']['level']}",
1758
+ f"Category: {_sarif_label(taxonomy['category'])}",
1759
+ ]
1760
+ if taxonomy["cwe"]:
1761
+ details.append(f"Weaknesses: {', '.join(taxonomy['cwe'])}")
1762
+ details.append(f"Remediation:\n{finding['remediation']}")
1763
+ for key, label in (
1764
+ ("remediationTests", "Remediation tests"),
1765
+ ("preventiveControls", "Preventive controls"),
1766
+ ):
1767
+ if finding.get(key):
1768
+ details.append(f"{label}:\n" + "\n".join(f"- {item}" for item in finding[key]))
1769
+ return "\n\n".join(details)
1770
+
1771
+
1505
1772
  def _utf16_code_units(value: str) -> Iterator[int]:
1506
1773
  encoded = value.encode("utf-16-le")
1507
1774
  for index in range(0, len(encoded), 2):
@@ -1608,21 +1875,94 @@ def _sarif_primary_location(finding: dict[str, Any]) -> dict[str, Any]:
1608
1875
  )
1609
1876
 
1610
1877
 
1878
+ def _merged_code_evidence(finding: dict[str, Any]) -> list[dict[str, Any]]:
1879
+ catalog: dict[str, dict[str, Any]] = {}
1880
+ for evidence_key in ("codeEvidence", "code_evidence"):
1881
+ code_evidence = finding.get(evidence_key)
1882
+ if not isinstance(code_evidence, list):
1883
+ continue
1884
+ for evidence in code_evidence:
1885
+ if not isinstance(evidence, dict):
1886
+ continue
1887
+ evidence_id = evidence.get("id")
1888
+ if isinstance(evidence_id, str) and evidence_id:
1889
+ catalog.setdefault(evidence_id, evidence)
1890
+ return list(catalog.values())
1891
+
1892
+
1893
+ def _finding_evidence_strength(finding: dict[str, Any]) -> int:
1894
+ evidence = _merged_code_evidence(finding)
1895
+ seen_ids = {
1896
+ item["id"] for item in evidence if isinstance(item.get("id"), str) and item["id"].strip()
1897
+ }
1898
+ seen_codes = {
1899
+ item["code"]
1900
+ for item in evidence
1901
+ if isinstance(item.get("code"), str) and item["code"].strip()
1902
+ }
1903
+ strength = len(evidence)
1904
+ for section_name in ("rootCause", "root_cause"):
1905
+ section = finding.get(section_name)
1906
+ if not isinstance(section, dict):
1907
+ continue
1908
+ for evidence_name in ("codeEvidence", "code_evidence"):
1909
+ embedded = section.get(evidence_name)
1910
+ if not isinstance(embedded, list):
1911
+ continue
1912
+ for item in embedded:
1913
+ if not isinstance(item, dict):
1914
+ continue
1915
+ code = item.get("code")
1916
+ if not isinstance(code, str) or not code.strip() or code in seen_codes:
1917
+ continue
1918
+ evidence_id = item.get("id")
1919
+ if isinstance(evidence_id, str) and evidence_id.strip():
1920
+ if evidence_id in seen_ids:
1921
+ continue
1922
+ seen_ids.add(evidence_id)
1923
+ seen_codes.add(code)
1924
+ strength += 1
1925
+ code = section.get("code")
1926
+ if isinstance(code, str) and code.strip() and code not in seen_codes:
1927
+ seen_codes.add(code)
1928
+ strength += 1
1929
+ return strength
1930
+
1931
+
1611
1932
  def _sarif_locations(finding: dict[str, Any]) -> list[dict[str, Any]]:
1612
1933
  primary = _sarif_primary_location(finding)
1613
1934
  locations = [
1614
1935
  primary,
1615
1936
  *(location for location in finding["locations"] if location is not primary),
1616
1937
  ]
1617
- locations.extend(
1618
- {
1619
- "path": evidence["path"],
1620
- "startLine": evidence["startLine"],
1621
- "endLine": evidence.get("endLine", evidence["startLine"]),
1622
- "role": f"evidence:{evidence['id']}",
1623
- }
1624
- for evidence in finding.get("codeEvidence", [])
1625
- )
1938
+ for evidence in _merged_code_evidence(finding):
1939
+ path = evidence.get("path")
1940
+ start_line = evidence.get("startLine")
1941
+ if (
1942
+ not isinstance(path, str)
1943
+ or not isinstance(start_line, int)
1944
+ or isinstance(start_line, bool)
1945
+ or start_line < 1
1946
+ ):
1947
+ continue
1948
+ try:
1949
+ path = _require_safe_relative_path(path, "SARIF evidence location")
1950
+ except ContractError:
1951
+ continue
1952
+ locations.append(
1953
+ {
1954
+ "path": path,
1955
+ "startLine": start_line,
1956
+ "endLine": (
1957
+ evidence["endLine"]
1958
+ if isinstance(evidence.get("endLine"), int)
1959
+ and not isinstance(evidence["endLine"], bool)
1960
+ and evidence["endLine"] >= start_line
1961
+ else start_line
1962
+ ),
1963
+ "role": f"evidence:{evidence['id']}",
1964
+ }
1965
+ )
1626
1966
  unique: dict[tuple[str, int, int], dict[str, Any]] = {}
1627
1967
  for location in locations:
1628
1968
  key = (
@@ -1732,7 +2072,7 @@ def _sarif_result(
1732
2072
  "ruleId": finding["ruleId"],
1733
2073
  "ruleIndex": rule_index,
1734
2074
  "level": SARIF_LEVELS[finding["severity"]["level"]],
1735
- "message": {"text": finding["summary"]},
2075
+ "message": {"text": _sarif_finding_message(finding)},
1736
2076
  "locations": [_sarif_location(location) for location in _sarif_locations(finding)],
1737
2077
  "partialFingerprints": partial_fingerprints,
1738
2078
  "properties": properties,
@@ -1757,7 +2097,9 @@ def build_sarif(
1757
2097
  "driver": {
1758
2098
  "name": "Codex Security",
1759
2099
  "version": scan["producer"]["version"],
1760
- "rules": [_sarif_rule(rule_id) for rule_id in ordered_rule_ids],
2100
+ "rules": [
2101
+ _sarif_rule(rule_id, findings_by_rule[rule_id]) for rule_id in ordered_rule_ids
2102
+ ],
1761
2103
  }
1762
2104
  },
1763
2105
  "automationDetails": {"id": scan["id"]},
@@ -1894,11 +2236,12 @@ def _read_sealed_scan(
1894
2236
  },
1895
2237
  )
1896
2238
  _validate_manifest(manifest)
1897
- _validate_findings(manifest, findings)
2239
+ findings_for_validation = _legacy_sealed_findings_for_validation(findings)
2240
+ _validate_findings(manifest, findings_for_validation)
1898
2241
  _validate_coverage(manifest, coverage, scan_dir)
1899
2242
  _validate_sealed_coverage_receipts(scan, coverage)
1900
2243
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
1901
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2244
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
1902
2245
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
1903
2246
  _validate_derived_finding_identities(manifest, findings)
1904
2247
  return manifest, findings, coverage, findings_bytes
@@ -2196,8 +2539,11 @@ def _prepare_scan_finalization(
2196
2539
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
2197
2540
  _validate_target(_require_dict(scan, "target", "manifest.scan"))
2198
2541
  _validate_completion_binding(manifest, findings, coverage, completion_binding)
2542
+ findings_for_validation = (
2543
+ _legacy_sealed_findings_for_validation(findings) if was_sealed else findings
2544
+ )
2199
2545
  if was_sealed:
2200
- _validate_findings(manifest, findings)
2546
+ _validate_findings(manifest, findings_for_validation)
2201
2547
  _validate_derived_finding_identities(manifest, findings)
2202
2548
  elif completion_warnings is not None:
2203
2549
  discarded_findings = _recover_unsealed_findings(
@@ -2209,16 +2555,20 @@ def _prepare_scan_finalization(
2209
2555
  _recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
2210
2556
  else:
2211
2557
  _populate_unsealed_finding_identities(manifest, findings)
2212
- _validate_findings(manifest, findings)
2558
+ _validate_findings(manifest, findings_for_validation)
2213
2559
  _validate_coverage(manifest, coverage, scan_dir)
2214
- _validate_canonical_schemas_before_projection(manifest, findings, coverage, schema_dir)
2560
+ _validate_canonical_schemas_before_projection(
2561
+ manifest, findings_for_validation, coverage, schema_dir
2562
+ )
2215
2563
  _require_derived_writeup_files(scan_dir, findings)
2216
2564
  _require_hardening_portfolio_file(scan_dir, scan)
2217
2565
  if was_sealed:
2218
2566
  _validate_sealed_coverage_receipts(scan, coverage)
2219
2567
  _validate_manifest(manifest)
2220
2568
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2221
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2569
+ validate_against_schema(
2570
+ findings_for_validation, schema_dir / "findings.schema.json"
2571
+ )
2222
2572
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2223
2573
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2224
2574
  _validate_report_output_paths(scan_dir)