@openai/codex-security 0.8.3 → 0.9.1

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 (534) hide show
  1. package/README.md +192 -151
  2. package/_bundled_plugin/.mcp.json +5 -1
  3. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  4. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  6. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  7. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  8. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  9. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  10. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/package.json +1 -0
  19. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  20. package/_bundled_plugin/mcp/server.mjs +2 -11
  21. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  22. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  23. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  24. package/_bundled_plugin/references/final-report.md +5 -3
  25. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  26. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  27. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  28. package/_bundled_plugin/references/scan-contract.md +27 -33
  29. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  30. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  31. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  32. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  33. package/_bundled_plugin/scripts/deep_scan_workbench.py +165 -342
  34. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  35. package/_bundled_plugin/scripts/finalize_scan_contract.py +153 -227
  36. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  37. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  38. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  39. package/_bundled_plugin/scripts/posix_scan_local_files.py +11 -0
  40. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  41. package/_bundled_plugin/scripts/report_projection.py +81 -43
  42. package/_bundled_plugin/scripts/review_state.py +8 -2
  43. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  44. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  45. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  46. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  47. package/_bundled_plugin/scripts/windows_scan_local_files.py +388 -17
  48. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  49. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  50. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  51. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  52. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  53. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  54. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  55. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  56. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  57. package/_bundled_plugin/scripts/workbench_cli.py +30 -12
  58. package/_bundled_plugin/scripts/workbench_constants.py +10 -0
  59. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  60. package/_bundled_plugin/scripts/workbench_db.py +369 -137
  61. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  62. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  63. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  64. package/_bundled_plugin/scripts/workbench_native_indexes.py +12 -12
  65. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  66. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  67. package/_bundled_plugin/scripts/workbench_remediation.py +13 -0
  68. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  69. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -55
  70. package/_bundled_plugin/scripts/workbench_scan_start.py +83 -24
  71. package/_bundled_plugin/scripts/workbench_scan_usage.py +644 -68
  72. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  73. package/_bundled_plugin/scripts/workbench_setup.py +13 -1
  74. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  75. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  76. package/_bundled_plugin/scripts/workbench_target.py +127 -56
  77. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  78. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  79. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -23
  80. package/_bundled_plugin/shared/workbench-migrations.json +34 -0
  81. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  82. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  83. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -1
  84. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -25
  85. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  86. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  87. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  88. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  90. package/dist/api.d.ts +39 -4
  91. package/dist/api.d.ts.map +1 -1
  92. package/dist/api.js +774 -292
  93. package/dist/api.js.map +1 -1
  94. package/dist/auth.d.ts.map +1 -1
  95. package/dist/auth.js +4 -6
  96. package/dist/auth.js.map +1 -1
  97. package/dist/bedrock-oss-pricing.d.ts +6 -0
  98. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  99. package/dist/bedrock-oss-pricing.js +58 -0
  100. package/dist/bedrock-oss-pricing.js.map +1 -0
  101. package/dist/bedrock-pricing.d.ts +15 -0
  102. package/dist/bedrock-pricing.d.ts.map +1 -0
  103. package/dist/bedrock-pricing.js +117 -0
  104. package/dist/bedrock-pricing.js.map +1 -0
  105. package/dist/blackduck-findings.d.ts.map +1 -1
  106. package/dist/blackduck-findings.js +35 -20
  107. package/dist/blackduck-findings.js.map +1 -1
  108. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  109. package/dist/bulk-scan-discovery.js +4 -4
  110. package/dist/bulk-scan-discovery.js.map +1 -1
  111. package/dist/checkmarx-evidence.d.ts +19 -0
  112. package/dist/checkmarx-evidence.d.ts.map +1 -0
  113. package/dist/checkmarx-evidence.js +36 -0
  114. package/dist/checkmarx-evidence.js.map +1 -0
  115. package/dist/checkmarx-findings.d.ts +4 -0
  116. package/dist/checkmarx-findings.d.ts.map +1 -0
  117. package/dist/checkmarx-findings.js +27 -0
  118. package/dist/checkmarx-findings.js.map +1 -0
  119. package/dist/checkmarx-one.d.ts +4 -0
  120. package/dist/checkmarx-one.d.ts.map +1 -0
  121. package/dist/checkmarx-one.js +53 -0
  122. package/dist/checkmarx-one.js.map +1 -0
  123. package/dist/checkmarx-repository.d.ts +12 -0
  124. package/dist/checkmarx-repository.d.ts.map +1 -0
  125. package/dist/checkmarx-repository.js +181 -0
  126. package/dist/checkmarx-repository.js.map +1 -0
  127. package/dist/checkmarx-xml.d.ts +12 -0
  128. package/dist/checkmarx-xml.d.ts.map +1 -0
  129. package/dist/checkmarx-xml.js +196 -0
  130. package/dist/checkmarx-xml.js.map +1 -0
  131. package/dist/classify-severity-records.d.ts +1 -9
  132. package/dist/classify-severity-records.d.ts.map +1 -1
  133. package/dist/classify-severity-records.js +3 -13
  134. package/dist/classify-severity-records.js.map +1 -1
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +2 -4
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli.d.ts +11 -5
  139. package/dist/cli.d.ts.map +1 -1
  140. package/dist/cli.js +1734 -1238
  141. package/dist/cli.js.map +1 -1
  142. package/dist/cloud-publish.js +2 -2
  143. package/dist/cloud-publish.js.map +1 -1
  144. package/dist/component-scan.d.ts +16 -3
  145. package/dist/component-scan.d.ts.map +1 -1
  146. package/dist/component-scan.js +27 -2
  147. package/dist/component-scan.js.map +1 -1
  148. package/dist/config.d.ts.map +1 -1
  149. package/dist/config.js +100 -66
  150. package/dist/config.js.map +1 -1
  151. package/dist/continuum-findings.d.ts.map +1 -1
  152. package/dist/continuum-findings.js +80 -12
  153. package/dist/continuum-findings.js.map +1 -1
  154. package/dist/contract-values.d.ts +2 -0
  155. package/dist/contract-values.d.ts.map +1 -1
  156. package/dist/contract-values.js +12 -9
  157. package/dist/contract-values.js.map +1 -1
  158. package/dist/cost-model.d.ts +13 -1
  159. package/dist/cost-model.d.ts.map +1 -1
  160. package/dist/cost-model.js +66 -112
  161. package/dist/cost-model.js.map +1 -1
  162. package/dist/cost.d.ts +42 -3
  163. package/dist/cost.d.ts.map +1 -1
  164. package/dist/cost.js +483 -104
  165. package/dist/cost.js.map +1 -1
  166. package/dist/custom-publish.d.ts +4 -0
  167. package/dist/custom-publish.d.ts.map +1 -1
  168. package/dist/custom-publish.js +40 -3
  169. package/dist/custom-publish.js.map +1 -1
  170. package/dist/deduplication/local.d.ts +2 -2
  171. package/dist/deduplication/local.d.ts.map +1 -1
  172. package/dist/deduplication/local.js +2 -2
  173. package/dist/deduplication/local.js.map +1 -1
  174. package/dist/deduplication/refusal.d.ts.map +1 -1
  175. package/dist/deduplication/refusal.js +25 -5
  176. package/dist/deduplication/refusal.js.map +1 -1
  177. package/dist/deduplication/scan.d.ts +3 -0
  178. package/dist/deduplication/scan.d.ts.map +1 -1
  179. package/dist/deduplication/scan.js +1 -1
  180. package/dist/deduplication/scan.js.map +1 -1
  181. package/dist/deep-config.d.ts +0 -1
  182. package/dist/deep-config.d.ts.map +1 -1
  183. package/dist/deep-config.js +22 -33
  184. package/dist/deep-config.js.map +1 -1
  185. package/dist/deep-scan-defaults.d.ts +2 -0
  186. package/dist/deep-scan-defaults.d.ts.map +1 -1
  187. package/dist/deep-scan-defaults.js +28 -1
  188. package/dist/deep-scan-defaults.js.map +1 -1
  189. package/dist/deep-scan.d.ts +2 -0
  190. package/dist/deep-scan.d.ts.map +1 -1
  191. package/dist/deep-scan.js +28 -4
  192. package/dist/deep-scan.js.map +1 -1
  193. package/dist/default-severity-rubric.d.ts +1 -1
  194. package/dist/default-severity-rubric.d.ts.map +1 -1
  195. package/dist/default-severity-rubric.js +1 -1
  196. package/dist/default-severity-rubric.js.map +1 -1
  197. package/dist/endor-findings.d.ts +3 -1
  198. package/dist/endor-findings.d.ts.map +1 -1
  199. package/dist/endor-findings.js +103 -45
  200. package/dist/endor-findings.js.map +1 -1
  201. package/dist/errors.d.ts +1 -1
  202. package/dist/errors.d.ts.map +1 -1
  203. package/dist/errors.js +8 -1
  204. package/dist/errors.js.map +1 -1
  205. package/dist/external-findings-import.d.ts +5 -3
  206. package/dist/external-findings-import.d.ts.map +1 -1
  207. package/dist/external-findings-import.js +7 -6
  208. package/dist/external-findings-import.js.map +1 -1
  209. package/dist/external-findings-local.d.ts +7 -5
  210. package/dist/external-findings-local.d.ts.map +1 -1
  211. package/dist/external-findings-local.js +337 -89
  212. package/dist/external-findings-local.js.map +1 -1
  213. package/dist/external-findings-publish.d.ts +8 -6
  214. package/dist/external-findings-publish.d.ts.map +1 -1
  215. package/dist/external-findings-publish.js +1318 -258
  216. package/dist/external-findings-publish.js.map +1 -1
  217. package/dist/external-findings-read.d.ts +20 -2
  218. package/dist/external-findings-read.d.ts.map +1 -1
  219. package/dist/external-findings-read.js +148 -66
  220. package/dist/external-findings-read.js.map +1 -1
  221. package/dist/external-findings.d.ts +15 -3
  222. package/dist/external-findings.d.ts.map +1 -1
  223. package/dist/external-findings.js +42 -1
  224. package/dist/external-findings.js.map +1 -1
  225. package/dist/external-import-contract.d.ts +5 -1
  226. package/dist/external-import-contract.d.ts.map +1 -1
  227. package/dist/external-import-contract.js +23 -9
  228. package/dist/external-import-contract.js.map +1 -1
  229. package/dist/external-import-models.d.ts +1 -1
  230. package/dist/external-import-models.d.ts.map +1 -1
  231. package/dist/external-import-models.js.map +1 -1
  232. package/dist/feedback.d.ts.map +1 -1
  233. package/dist/feedback.js +5 -4
  234. package/dist/feedback.js.map +1 -1
  235. package/dist/finding-prompt.d.ts +5 -0
  236. package/dist/finding-prompt.d.ts.map +1 -0
  237. package/dist/finding-prompt.js +32 -0
  238. package/dist/finding-prompt.js.map +1 -0
  239. package/dist/findings-client.d.ts +1 -0
  240. package/dist/findings-client.d.ts.map +1 -1
  241. package/dist/findings-client.js +27 -3
  242. package/dist/findings-client.js.map +1 -1
  243. package/dist/github-advisories.d.ts.map +1 -1
  244. package/dist/github-advisories.js +0 -2
  245. package/dist/github-advisories.js.map +1 -1
  246. package/dist/github-dependabot-findings.d.ts.map +1 -1
  247. package/dist/github-dependabot-findings.js +15 -4
  248. package/dist/github-dependabot-findings.js.map +1 -1
  249. package/dist/github-findings.d.ts +4 -1
  250. package/dist/github-findings.d.ts.map +1 -1
  251. package/dist/github-findings.js +55 -30
  252. package/dist/github-findings.js.map +1 -1
  253. package/dist/hosted-git-remotes.d.ts +5 -0
  254. package/dist/hosted-git-remotes.d.ts.map +1 -0
  255. package/dist/hosted-git-remotes.js +285 -0
  256. package/dist/hosted-git-remotes.js.map +1 -0
  257. package/dist/hosted-git-repository.d.ts +28 -0
  258. package/dist/hosted-git-repository.d.ts.map +1 -0
  259. package/dist/hosted-git-repository.js +222 -0
  260. package/dist/hosted-git-repository.js.map +1 -0
  261. package/dist/hosted-scan-protocol.js +2 -2
  262. package/dist/hosted-scan-protocol.js.map +1 -1
  263. package/dist/hosted-scan.d.ts.map +1 -1
  264. package/dist/hosted-scan.js +16 -11
  265. package/dist/hosted-scan.js.map +1 -1
  266. package/dist/hosted-scanner-http.d.ts +21 -0
  267. package/dist/hosted-scanner-http.d.ts.map +1 -0
  268. package/dist/hosted-scanner-http.js +204 -0
  269. package/dist/hosted-scanner-http.js.map +1 -0
  270. package/dist/hosted-scanner-v1.d.ts +6 -0
  271. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  272. package/dist/hosted-scanner-v1.js +60 -0
  273. package/dist/hosted-scanner-v1.js.map +1 -0
  274. package/dist/import-scan.d.ts.map +1 -1
  275. package/dist/import-scan.js +3 -0
  276. package/dist/import-scan.js.map +1 -1
  277. package/dist/index.d.ts +18 -7
  278. package/dist/index.d.ts.map +1 -1
  279. package/dist/index.js +10 -2
  280. package/dist/index.js.map +1 -1
  281. package/dist/inspector-findings.d.ts.map +1 -1
  282. package/dist/inspector-findings.js +47 -65
  283. package/dist/inspector-findings.js.map +1 -1
  284. package/dist/knowledge-base.d.ts.map +1 -1
  285. package/dist/knowledge-base.js +68 -5
  286. package/dist/knowledge-base.js.map +1 -1
  287. package/dist/local-git-metadata.d.ts +1 -1
  288. package/dist/local-git-metadata.d.ts.map +1 -1
  289. package/dist/local-git-metadata.js +1 -2
  290. package/dist/local-git-metadata.js.map +1 -1
  291. package/dist/multiscan.d.ts +6 -4
  292. package/dist/multiscan.d.ts.map +1 -1
  293. package/dist/multiscan.js +138 -65
  294. package/dist/multiscan.js.map +1 -1
  295. package/dist/native-json-findings.d.ts +2 -1
  296. package/dist/native-json-findings.d.ts.map +1 -1
  297. package/dist/native-json-findings.js +12 -2
  298. package/dist/native-json-findings.js.map +1 -1
  299. package/dist/opengrep-findings.d.ts +1 -0
  300. package/dist/opengrep-findings.d.ts.map +1 -1
  301. package/dist/opengrep-findings.js +17 -13
  302. package/dist/opengrep-findings.js.map +1 -1
  303. package/dist/operation-telemetry.d.ts +104 -0
  304. package/dist/operation-telemetry.d.ts.map +1 -0
  305. package/dist/operation-telemetry.js +293 -0
  306. package/dist/operation-telemetry.js.map +1 -0
  307. package/dist/plugin-python-probe.d.ts +4 -0
  308. package/dist/plugin-python-probe.d.ts.map +1 -0
  309. package/dist/plugin-python-probe.js +10 -0
  310. package/dist/plugin-python-probe.js.map +1 -0
  311. package/dist/private-finding-import.d.ts +97 -2
  312. package/dist/private-finding-import.d.ts.map +1 -1
  313. package/dist/private-finding-import.js +58 -34
  314. package/dist/private-finding-import.js.map +1 -1
  315. package/dist/provider-profile.d.ts +1 -1
  316. package/dist/provider-profile.d.ts.map +1 -1
  317. package/dist/provider-profile.js +8 -1
  318. package/dist/provider-profile.js.map +1 -1
  319. package/dist/publication-telemetry.d.ts +45 -0
  320. package/dist/publication-telemetry.d.ts.map +1 -0
  321. package/dist/publication-telemetry.js +50 -0
  322. package/dist/publication-telemetry.js.map +1 -0
  323. package/dist/publish.d.ts +4 -0
  324. package/dist/publish.d.ts.map +1 -1
  325. package/dist/publish.js +42 -2
  326. package/dist/publish.js.map +1 -1
  327. package/dist/reader-selection.d.ts +2 -0
  328. package/dist/reader-selection.d.ts.map +1 -1
  329. package/dist/reader-selection.js +8 -0
  330. package/dist/reader-selection.js.map +1 -1
  331. package/dist/remediation.d.ts +1 -4
  332. package/dist/remediation.d.ts.map +1 -1
  333. package/dist/remediation.js +3 -7
  334. package/dist/remediation.js.map +1 -1
  335. package/dist/request-metadata.d.ts +3 -0
  336. package/dist/request-metadata.d.ts.map +1 -1
  337. package/dist/request-metadata.js +9 -0
  338. package/dist/request-metadata.js.map +1 -1
  339. package/dist/result.d.ts +4 -0
  340. package/dist/result.d.ts.map +1 -1
  341. package/dist/result.js +1 -1
  342. package/dist/result.js.map +1 -1
  343. package/dist/retry-windows-rename.d.ts +8 -0
  344. package/dist/retry-windows-rename.d.ts.map +1 -0
  345. package/dist/retry-windows-rename.js +24 -0
  346. package/dist/retry-windows-rename.js.map +1 -0
  347. package/dist/runtime.d.ts +20 -0
  348. package/dist/runtime.d.ts.map +1 -1
  349. package/dist/runtime.js +313 -110
  350. package/dist/runtime.js.map +1 -1
  351. package/dist/saved-scan-bootstrap.d.ts +1 -0
  352. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  353. package/dist/saved-scan-bootstrap.js +18 -15
  354. package/dist/saved-scan-bootstrap.js.map +1 -1
  355. package/dist/scan-activity.d.ts.map +1 -1
  356. package/dist/scan-activity.js +141 -56
  357. package/dist/scan-activity.js.map +1 -1
  358. package/dist/scan-comparison.d.ts +10 -5
  359. package/dist/scan-comparison.d.ts.map +1 -1
  360. package/dist/scan-comparison.js +60 -15
  361. package/dist/scan-comparison.js.map +1 -1
  362. package/dist/scan-dashboard.d.ts +6 -6
  363. package/dist/scan-dashboard.d.ts.map +1 -1
  364. package/dist/scan-dashboard.js +75 -42
  365. package/dist/scan-dashboard.js.map +1 -1
  366. package/dist/scan-executor.d.ts +10 -1
  367. package/dist/scan-executor.d.ts.map +1 -1
  368. package/dist/scan-executor.js +22 -2
  369. package/dist/scan-executor.js.map +1 -1
  370. package/dist/scan-history-renderer.d.ts.map +1 -1
  371. package/dist/scan-history-renderer.js +9 -19
  372. package/dist/scan-history-renderer.js.map +1 -1
  373. package/dist/scan-logs.d.ts +12 -0
  374. package/dist/scan-logs.d.ts.map +1 -1
  375. package/dist/scan-logs.js +106 -77
  376. package/dist/scan-logs.js.map +1 -1
  377. package/dist/scan-measurement.d.ts +26 -0
  378. package/dist/scan-measurement.d.ts.map +1 -0
  379. package/dist/scan-measurement.js +77 -0
  380. package/dist/scan-measurement.js.map +1 -0
  381. package/dist/scan-progress.d.ts +1 -0
  382. package/dist/scan-progress.d.ts.map +1 -1
  383. package/dist/scan-progress.js +3 -0
  384. package/dist/scan-progress.js.map +1 -1
  385. package/dist/scan-sessions.d.ts.map +1 -1
  386. package/dist/scan-sessions.js +4 -1
  387. package/dist/scan-sessions.js.map +1 -1
  388. package/dist/scan-settings.d.ts +1 -1
  389. package/dist/scan-settings.d.ts.map +1 -1
  390. package/dist/scan-settings.js +1 -24
  391. package/dist/scan-settings.js.map +1 -1
  392. package/dist/scanner-import.d.ts +20 -2
  393. package/dist/scanner-import.d.ts.map +1 -1
  394. package/dist/scanner-import.js +200 -8
  395. package/dist/scanner-import.js.map +1 -1
  396. package/dist/scanner-repository-url.d.ts +4 -1
  397. package/dist/scanner-repository-url.d.ts.map +1 -1
  398. package/dist/scanner-repository-url.js +10 -6
  399. package/dist/scanner-repository-url.js.map +1 -1
  400. package/dist/security-policy.d.ts +1 -1
  401. package/dist/security-policy.d.ts.map +1 -1
  402. package/dist/security-policy.js.map +1 -1
  403. package/dist/semgrep-findings.d.ts +6 -3
  404. package/dist/semgrep-findings.d.ts.map +1 -1
  405. package/dist/semgrep-findings.js +107 -43
  406. package/dist/semgrep-findings.js.map +1 -1
  407. package/dist/semgrep-guardian-findings.d.ts +38 -0
  408. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  409. package/dist/semgrep-guardian-findings.js +165 -0
  410. package/dist/semgrep-guardian-findings.js.map +1 -0
  411. package/dist/semgrep-platform-collector.d.ts +26 -0
  412. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  413. package/dist/semgrep-platform-collector.js +108 -0
  414. package/dist/semgrep-platform-collector.js.map +1 -0
  415. package/dist/semgrep-platform-findings.d.ts +207 -6
  416. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  417. package/dist/semgrep-platform-findings.js +983 -103
  418. package/dist/semgrep-platform-findings.js.map +1 -1
  419. package/dist/semgrep-platform-v1.d.ts +6 -0
  420. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  421. package/dist/semgrep-platform-v1.js +83 -0
  422. package/dist/semgrep-platform-v1.js.map +1 -0
  423. package/dist/server/api.d.ts +1 -1
  424. package/dist/server/api.d.ts.map +1 -1
  425. package/dist/server/api.js.map +1 -1
  426. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  427. package/dist/server/embedding-tokenizer.d.ts +2 -0
  428. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  429. package/dist/server/embedding-tokenizer.js +322 -0
  430. package/dist/server/embedding-tokenizer.js.map +6 -0
  431. package/dist/server/embeddings.d.ts +16 -2
  432. package/dist/server/embeddings.d.ts.map +1 -1
  433. package/dist/server/embeddings.js +35 -5
  434. package/dist/server/embeddings.js.map +1 -1
  435. package/dist/session-lines.d.ts +5 -0
  436. package/dist/session-lines.d.ts.map +1 -0
  437. package/dist/session-lines.js +60 -0
  438. package/dist/session-lines.js.map +1 -0
  439. package/dist/severity-review.d.ts +3 -1
  440. package/dist/severity-review.d.ts.map +1 -1
  441. package/dist/severity-review.js +3 -2
  442. package/dist/severity-review.js.map +1 -1
  443. package/dist/skill-authentication.d.ts +1 -0
  444. package/dist/skill-authentication.d.ts.map +1 -1
  445. package/dist/skill-authentication.js +1 -0
  446. package/dist/skill-authentication.js.map +1 -1
  447. package/dist/snyk-findings.d.ts +7 -2
  448. package/dist/snyk-findings.d.ts.map +1 -1
  449. package/dist/snyk-findings.js +93 -70
  450. package/dist/snyk-findings.js.map +1 -1
  451. package/dist/snyk-rest-findings.d.ts +76 -0
  452. package/dist/snyk-rest-findings.d.ts.map +1 -0
  453. package/dist/snyk-rest-findings.js +1051 -0
  454. package/dist/snyk-rest-findings.js.map +1 -0
  455. package/dist/snyk-rest-v1.d.ts +28 -0
  456. package/dist/snyk-rest-v1.d.ts.map +1 -0
  457. package/dist/snyk-rest-v1.js +132 -0
  458. package/dist/snyk-rest-v1.js.map +1 -0
  459. package/dist/snyk-token-origin.d.ts +4 -0
  460. package/dist/snyk-token-origin.d.ts.map +1 -0
  461. package/dist/snyk-token-origin.js +82 -0
  462. package/dist/snyk-token-origin.js.map +1 -0
  463. package/dist/sonar-collector.d.ts.map +1 -1
  464. package/dist/sonar-collector.js +0 -3
  465. package/dist/sonar-collector.js.map +1 -1
  466. package/dist/sonar-import.d.ts.map +1 -1
  467. package/dist/sonar-import.js +2 -4
  468. package/dist/sonar-import.js.map +1 -1
  469. package/dist/target-drift.d.ts +9 -0
  470. package/dist/target-drift.d.ts.map +1 -0
  471. package/dist/target-drift.js +27 -0
  472. package/dist/target-drift.js.map +1 -0
  473. package/dist/targets.d.ts +2 -0
  474. package/dist/targets.d.ts.map +1 -1
  475. package/dist/targets.js +56 -20
  476. package/dist/targets.js.map +1 -1
  477. package/dist/tenable-findings.d.ts +9 -0
  478. package/dist/tenable-findings.d.ts.map +1 -0
  479. package/dist/tenable-findings.js +122 -0
  480. package/dist/tenable-findings.js.map +1 -0
  481. package/dist/terminal-stream.d.ts +13 -0
  482. package/dist/terminal-stream.d.ts.map +1 -0
  483. package/dist/terminal-stream.js +35 -0
  484. package/dist/terminal-stream.js.map +1 -0
  485. package/dist/trivy-findings.d.ts +19 -0
  486. package/dist/trivy-findings.d.ts.map +1 -0
  487. package/dist/trivy-findings.js +435 -0
  488. package/dist/trivy-findings.js.map +1 -0
  489. package/dist/trivy-import.d.ts +19 -0
  490. package/dist/trivy-import.d.ts.map +1 -0
  491. package/dist/trivy-import.js +151 -0
  492. package/dist/trivy-import.js.map +1 -0
  493. package/dist/validation-records.js +1 -1
  494. package/dist/validation-records.js.map +1 -1
  495. package/dist/veracode-findings.d.ts +2 -0
  496. package/dist/veracode-findings.d.ts.map +1 -1
  497. package/dist/veracode-findings.js +49 -11
  498. package/dist/veracode-findings.js.map +1 -1
  499. package/dist/vertex-pricing.d.ts +8 -0
  500. package/dist/vertex-pricing.d.ts.map +1 -0
  501. package/dist/vertex-pricing.js +20 -0
  502. package/dist/vertex-pricing.js.map +1 -0
  503. package/dist/windows-path.d.ts +1 -0
  504. package/dist/windows-path.d.ts.map +1 -1
  505. package/dist/windows-path.js +26 -1
  506. package/dist/windows-path.js.map +1 -1
  507. package/dist/wiz-findings.d.ts +4 -0
  508. package/dist/wiz-findings.d.ts.map +1 -1
  509. package/dist/wiz-findings.js +57 -3
  510. package/dist/wiz-findings.js.map +1 -1
  511. package/docs/classify-severity-records.md +27 -12
  512. package/docs/cli.md +497 -550
  513. package/docs/dedupe-records.md +44 -24
  514. package/docs/findings-service.md +66 -39
  515. package/docs/hosted-remediation.md +14 -7
  516. package/docs/hosted-scans.md +50 -42
  517. package/docs/telemetry.md +236 -0
  518. package/docs/validate-records.md +78 -44
  519. package/package.json +18 -15
  520. package/schemas/external-findings.schema.json +3 -1
  521. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  522. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  523. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  524. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  525. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  526. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  527. package/dist/external-imports-feature.d.ts +0 -6
  528. package/dist/external-imports-feature.d.ts.map +0 -1
  529. package/dist/external-imports-feature.js +0 -51
  530. package/dist/external-imports-feature.js.map +0 -1
  531. package/dist/finding-normalization.d.ts +0 -5
  532. package/dist/finding-normalization.d.ts.map +0 -1
  533. package/dist/finding-normalization.js +0 -155
  534. package/dist/finding-normalization.js.map +0 -1
@@ -70,7 +70,8 @@ from workbench.saved_sources import (
70
70
  _frozen_checkpoint_heads,
71
71
  _frozen_source_times,
72
72
  _is_source_order_snapshot,
73
- _latest_successful_reducer,
73
+ _iteration_order,
74
+ _latest_iteration,
74
75
  _model_capture,
75
76
  _parent_publication_ancestors,
76
77
  _read_saved_parent_result,
@@ -115,7 +116,13 @@ def merge_saved_results(
115
116
  current_contract: bool = False,
116
117
  recovery_snapshot_error: _CheckpointSnapshotError | None = None,
117
118
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
118
- """Read only bound parent/worker files; return an unsealed loss-preserving union."""
119
+ """Reconcile the bound parent and worker checkpoints into an unsealed scan draft.
120
+
121
+ Return the manifest, findings document, and coverage document, or None when there
122
+ is no saved input or the sealed parent already reflects the selected checkpoints.
123
+ Frozen digests and heads identify the inputs selected when the scan stopped.
124
+ Recovery appends diagnostics to the caller's warnings list.
125
+ """
119
126
  initial_warnings = set(warnings)
120
127
  if frozen_source_digests is None:
121
128
  checkpoint_heads = {}
@@ -255,7 +262,7 @@ def merge_saved_results(
255
262
  reducer_paths: set[str] = set()
256
263
  current_results: set[str] = set()
257
264
  reducer_outputs: list[tuple[Any, str, list[str], int]] = []
258
- reducer = _latest_successful_reducer(workers)
265
+ reducer = _latest_iteration(workers)
259
266
  latest_reducer: str | None = None
260
267
  if reducer is not None:
261
268
  try:
@@ -620,18 +627,16 @@ def merge_saved_results(
620
627
  if previous is not None and isinstance(previous.get("id"), str):
621
628
  result["id"] = previous["id"]
622
629
  else:
623
- surfaces = coverage.get("surfaces", [])
624
630
  if any(
625
631
  isinstance(row, dict) and row.get("id") == result["id"]
626
- for row in (surfaces if isinstance(surfaces, list) else [])
632
+ for row in _coverage_rows(coverage, "surfaces")
627
633
  ):
628
634
  result["id"] = f"{result['id']}-{_digest(result)[:16]}"
629
635
  elif field == "deferred":
630
636
  result["id"] = f"{prefix}-deferred-{index}"
631
637
  if isinstance(item.get("surfaceIds"), list):
632
638
  surface_ids: dict[str, str] = {}
633
- surfaces = projected_coverage.get("surfaces", [])
634
- for surface in surfaces if isinstance(surfaces, list) else []:
639
+ for surface in _coverage_rows(projected_coverage, "surfaces"):
635
640
  if not isinstance(surface, dict) or not isinstance(surface.get("id"), str):
636
641
  continue
637
642
  provenance = surface.get("provenance", {})
@@ -642,9 +647,8 @@ def merge_saved_results(
642
647
  and isinstance(provenance.get("sourceId"), str)
643
648
  ):
644
649
  surface_ids.setdefault(provenance["sourceId"], surface["id"])
645
- surfaces = source.get("surfaces", [])
646
650
  source_surface_ids: dict[str, tuple[int, dict[str, Any]]] = {}
647
- for offset, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
651
+ for offset, surface in enumerate(_coverage_rows(source, "surfaces"), 1):
648
652
  if isinstance(surface, dict) and isinstance(surface.get("id"), str):
649
653
  source_surface_ids.setdefault(surface["id"], (offset, surface))
650
654
  for (owner, source_id), accepted in accepted_surfaces.items():
@@ -679,7 +683,7 @@ def merge_saved_results(
679
683
 
680
684
  workers_by_id = {worker["id"]: worker for worker in workers}
681
685
  latest_reducer_key = (
682
- (reducer["completed_at"] or "", reducer["id"], int(reducer["attempt"] or 0))
686
+ (_iteration_order(reducer), int(reducer["attempt"] or 0))
683
687
  if reducer is not None and latest_reducer in drafts_by_path
684
688
  else None
685
689
  )
@@ -692,7 +696,7 @@ def merge_saved_results(
692
696
  ):
693
697
  continue
694
698
  current_results.add(result_path)
695
- candidate_key = (worker["completed_at"] or "", worker["id"], attempt)
699
+ candidate_key = (_iteration_order(worker), attempt)
696
700
  if latest_reducer_key is None or candidate_key > latest_reducer_key:
697
701
  latest_reducer_key = candidate_key
698
702
  latest_reducer = result_path
@@ -733,7 +737,7 @@ def merge_saved_results(
733
737
  projected_coverage = saved_parent["reviewState"] if saved_parent else {}
734
738
  # Reconcile raw source IDs and timestamps before projecting accepted outputs.
735
739
  accepted_sources = {
736
- relative
740
+ (worker_id, relative): draft
737
741
  for relative, draft, worker_id in sources
738
742
  if (worker := workers_by_id.get(worker_id)) is not None
739
743
  and worker["status"] == "succeeded"
@@ -763,15 +767,12 @@ def merge_saved_results(
763
767
  retained_surface_rows.add(id(source))
764
768
  return retained
765
769
 
766
- accepted_coverage_sources = {
767
- id(draft["reviewState"]) for relative, draft, _ in sources if relative in accepted_sources
768
- }
770
+ accepted_coverage_sources = {id(draft["reviewState"]) for draft in accepted_sources.values()}
771
+ accepted_by_worker = {}
769
772
  accepted_surfaces: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = {}
770
- for relative, draft, worker_id in sources:
771
- if relative not in accepted_sources:
772
- continue
773
- surfaces = draft["reviewState"].get("surfaces", [])
774
- for index, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
773
+ for (worker_id, relative), draft in accepted_sources.items():
774
+ accepted_by_worker.setdefault(worker_id, (relative, draft["reviewState"]))
775
+ for index, surface in enumerate(_coverage_rows(draft["reviewState"], "surfaces"), 1):
775
776
  if isinstance(surface, dict) and isinstance(surface.get("id"), str):
776
777
  accepted_surfaces.setdefault((worker_id, surface["id"]), []).append(
777
778
  (index, surface)
@@ -807,7 +808,7 @@ def merge_saved_results(
807
808
  if origin is None:
808
809
  return item
809
810
  worker_id, relative, _, index, source = origin
810
- if relative not in accepted_sources:
811
+ if (worker_id, relative) not in accepted_sources:
811
812
  directory = Path(relative).parent
812
813
  if directory.name == "checkpoints":
813
814
  directory = directory.parent
@@ -819,14 +820,7 @@ def merge_saved_results(
819
820
  return item
820
821
  # Reproduced outputs and links from omitted checkpoints use the
821
822
  # accepted worker's surface namespace.
822
- accepted = next(
823
- (
824
- (path, draft["reviewState"])
825
- for path, draft, owner in sources
826
- if owner == worker_id and path in accepted_sources
827
- ),
828
- None,
829
- )
823
+ accepted = accepted_by_worker.get(worker_id)
830
824
  if accepted is not None and source == accepted[1]:
831
825
  relative, source = accepted
832
826
  elif relative not in selected_observations or accepted is None:
@@ -892,11 +886,7 @@ def merge_saved_results(
892
886
  surface_ids_by_source: dict[tuple[str, str], list[str]] = {
893
887
  (relative, row["id"]): []
894
888
  for relative, draft, _ in all_sources
895
- for row in (
896
- draft["reviewState"].get("surfaces", [])
897
- if isinstance(draft["reviewState"].get("surfaces"), list)
898
- else []
899
- )
889
+ for row in _coverage_rows(draft["reviewState"], "surfaces")
900
890
  if isinstance(row, dict) and isinstance(row.get("id"), str)
901
891
  }
902
892
  discarded_coverage_sources: set[str] = set()
@@ -1154,8 +1144,7 @@ def merge_saved_results(
1154
1144
  retained_surface_rows: set[int] = set()
1155
1145
  for relative, draft, _ in all_sources:
1156
1146
  for field in ("surfaces", "deferred"):
1157
- rows = draft["reviewState"].get(field)
1158
- for row in rows if isinstance(rows, list) else []:
1147
+ for row in _coverage_rows(draft["reviewState"], field):
1159
1148
  if isinstance(row, dict):
1160
1149
  paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
1161
1150
  if relative not in paths_for_row:
@@ -1305,9 +1294,7 @@ def merge_saved_results(
1305
1294
  selected_reported_candidates.get(key, source_order[relative]),
1306
1295
  source_order[relative],
1307
1296
  )
1308
- for relative, draft, worker_id in sources:
1309
- if relative not in accepted_sources:
1310
- continue
1297
+ for (worker_id, relative), draft in accepted_sources.items():
1311
1298
  worker = workers_by_id[worker_id]
1312
1299
  reported = {
1313
1300
  finding_candidate_id(finding)
@@ -1315,8 +1302,7 @@ def merge_saved_results(
1315
1302
  if isinstance(finding, dict) and valid_finding(finding)
1316
1303
  }
1317
1304
  for field in ("surfaces", "deferred", "explicitExclusions"):
1318
- rows = draft["reviewState"].get(field, [])
1319
- for index, row in enumerate(rows if isinstance(rows, list) else [], 1):
1305
+ for index, row in enumerate(_coverage_rows(draft["reviewState"], field), 1):
1320
1306
  if not isinstance(row, dict):
1321
1307
  continue
1322
1308
  if (
@@ -1438,8 +1424,7 @@ def merge_saved_results(
1438
1424
 
1439
1425
  pending_surface_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
1440
1426
  for relative, draft, owner in all_sources:
1441
- surfaces = draft["reviewState"].get("surfaces", [])
1442
- for surface in surfaces if isinstance(surfaces, list) else []:
1427
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
1443
1428
  if (
1444
1429
  isinstance(surface, dict)
1445
1430
  and surface.get("disposition") == "needs_follow_up"
@@ -2940,12 +2925,7 @@ def merge_saved_results(
2940
2925
  worker = workers_by_id.get(worker_id)
2941
2926
  # Only the accepted current output belongs to this worker attempt. An
2942
2927
  # unsuperseded archive can remain evidence after that output is lost.
2943
- project_coverage = (
2944
- worker is not None
2945
- and worker["status"] == "succeeded"
2946
- and worker["result_manifest_path"] == str(scan_dir / relative)
2947
- and draft.get("complete") is not False
2948
- )
2928
+ project_coverage = (worker_id, relative) in accepted_sources
2949
2929
  if coverage_superseded and not selected_candidates and not retain_pending:
2950
2930
  continue
2951
2931
  if project_coverage:
@@ -3173,8 +3153,7 @@ def merge_saved_results(
3173
3153
  item = {"id": "scan-stopped", "reason": reason}
3174
3154
  if item not in coverage["deferred"]:
3175
3155
  coverage["deferred"].append(item)
3176
- surfaces = coverage.get("surfaces", [])
3177
- for surface in surfaces if isinstance(surfaces, list) else []:
3156
+ for surface in _coverage_rows(coverage, "surfaces"):
3178
3157
  if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
3179
3158
  surface["provenance"].pop("scanReceiptRefs", None)
3180
3159
  if (
@@ -17,10 +17,10 @@ from finalize_scan_contract import (
17
17
  _recover_unsealed_coverage,
18
18
  _recover_unsealed_findings,
19
19
  _require_safe_json_value,
20
- _validate_current_findings,
21
20
  _validate_schema_node,
22
21
  finding_candidate_id,
23
22
  )
23
+ from finalize_scan_contract import _schema_values_equal as same_raw_value
24
24
  from workbench.saved_coverage import _coverage_rows, _saved_coverage_id
25
25
  from workbench.saved_sources import _digest, _encoded
26
26
  from workbench_coverage_receipts import resolve_coverage_receipts
@@ -243,6 +243,7 @@ def _append_previous_finding(
243
243
  def _recover_preserved_worker_source(
244
244
  scan_dir, relative, scan_id, binding, worker_id, worker, draft, warnings
245
245
  ):
246
+ """Normalize findings and receipt references in the draft and return diagnostics for discarded findings."""
246
247
  discarded_findings = []
247
248
  # Recover imported records without relaxing canonical parent validation.
248
249
  if "complete" in draft and not isinstance(draft["complete"], bool):
@@ -280,15 +281,8 @@ def _recover_preserved_worker_source(
280
281
  schema_dir,
281
282
  scan_dir / directory,
282
283
  source_warnings,
284
+ current_contract=True,
283
285
  )
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
286
  if discarded:
293
287
  discarded_findings.extend(discarded)
294
288
  for recovered_finding in recovered["findings"]:
@@ -328,10 +322,10 @@ def _recover_preserved_worker_source(
328
322
  def _recover_preserved_worker_coverage(
329
323
  scan_dir, relative, worker_id, draft, discarded_findings, warnings
330
324
  ):
325
+ """Repair coverage in the draft, append source warnings, and return whether coverage was discarded."""
331
326
  discarded_coverage = False
332
327
  for field in ("surfaces", "explicitExclusions", "deferred"):
333
- rows = draft["reviewState"].get(field)
334
- for row in rows if isinstance(rows, list) else []:
328
+ for row in _coverage_rows(draft["reviewState"], field):
335
329
  if isinstance(row, dict):
336
330
  row.setdefault("id", _saved_coverage_id(row))
337
331
  if field == "surfaces":
@@ -360,6 +354,7 @@ def _recover_preserved_worker_coverage(
360
354
 
361
355
 
362
356
  def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
357
+ """Return the report ID and ledger row ID from extensions, using None for missing or blank IDs."""
363
358
  extensions = value.get("extensions")
364
359
  return tuple(
365
360
  identifier if _has_identity_text(identifier) else None
@@ -371,6 +366,7 @@ def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
371
366
 
372
367
 
373
368
  def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None) -> bool:
369
+ """Check the latest observations for conflicting report IDs or ledger row IDs."""
374
370
  return (
375
371
  left is not None
376
372
  and right is not None
@@ -382,6 +378,7 @@ def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None)
382
378
 
383
379
 
384
380
  def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
381
+ """Return the source owner, falling back to the worker ID recorded in finding provenance."""
385
382
  if source_owner is not None:
386
383
  return source_owner
387
384
  provenance = value.get("provenance", {})
@@ -390,6 +387,7 @@ def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
390
387
 
391
388
 
392
389
  def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
390
+ """Return the rule, path, and line range of the first location used to match anonymous reports."""
393
391
  # Match scanFindingIdentity's primary location for anonymous reports.
394
392
  location = value["locations"][0]
395
393
  return (
@@ -401,6 +399,7 @@ def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
401
399
 
402
400
 
403
401
  def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
402
+ """Check whether semantic identities match or, in their absence, whether candidate and report IDs are compatible."""
404
403
  if isinstance(left.get("identity"), dict) and isinstance(right.get("identity"), dict):
405
404
  return _semantic_identity_key(left, _finding_identity(left)) == _semantic_identity_key(
406
405
  right, _finding_identity(right)
@@ -417,24 +416,9 @@ def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
417
416
  return True
418
417
 
419
418
 
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
419
  def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
420
+ """Compare substantive finding fields while ignoring identity, provenance, and report-tracking IDs."""
421
+
438
422
  def content(value: dict[str, Any]) -> dict[str, Any]:
439
423
  result = _finding_content(value)
440
424
  if isinstance(result.get("extensions"), dict):
@@ -451,6 +435,10 @@ def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
451
435
 
452
436
 
453
437
  def contains_raw_value(current: Any, previous: Any) -> bool:
438
+ """Check whether the current JSON value retains every part of the previous value.
439
+
440
+ Match dictionary values by key and list elements by content, regardless of order.
441
+ """
454
442
  if isinstance(previous, dict):
455
443
  return isinstance(current, dict) and all(
456
444
  key in current and contains_raw_value(current[key], value)
@@ -529,6 +517,7 @@ def _saved_candidate_outcomes(
529
517
  workers_by_id,
530
518
  coverage_schema,
531
519
  ):
520
+ """Return saved candidate outcomes with their evidence and the ordering of pending candidates by owner."""
532
521
  pending_candidate_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
533
522
  outcomes = []
534
523
  for relative, draft, owner in current_drafts:
@@ -539,8 +528,7 @@ def _saved_candidate_outcomes(
539
528
  }
540
529
  pending_candidates = set()
541
530
  for field in ("deferred", "surfaces"):
542
- items = draft["reviewState"].get(field, [])
543
- for item in items if isinstance(items, list) else []:
531
+ for item in _coverage_rows(draft["reviewState"], field):
544
532
  if isinstance(item, dict) and (
545
533
  field == "deferred" or item.get("disposition") == "needs_follow_up"
546
534
  ):
@@ -1,4 +1,7 @@
1
- """Load TOML using the supported Python runtime."""
1
+ """Expose tomllib to workbench callers, using tomli on Python 3.10.
2
+
3
+ Import exits with setup guidance when the runtime is too old or the backport is missing.
4
+ """
2
5
 
3
6
  import sys
4
7
 
@@ -250,7 +250,7 @@ def prepare_saved_coverage_projection(
250
250
 
251
251
 
252
252
  class SavedCoverageProjection:
253
- """Keep worker source links stable while legacy and accepted rows converge."""
253
+ """Track which worker supplied a coverage row so reconstructed links can resolve to the retained surface."""
254
254
 
255
255
  def __init__(self, project_worker_coverage, legacy_surface_links, projection_origins):
256
256
  self.project_worker_coverage = project_worker_coverage
@@ -293,8 +293,7 @@ class SavedCoverageProjection:
293
293
  if field == "surfaces":
294
294
  # Canonical IDs can change while source content and ownership stay the same.
295
295
  item = {key: value for key, value in item.items() if key != "id"}
296
- records = coverage.get(field, [])
297
- for record in records if isinstance(records, list) else []:
296
+ for record in _coverage_rows(coverage, field):
298
297
  if not isinstance(record, dict):
299
298
  continue
300
299
  original = dict(canonical_record(field, record))
@@ -329,12 +328,11 @@ class SavedCoverageProjection:
329
328
  or worker["merge_state"] != "merged"
330
329
  ):
331
330
  return False
332
- reviews = canonical.get("reviews", [])
333
331
  return any(
334
332
  isinstance(review, dict)
335
333
  and review.get("workerId") == worker["id"]
336
334
  and review.get("attempt") == worker["attempt"]
337
- for review in (reviews if isinstance(reviews, list) else [])
335
+ for review in _coverage_rows(canonical, "reviews")
338
336
  )
339
337
 
340
338
  def repair_reviewed_surface(self, coverage, canonical, worker, source, surface):
@@ -446,11 +444,8 @@ class SavedCoverageProjection:
446
444
  retained_legacy_surface_links: dict[
447
445
  int, tuple[dict[str, Any], dict[str, dict[str, Any]]]
448
446
  ] = {}
449
- output_tasks = coverage.get("deferred", [])
450
- task_candidates = [
451
- (self.worker_row_owners.get(id(row)), row)
452
- for row in (output_tasks if isinstance(output_tasks, list) else [])
453
- ]
447
+ output_tasks = _coverage_rows(coverage, "deferred")
448
+ task_candidates = [(self.worker_row_owners.get(id(row)), row) for row in output_tasks]
454
449
  for task, published_id, surface, _ in self.task_surface_links(task_candidates):
455
450
  retained_surface = self.linked_surface(
456
451
  surface,
@@ -481,8 +476,7 @@ class SavedCoverageProjection:
481
476
  named_surface_outputs = {
482
477
  identity for outputs in self.worker_surface_outputs.values() for identity in outputs
483
478
  }
484
- surfaces = coverage.get("surfaces", [])
485
- for surface in surfaces if isinstance(surfaces, list) else []:
479
+ for surface in _coverage_rows(coverage, "surfaces"):
486
480
  if not isinstance(surface, dict):
487
481
  continue
488
482
  owner, identity = self.worker_row_owners.get(id(surface)), surface.get("id")
@@ -496,7 +490,7 @@ class SavedCoverageProjection:
496
490
  and id(existing) not in named_surface_outputs
497
491
  ):
498
492
  worker_surfaces[key] = surface
499
- for task in output_tasks if isinstance(output_tasks, list) else []:
493
+ for task in output_tasks:
500
494
  if (
501
495
  not isinstance(task, dict)
502
496
  or (owner := self.worker_row_owners.get(id(task))) is None
@@ -610,8 +604,7 @@ class SavedCoverageProjection:
610
604
  # tasks. Preserve their original links, even when the outcome changes ID
611
605
  # or a distinct retained surface shares the old source-local ID.
612
606
  for relative, draft, owner in all_sources:
613
- originals = draft["reviewState"].get("surfaces", [])
614
- for original in originals if isinstance(originals, list) else []:
607
+ for original in _coverage_rows(draft["reviewState"], "surfaces"):
615
608
  if (
616
609
  not isinstance(original, dict)
617
610
  or id(original) in retained_surface_rows
@@ -652,8 +645,7 @@ class SavedCoverageProjection:
652
645
  prospective_surfaces = {}
653
646
  prospective_named = {}
654
647
  for relative, draft, owner in all_sources:
655
- rows = draft["reviewState"].get("surfaces", [])
656
- for row in rows if isinstance(rows, list) else []:
648
+ for row in _coverage_rows(draft["reviewState"], "surfaces"):
657
649
  if owner is None or not isinstance(row, dict):
658
650
  continue
659
651
  emitted = surface_is_retained(relative, owner, row)
@@ -26,6 +26,11 @@ _PUBLISHED_OUTPUTS = (
26
26
  def _snapshot_published_outputs(
27
27
  scan_dir: Path, relative_paths: tuple[str, ...] = _PUBLISHED_OUTPUTS
28
28
  ) -> dict[str, tuple[bytes, os.stat_result] | None]:
29
+ """Capture each artifact's bytes and stat metadata before publication.
30
+
31
+ A None entry records an absent artifact. An unsafe optional threatmodel.md is
32
+ omitted so rollback leaves it alone. Other unreadable existing outputs raise ContractError.
33
+ """
29
34
  snapshots: dict[str, tuple[bytes, os.stat_result] | None] = {}
30
35
  for relative in relative_paths:
31
36
  descriptor = -1
@@ -56,6 +61,10 @@ def _restore_published_outputs(
56
61
  snapshots: dict[str, tuple[bytes, os.stat_result] | None],
57
62
  created_paths: set[str] | None = None,
58
63
  ) -> None:
64
+ """Restore the captured bytes and timestamps after a publication failure.
65
+
66
+ Remove outputs that were originally absent and paths journaled as newly created by the caller.
67
+ """
59
68
  for relative, snapshot in snapshots.items():
60
69
  if snapshot is None:
61
70
  path = scan_dir / relative
@@ -8,7 +8,7 @@ import json
8
8
  import os
9
9
  import re
10
10
  import stat
11
- from collections.abc import Iterator
11
+ from collections.abc import Iterable, Iterator
12
12
  from functools import partial
13
13
  from pathlib import Path
14
14
  from typing import Any
@@ -56,23 +56,30 @@ def _source_digests(value: Any, error: str) -> dict[str, str]:
56
56
  return value
57
57
 
58
58
 
59
- def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:
60
- if isinstance(value, dict) and isinstance(value.get("sources"), dict):
61
- sources = _source_digests(
62
- value["sources"], "Saved stopped-scan source digests are malformed."
63
- )
64
- model_source = value.get("threatModelSource")
65
- if "threatModelSource" in value and (
66
- not isinstance(model_source, str) or model_source not in sources
67
- ):
68
- raise ContractError("Saved stopped-scan model source is outside its checkpoint set.")
69
- return sources, model_source
70
- return _source_digests(value, "Saved stopped-scan source digests are malformed."), None
59
+ def _retained_source_state(raw: str | None) -> dict[str, Any]:
60
+ """Decode stopped-scan sources, preserving the distinction between absent and frozen empty."""
61
+ if raw is None:
62
+ return {}
63
+ state = json.loads(raw)
64
+ if not isinstance(state, dict) or not isinstance(state.get("sources"), dict):
65
+ state = {"sources": state} # Legacy rows store only the path-to-digest map.
66
+ sources = _source_digests(state["sources"], "Saved stopped-scan source digests are malformed.")
67
+ model_source = state.get("threatModelSource")
68
+ if "threatModelSource" in state and (
69
+ not isinstance(model_source, str) or model_source not in sources
70
+ ):
71
+ raise ContractError("Saved stopped-scan model source is outside its checkpoint set.")
72
+ return state
71
73
 
72
74
 
73
75
  def _retained_checkpoint_state(
74
76
  scan: Any,
75
77
  ) -> tuple[dict[str, str | None] | None, dict[str, Any] | None]:
78
+ """Return selected checkpoint heads and any pending recovery record.
79
+
80
+ Older scans can store the head map directly. Recovery records also bind
81
+ the selection to a sealed manifest digest. A conflicting digest raises ContractError.
82
+ """
76
83
  raw = scan["retained_checkpoint_heads_json"]
77
84
  if raw is None:
78
85
  return None, None
@@ -125,6 +132,7 @@ def _checkpoint_paths(scan_dir: Path, directory: str) -> list[str]:
125
132
 
126
133
 
127
134
  def _checkpoint_head_directory(relative: str) -> Path | None:
135
+ """Return the owner directory of a current or archived checkpoint head path, or None for another file."""
128
136
  path = Path(relative)
129
137
  if path.name == "checkpoint-head.json":
130
138
  return path.parent
@@ -162,6 +170,7 @@ def _capture_saved_source(
162
170
  checkpoint_heads: dict[str, str | None] | None = None,
163
171
  expected_digest: str | None = None,
164
172
  ) -> dict[str, tuple[str, int]]:
173
+ """Capture digests and observation times for a saved source and its selected checkpoint or receipt inputs."""
165
174
  if not snapshot_head or Path(relative).name != "checkpoint-head.json":
166
175
  _, digest, observed = _read_saved_result(scan_dir, relative, scan_id, kind=kind)
167
176
  return capture_receipt_checkpoints(
@@ -241,14 +250,18 @@ def _read_saved_result(
241
250
  return draft, _digest(draft), int(observed)
242
251
  if draft.get("scanId") != scan_id:
243
252
  raise ContractError("checkpoint belongs to a different scan")
244
- if not _is_source_order_snapshot(relative) and (
245
- not isinstance(draft.get("findings"), list)
246
- or not isinstance(
247
- draft.get("reviewState", draft.get("coverage", {} if kind == "dedup" else None)), dict
248
- )
253
+ if _is_source_order_snapshot(relative):
254
+ return draft, _digest(draft), metadata.st_mtime_ns
255
+ if not isinstance(draft.get("findings"), list) or not isinstance(
256
+ draft.get("reviewState", draft.get("coverage", {} if kind == "dedup" else None)), dict
249
257
  ):
250
258
  raise ContractError("checkpoint has no semantic findings or coverage")
251
259
  digest = _digest(draft)
260
+ if kind == "dedup" and normalize_review:
261
+ # The host keeps grouping state in iteration checkpoints for resume only.
262
+ for finding in draft["findings"]:
263
+ if isinstance(finding, dict) and isinstance(finding.get("provenance"), dict):
264
+ finding["provenance"].pop("deepScanRepairGroups", None)
252
265
  if normalize_review and "coverage" in draft and "reviewState" not in draft:
253
266
  draft["reviewState"] = draft.pop("coverage")
254
267
  return draft, digest, metadata.st_mtime_ns
@@ -388,6 +401,7 @@ def _restore_checkpoint_head(
388
401
  sources: dict[str, str],
389
402
  relative: str,
390
403
  ) -> None:
404
+ """Restore the prior selection for a checkpoint directory, allowing legacy evidence with no selected head."""
391
405
  path = Path(relative)
392
406
  if path.name != "checkpoint-head.json":
393
407
  return
@@ -639,25 +653,10 @@ def _require_current_deep_publication(
639
653
  raise SystemExit("Deep Scan is terminal; drafts cannot replace its publication.")
640
654
  return
641
655
 
642
- # Match the durable reducer sequence used by coordinator recovery.
643
- def reducer_order(worker: Any) -> tuple[int, str]:
644
- match = re.fullmatch(r"dedup-([0-9]+)", Path(worker["prompt_path"]).parent.name)
645
- return (int(match[1]) if match else 0, worker["id"])
646
-
647
- reducer = max(
648
- (
649
- worker
650
- for worker in connection.execute(
651
- "SELECT * FROM deep_scan_workers WHERE scan_id = ?", (scan_id,)
652
- )
653
- if worker["kind"] == "dedup"
654
- and worker["status"] == "succeeded"
655
- and worker["result_manifest_path"]
656
- ),
657
- key=reducer_order,
658
- default=None,
656
+ iteration = _latest_iteration(
657
+ connection.execute("SELECT * FROM deep_scan_workers WHERE scan_id = ?", (scan_id,))
659
658
  )
660
- selected_result = reducer["result_manifest_path"] if reducer is not None else None
659
+ selected_result = iteration["result_manifest_path"] if iteration is not None else None
661
660
  if publication["resultPath"] != selected_result:
662
661
  raise SystemExit("Deep Scan aggregate belongs to a superseded publication selection.")
663
662
 
@@ -666,7 +665,15 @@ if __name__ == "__main__":
666
665
  argparse.ArgumentParser(description=__doc__).parse_args()
667
666
 
668
667
 
669
- def _latest_successful_reducer(workers: list[Any]) -> Any | None:
668
+ def _iteration_order(worker: Any) -> tuple[int, str, str]:
669
+ result = worker["result_manifest_path"]
670
+ output = Path(result).parent if result else Path(worker["artifact_dir"])
671
+ label = output.parent.name if output.name == "output" else output.name
672
+ match = re.fullmatch(r"dedup-([0-9]+)", label)
673
+ return (int(match[1]) if match else 0, worker["completed_at"] or "", worker["id"])
674
+
675
+
676
+ def _latest_iteration(workers: Iterable[Any]) -> Any | None:
670
677
  return max(
671
678
  (
672
679
  worker
@@ -675,7 +682,7 @@ def _latest_successful_reducer(workers: list[Any]) -> Any | None:
675
682
  and worker["status"] == "succeeded"
676
683
  and worker["result_manifest_path"]
677
684
  ),
678
- key=lambda worker: (worker["completed_at"] or "", worker["id"]),
685
+ key=_iteration_order,
679
686
  default=None,
680
687
  )
681
688
 
@@ -695,7 +702,7 @@ def _worker_outputs(scan_dir: Path, worker: Any) -> list[tuple[str, int]]:
695
702
 
696
703
 
697
704
  def _saved_result_paths(scan_dir: Path, workers: list[Any]) -> Iterator[tuple[str, str | None]]:
698
- latest_reducer = _latest_successful_reducer(workers)
705
+ iteration = _latest_iteration(workers)
699
706
  yield "checkpoint-head.json", None
700
707
  for directory in ("checkpoint-heads", "checkpoints"):
701
708
  yield from ((path, None) for path in _checkpoint_paths(scan_dir, directory))
@@ -719,7 +726,7 @@ def _saved_result_paths(scan_dir: Path, workers: list[Any]) -> Iterator[tuple[st
719
726
  yield from ((path, worker["kind"]) for path in checkpoint_paths)
720
727
  if worker["result_manifest_path"] and (
721
728
  worker["kind"] == "discovery"
722
- or (latest_reducer is not None and worker["id"] == latest_reducer["id"])
729
+ or (iteration is not None and worker["id"] == iteration["id"])
723
730
  ):
724
731
  try:
725
732
  yield (