@openai/codex-security 0.6.0 → 0.8.0

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 (308) hide show
  1. package/README.md +76 -39
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  4. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  6. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  9. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  11. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  12. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  13. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  23. package/_bundled_plugin/references/access-advisory.md +11 -0
  24. package/_bundled_plugin/references/core-scan.md +30 -77
  25. package/_bundled_plugin/references/final-report.md +50 -184
  26. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  27. package/_bundled_plugin/references/scan-contract.md +12 -12
  28. package/_bundled_plugin/references/scan-prologue.md +1 -1
  29. package/_bundled_plugin/references/scan-runtime.md +1 -5
  30. package/_bundled_plugin/references/threat-model.md +33 -41
  31. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  32. package/_bundled_plugin/schemas/scan-manifest.schema.json +37 -11
  33. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  34. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  35. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  36. package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
  37. package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
  38. package/_bundled_plugin/scripts/report_projection.py +49 -17
  39. package/_bundled_plugin/scripts/review_state.py +68 -0
  40. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  41. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  43. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
  44. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  45. package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
  46. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  47. package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
  48. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  49. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  50. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  51. package/_bundled_plugin/scripts/workbench_db.py +55 -171
  52. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  53. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  54. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  55. package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
  56. package/_bundled_plugin/scripts/workbench_scan_history.py +77 -7
  57. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  58. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  59. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  60. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  61. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  62. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  63. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  64. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  65. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  66. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  67. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  68. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  69. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  70. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  71. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  72. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  73. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  74. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -24
  75. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  76. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  77. package/_bundled_plugin/skills/security-scan/SKILL.md +29 -17
  78. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  79. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  80. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  81. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  82. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  83. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  84. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  85. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  86. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  87. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  88. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  89. package/dist/api.d.ts +5 -3
  90. package/dist/api.d.ts.map +1 -1
  91. package/dist/api.js +359 -53
  92. package/dist/api.js.map +1 -1
  93. package/dist/auth.d.ts.map +1 -1
  94. package/dist/auth.js +4 -1
  95. package/dist/auth.js.map +1 -1
  96. package/dist/cli.d.ts +2 -2
  97. package/dist/cli.d.ts.map +1 -1
  98. package/dist/cli.js +696 -430
  99. package/dist/cli.js.map +1 -1
  100. package/dist/cloud-publish.d.ts.map +1 -1
  101. package/dist/cloud-publish.js +2 -23
  102. package/dist/cloud-publish.js.map +1 -1
  103. package/dist/component-scan.d.ts +8 -2
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +2 -0
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/contract.d.ts +5 -2
  108. package/dist/contract.d.ts.map +1 -1
  109. package/dist/contract.js +93 -45
  110. package/dist/contract.js.map +1 -1
  111. package/dist/cost.d.ts +18 -0
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +107 -12
  114. package/dist/cost.js.map +1 -1
  115. package/dist/coverage-presentation.d.ts +6 -0
  116. package/dist/coverage-presentation.d.ts.map +1 -0
  117. package/dist/coverage-presentation.js +34 -0
  118. package/dist/coverage-presentation.js.map +1 -0
  119. package/dist/custom-publish.js +2 -2
  120. package/dist/custom-publish.js.map +1 -1
  121. package/dist/custom-validation-prompt.js +5 -5
  122. package/dist/custom-validation-prompt.js.map +1 -1
  123. package/dist/custom-validation.d.ts.map +1 -1
  124. package/dist/custom-validation.js +47 -19
  125. package/dist/custom-validation.js.map +1 -1
  126. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  127. package/dist/deduplication/checkpointed-review.js +3 -1
  128. package/dist/deduplication/checkpointed-review.js.map +1 -1
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +2 -2
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  133. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  134. package/dist/deduplication/deduplication-prompts.js +3 -0
  135. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  136. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  137. package/dist/deduplication/records-protocol.js +21 -1
  138. package/dist/deduplication/records-protocol.js.map +1 -1
  139. package/dist/deduplication/scan.d.ts.map +1 -1
  140. package/dist/deduplication/scan.js +9 -7
  141. package/dist/deduplication/scan.js.map +1 -1
  142. package/dist/endor-findings.d.ts +4 -3
  143. package/dist/endor-findings.d.ts.map +1 -1
  144. package/dist/endor-findings.js +16 -11
  145. package/dist/endor-findings.js.map +1 -1
  146. package/dist/external-findings-import.d.ts.map +1 -1
  147. package/dist/external-findings-import.js +13 -5
  148. package/dist/external-findings-import.js.map +1 -1
  149. package/dist/external-findings-local.d.ts +1 -0
  150. package/dist/external-findings-local.d.ts.map +1 -1
  151. package/dist/external-findings-local.js +14 -3
  152. package/dist/external-findings-local.js.map +1 -1
  153. package/dist/external-findings-publish.d.ts +2 -1
  154. package/dist/external-findings-publish.d.ts.map +1 -1
  155. package/dist/external-findings-publish.js +64 -28
  156. package/dist/external-findings-publish.js.map +1 -1
  157. package/dist/external-findings-read.d.ts +12 -1
  158. package/dist/external-findings-read.d.ts.map +1 -1
  159. package/dist/external-findings-read.js +25 -6
  160. package/dist/external-findings-read.js.map +1 -1
  161. package/dist/external-findings.d.ts +2 -0
  162. package/dist/external-findings.d.ts.map +1 -1
  163. package/dist/external-findings.js.map +1 -1
  164. package/dist/external-import-contract.d.ts +7 -1
  165. package/dist/external-import-contract.d.ts.map +1 -1
  166. package/dist/external-import-contract.js +63 -31
  167. package/dist/external-import-contract.js.map +1 -1
  168. package/dist/external-imports-feature.d.ts +6 -0
  169. package/dist/external-imports-feature.d.ts.map +1 -0
  170. package/dist/external-imports-feature.js +51 -0
  171. package/dist/external-imports-feature.js.map +1 -0
  172. package/dist/finding-workflow.d.ts +24 -5
  173. package/dist/finding-workflow.d.ts.map +1 -1
  174. package/dist/finding-workflow.js +24 -9
  175. package/dist/finding-workflow.js.map +1 -1
  176. package/dist/github-advisories.d.ts.map +1 -1
  177. package/dist/github-advisories.js +3 -1
  178. package/dist/github-advisories.js.map +1 -1
  179. package/dist/github-findings.d.ts +4 -3
  180. package/dist/github-findings.d.ts.map +1 -1
  181. package/dist/github-findings.js +16 -14
  182. package/dist/github-findings.js.map +1 -1
  183. package/dist/host-protocol.d.ts +1 -1
  184. package/dist/host-protocol.d.ts.map +1 -1
  185. package/dist/host-protocol.js +2 -2
  186. package/dist/host-protocol.js.map +1 -1
  187. package/dist/hosted-remediation.d.ts.map +1 -1
  188. package/dist/hosted-remediation.js +19 -2
  189. package/dist/hosted-remediation.js.map +1 -1
  190. package/dist/hosted-scan.d.ts +1 -1
  191. package/dist/hosted-scan.d.ts.map +1 -1
  192. package/dist/hosted-scan.js +0 -6
  193. package/dist/hosted-scan.js.map +1 -1
  194. package/dist/import-scan.js +17 -17
  195. package/dist/import-scan.js.map +1 -1
  196. package/dist/index.d.ts +4 -3
  197. package/dist/index.d.ts.map +1 -1
  198. package/dist/index.js +2 -1
  199. package/dist/index.js.map +1 -1
  200. package/dist/knowledge-base.d.ts +1 -0
  201. package/dist/knowledge-base.d.ts.map +1 -1
  202. package/dist/knowledge-base.js +20 -8
  203. package/dist/knowledge-base.js.map +1 -1
  204. package/dist/mock-scan.d.ts +1 -2
  205. package/dist/mock-scan.d.ts.map +1 -1
  206. package/dist/mock-scan.js +12 -17
  207. package/dist/mock-scan.js.map +1 -1
  208. package/dist/models.d.ts +10 -1
  209. package/dist/models.d.ts.map +1 -1
  210. package/dist/models.js.map +1 -1
  211. package/dist/multiscan.d.ts.map +1 -1
  212. package/dist/multiscan.js +1 -6
  213. package/dist/multiscan.js.map +1 -1
  214. package/dist/native-json-findings.d.ts +30 -0
  215. package/dist/native-json-findings.d.ts.map +1 -0
  216. package/dist/native-json-findings.js +114 -0
  217. package/dist/native-json-findings.js.map +1 -0
  218. package/dist/opengrep-findings.d.ts +10 -0
  219. package/dist/opengrep-findings.d.ts.map +1 -0
  220. package/dist/opengrep-findings.js +198 -0
  221. package/dist/opengrep-findings.js.map +1 -0
  222. package/dist/owner-evidence.d.ts +2 -0
  223. package/dist/owner-evidence.d.ts.map +1 -1
  224. package/dist/owner-evidence.js +2 -1
  225. package/dist/owner-evidence.js.map +1 -1
  226. package/dist/patch-tui.d.ts.map +1 -1
  227. package/dist/patch-tui.js +2 -0
  228. package/dist/patch-tui.js.map +1 -1
  229. package/dist/publication.js +1 -2
  230. package/dist/publication.js.map +1 -1
  231. package/dist/publish.d.ts +2 -0
  232. package/dist/publish.d.ts.map +1 -1
  233. package/dist/publish.js +1 -1
  234. package/dist/publish.js.map +1 -1
  235. package/dist/record.d.ts +1 -0
  236. package/dist/record.d.ts.map +1 -1
  237. package/dist/record.js +10 -0
  238. package/dist/record.js.map +1 -1
  239. package/dist/remediation.d.ts +1 -25
  240. package/dist/remediation.d.ts.map +1 -1
  241. package/dist/remediation.js +3 -24
  242. package/dist/remediation.js.map +1 -1
  243. package/dist/result.d.ts +5 -3
  244. package/dist/result.d.ts.map +1 -1
  245. package/dist/result.js +9 -6
  246. package/dist/result.js.map +1 -1
  247. package/dist/runtime.d.ts.map +1 -1
  248. package/dist/runtime.js +7 -7
  249. package/dist/runtime.js.map +1 -1
  250. package/dist/scan-dashboard.d.ts +5 -3
  251. package/dist/scan-dashboard.d.ts.map +1 -1
  252. package/dist/scan-dashboard.js +79 -26
  253. package/dist/scan-dashboard.js.map +1 -1
  254. package/dist/scan-history-renderer.d.ts.map +1 -1
  255. package/dist/scan-history-renderer.js +9 -3
  256. package/dist/scan-history-renderer.js.map +1 -1
  257. package/dist/scan-owner-suggestions.d.ts +1 -1
  258. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  259. package/dist/scan-owner-suggestions.js +4 -4
  260. package/dist/scan-owner-suggestions.js.map +1 -1
  261. package/dist/scan-usage-display.d.ts +8 -0
  262. package/dist/scan-usage-display.d.ts.map +1 -0
  263. package/dist/scan-usage-display.js +46 -0
  264. package/dist/scan-usage-display.js.map +1 -0
  265. package/dist/scanner-import.d.ts +1 -1
  266. package/dist/scanner-import.d.ts.map +1 -1
  267. package/dist/scanner-import.js +7 -3
  268. package/dist/scanner-import.js.map +1 -1
  269. package/dist/security-policy.d.ts.map +1 -1
  270. package/dist/security-policy.js +17 -22
  271. package/dist/security-policy.js.map +1 -1
  272. package/dist/semgrep-findings.d.ts +4 -3
  273. package/dist/semgrep-findings.d.ts.map +1 -1
  274. package/dist/semgrep-findings.js +22 -89
  275. package/dist/semgrep-findings.js.map +1 -1
  276. package/dist/skill-authentication.d.ts +18 -0
  277. package/dist/skill-authentication.d.ts.map +1 -0
  278. package/dist/skill-authentication.js +82 -0
  279. package/dist/skill-authentication.js.map +1 -0
  280. package/dist/snyk-findings.d.ts +5 -4
  281. package/dist/snyk-findings.d.ts.map +1 -1
  282. package/dist/snyk-findings.js +18 -17
  283. package/dist/snyk-findings.js.map +1 -1
  284. package/dist/suggest-owners.d.ts +4 -1
  285. package/dist/suggest-owners.d.ts.map +1 -1
  286. package/dist/suggest-owners.js +53 -21
  287. package/dist/suggest-owners.js.map +1 -1
  288. package/dist/targets.d.ts.map +1 -1
  289. package/dist/targets.js +4 -1
  290. package/dist/targets.js.map +1 -1
  291. package/dist/wiz-csv.d.ts +2 -1
  292. package/dist/wiz-csv.d.ts.map +1 -1
  293. package/dist/wiz-csv.js +3 -3
  294. package/dist/wiz-csv.js.map +1 -1
  295. package/dist/wiz-findings.d.ts +2 -1
  296. package/dist/wiz-findings.d.ts.map +1 -1
  297. package/dist/wiz-findings.js +27 -23
  298. package/dist/wiz-findings.js.map +1 -1
  299. package/docs/classify-severity-records.md +3 -4
  300. package/docs/cli.md +171 -41
  301. package/docs/dedupe-records.md +15 -1
  302. package/docs/findings-service.md +119 -118
  303. package/docs/hosted-remediation.md +19 -17
  304. package/docs/hosted-scans.md +37 -11
  305. package/package.json +9 -9
  306. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  307. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  308. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -0,0 +1,627 @@
