@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
@@ -15,13 +15,19 @@ from workbench_constants import (
15
15
  FINDING_LOCATION_PATH_BYTES,
16
16
  FINDING_SUMMARY_BYTES,
17
17
  FINDING_TITLE_BYTES,
18
+ PRIMARY_FINDING_LOCATION_SQL,
18
19
  )
19
20
  from workbench_validation import bounded_output_text
20
21
 
21
22
 
22
23
  def get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict[str, Any]:
24
+ """Return reviewed false-positive decisions from other completed scans of the same target.
25
+
26
+ For each finding, include the latest decision only if it closes the finding as a
27
+ false positive with a nonblank reason. Prefer the root-control location in its preview.
28
+ """
23
29
  rows = connection.execute(
24
- """
30
+ f"""
25
31
  WITH ranked_decisions AS (
26
32
  SELECT findings.id AS finding_id, findings.fingerprint, findings.rule_id,
27
33
  findings.identity_anchor, findings.identity_instance, occurrences.title,
@@ -43,12 +49,7 @@ def get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict
43
49
  JOIN scans AS source_scans ON source_scans.id = occurrences.scan_id
44
50
  LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
45
51
  JOIN finding_locations AS locations ON locations.id = (
46
- SELECT candidate.id
47
- FROM finding_locations AS candidate
48
- WHERE candidate.occurrence_id = occurrences.id
49
- ORDER BY CASE WHEN candidate.role = 'root_control' THEN 0 ELSE 1 END,
50
- candidate.sort_order
51
- LIMIT 1
52
+ SELECT id {PRIMARY_FINDING_LOCATION_SQL}
52
53
  )
53
54
  WHERE source_scans.target_id = ?
54
55
  AND source_scans.id != ?
@@ -70,6 +70,7 @@ def index_findings(
70
70
  document: dict[str, Any],
71
71
  timestamp: str,
72
72
  ) -> None:
73
+ """Index findings for this scan and write occurrence and ordered location rows in the caller’s transaction."""
73
74
  repository_id = connection.execute(
74
75
  "SELECT target_id FROM scans WHERE id = ?", (scan_id,)
75
76
  ).fetchone()["target_id"]
@@ -95,6 +95,7 @@ def _recorded_cost(value: str | None) -> dict[str, Any] | None:
95
95
 
96
96
 
97
97
  def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str, Any] | None:
98
+ """Return the stored stages, scope, and available scan cost, or None if the workflow ID is unknown."""
98
99
  row = connection.execute(
99
100
  """SELECT w.*, s.cost_json FROM finding_workflows AS w
100
101
  LEFT JOIN scans AS s ON s.id = w.scan_id AND s.scan_dir = w.scan_dir
@@ -128,6 +129,7 @@ def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str,
128
129
 
129
130
 
130
131
  def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestamp: str) -> None:
132
+ """Insert or update the workflow bindings, scope, stage statuses, and saved results in the caller’s connection."""
131
133
  values = {"id": state["id"]}
132
134
  values.update({column: state.get(field) for field, column in WORKFLOW_BINDINGS.items()})
133
135
  scope = state.get("scope", {})
@@ -160,6 +162,7 @@ def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timesta
160
162
 
161
163
 
162
164
  def bind_workflow(state: dict[str, Any], binding: dict[str, Any]) -> None:
165
+ """Add bindings to the supplied state in place, raising SystemExit for unknown or conflicting fields."""
163
166
  for field, value in binding.items():
164
167
  if field not in WORKFLOW_BINDINGS and field != "scope":
165
168
  raise SystemExit("Unknown workflow binding.")
@@ -206,6 +209,7 @@ def register_workflow_scan(
206
209
  def finding_workflow(
207
210
  connection: sqlite3.Connection, payload: dict[str, Any], timestamp: str
208
211
  ) -> dict[str, Any]:
212
+ """Dispatch a workflow request by ID and return its state, source snapshot, or review as the action specifies."""
209
213
  workflow_id = payload["id"]
210
214
  if not isinstance(workflow_id, str) or not workflow_id.strip():
211
215
  raise SystemExit("workflowId must be a nonempty string.")
@@ -12,7 +12,12 @@ from typing import Any
12
12
  # Some plugin hosts launch Python with safe-path isolation enabled.
13
13
  sys.path.insert(0, str(Path(__file__).resolve().parent))
14
14
  import workbench_scan_history as scan_history
15
- from workbench_constants import FINDING_SUMMARY_BYTES, FINDING_TITLE_BYTES, FINDINGS_PAGE_MAX
15
+ from workbench_constants import (
16
+ FINDING_SUMMARY_BYTES,
17
+ FINDING_TITLE_BYTES,
18
+ FINDINGS_PAGE_MAX,
19
+ PRIMARY_FINDING_LOCATION_SQL,
20
+ )
16
21
  from workbench_validation import bounded_output_text, timestamp_key
17
22
 
18
23
 
@@ -20,6 +25,7 @@ def list_global_findings(
20
25
  connection: sqlite3.Connection,
21
26
  args: argparse.Namespace,
22
27
  ) -> dict[str, Any]:
28
+ """Return a page of indexed findings after applying the requested filters, with nextOffset for continuation."""
23
29
  limit = min(args.limit, FINDINGS_PAGE_MAX)
24
30
  query = args.query.strip().casefold() if args.query else ""
25
31
  findings = (
@@ -107,7 +113,7 @@ def _indexed_findings(connection: sqlite3.Connection) -> Iterator[dict[str, Any]
107
113
 
108
114
  grouped: dict[tuple[str, str], list[sqlite3.Row]] = {}
109
115
  for row in connection.execute(
110
- """
116
+ f"""
111
117
  SELECT
112
118
  occurrences.id AS occurrence_id,
113
119
  occurrences.finding_id,
@@ -124,15 +130,7 @@ def _indexed_findings(connection: sqlite3.Connection) -> Iterator[dict[str, Any]
124
130
  triage.updated_at AS decision_updated_at,
125
131
  occurrences.title,
126
132
  occurrences.summary,
127
- (
128
- SELECT locations.relative_path
129
- FROM finding_locations AS locations
130
- WHERE locations.occurrence_id = occurrences.id
131
- ORDER BY
132
- CASE WHEN locations.role = 'root_control' THEN 0 ELSE 1 END,
133
- locations.sort_order
134
- LIMIT 1
135
- ) AS location_path
133
+ (SELECT relative_path {PRIMARY_FINDING_LOCATION_SQL}) AS location_path
136
134
  FROM finding_occurrences AS occurrences
137
135
  JOIN scans ON scans.id = occurrences.scan_id
138
136
  JOIN security_targets AS targets ON targets.id = scans.target_id
@@ -203,6 +201,7 @@ def list_repositories(
203
201
  connection: sqlite3.Connection,
204
202
  args: argparse.Namespace | None = None,
205
203
  ) -> dict[str, Any]:
204
+ """Return tracked targets with scan summaries, finding counts, and current checkout availability."""
206
205
  by_target: dict[str, dict[str, Any]] = {}
207
206
  for row in connection.execute(
208
207
  f"""
@@ -212,6 +211,7 @@ def list_repositories(
212
211
  LEFT JOIN scans ON scans.target_id = targets.id
213
212
  AND scans.id IN (SELECT scan_id FROM scan_progress)
214
213
  LEFT JOIN scan_progress AS progress ON progress.scan_id = scans.id
214
+ LEFT JOIN scan_lifecycles AS lifecycle ON lifecycle.scan_id = scans.id
215
215
  ORDER BY julianday(upper(scans.started_at)) DESC, scans.id DESC, targets.id
216
216
  """
217
217
  ).fetchall():
@@ -252,7 +252,7 @@ def list_repositories(
252
252
  )
253
253
  ]
254
254
  if args.limit is not None or args.offset:
255
- limit = min(args.limit or FINDINGS_PAGE_MAX, FINDINGS_PAGE_MAX)
255
+ limit = args.limit or FINDINGS_PAGE_MAX
256
256
  end = args.offset + limit
257
257
  pagination = {
258
258
  "limit": limit,
@@ -8,7 +8,7 @@ from typing import Any
8
8
 
9
9
  sys.path.insert(0, str(Path(__file__).resolve().parent))
10
10
  from deep_scan_workbench import require_current_coordinator
11
- from workbench.handoff import require_current_continuation
11
+ from workbench.handoff import require_current_continuation, require_tokenless_scan_owner
12
12
  from workbench_constants import PHASES
13
13
  from workbench_validation import optional_text, require_uuid, user_context_argument
14
14
 
@@ -16,6 +16,7 @@ from workbench_validation import optional_text, require_uuid, user_context_argum
16
16
  def reportable_count(
17
17
  current_phase: str, requested_phase: str | None, count: int | None
18
18
  ) -> int | None:
19
+ """Default a missing count to zero on entering validation or a later phase from an earlier phase."""
19
20
  if count is None and requested_phase in PHASES[3:] and current_phase in PHASES[:3]:
20
21
  return 0
21
22
  return count
@@ -26,6 +27,7 @@ def update_context(
26
27
  connection: sqlite3.Connection,
27
28
  args: argparse.Namespace,
28
29
  ) -> dict[str, Any]:
30
+ """Update user context on a running scan and return the refreshed scan context in the same workbench."""
29
31
  scan_id = require_uuid(args.scan_id, "scan-id")
30
32
  context = user_context_argument(args)
31
33
  connection.execute("BEGIN IMMEDIATE")
@@ -72,6 +74,12 @@ def update_progress(
72
74
  connection: sqlite3.Connection,
73
75
  args: argparse.Namespace,
74
76
  ) -> dict[str, Any]:
77
+ """Record phase and review counters for a running scan and return its updated context.
78
+
79
+ Check continuation and coordinator ownership where applicable. A new phase
80
+ starts with fresh phase counters. A new Deep Scan review pass must start
81
+ with zero completed items. Invalid progress raises SystemExit.
82
+ """
75
83
  scan_id = require_uuid(args.scan_id, "scan-id")
76
84
  model = optional_text(args.model, maximum=200)
77
85
  reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
@@ -79,6 +87,7 @@ def update_progress(
79
87
  with connection:
80
88
  timestamp = wb.now()
81
89
  scan = wb.require_scan(connection, scan_id)
90
+ require_tokenless_scan_owner(connection, scan, getattr(args, "model_thread_id", None))
82
91
  if scan["status"] != "running":
83
92
  raise SystemExit("Only a running scan can update progress.")
84
93
  if scan["mode"] == "deep":
@@ -28,9 +28,11 @@ from finalize_scan_contract import (
28
28
  write_sarif_projection,
29
29
  )
30
30
  from validate_scan_contract import validate_contract
31
+ from workbench_constants import PRIMARY_FINDING_LOCATION_SQL
31
32
 
32
33
 
33
34
  def destination_key(destination: Any) -> str:
35
+ """Encode exact provider-specific destination IDs into a stable key for matching issue receipts."""
34
36
  if not isinstance(destination, dict):
35
37
  raise SystemExit("Finding issues require an exact tracker destination.")
36
38
  kind = destination.get("type")
@@ -59,6 +61,12 @@ def verify_publication_history(
59
61
  scan_directory: str,
60
62
  findings: list[dict[str, Any]],
61
63
  ) -> None:
64
+ """Require publication input to match the completed scan in local history.
65
+
66
+ Check the exact scan ID, directory, pinned manifest digest when present,
67
+ and the complete set of occurrence-to-finding associations. Raise
68
+ SystemExit if any of these disagree.
69
+ """
62
70
  try:
63
71
  scan = db.require_scan(connection, scan_id)
64
72
  except SystemExit as exc:
@@ -109,6 +117,7 @@ def inspect_issue_receipts(
109
117
  key: str,
110
118
  finding_ids: list[str],
111
119
  ) -> list[dict[str, Any]]:
120
+ """Return receipts for the selected findings and destination, including receipts from older Linear tables."""
112
121
  tables = {
113
122
  row[0] for row in connection.execute("SELECT name FROM sqlite_master WHERE type = 'table'")
114
123
  }
@@ -132,6 +141,7 @@ def inspect_issue_receipts(
132
141
 
133
142
 
134
143
  def validate_issue_receipts(receipts: Any, selected: dict[str, str]) -> list[dict[str, Any]]:
144
+ """Return receipts bound to the selected finding occurrences or raise SystemExit on invalid receipt data."""
135
145
  if not isinstance(receipts, list):
136
146
  raise SystemExit("Finding issue receipts must be an array.")
137
147
  for receipt in receipts:
@@ -367,6 +377,7 @@ def write_csv_export(
367
377
  scan: sqlite3.Row,
368
378
  findings_document: dict[str, Any],
369
379
  ) -> Path:
380
+ """Write indexed findings to exports/findings.csv, adding candidate IDs for Deep Scans, and return its path."""
370
381
  scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
371
382
  output = io.StringIO(newline="")
372
383
  writer = csv.writer(output)
@@ -412,7 +423,7 @@ def write_csv_export(
412
423
 
413
424
  def finding_export_rows(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Cursor:
414
425
  return connection.execute(
415
- """
426
+ f"""
416
427
  SELECT
417
428
  occurrences.id AS occurrence_id,
418
429
  occurrences.finding_id,
@@ -430,15 +441,8 @@ def finding_export_rows(connection: sqlite3.Connection, scan_id: str) -> sqlite3
430
441
  FROM finding_occurrences AS occurrences
431
442
  LEFT JOIN finding_triage AS triage ON triage.occurrence_id = occurrences.id
432
443
  LEFT JOIN finding_locations AS locations
433
- ON locations.occurrence_id = occurrences.id
434
- AND locations.sort_order = (
435
- SELECT primary_location.sort_order
436
- FROM finding_locations AS primary_location
437
- WHERE primary_location.occurrence_id = occurrences.id
438
- ORDER BY
439
- CASE WHEN primary_location.role = 'root_control' THEN 0 ELSE 1 END,
440
- primary_location.sort_order
441
- LIMIT 1
444
+ ON locations.id = (
445
+ SELECT id {PRIMARY_FINDING_LOCATION_SQL}
442
446
  )
443
447
  WHERE occurrences.scan_id = ?
444
448
  ORDER BY occurrences.created_at, occurrences.id
@@ -47,6 +47,7 @@ SCAN_STATUS_ERROR = "Remediation is available only for successfully completed sc
47
47
 
48
48
 
49
49
  def require_available(connection: sqlite3.Connection, args: Any, require_scan: Any) -> None:
50
+ """Require a successfully completed scan for commands that act on a remediation request."""
50
51
  if args.command not in COMMANDS:
51
52
  return
52
53
  occurrence = require_occurrence(connection, args.occurrence_id)
@@ -57,6 +58,7 @@ def require_available(connection: sqlite3.Connection, args: Any, require_scan: A
57
58
  def require_request(
58
59
  connection: sqlite3.Connection, request_id: str, occurrence: sqlite3.Row
59
60
  ) -> sqlite3.Row:
61
+ """Return the request row or raise SystemExit if the request is missing or belongs to a different occurrence."""
60
62
  current = connection.execute(
61
63
  "SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
62
64
  (request_id,),
@@ -67,6 +69,7 @@ def require_request(
67
69
 
68
70
 
69
71
  def latest_attempt(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row | None:
72
+ """Return the newest remediation attempt for the occurrence, breaking timestamp ties by insertion order."""
70
73
  return connection.execute(
71
74
  """
72
75
  SELECT * FROM finding_remediation_attempts
@@ -344,6 +347,12 @@ def patch_metadata(
344
347
  patch: bytes | None,
345
348
  resolve_path: Callable[[str], str],
346
349
  ) -> tuple[str | None, str | None]:
350
+ """Resolve a remediation attempt’s patch path and SHA-256 digest.
351
+
352
+ For newly generated bytes, compute the digest and use the existing or
353
+ request-specific path. For a referenced patch, validate the supplied path
354
+ and digest. Raise SystemExit if either conflicts with a previously reviewed value.
355
+ """
347
356
  path = args.patch_path
348
357
  digest = args.patch_digest
349
358
  if patch is not None:
@@ -371,6 +380,7 @@ def patch_metadata(
371
380
  def same_file_version(
372
381
  original: tuple[os.stat_result, int], current: tuple[os.stat_result, int]
373
382
  ) -> bool:
383
+ """Compare file identity, size, modification time, and the platform-specific change-time token."""
374
384
  before, before_change = original
375
385
  after, after_change = current
376
386
  return (
@@ -382,6 +392,7 @@ def same_file_version(
382
392
 
383
393
 
384
394
  def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[os.stat_result, int]]:
395
+ """Hash the remaining stream bytes and return their digest and file version, raising SystemExit if the file changes."""
385
396
  before = scan_local_file_version(source.fileno())
386
397
  digest = hashlib.sha256()
387
398
  for chunk in iter(lambda: source.read(1024 * 1024), b""):
@@ -393,6 +404,7 @@ def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[os
393
404
 
394
405
 
395
406
  def matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.stat_result, int]:
407
+ """Return the stable patch version or raise SystemExit if its bytes differ from expected_digest."""
396
408
  digest, version = file_digest_and_version(source, "scan-local patch")
397
409
  if digest != expected_digest:
398
410
  raise SystemExit("Patch digest does not match the scan-local patch file.")
@@ -402,6 +414,7 @@ def matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.
402
414
  def patch_manifest_version(
403
415
  db: Any, scan: sqlite3.Row, scan_dir: Path
404
416
  ) -> tuple[str, tuple[os.stat_result, int]]:
417
+ """Verify the sealed scan manifest and return its byte digest and file version, including for legacy scans."""
405
418
  manifest_path = db.ARTIFACTS["manifest"]
406
419
  expected = scan["seal_manifest_digest"]
407
420
  if expected is None: