@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
@@ -27,6 +27,7 @@ from urllib.parse import quote, urlsplit
27
27
  sys.path.insert(0, str(Path(__file__).resolve().parent))
28
28
  import report_projection
29
29
  import threat_model_projection
30
+ from review_state import checkpoint_review_state, review_state, review_summary
30
31
 
31
32
  SCHEMA_VERSION = "1.0"
32
33
  PRODUCER_NAME = "codex-security-plugin"
@@ -97,6 +98,10 @@ class ContractError(ValueError):
97
98
  """Raised when a completed scan does not satisfy the additive contract."""
98
99
 
99
100
 
101
+ class ScanLocalIOError(ContractError):
102
+ """Raised when scan-local storage I/O fails, distinct from path validation."""
103
+
104
+
100
105
  class MissingScanLocalFileError(ContractError):
101
106
  """Raised when a scan-local file or its containing directory is absent."""
102
107
 
@@ -199,11 +204,7 @@ def _read_saved_threat_model(
199
204
  if filename == "scan-manifest.json"
200
205
  else manifest
201
206
  )
202
- if (
203
- validate_seal
204
- and filename == "scan-manifest.json"
205
- and (scan.get("sealedAt") is not None or scan.get("artifacts"))
206
- ):
207
+ if validate_seal and filename == "scan-manifest.json" and manifest_is_sealed(scan):
207
208
  if "threatModel" not in scan:
208
209
  _validate_manifest(manifest)
209
210
  recorded_paths = {
@@ -428,7 +429,7 @@ def _require_safe_relative_path(value: object, context: str, *, allow_dot: bool
428
429
  normalized = path.as_posix()
429
430
  if (
430
431
  (normalized == "." and not allow_dot)
431
- or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
432
+ or re.match(r"^[A-Za-z]:", value)
432
433
  or "\\" in value
433
434
  or "\0" in value
434
435
  or any(ord(character) < 32 for character in value)
@@ -452,18 +453,28 @@ def _windows_unsafe_path_component(value: str) -> bool:
452
453
  return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None
453
454
 
454
455
 
456
+ def _scan_local_directory_error(message: str, error: OSError) -> ContractError:
457
+ if error.errno in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
458
+ return ContractError(message)
459
+ return ScanLocalIOError(message)
460
+
461
+
455
462
  def _require_scan_directory(scan_dir: Path) -> Path:
456
463
  scan_dir = scan_dir.absolute()
457
464
  try:
458
465
  metadata = scan_dir.lstat()
459
466
  except OSError as exc:
460
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
467
+ raise _scan_local_directory_error(
468
+ "scan directory: expected an existing non-symlink directory", exc
469
+ ) from exc
461
470
  if not stat.S_ISDIR(metadata.st_mode):
462
471
  raise ContractError("scan directory: expected an existing non-symlink directory")
463
472
  try:
464
473
  resolved = scan_dir.resolve(strict=True)
465
474
  except OSError as exc:
466
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
475
+ raise _scan_local_directory_error(
476
+ "scan directory: expected an existing non-symlink directory", exc
477
+ ) from exc
467
478
  if os.path.normcase(resolved) != os.path.normcase(scan_dir):
468
479
  raise ContractError("scan directory: expected a canonical non-symlink directory")
469
480
  return resolved
@@ -518,7 +529,9 @@ def _open_verified_scan_directory(
518
529
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
519
530
  )
520
531
  except OSError as exc:
521
- raise ContractError("scan directory: expected an existing non-symlink directory") from exc
532
+ raise _scan_local_directory_error(
533
+ "scan directory: expected an existing non-symlink directory", exc
534
+ ) from exc
522
535
  opened = os.fstat(descriptor)
523
536
  opened_identity = (opened.st_dev, opened.st_ino)
524
537
  if opened_identity != observed_identity or (
@@ -770,15 +783,18 @@ def write_scan_local_bytes(
770
783
  if not _descriptor_relative_writes_available():
771
784
  if not _is_windows():
772
785
  raise ContractError("scan-local output requires descriptor-relative file operations")
786
+ backend = _windows_scan_local_files()
773
787
  try:
774
- _windows_scan_local_files().atomic_write(
788
+ backend.atomic_write(
775
789
  scan_dir,
776
790
  relative_path,
777
791
  payload,
778
792
  expected_root_identity=expected_root_identity,
779
793
  )
780
- except OSError as exc:
794
+ except backend.WindowsScanLocalPathError as exc:
781
795
  raise ContractError(f"{relative_path}: {exc}") from exc
796
+ except OSError as exc:
797
+ raise ScanLocalIOError(f"{relative_path}: {exc}") from exc
782
798
  return
783
799
  root_fd: int | None = None
784
800
  parent_fd: int | None = None
@@ -789,8 +805,8 @@ def write_scan_local_bytes(
789
805
  try:
790
806
  parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=True)
791
807
  except OSError as exc:
792
- raise ContractError(
793
- f"{relative_path}: expected a path inside the scan directory"
808
+ raise _scan_local_directory_error(
809
+ f"{relative_path}: expected a path inside the scan directory", exc
794
810
  ) from exc
795
811
  # The held descriptor is the authority for the validated parent. A
796
812
  # concurrent rename cannot redirect later operations through a
@@ -1075,6 +1091,8 @@ def _recover_unsealed_findings(
1075
1091
  schema_dir: Path,
1076
1092
  scan_dir: Path,
1077
1093
  warnings: list[str],
1094
+ *,
1095
+ current_contract: bool = False,
1078
1096
  ) -> list[str]:
1079
1097
  schema = _read_json(schema_dir / "findings.schema.json")
1080
1098
  properties = _require_dict(schema, "properties", "findings.schema")
@@ -1190,6 +1208,9 @@ def _recover_unsealed_findings(
1190
1208
  f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
1191
1209
  )
1192
1210
  _validate_schema_node(finding, finding_schema, context, schema)
1211
+ _require_safe_json_value(finding, context)
1212
+ if current_contract:
1213
+ _validate_current_findings({"findings": [finding]}, schema_dir)
1193
1214
  except ContractError as exc:
1194
1215
  warning = f"Skipped malformed finding {index + 1}: {exc}."
1195
1216
  warnings.append(warning)
@@ -1245,9 +1266,12 @@ def _recover_unsealed_coverage(
1245
1266
  scan_dir: Path,
1246
1267
  warnings: list[str],
1247
1268
  discarded_findings: list[str],
1248
- ) -> None:
1269
+ *,
1270
+ worker_draft: bool = False,
1271
+ ) -> set[str]:
1249
1272
  schema = _read_json(schema_dir / "coverage.schema.json")
1250
1273
  properties = _require_dict(schema, "properties", "coverage.schema")
1274
+ discarded_fields: set[str] = set()
1251
1275
  if (
1252
1276
  coverage.get("mode") == "deep_repository"
1253
1277
  and coverage.get("inventoryStrategy") != "repository"
@@ -1257,16 +1281,24 @@ def _recover_unsealed_coverage(
1257
1281
 
1258
1282
  surface_ids: set[str] = set()
1259
1283
  receipt_paths: dict[str, str] = {}
1260
- for field, label in (
1284
+ fields = [
1261
1285
  ("surfaces", "coverage surface"),
1262
1286
  ("explicitExclusions", "coverage exclusion"),
1263
1287
  ("deferred", "deferred coverage item"),
1264
- ):
1288
+ ]
1289
+ if worker_draft:
1290
+ if "openQuestions" in coverage:
1291
+ _normalize_unsealed_open_questions(coverage)
1292
+ fields.append(("openQuestions", "coverage open question"))
1293
+ if "resolvedDeferred" in coverage:
1294
+ fields.append(("resolvedDeferred", "resolved deferred item"))
1295
+ for field, label in fields:
1265
1296
  array_schema = _require_dict(properties, field, "coverage.schema.properties")
1266
1297
  item_schema = _require_dict(array_schema, "items", f"coverage.schema.properties.{field}")
1267
1298
  items = coverage.get(field)
1268
1299
  if not isinstance(items, list):
1269
1300
  warnings.append(f"Skipped malformed {label} records: expected an array.")
1301
+ discarded_fields.add(field)
1270
1302
  coverage[field] = []
1271
1303
  continue
1272
1304
 
@@ -1279,7 +1311,9 @@ def _recover_unsealed_coverage(
1279
1311
  if field == "surfaces":
1280
1312
  surface_receipt_paths = dict(receipt_paths)
1281
1313
  surface_id = _require_str(item, "id", context)
1282
- if surface_id in surface_ids:
1314
+ if worker_draft:
1315
+ _require_str(item, "label", context)
1316
+ if surface_id in surface_ids and not worker_draft:
1283
1317
  raise ContractError(f"{context}.id: duplicate surface id")
1284
1318
  disposition = item.get("disposition")
1285
1319
  surface_recovered = False
@@ -1329,12 +1363,18 @@ def _recover_unsealed_coverage(
1329
1363
  item["receiptRefs"] = recovered_receipts
1330
1364
  if surface_recovered:
1331
1365
  item["disposition"] = "needs_follow_up"
1366
+ discarded_fields.add(field)
1332
1367
 
1333
1368
  if field == "deferred":
1334
1369
  _validate_deferred_paths(item, context)
1335
1370
  _validate_schema_node(item, item_schema, context)
1371
+ if field == "resolvedDeferred":
1372
+ _validate_resolved_deferred({"resolvedDeferred": [item]})
1373
+ if worker_draft:
1374
+ _require_safe_json_value(item, context)
1336
1375
  except ContractError as exc:
1337
1376
  warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
1377
+ discarded_fields.add(field)
1338
1378
  continue
1339
1379
 
1340
1380
  if field == "surfaces":
@@ -1346,6 +1386,13 @@ def _recover_unsealed_coverage(
1346
1386
 
1347
1387
  if discarded_findings:
1348
1388
  for surface in coverage["surfaces"]:
1389
+ if (
1390
+ worker_draft
1391
+ and surface.get("candidateId")
1392
+ and surface["disposition"] in {"rejected", "not_applicable"}
1393
+ ):
1394
+ # A valid explicit outcome can still resolve that worker's history.
1395
+ continue
1349
1396
  surface["disposition"] = "needs_follow_up"
1350
1397
  coverage["deferred"].extend(
1351
1398
  {"id": f"discarded-finding-{index}", "reason": warning}
@@ -1360,9 +1407,13 @@ def _recover_unsealed_coverage(
1360
1407
  "coverage.resolvedDeferred",
1361
1408
  )
1362
1409
  _validate_resolved_deferred(coverage)
1410
+ if worker_draft:
1411
+ _require_safe_json_value(coverage["resolvedDeferred"], "coverage.resolvedDeferred")
1363
1412
  except ContractError as exc:
1364
1413
  coverage.pop("resolvedDeferred")
1365
1414
  warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
1415
+ discarded_fields.add("resolvedDeferred")
1416
+ return discarded_fields
1366
1417
 
1367
1418
 
1368
1419
  def _recover_unsealed_hardening(
@@ -1417,8 +1468,9 @@ def _populate_unsealed_manifest_envelope(
1417
1468
  scan["status"] = (
1418
1469
  completion_binding.get("status", "completed") if completion_binding else "completed"
1419
1470
  )
1420
- scan["coverageRef"] = "coverage.json"
1421
1471
  scan["findingsRef"] = "findings.json"
1472
+ if "coverageRef" in scan:
1473
+ scan["coverageRef"] = "coverage.json"
1422
1474
  if completion_binding is None:
1423
1475
  started_at = os.environ.get("CODEX_SECURITY_STARTED_AT")
1424
1476
  if started_at is not None:
@@ -1831,7 +1883,7 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1831
1883
  artifact_collision_keys.add(collision_key)
1832
1884
  _require_str(artifact, "sha256", context)
1833
1885
  _require_str(artifact, "mediaType", context)
1834
- for required_path in ("findings.json", "coverage.json"):
1886
+ for required_path in ("findings.json", *(["coverage.json"] if "coverageRef" in scan else [])):
1835
1887
  if required_path not in artifact_paths:
1836
1888
  raise ContractError(
1837
1889
  f"manifest.scan.artifacts: missing required artifact: {required_path}"
@@ -1921,6 +1973,21 @@ def _resolve_schema_reference(
1921
1973
  return target
1922
1974
 
1923
1975
 
1976
+ def _matches_sealed_path_exclusion(value: str, one_of: Any) -> bool:
1977
+ # The empty alternative always matches, so a path must not match the second one.
1978
+ if not isinstance(one_of, list) or len(one_of) != 2 or one_of[0] != {}:
1979
+ return False
1980
+ excluded = one_of[1]
1981
+ return (
1982
+ isinstance(excluded, dict)
1983
+ and excluded.keys() == {"$comment", "type", "pattern"}
1984
+ and excluded["$comment"] == "invalidSealedDeferredPath"
1985
+ and excluded["type"] == "string"
1986
+ and isinstance(excluded["pattern"], str)
1987
+ and re.search(excluded["pattern"], value) is not None
1988
+ )
1989
+
1990
+
1924
1991
  def _validate_schema_node(
1925
1992
  value: Any,
1926
1993
  schema: dict[str, Any],
@@ -1970,6 +2037,8 @@ def _validate_schema_node(
1970
2037
  raise ContractError(f"{context}: string is too long")
1971
2038
  if "pattern" in schema and not re.search(schema["pattern"], value):
1972
2039
  raise ContractError(f"{context}: string does not match schema pattern")
2040
+ if _matches_sealed_path_exclusion(value, schema.get("oneOf")):
2041
+ raise ContractError(f"{context}: string matches excluded schema pattern")
1973
2042
  if schema.get("format") == "date-time":
1974
2043
  _validate_date_time(value, context)
1975
2044
  if isinstance(value, (int, float)) and not isinstance(value, bool):
@@ -2238,6 +2307,9 @@ def _validate_canonical_schemas_before_projection(
2238
2307
  {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
2239
2308
  {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
2240
2309
  ]
2310
+ if "coverageRef" not in provisional_scan:
2311
+ provisional_scan["mode"] = coverage["mode"]
2312
+ provisional_scan["review"] = review_summary(coverage)
2241
2313
  validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
2242
2314
  validate_against_schema(findings, schema_dir / "findings.schema.json")
2243
2315
  validate_against_schema(coverage, schema_dir / "coverage.schema.json")
@@ -2248,6 +2320,8 @@ def _validate_contract_refs(scan: dict[str, Any]) -> None:
2248
2320
  ("coverageRef", "coverage.json"),
2249
2321
  ("findingsRef", "findings.json"),
2250
2322
  ):
2323
+ if field == "coverageRef" and field not in scan:
2324
+ continue
2251
2325
  actual = _require_str(scan, field, "manifest.scan")
2252
2326
  if actual != expected:
2253
2327
  raise ContractError(f"manifest.scan.{field}: expected {expected!r}")
@@ -2505,7 +2579,7 @@ def _sarif_locations(finding: dict[str, Any]) -> list[dict[str, Any]]:
2505
2579
  unique: dict[tuple[str, int, int], dict[str, Any]] = {}
2506
2580
  for location in locations:
2507
2581
  key = (
2508
- location["path"],
2582
+ PurePosixPath(location["path"]).as_posix(),
2509
2583
  location["startLine"],
2510
2584
  location.get("endLine", location["startLine"]),
2511
2585
  )
@@ -2726,17 +2800,15 @@ def _read_sealed_artifacts(
2726
2800
  findings, findings_bytes = _read_scan_local_json_bytes(
2727
2801
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2728
2802
  )
2729
- coverage, coverage_bytes = _read_scan_local_json_bytes(
2730
- scan_dir, scan["coverageRef"], scan["coverageRef"]
2731
- )
2732
- _validate_existing_seal(
2733
- scan_dir,
2734
- scan,
2735
- artifact_contents={
2736
- scan["findingsRef"]: findings_bytes,
2737
- scan["coverageRef"]: coverage_bytes,
2738
- },
2739
- )
2803
+ contents = {scan["findingsRef"]: findings_bytes}
2804
+ if "coverageRef" in scan:
2805
+ coverage, coverage_bytes = _read_scan_local_json_bytes(
2806
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
2807
+ )
2808
+ contents[scan["coverageRef"]] = coverage_bytes
2809
+ else:
2810
+ coverage = review_state(scan)
2811
+ _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
2740
2812
  return findings, coverage, findings_bytes
2741
2813
 
2742
2814
 
@@ -2777,14 +2849,17 @@ def build_sarif_projection(
2777
2849
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2778
2850
  sarif = build_sarif(manifest, findings, source_root)
2779
2851
  execution_successful = manifest["scan"]["status"] == "completed"
2780
- if not execution_successful or coverage["deferred"]:
2852
+ messages = [item["reason"] for item in coverage["deferred"]]
2853
+ for warning in manifest["scan"].get("warnings", []):
2854
+ if warning not in messages:
2855
+ messages.append(warning)
2856
+ if not execution_successful or messages:
2781
2857
  run = sarif["runs"][0]
2782
2858
  run["invocations"] = [
2783
2859
  {
2784
2860
  "executionSuccessful": execution_successful,
2785
2861
  "toolExecutionNotifications": [
2786
- {"level": "warning", "message": {"text": item["reason"]}}
2787
- for item in coverage["deferred"]
2862
+ {"level": "warning", "message": {"text": message}} for message in messages
2788
2863
  ],
2789
2864
  }
2790
2865
  ]
@@ -2810,13 +2885,20 @@ def csv_cell(value: Any) -> Any:
2810
2885
  return value
2811
2886
 
2812
2887
 
2888
+ def _has_identity_text(value: Any) -> bool:
2889
+ # Match JavaScript String.trim when selecting optional identity metadata.
2890
+ return isinstance(value, str) and bool(
2891
+ value.strip(
2892
+ "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680"
2893
+ "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
2894
+ "\u2028\u2029\u202f\u205f\u3000\ufeff"
2895
+ )
2896
+ )
2897
+
2898
+
2813
2899
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2814
2900
  provenance = finding.get("provenance")
2815
- if (
2816
- isinstance(provenance, dict)
2817
- and isinstance(value := provenance.get("candidateId"), str)
2818
- and value.strip()
2819
- ):
2901
+ if isinstance(provenance, dict) and _has_identity_text(value := provenance.get("candidateId")):
2820
2902
  return value
2821
2903
  extensions = finding.get("extensions")
2822
2904
  if not isinstance(extensions, dict):
@@ -2825,12 +2907,29 @@ def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2825
2907
  (
2826
2908
  value
2827
2909
  for field in ("candidateId", "reportId", "ledgerRowId")
2828
- if isinstance(value := extensions.get(field), str) and value.strip()
2910
+ if _has_identity_text(value := extensions.get(field))
2829
2911
  ),
2830
2912
  None,
2831
2913
  )
2832
2914
 
2833
2915
 
2916
+ def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
2917
+ candidate_id = finding_candidate_id(finding)
2918
+ if candidate_id is not None:
2919
+ return candidate_id
2920
+ # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
2921
+ for metadata, fields in (
2922
+ (finding.get("provenance"), ("candidateId",)),
2923
+ (finding.get("extensions"), ("candidateId", "reportId", "ledgerRowId")),
2924
+ ):
2925
+ if isinstance(metadata, dict):
2926
+ for field in fields:
2927
+ value = metadata.get(field)
2928
+ if isinstance(value, str) and value.strip():
2929
+ return value
2930
+ return None
2931
+
2932
+
2834
2933
  def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2835
2934
  return (
2836
2935
  "occurrence_id",
@@ -2861,7 +2960,7 @@ def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) ->
2861
2960
  (
2862
2961
  csv_cell(finding["occurrenceId"]),
2863
2962
  csv_cell(finding["findingId"]),
2864
- *((csv_cell(finding_candidate_id(finding)),) if deep_scan else ()),
2963
+ *((csv_cell(_csv_candidate_id(finding)),) if deep_scan else ()),
2865
2964
  csv_cell(finding["title"]),
2866
2965
  csv_cell(finding["summary"]),
2867
2966
  csv_cell(finding["severity"]["level"]),
@@ -2898,6 +2997,30 @@ def build_findings_export(
2898
2997
  return build_csv_projection(findings, coverage)
2899
2998
 
2900
2999
 
3000
+ def _is_sealed_artifact(scan_dir: Path, relative_output: str, artifact_paths: list[str]) -> bool:
3001
+ try:
3002
+ output_metadata = (scan_dir / relative_output).stat(follow_symlinks=False)
3003
+ except FileNotFoundError:
3004
+ output_metadata = None
3005
+ except OSError as exc:
3006
+ raise ContractError(f"{relative_output}: unable to inspect export output") from exc
3007
+ for artifact_path in artifact_paths:
3008
+ if artifact_path == relative_output:
3009
+ return True
3010
+ if output_metadata is None:
3011
+ continue
3012
+ descriptor = open_scan_local_file_descriptor(
3013
+ scan_dir, artifact_path, f"sealed artifact {artifact_path}"
3014
+ )
3015
+ try:
3016
+ artifact_metadata = os.fstat(descriptor)
3017
+ finally:
3018
+ os.close(descriptor)
3019
+ if os.path.samestat(output_metadata, artifact_metadata):
3020
+ return True
3021
+ return False
3022
+
3023
+
2901
3024
  def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
2902
3025
  output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
2903
3026
  if export_format not in output_paths:
@@ -2948,40 +3071,25 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2948
3071
  for index, artifact in enumerate(artifacts)
2949
3072
  if isinstance(artifact, dict)
2950
3073
  ]
2951
- try:
2952
- output_metadata = output.stat(follow_symlinks=False)
2953
- except FileNotFoundError:
2954
- output_metadata = None
2955
- except OSError as exc:
2956
- raise ContractError(f"{relative_output}: unable to inspect export output") from exc
2957
- for artifact_path in artifact_paths:
2958
- if artifact_path == relative_output:
2959
- raise SealedArtifactError(
2960
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2961
- )
2962
- if output_metadata is None:
2963
- continue
2964
- descriptor = open_scan_local_file_descriptor(
2965
- scan_dir, artifact_path, f"sealed artifact {artifact_path}"
3074
+ if _is_sealed_artifact(scan_dir, relative_output, artifact_paths):
3075
+ raise SealedArtifactError(
3076
+ f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2966
3077
  )
2967
- try:
2968
- artifact_metadata = os.fstat(descriptor)
2969
- finally:
2970
- os.close(descriptor)
2971
- if os.path.samestat(output_metadata, artifact_metadata):
2972
- raise SealedArtifactError(
2973
- f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2974
- )
2975
3078
  write_scan_local_bytes(
2976
3079
  scan_dir, relative_output, contents, owner_read_write=export_format == "md"
2977
3080
  )
2978
3081
 
2979
3082
 
2980
3083
  def _write_sarif_projection_if_possible(
2981
- scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
3084
+ scan_dir: Path,
3085
+ source_root: Path | None = None,
3086
+ schema_dir: Path | None = None,
3087
+ *,
3088
+ sealed_paths: list[str],
2982
3089
  ) -> None:
2983
3090
  try:
2984
- write_sarif_projection(scan_dir, source_root, schema_dir)
3091
+ if not _is_sealed_artifact(scan_dir, "exports/results.sarif", sealed_paths):
3092
+ write_sarif_projection(scan_dir, source_root, schema_dir)
2985
3093
  except (ContractError, OSError) as error:
2986
3094
  print(
2987
3095
  f"codex-security: warning: automatic SARIF export failed: {error}. "
@@ -3001,6 +3109,10 @@ class PreparedScanFinalization(NamedTuple):
3001
3109
  warnings: list[str]
3002
3110
 
3003
3111
 
3112
+ def manifest_is_sealed(scan: dict[str, Any]) -> bool:
3113
+ return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
3114
+
3115
+
3004
3116
  def _prepare_scan_finalization(
3005
3117
  scan_dir: Path,
3006
3118
  schema_dir: Path | None = None,
@@ -3025,7 +3137,15 @@ def _prepare_scan_finalization(
3025
3137
  scan = _require_dict(manifest, "scan", "manifest")
3026
3138
  if scan.get("sealedAt") is None and scan.get("artifacts") == []:
3027
3139
  del scan["artifacts"]
3028
- was_sealed = scan.get("sealedAt") is not None or scan.get("artifacts") is not None
3140
+ was_sealed = manifest_is_sealed(scan)
3141
+ if (
3142
+ not was_sealed
3143
+ and "review" not in scan
3144
+ and "reviewState" not in scan
3145
+ and draft_documents is None
3146
+ and (scan_dir / "coverage.json").exists()
3147
+ ):
3148
+ scan["coverageRef"] = "coverage.json"
3029
3149
  if not was_sealed:
3030
3150
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3031
3151
  _validate_contract_refs(scan)
@@ -3033,9 +3153,13 @@ def _prepare_scan_finalization(
3033
3153
  findings, findings_input_bytes = _read_scan_local_json_bytes(
3034
3154
  scan_dir, scan["findingsRef"], scan["findingsRef"]
3035
3155
  )
3036
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3037
- scan_dir, scan["coverageRef"], scan["coverageRef"]
3038
- )
3156
+ if "coverageRef" in scan:
3157
+ coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3158
+ scan_dir, scan["coverageRef"], scan["coverageRef"]
3159
+ )
3160
+ else:
3161
+ coverage = review_state(scan)
3162
+ coverage_input_bytes = _json_bytes(coverage)
3039
3163
  else:
3040
3164
  findings, coverage = copy.deepcopy(draft_documents[1:])
3041
3165
  findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
@@ -3067,7 +3191,7 @@ def _prepare_scan_finalization(
3067
3191
  scan,
3068
3192
  artifact_contents={
3069
3193
  scan["findingsRef"]: findings_input_bytes,
3070
- scan["coverageRef"]: coverage_input_bytes,
3194
+ **({scan["coverageRef"]: coverage_input_bytes} if "coverageRef" in scan else {}),
3071
3195
  },
3072
3196
  )
3073
3197
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
@@ -3149,11 +3273,19 @@ def _prepare_scan_finalization(
3149
3273
  else:
3150
3274
  findings_bytes = _contract_json_bytes("findings.json", findings)
3151
3275
  coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3276
+ if "coverageRef" not in scan:
3277
+ scan["mode"] = coverage["mode"]
3278
+ scan["review"] = review_summary(coverage)
3279
+ scan.pop("reviewState", None)
3152
3280
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3153
3281
  _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3154
3282
  scan["artifacts"] = [
3155
3283
  _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
3156
- _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
3284
+ *(
3285
+ [_artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes)]
3286
+ if "coverageRef" in scan
3287
+ else []
3288
+ ),
3157
3289
  *[
3158
3290
  _artifact_record(scan_dir, ref, "application/octet-stream")
3159
3291
  for ref in _supplementary_artifact_refs(scan, coverage)
@@ -3185,14 +3317,55 @@ def _write_prepared_scan_finalization(
3185
3317
  scan_dir = prepared.scan_dir
3186
3318
  scan = _require_dict(prepared.manifest, "scan", "manifest")
3187
3319
  if not prepared.was_sealed:
3320
+ # Capture warnings before the first seal; later operation diagnostics must
3321
+ # not change an existing scan's portable results.
3322
+ # Escape surrogate-escaped filesystem bytes for the Unicode JSON contract.
3323
+ warnings = list(
3324
+ dict.fromkeys(
3325
+ warning.encode("utf-8", errors="backslashreplace").decode("utf-8")
3326
+ for warning in [
3327
+ *scan.get("warnings", []),
3328
+ *(projection_warnings or []),
3329
+ *prepared.warnings,
3330
+ ]
3331
+ )
3332
+ )
3333
+ if warnings:
3334
+ scan["warnings"] = warnings
3335
+ validate_against_schema(
3336
+ prepared.manifest, prepared.schema_dir / "scan-manifest.schema.json"
3337
+ )
3188
3338
  _write_scan_local_json(scan_dir, "findings.json", prepared.findings)
3189
- _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3190
- write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
3191
- _remove_scan_local_file_if_exists(scan_dir, "report.html")
3339
+ if "coverageRef" in scan:
3340
+ _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3341
+ elif "preservedSources" not in scan and not (scan_dir / "checkpoint-head.json").exists():
3342
+ checkpoint = {
3343
+ "scanId": scan["id"],
3344
+ "complete": scan["status"] == "completed",
3345
+ "scope": scan["scope"],
3346
+ "findings": prepared.findings["findings"],
3347
+ "reviewState": checkpoint_review_state(prepared.coverage),
3348
+ **({"threatModel": scan["threatModel"]} if "threatModel" in scan else {}),
3349
+ }
3350
+ contents = _json_bytes(checkpoint)
3351
+ name = hashlib.sha256(contents).hexdigest() + ".json"
3352
+ write_scan_local_bytes(scan_dir, "checkpoints/" + name, contents)
3353
+ _write_scan_local_json(scan_dir, "checkpoint-head.json", {"checkpoint": name})
3354
+ if not prepared.was_sealed and "coverageRef" not in scan:
3355
+ _remove_scan_local_file_if_exists(scan_dir, "coverage.json")
3356
+ sealed_paths = (
3357
+ [artifact["path"] for artifact in scan["artifacts"]] if prepared.was_sealed else []
3358
+ )
3359
+ if not _is_sealed_artifact(scan_dir, "report.md", sealed_paths):
3360
+ write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
3361
+ if not _is_sealed_artifact(scan_dir, "report.html", sealed_paths):
3362
+ _remove_scan_local_file_if_exists(scan_dir, "report.html")
3192
3363
  if not prepared.was_sealed:
3193
3364
  _write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
3194
3365
  _validate_existing_seal(scan_dir, scan)
3195
- _write_sarif_projection_if_possible(scan_dir, source_root, prepared.schema_dir)
3366
+ _write_sarif_projection_if_possible(
3367
+ scan_dir, source_root, prepared.schema_dir, sealed_paths=sealed_paths
3368
+ )
3196
3369
  warning = write_threat_model_projection_if_possible(scan_dir, prepared.manifest)
3197
3370
  if (
3198
3371
  warning is not None