1
+ """Identify and recover records retained from saved scan evidence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import re
7
+ import unicodedata
8
+ from collections import Counter
9
+ from collections.abc import Iterator
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ from finalize_scan_contract import (
14
+ ContractError,
15
+ _has_identity_text,
16
+ _read_json,
17
+ _recover_unsealed_coverage,
18
+ _recover_unsealed_findings,
19
+ _require_safe_json_value,
20
+ _validate_current_findings,
21
+ _validate_schema_node,
22
+ finding_candidate_id,
23
+ )
24
+ from workbench.saved_coverage import _coverage_rows, _saved_coverage_id
25
+ from workbench.saved_sources import _digest, _encoded
26
+ from workbench_coverage_receipts import resolve_coverage_receipts
27
+
28
+ _FINDING_IDENTITY_SCHEMA = _read_json(
29
+ Path(__file__).resolve().parents[2] / "schemas" / "findings.schema.json"
30
+ )["properties"]["findings"]["items"]["properties"]["identity"]
31
+
32
+
33
+ def _finding_identity(finding: dict[str, Any]) -> Any:
34
+ provenance = finding.get("provenance")
35
+ if isinstance(provenance, dict) and "preservedIdentity" in provenance:
36
+ try:
37
+ _validate_schema_node(
38
+ provenance["preservedIdentity"], _FINDING_IDENTITY_SCHEMA, "finding.identity"
39
+ )
40
+ except ContractError:
41
+ pass
42
+ else:
43
+ return provenance["preservedIdentity"]
44
+ return finding.get("identity")
45
+
46
+
47
+ def _finding_key(finding: dict[str, Any], owner: str | None = None) -> str:
48
+ # Wording and evidence may improve between checkpoints; distinct source locations
49
+ # must not collide merely because two workers chose the same semantic identity.
50
+ provenance = finding.get("provenance")
51
+ identity = _finding_identity(finding)
52
+ if not isinstance(identity, dict):
53
+ normalized = dict(finding)
54
+ normalized.pop("identity", None)
55
+ _ensure_finding_identity(normalized)
56
+ identity = normalized["identity"]
57
+ owner = provenance.get("workerId", owner) if isinstance(provenance, dict) else owner
58
+ parts = [finding.get("ruleId"), identity, _finding_locations(finding)]
59
+ if owner is not None and finding_candidate_id(finding):
60
+ parts.append(owner)
61
+ return _digest(parts)
62
+
63
+
64
+ def _finding_locations(finding: dict[str, Any]) -> list[tuple[Any, Any, Any]]:
65
+ locations = finding.get("locations", [])
66
+ return sorted(
67
+ (
68
+ (
69
+ location.get("path"),
70
+ location.get("startLine"),
71
+ location.get("endLine", location.get("startLine")),
72
+ )
73
+ for location in (locations if isinstance(locations, list) else [])
74
+ if isinstance(location, dict)
75
+ ),
76
+ key=_encoded,
77
+ )
78
+
79
+
80
+ def _worker_candidate_key(
81
+ worker_id: str, candidate_id: str, finding: dict[str, Any]
82
+ ) -> tuple[str, str, Any, Any, Any]:
83
+ """Identify one worker-local candidate without merging unrelated locations."""
84
+ identity = _finding_identity(finding)
85
+ if not isinstance(identity, dict):
86
+ normalized = dict(finding)
87
+ _ensure_finding_identity(normalized)
88
+ identity = normalized.get("identity")
89
+ anchor = identity.get("anchor") if isinstance(identity, dict) else None
90
+ instance = identity.get("instance") if isinstance(identity, dict) else None
91
+ return worker_id, candidate_id, finding.get("ruleId"), anchor, instance
92
+
93
+
94
+ def _finding_content(finding: dict[str, Any]) -> dict[str, Any]:
95
+ """Return substantive finding content without generated identity or provenance."""
96
+ return {
97
+ key: value
98
+ for key, value in finding.items()
99
+ if key not in {"findingId", "occurrenceId", "fingerprints", "identity", "provenance"}
100
+ }
101
+
102
+
103
+ def _identity_candidate(finding: dict[str, Any]) -> str | None:
104
+ return next(
105
+ (
106
+ value
107
+ for section in (finding.get("extensions"), finding.get("provenance"))
108
+ if isinstance(section, dict) and _has_identity_text(value := section.get("candidateId"))
109
+ ),
110
+ None,
111
+ )
112
+
113
+
114
+ def _ensure_finding_identity(finding: Any) -> None:
115
+ _ensure_finding_identities([finding])
116
+
117
+
118
+ def _semantic_identifier(value: str, fallback: str) -> str:
119
+ normalized = re.sub(r"[\u0300-\u036f]", "", unicodedata.normalize("NFKD", value))
120
+ identifier = re.sub(r"[^a-z0-9._/-]+", "-", normalized.lower())
121
+ return re.sub(r"^[^a-z0-9]+|-+$", "", identifier) or fallback
122
+
123
+
124
+ def _semantic_identity_key(finding: dict[str, Any], identity: Any = None) -> bytes:
125
+ identity = finding.get("identity") if identity is None else identity
126
+ if isinstance(identity, dict):
127
+ identity = {key: identity.get(key) for key in ("anchor", "instance")}
128
+ return _encoded([finding.get("ruleId"), identity])
129
+
130
+
131
+ def _ensure_finding_identities(findings: list[Any], *, deep: bool = False) -> None:
132
+ """Use the same candidate, anchor and sibling rules as draft publication."""
133
+ anchors: dict[int, Any] = {}
134
+ for index, finding in enumerate(findings):
135
+ if not isinstance(finding, dict):
136
+ continue
137
+ identity = finding.get("identity")
138
+ if "identity" in finding:
139
+ anchors[index] = identity.get("anchor") if isinstance(identity, dict) else None
140
+ continue
141
+ candidate = _identity_candidate(finding)
142
+ anchors[index] = _semantic_identifier(
143
+ candidate or str(finding.get("title") or "finding"), f"finding-{index + 1}"
144
+ )
145
+ counts = Counter(
146
+ _digest([findings[index].get("ruleId"), anchor]) for index, anchor in anchors.items()
147
+ )
148
+
149
+ authored = {
150
+ _semantic_identity_key(finding)
151
+ for finding in findings
152
+ if isinstance(finding, dict) and "identity" in finding
153
+ }
154
+ generated = []
155
+ for index, anchor in anchors.items():
156
+ finding = findings[index]
157
+ if "identity" in finding:
158
+ continue
159
+ identity = {"anchor": anchor}
160
+ extensions = finding.get("extensions")
161
+ sibling = next(
162
+ (
163
+ value
164
+ for field in ("reportId", "ledgerRowId")
165
+ if isinstance(extensions, dict)
166
+ and _has_identity_text(value := extensions.get(field))
167
+ ),
168
+ None,
169
+ )
170
+ if sibling or counts[_digest([finding.get("ruleId"), anchor])] > 1:
171
+ identity["instance"] = _semantic_identifier(
172
+ sibling or str(finding.get("title") or "finding"), f"finding-{index + 1}"
173
+ )
174
+ finding["identity"] = identity
175
+ generated.append(finding)
176
+
177
+ reserved = {
178
+ _semantic_identity_key(finding) for finding in findings if isinstance(finding, dict)
179
+ }
180
+ used = set() if deep else authored.copy()
181
+ generated_ids = {id(finding) for finding in generated}
182
+ for finding in findings if deep else generated:
183
+ key = _semantic_identity_key(finding)
184
+ if key in used or (id(finding) in generated_ids and key in authored):
185
+ identity = finding["identity"]
186
+ if id(finding) not in generated_ids:
187
+ finding.setdefault("provenance", {}).setdefault(
188
+ "preservedIdentity", copy.deepcopy(identity)
189
+ )
190
+ base_instance = identity.get("instance", "saved")
191
+ suffix = 2
192
+ while True:
193
+ identity["instance"] = f"{base_instance}-{suffix}"
194
+ key = _semantic_identity_key(finding)
195
+ if key not in reserved:
196
+ reserved.add(key)
197
+ break
198
+ suffix += 1
199
+ used.add(key)
200
+
201
+
202
+ def _retained_findings(finding: dict[str, Any]) -> Iterator[dict[str, Any]]:
203
+ """Yield canonical and historical findings without trusting candidate IDs."""
204
+ pending = [finding]
205
+ seen: set[int] = set()
206
+ while pending:
207
+ current = pending.pop()
208
+ marker = id(current)
209
+ if marker in seen:
210
+ continue
211
+ seen.add(marker)
212
+ yield current
213
+ provenance = current.get("provenance")
214
+ if not isinstance(provenance, dict):
215
+ continue
216
+ previous = provenance.get("previousFindings")
217
+ if isinstance(previous, list):
218
+ pending.extend(item for item in reversed(previous) if isinstance(item, dict))
219
+ sources = provenance.get("sourceFindings")
220
+ if isinstance(sources, list):
221
+ pending.extend(
222
+ source["finding"]
223
+ for source in reversed(sources)
224
+ if isinstance(source, dict) and isinstance(source.get("finding"), dict)
225
+ )
226
+
227
+
228
+ def _append_previous_finding(
229
+ item: dict[str, Any], finding: dict[str, Any], *, clone: bool = False
230
+ ) -> None:
231
+ if not isinstance(item.get("previousFindings"), list):
232
+ item["previousFindings"] = []
233
+ history = item["previousFindings"]
234
+ if not any(
235
+ isinstance(previous, dict)
236
+ and _finding_key(previous) == _finding_key(finding)
237
+ and _finding_content(previous) == _finding_content(finding)
238
+ for previous in history
239
+ ):
240
+ history.append(copy.deepcopy(finding) if clone else finding)
241
+
242
+
243
+ def _recover_preserved_worker_source(
244
+ scan_dir, relative, scan_id, binding, worker_id, worker, draft, warnings
245
+ ):
246
+ discarded_findings = []
247
+ # Recover imported records without relaxing canonical parent validation.
248
+ if "complete" in draft and not isinstance(draft["complete"], bool):
249
+ draft["complete"] = False
250
+ warnings.append(f"{relative}: Invalid complete marker; retained as a progress checkpoint.")
251
+ schema_dir = Path(__file__).resolve().parents[2] / "schemas"
252
+ if "threatModel" in draft:
253
+ try:
254
+ model = draft["threatModel"]
255
+ if isinstance(model, dict):
256
+ model = {**model, "origin": "recovered"}
257
+ schema = _read_json(schema_dir / "scan-manifest.schema.json")
258
+ _validate_schema_node(
259
+ model,
260
+ schema["properties"]["scan"]["properties"]["threatModel"],
261
+ "threatModel",
262
+ schema,
263
+ )
264
+ _require_safe_json_value(model, "threatModel")
265
+ except ContractError as exc:
266
+ draft.pop("threatModel")
267
+ warnings.append(f"{relative}: Skipped malformed threat model: {exc}.")
268
+ directory = Path(relative).parent
269
+ if directory.name == "checkpoints":
270
+ directory = directory.parent
271
+ recovered_findings = []
272
+ for index, finding in enumerate(draft["findings"]):
273
+ needs_identity = isinstance(finding, dict) and "identity" not in finding
274
+ _ensure_finding_identity(finding)
275
+ recovered = {"scanId": scan_id, "findings": [finding]}
276
+ source_warnings: list[str] = []
277
+ discarded = _recover_unsealed_findings(
278
+ {"scan": {"id": scan_id, "target": binding["target"]}},
279
+ recovered,
280
+ schema_dir,
281
+ scan_dir / directory,
282
+ source_warnings,
283
+ )
284
+ if recovered["findings"]:
285
+ try:
286
+ _validate_current_findings(recovered, schema_dir)
287
+ except ContractError as exc:
288
+ warning = f"Skipped malformed finding: {exc}."
289
+ source_warnings.append(warning)
290
+ discarded.append(warning)
291
+ recovered["findings"] = []
292
+ if discarded:
293
+ discarded_findings.extend(discarded)
294
+ for recovered_finding in recovered["findings"]:
295
+ if needs_identity:
296
+ # Reconcile anonymous revisions before assigning sibling identities.
297
+ recovered_finding.pop("identity", None)
298
+ writeup = recovered_finding.pop("writeup", None)
299
+ if writeup is not None:
300
+ source_warnings.append(
301
+ "Retained worker writeup at "
302
+ f"{directory.as_posix()}/{writeup['reportPath']}; "
303
+ "the parent report renders this finding inline."
304
+ )
305
+ recovered_findings.extend(recovered["findings"])
306
+ warnings.extend(f"{relative} finding {index + 1}: {warning}" for warning in source_warnings)
307
+ draft["findings"] = recovered_findings
308
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
309
+ rows = draft["reviewState"].get(field)
310
+ if not isinstance(rows, list):
311
+ continue
312
+ for index, row in enumerate(rows):
313
+ if field == "openQuestions" and isinstance(row, str):
314
+ row = rows[index] = {"question": row}
315
+ if not isinstance(row, dict):
316
+ continue
317
+ row["workerId"] = worker_id
318
+ if field == "surfaces":
319
+ row["receiptRefs"] = resolve_coverage_receipts(
320
+ scan_dir,
321
+ row,
322
+ worker,
323
+ relative,
324
+ )
325
+ return discarded_findings
326
+
327
+
328
+ def _recover_preserved_worker_coverage(
329
+ scan_dir, relative, worker_id, draft, discarded_findings, warnings
330
+ ):
331
+ discarded_coverage = False
332
+ for field in ("surfaces", "explicitExclusions", "deferred"):
333
+ rows = draft["reviewState"].get(field)
334
+ for row in rows if isinstance(rows, list) else []:
335
+ if isinstance(row, dict):
336
+ row.setdefault("id", _saved_coverage_id(row))
337
+ if field == "surfaces":
338
+ row.setdefault("receiptRefs", [])
339
+ source_warnings = []
340
+ discarded_fields = _recover_unsealed_coverage(
341
+ draft["reviewState"],
342
+ Path(__file__).resolve().parents[2] / "schemas",
343
+ scan_dir,
344
+ source_warnings,
345
+ discarded_findings,
346
+ # Reconcile local IDs and valid outcomes against worker history below.
347
+ worker_draft=True,
348
+ )
349
+ if discarded_fields & {
350
+ "surfaces",
351
+ "explicitExclusions",
352
+ "deferred",
353
+ "resolvedDeferred",
354
+ }:
355
+ discarded_coverage = True
356
+ for row in draft["reviewState"]["deferred"]:
357
+ row["workerId"] = worker_id
358
+ warnings.extend(f"{relative}: {warning}" for warning in source_warnings)
359
+ return discarded_coverage
360
+
361
+
362
+ def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
363
+ extensions = value.get("extensions")
364
+ return tuple(
365
+ identifier if _has_identity_text(identifier) else None
366
+ for identifier in (
367
+ extensions.get(field) if isinstance(extensions, dict) else None
368
+ for field in ("reportId", "ledgerRowId")
369
+ )
370
+ )
371
+
372
+
373
+ def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None) -> bool:
374
+ return (
375
+ left is not None
376
+ and right is not None
377
+ and any(
378
+ a is not None and b is not None and a != b
379
+ for a, b in zip(identifiers(left["latest"]), identifiers(right["latest"]), strict=True)
380
+ )
381
+ )
382
+
383
+
384
+ def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
385
+ if source_owner is not None:
386
+ return source_owner
387
+ provenance = value.get("provenance", {})
388
+ owner = provenance.get("workerId")
389
+ return owner if isinstance(owner, str) else source_owner
390
+
391
+
392
+ def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
393
+ # Match scanFindingIdentity's primary location for anonymous reports.
394
+ location = value["locations"][0]
395
+ return (
396
+ value.get("ruleId"),
397
+ location["path"],
398
+ location["startLine"],
399
+ location.get("endLine"),
400
+ )
401
+
402
+
403
+ def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
404
+ if isinstance(left.get("identity"), dict) and isinstance(right.get("identity"), dict):
405
+ return _semantic_identity_key(left, _finding_identity(left)) == _semantic_identity_key(
406
+ right, _finding_identity(right)
407
+ )
408
+ candidates = (_identity_candidate(left), _identity_candidate(right))
409
+ if all(candidates) and candidates[0] != candidates[1]:
410
+ return False
411
+ pairs = list(zip(identifiers(left), identifiers(right), strict=True))
412
+ if any(a is not None for a, _ in pairs) and any(b is not None for _, b in pairs):
413
+ if not any(a is not None and b is not None for a, b in pairs) or any(
414
+ a is not None and b is not None and a != b for a, b in pairs
415
+ ):
416
+ return False
417
+ return True
418
+
419
+
420
+ def same_raw_value(left: Any, right: Any) -> bool:
421
+ if isinstance(left, dict):
422
+ return (
423
+ isinstance(right, dict)
424
+ and left.keys() == right.keys()
425
+ and all(same_raw_value(value, right[key]) for key, value in left.items())
426
+ )
427
+ if isinstance(left, list):
428
+ return (
429
+ isinstance(right, list)
430
+ and len(left) == len(right)
431
+ and all(same_raw_value(a, b) for a, b in zip(left, right, strict=True))
432
+ )
433
+ # JSON numbers compare by value, but booleans are a distinct scalar type.
434
+ return isinstance(left, bool) == isinstance(right, bool) and left == right
435
+
436
+
437
+ def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
438
+ def content(value: dict[str, Any]) -> dict[str, Any]:
439
+ result = _finding_content(value)
440
+ if isinstance(result.get("extensions"), dict):
441
+ result["extensions"] = {
442
+ key: value
443
+ for key, value in result["extensions"].items()
444
+ if key not in {"candidateId", "reportId", "ledgerRowId"}
445
+ }
446
+ if not result["extensions"]:
447
+ result.pop("extensions")
448
+ return result
449
+
450
+ return same_raw_value(content(left), content(right))
451
+
452
+
453
+ def contains_raw_value(current: Any, previous: Any) -> bool:
454
+ if isinstance(previous, dict):
455
+ return isinstance(current, dict) and all(
456
+ key in current and contains_raw_value(current[key], value)
457
+ for key, value in previous.items()
458
+ )
459
+ if isinstance(previous, list):
460
+ return isinstance(current, list) and all(
461
+ any(contains_raw_value(item, value) for item in current) for value in previous
462
+ )
463
+ return isinstance(current, bool) == isinstance(previous, bool) and current == previous
464
+
465
+
466
+ def _saved_outcome_receipts(scan_dir, relative, worker, field, item, coverage_schema):
467
+ normalized = dict(item)
468
+ if field == "surfaces":
469
+ normalized.setdefault("id", _saved_coverage_id(item))
470
+ normalized.setdefault("receiptRefs", [])
471
+ if worker is not None:
472
+ normalized["receiptRefs"] = resolve_coverage_receipts(
473
+ scan_dir, normalized, worker, relative
474
+ )
475
+ verified = {
476
+ "completeness": "partial",
477
+ "surfaces": [normalized],
478
+ "explicitExclusions": [],
479
+ "deferred": [],
480
+ }
481
+ _recover_unsealed_coverage(
482
+ verified, Path(__file__).resolve().parents[2] / "schemas", scan_dir, [], []
483
+ )
484
+ if (
485
+ not verified["surfaces"]
486
+ or verified["surfaces"][0]["disposition"] != item["disposition"]
487
+ ):
488
+ return None
489
+ normalized = verified["surfaces"][0]
490
+ try:
491
+ _validate_schema_node(normalized, coverage_schema[field]["items"], f"coverage.{field}")
492
+ except ContractError:
493
+ return None
494
+ return tuple(normalized.get("receiptRefs", [])) if field == "surfaces" else ()
495
+
496
+
497
+ def _conflicting_outcome_receipts(coverage, scan_dir, receipts):
498
+ # Only a recovered surface can reserve the spelling that invalidates a second row.
499
+ surfaces = _coverage_rows(coverage, "surfaces")
500
+ projected = {
501
+ "surfaces": [dict(row) if isinstance(row, dict) else row for row in surfaces],
502
+ "deferred": [],
503
+ "explicitExclusions": [],
504
+ }
505
+ _recover_unsealed_coverage(
506
+ projected, Path(__file__).resolve().parents[2] / "schemas", scan_dir, [], []
507
+ )
508
+ kept = {ref.lower(): ref for row in projected["surfaces"] for ref in row["receiptRefs"]}
509
+ for row in surfaces:
510
+ if not (
511
+ isinstance(row, dict)
512
+ and isinstance(row.get("candidateId"), str)
513
+ and row.get("disposition") in ("rejected", "not_applicable")
514
+ and isinstance(row.get("receiptRefs"), list)
515
+ ):
516
+ continue
517
+ normalized = {Path(ref).as_posix() for ref in row["receiptRefs"] if isinstance(ref, str)}
518
+ if losing := {ref for ref in normalized & receipts if kept.get(ref.lower(), ref) != ref}:
519
+ return losing
520
+ return set()
521
+
522
+
523
+ def _saved_candidate_outcomes(
524
+ scan_dir,
525
+ current_drafts,
526
+ valid_finding,
527
+ coverage_candidate,
528
+ candidate_order,
529
+ workers_by_id,
530
+ coverage_schema,
531
+ ):
532
+ pending_candidate_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
533
+ outcomes = []
534
+ for relative, draft, owner in current_drafts:
535
+ reported_candidates = {
536
+ finding_candidate_id(finding)
537
+ for finding in draft["findings"]
538
+ if isinstance(finding, dict) and valid_finding(finding)
539
+ }
540
+ pending_candidates = set()
541
+ for field in ("deferred", "surfaces"):
542
+ items = draft["reviewState"].get(field, [])
543
+ for item in items if isinstance(items, list) else []:
544
+ if isinstance(item, dict) and (
545
+ field == "deferred" or item.get("disposition") == "needs_follow_up"
546
+ ):
547
+ if (pending := coverage_candidate(owner, item)) is not None:
548
+ if (
549
+ owner is not None
550
+ and pending[0] == owner
551
+ and pending[1] in reported_candidates
552
+ ):
553
+ continue
554
+ pending_candidates.add(pending)
555
+ order = candidate_order(relative, pending[0], item)
556
+ pending_candidate_orders[pending] = max(
557
+ pending_candidate_orders.get(pending, order), order
558
+ )
559
+ for finding in draft["findings"]:
560
+ if (
561
+ isinstance(finding, dict)
562
+ and valid_finding(finding)
563
+ and (candidate_id := finding_candidate_id(finding))
564
+ ):
565
+ outcomes.append(
566
+ (
567
+ relative,
568
+ owner,
569
+ candidate_id,
570
+ "reported",
571
+ candidate_order(relative, owner),
572
+ (),
573
+ )
574
+ )
575
+ for field in ("surfaces", "explicitExclusions"):
576
+ for item in _coverage_rows(draft["reviewState"], field):
577
+ if (
578
+ isinstance(item, dict)
579
+ and isinstance(item.get("candidateId"), str)
580
+ and item.get("disposition") in ("reported", "rejected", "not_applicable")
581
+ and (candidate := coverage_candidate(owner, item)) is not None
582
+ and (item["disposition"] != "reported" or candidate[1] in reported_candidates)
583
+ and (candidate not in pending_candidates or item["disposition"] == "reported")
584
+ ):
585
+ receipts = ()
586
+ if item["disposition"] != "reported":
587
+ receipts = _saved_outcome_receipts(
588
+ scan_dir,
589
+ relative,
590
+ workers_by_id.get(owner),
591
+ field,
592
+ item,
593
+ coverage_schema,
594
+ )
595
+ if receipts is None:
596
+ continue
597
+ outcomes.append(
598
+ (
599
+ relative,
600
+ candidate[0],
601
+ candidate[1],
602
+ item["disposition"],
603
+ candidate_order(relative, candidate[0], item),
604
+ receipts,
605
+ )
606
+ )
607
+ return outcomes, pending_candidate_orders
608
+
609
+
610
+ def _competing_rejection_receipts(outcomes, all_sources, source_surface_receipts):
611
+ receipt_spellings: dict[str, set[str]] = {}
612
+ for _, _, _, _, _, receipts in outcomes:
613
+ for ref in receipts:
614
+ receipt_spellings.setdefault(ref.lower(), set()).add(ref)
615
+ if receipt_spellings and any(
616
+ isinstance(ref, str)
617
+ and (spellings := receipt_spellings.get(Path(ref).as_posix().lower())) is not None
618
+ and spellings != {Path(ref).as_posix()}
619
+ for relative, draft, owner in all_sources
620
+ for row in _coverage_rows(draft["reviewState"], "surfaces")
621
+ if isinstance(row, dict)
622
+ for refs in (source_surface_receipts(relative, row),)
623
+ if isinstance(refs, list)
624
+ for ref in refs
625
+ ):
626
+ return {ref for spellings in receipt_spellings.values() for ref in spellings}
627
+ return set()