@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
@@ -19,6 +19,7 @@ def serialize_filesystem_identity(value: int) -> int | str:
19
19
 
20
20
 
21
21
  def stored_filesystem_identity_matches(stored: object, current: int) -> bool:
22
+ """Compare a stored SQLite value with the platform file ID in its database representation."""
22
23
  return stored == serialize_filesystem_identity(current)
23
24
 
24
25
 
@@ -29,6 +29,10 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
29
29
  import report_projection
30
30
  import servicenow_avit
31
31
  import threat_model_projection
32
+ from legacy_findings import (
33
+ _legacy_sealed_findings_for_validation,
34
+ _normalize_legacy_string_list_fields,
35
+ )
32
36
  from posix_scan_local_files import (
33
37
  descriptor_relative_writes_available as _descriptor_relative_writes_available,
34
38
  )
@@ -466,24 +470,24 @@ def _scan_local_directory_error(message: str, error: OSError) -> ContractError:
466
470
  return ScanLocalIOError(message)
467
471
 
468
472
 
469
- def _require_scan_directory(scan_dir: Path) -> Path:
473
+ def _require_scan_directory(scan_dir: Path, context: str = "scan directory") -> Path:
470
474
  scan_dir = scan_dir.absolute()
471
475
  try:
472
476
  metadata = scan_dir.lstat()
473
477
  except OSError as exc:
474
478
  raise _scan_local_directory_error(
475
- "scan directory: expected an existing non-symlink directory", exc
479
+ f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
476
480
  ) from exc
477
481
  if not stat.S_ISDIR(metadata.st_mode):
478
- raise ContractError("scan directory: expected an existing non-symlink directory")
482
+ raise ContractError(f"{context}: expected an existing non-symlink directory")
479
483
  try:
480
484
  resolved = scan_dir.resolve(strict=True)
481
485
  except OSError as exc:
482
486
  raise _scan_local_directory_error(
483
- "scan directory: expected an existing non-symlink directory", exc
487
+ f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
484
488
  ) from exc
485
489
  if os.path.normcase(resolved) != os.path.normcase(scan_dir):
486
- raise ContractError("scan directory: expected a canonical non-symlink directory")
490
+ raise ContractError(f"{context}: expected a canonical non-symlink directory")
487
491
  return resolved
488
492
 
489
493
 
@@ -624,7 +628,9 @@ def _open_scan_local_file_with_path(
624
628
  except OSError as exc:
625
629
  # The Windows backend retains native ERROR_FILE/PATH_NOT_FOUND codes.
626
630
  if exc.errno in {2, 3}:
627
- raise MissingScanLocalFileError(str(exc)) from exc
631
+ raise MissingScanLocalFileError(
632
+ f"{context}: expected a file inside the scan directory"
633
+ ) from exc
628
634
  raise ContractError(str(exc)) from exc
629
635
  root_fd: int | None = None
630
636
  parent_fd: int | None = None
@@ -792,7 +798,9 @@ def scan_local_file_version(descriptor: int) -> tuple[os.stat_result, int]:
792
798
  def _scan_local_write_path(
793
799
  scan_dir: Path, relative_path: str, external_name: bool
794
800
  ) -> tuple[Path, str]:
795
- scan_dir = _require_scan_directory(scan_dir)
801
+ scan_dir = _require_scan_directory(
802
+ scan_dir, "export output directory" if external_name else "scan directory"
803
+ )
796
804
  if external_name:
797
805
  if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
798
806
  raise ContractError("external output path: expected a safe file name")
@@ -858,6 +866,11 @@ def stage_scan_local_bytes(
858
866
  owner_read_write: bool = False,
859
867
  replace_existing: bool = False,
860
868
  ) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
869
+ """Stage payload under the scan directory and yield a callback that publishes it.
870
+
871
+ Call the callback inside the context to get file metadata and a platform-specific
872
+ change-time token. Leaving without publishing discards the staged write.
873
+ """
861
874
  scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
862
875
  if not _descriptor_relative_writes_available():
863
876
  if not _is_windows():
@@ -955,7 +968,9 @@ def _validate_remote(remote: str, context: str) -> None:
955
968
  parsed = urlsplit(remote)
956
969
  except ValueError as exc:
957
970
  # urlsplit rejects authorities with unbalanced brackets.
958
- raise ContractError(f"{context}: expected a sanitized canonical absolute URL") from exc
971
+ raise ContractError(
972
+ f"{context}: expected a sanitized canonical absolute URL: {exc}"
973
+ ) from exc
959
974
  if "\\" in remote or not parsed.scheme or not parsed.netloc:
960
975
  raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
961
976
  if "@" in parsed.netloc or parsed.query or parsed.fragment:
@@ -1119,6 +1134,48 @@ def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
1119
1134
  )
1120
1135
 
1121
1136
 
1137
+ def _recover_code_evidence(
1138
+ finding: dict[str, Any],
1139
+ item_schema: dict[str, Any],
1140
+ context: str,
1141
+ warnings: list[str],
1142
+ ) -> dict[str, Any]:
1143
+ evidence = finding["codeEvidence"]
1144
+ # Validate before the legacy adapter resolves references and deduplicates IDs.
1145
+ by_id: dict[str, dict[str, Any] | None] = {}
1146
+ if isinstance(evidence, list):
1147
+ for index, row in enumerate(evidence):
1148
+ location = f"{context}.codeEvidence[{index}]"
1149
+ try:
1150
+ _validate_schema_node(row, item_schema, location)
1151
+ _require_safe_json_value(row, location)
1152
+ _require_str(row, "code", location)
1153
+ _require_safe_relative_path(row["path"], f"{location}.path")
1154
+ evidence_id = row["id"]
1155
+ if evidence_id in by_id:
1156
+ if not _schema_values_equal(by_id[evidence_id], row):
1157
+ # Conflicting sources cannot both identify one evidence row.
1158
+ by_id[evidence_id] = None
1159
+ raise ContractError(f"{location}.id: duplicate code-evidence id")
1160
+ by_id[evidence_id] = row
1161
+ except ContractError as exc:
1162
+ warnings.append(f"Skipped malformed codeEvidence: {exc}.")
1163
+ rows = [row for row in by_id.values() if row is not None]
1164
+ if len(rows) == len(evidence):
1165
+ return finding
1166
+ else:
1167
+ warnings.append(
1168
+ f"Skipped malformed codeEvidence: {context}.codeEvidence: expected an array."
1169
+ )
1170
+ rows = []
1171
+ repaired = finding.copy()
1172
+ if rows:
1173
+ repaired["codeEvidence"] = rows
1174
+ else:
1175
+ repaired.pop("codeEvidence")
1176
+ return repaired
1177
+
1178
+
1122
1179
  def _recover_unsealed_findings(
1123
1180
  manifest: dict[str, Any],
1124
1181
  findings: dict[str, Any],
@@ -1153,11 +1210,23 @@ def _recover_unsealed_findings(
1153
1210
  discarded: list[str] = []
1154
1211
  finding_positions: dict[str, int] = {}
1155
1212
  writeup_paths: set[str] = set()
1213
+ evidence_schema = None
1156
1214
  for index, finding in enumerate(_require_list(findings, "findings", "findings")):
1157
1215
  context = f"findings.findings[{index}]"
1216
+ evidence_warnings: list[str] = []
1158
1217
  try:
1159
1218
  if not isinstance(finding, dict):
1160
1219
  raise ContractError(f"{context}: expected an object")
1220
+ if "codeEvidence" in finding:
1221
+ if evidence_schema is None:
1222
+ evidence_schema = (
1223
+ _current_finding_definition(schema_dir, "codeEvidence")
1224
+ if current_contract
1225
+ else finding_properties["codeEvidence"]["items"]
1226
+ )
1227
+ finding = _recover_code_evidence(
1228
+ finding, evidence_schema, context, evidence_warnings
1229
+ )
1161
1230
  compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
1162
1231
  "findings"
1163
1232
  ]
@@ -1172,6 +1241,10 @@ def _recover_unsealed_findings(
1172
1241
  if "instance" in identity:
1173
1242
  fields.append((identity, "instance", f"{context}.identity", "instance"))
1174
1243
  normalized_fields = ["legacy finding details"] if normalized_legacy_details else []
1244
+ taxonomy = finding.get("taxonomy")
1245
+ if isinstance(taxonomy, dict) and "cwe" not in taxonomy:
1246
+ taxonomy["cwe"] = []
1247
+ normalized_fields.append("missing taxonomy.cwe to an empty list")
1175
1248
  for parent, field, field_context, label in fields:
1176
1249
  value = _require_str(parent, field, field_context)
1177
1250
  if SLUG_RE.fullmatch(value):
@@ -1285,6 +1358,7 @@ def _recover_unsealed_findings(
1285
1358
 
1286
1359
  if "writeup" in finding:
1287
1360
  writeup_paths.add(finding["writeup"]["reportPath"])
1361
+ warnings.extend(evidence_warnings)
1288
1362
  if normalized_fields:
1289
1363
  warnings.append(
1290
1364
  f"Recovered finding {index + 1}: normalized {', '.join(normalized_fields)}."
@@ -2153,9 +2227,7 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
2153
2227
  _validate_schema_node(payload, schema, schema_path.stem, schema)
2154
2228
 
2155
2229
 
2156
- def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> None:
2157
- """Use the model's current finding contract for new completed results."""
2158
-
2230
+ def _current_finding_definition(schema_dir: Path, name: str) -> dict[str, Any]:
2159
2231
  draft = _read_json(schema_dir / "tools" / "scan-draft.schema.json")
2160
2232
  common = _read_json(schema_dir / "definitions" / "artifact-common.schema.json")
2161
2233
  documents = {document["$id"]: document for document in (draft, common)}
@@ -2174,7 +2246,12 @@ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> No
2174
2246
  resolved = {**resolve(referenced), **resolved}
2175
2247
  return resolved
2176
2248
 
2177
- finding_schema = resolve(draft["$defs"]["finding"])
2249
+ return resolve(draft["$defs"][name])
2250
+
2251
+
2252
+ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> None:
2253
+ """Use the model's current finding contract for new completed results."""
2254
+ finding_schema = _current_finding_definition(schema_dir, "finding")
2178
2255
  for index, finding in enumerate(findings["findings"]):
2179
2256
  # These fields belong to the host, not the authored finding contract.
2180
2257
  authored = {
@@ -2185,166 +2262,6 @@ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> No
2185
2262
  _validate_schema_node(authored, finding_schema, f"findings.findings[{index}]")
2186
2263
 
2187
2264
 
2188
- def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
2189
- for refs_field in ("evidenceRefs", "evidence_refs"):
2190
- refs = section.get(refs_field)
2191
- if isinstance(refs, list):
2192
- section[refs_field] = [
2193
- ref for ref in refs if isinstance(ref, str) and ref.strip() and ref in evidence_ids
2194
- ]
2195
-
2196
-
2197
- def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
2198
- for field in fields:
2199
- if field not in section:
2200
- continue
2201
- value = section[field]
2202
- if isinstance(value, str):
2203
- normalized = [value] if value.strip() else []
2204
- elif isinstance(value, list):
2205
- normalized = [item for item in value if isinstance(item, str) and item.strip()]
2206
- else:
2207
- normalized = []
2208
- if normalized:
2209
- section[field] = normalized
2210
- else:
2211
- section.pop(field)
2212
-
2213
-
2214
- def _remove_unsupported_legacy_scalar_fields(
2215
- section: dict[str, Any], fields: tuple[str, ...]
2216
- ) -> None:
2217
- for field in fields:
2218
- if field in section and (not isinstance(section[field], str) or section[field] == ""):
2219
- section.pop(field)
2220
-
2221
-
2222
- def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str, Any]:
2223
- compatible = copy.deepcopy(findings)
2224
- finding_items = compatible.get("findings")
2225
- if not isinstance(finding_items, list):
2226
- return compatible
2227
- for finding in finding_items:
2228
- if not isinstance(finding, dict):
2229
- continue
2230
- canonical_evidence = finding.get("codeEvidence")
2231
- canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
2232
- evidence_ids = {
2233
- evidence["id"]
2234
- for evidence in canonical_evidence
2235
- if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
2236
- }
2237
- legacy_evidence = finding.get("code_evidence")
2238
- if isinstance(legacy_evidence, list):
2239
- compatible_legacy_evidence = []
2240
- for evidence in report_projection.code_evidence_rows(legacy_evidence):
2241
- evidence_id = evidence.get("id")
2242
- if not isinstance(evidence_id, str) or not evidence_id.strip():
2243
- continue
2244
- if evidence_id in evidence_ids:
2245
- continue
2246
- evidence_ids.add(evidence_id)
2247
- compatible_legacy_evidence.append(evidence)
2248
- finding["code_evidence"] = compatible_legacy_evidence
2249
- elif "code_evidence" in finding:
2250
- finding.pop("code_evidence")
2251
- for section_name, list_fields in (
2252
- ("rootCause", ("evidenceRefs", "evidence_refs")),
2253
- ("root_cause", ("evidenceRefs", "evidence_refs")),
2254
- (
2255
- "validation",
2256
- (
2257
- "assertions",
2258
- "counterEvidence",
2259
- "evidence",
2260
- "evidenceRefs",
2261
- "evidence_refs",
2262
- "limitations",
2263
- ),
2264
- ),
2265
- (
2266
- "attackPath",
2267
- (
2268
- "assumptions",
2269
- "blindspots",
2270
- "controls",
2271
- "evidenceRefs",
2272
- "evidence_refs",
2273
- "limitations",
2274
- "preconditions",
2275
- "steps",
2276
- ),
2277
- ),
2278
- ):
2279
- section = finding.get(section_name)
2280
- if not isinstance(section, dict):
2281
- continue
2282
- _normalize_legacy_string_list_fields(section, list_fields)
2283
- _filter_unknown_legacy_evidence_refs(section, evidence_ids)
2284
- legacy_root_cause = finding.get("root_cause")
2285
- if isinstance(legacy_root_cause, dict):
2286
- _remove_unsupported_legacy_scalar_fields(
2287
- legacy_root_cause, ("summary", "code", "language")
2288
- )
2289
- elif (
2290
- "root_cause" in finding
2291
- and legacy_root_cause is not None
2292
- and (not isinstance(legacy_root_cause, str) or legacy_root_cause == "")
2293
- ):
2294
- finding.pop("root_cause")
2295
- validation = finding.get("validation")
2296
- if isinstance(validation, dict):
2297
- _remove_unsupported_legacy_scalar_fields(
2298
- validation, ("method", "status", "summary", "disposition", "result")
2299
- )
2300
- attack_path = finding.get("attackPath")
2301
- if not isinstance(attack_path, dict):
2302
- continue
2303
- _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
2304
- for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
2305
- detail = attack_path.get(field)
2306
- if isinstance(detail, dict):
2307
- detail_scalar_fields = ("summary", "source", "sink", "outcome")
2308
- if field == "reachability":
2309
- detail_scalar_fields += ("attacker", "entrypoint")
2310
- _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
2311
- _normalize_legacy_string_list_fields(
2312
- detail, ("evidenceRefs", "evidence_refs", "transformations")
2313
- )
2314
- _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
2315
- if field == "reachability":
2316
- _normalize_legacy_string_list_fields(detail, ("preconditions",))
2317
- elif not isinstance(detail, str) or detail == "":
2318
- attack_path.pop(field, None)
2319
- for field in ("impact", "likelihood"):
2320
- detail = attack_path.get(field)
2321
- if isinstance(detail, dict):
2322
- _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
2323
- elif detail is not None and (not isinstance(detail, str) or detail == ""):
2324
- attack_path.pop(field)
2325
- return compatible
2326
-
2327
-
2328
- def _validate_canonical_schemas_before_projection(
2329
- manifest: dict[str, Any],
2330
- findings: dict[str, Any],
2331
- coverage: dict[str, Any],
2332
- schema_dir: Path,
2333
- ) -> None:
2334
- provisional_manifest = copy.deepcopy(manifest)
2335
- provisional_scan = _require_dict(provisional_manifest, "scan", "manifest")
2336
- provisional_scan["artifacts"] = [
2337
- {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
2338
- {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
2339
- ]
2340
- if "coverageRef" not in provisional_scan:
2341
- provisional_scan["mode"] = coverage["mode"]
2342
- provisional_scan["review"] = review_summary(coverage)
2343
- validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
2344
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2345
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2346
-
2347
-
2348
2265
  def _validate_contract_refs(scan: dict[str, Any]) -> None:
2349
2266
  for field, expected in (
2350
2267
  ("coverageRef", "coverage.json"),
@@ -2810,9 +2727,9 @@ def _validate_existing_seal(
2810
2727
  raise ContractError(f"{context}: sealed artifact changed or is missing")
2811
2728
 
2812
2729
 
2813
- def _read_sealed_artifacts(
2730
+ def _read_scan_artifacts(
2814
2731
  scan_dir: Path, scan: dict[str, Any]
2815
- ) -> tuple[dict[str, Any], dict[str, Any], bytes]:
2732
+ ) -> tuple[dict[str, Any], dict[str, Any], dict[str, bytes]]:
2816
2733
  findings, findings_bytes = _read_scan_local_json_bytes(
2817
2734
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2818
2735
  )
@@ -2824,8 +2741,15 @@ def _read_sealed_artifacts(
2824
2741
  contents[scan["coverageRef"]] = coverage_bytes
2825
2742
  else:
2826
2743
  coverage = review_state(scan)
2744
+ return findings, coverage, contents
2745
+
2746
+
2747
+ def _read_sealed_artifacts(
2748
+ scan_dir: Path, scan: dict[str, Any]
2749
+ ) -> tuple[dict[str, Any], dict[str, Any], bytes]:
2750
+ findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
2827
2751
  _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
2828
- return findings, coverage, findings_bytes
2752
+ return findings, coverage, contents[scan["findingsRef"]]
2829
2753
 
2830
2754
 
2831
2755
  def _read_sealed_scan(
@@ -2854,6 +2778,7 @@ def _read_sealed_scan(
2854
2778
  def build_sarif_projection(
2855
2779
  scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
2856
2780
  ) -> dict[str, Any]:
2781
+ """Build SARIF for a sealed scan, using the optional source directory to resolve locations."""
2857
2782
  if source_root is not None:
2858
2783
  try:
2859
2784
  source_root = source_root.resolve(strict=True)
@@ -2912,38 +2837,30 @@ def _has_identity_text(value: Any) -> bool:
2912
2837
  )
2913
2838
 
2914
2839
 
2840
+ def _candidate_id_values(finding: dict[str, Any]) -> Iterator[Any]:
2841
+ if isinstance(provenance := finding.get("provenance"), dict):
2842
+ yield provenance.get("candidateId")
2843
+ if isinstance(extensions := finding.get("extensions"), dict):
2844
+ for key in ("candidateId", "reportId", "ledgerRowId"):
2845
+ yield extensions.get(key)
2846
+
2847
+
2915
2848
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2916
- provenance = finding.get("provenance")
2917
- if isinstance(provenance, dict) and _has_identity_text(value := provenance.get("candidateId")):
2918
- return value
2919
- extensions = finding.get("extensions")
2920
- if not isinstance(extensions, dict):
2921
- return None
2922
2849
  return next(
2923
- (
2924
- value
2925
- for field in ("candidateId", "reportId", "ledgerRowId")
2926
- if _has_identity_text(value := extensions.get(field))
2927
- ),
2928
- None,
2850
+ (value for value in _candidate_id_values(finding) if _has_identity_text(value)), None
2929
2851
  )
2930
2852
 
2931
2853
 
2932
2854
  def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
2933
- candidate_id = finding_candidate_id(finding)
2934
- if candidate_id is not None:
2935
- return candidate_id
2936
2855
  # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
2937
- for metadata, fields in (
2938
- (finding.get("provenance"), ("candidateId",)),
2939
- (finding.get("extensions"), ("candidateId", "reportId", "ledgerRowId")),
2940
- ):
2941
- if isinstance(metadata, dict):
2942
- for field in fields:
2943
- value = metadata.get(field)
2944
- if isinstance(value, str) and value.strip():
2945
- return value
2946
- return None
2856
+ return finding_candidate_id(finding) or next(
2857
+ (
2858
+ value
2859
+ for value in _candidate_id_values(finding)
2860
+ if isinstance(value, str) and value.strip()
2861
+ ),
2862
+ None,
2863
+ )
2947
2864
 
2948
2865
 
2949
2866
  def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
@@ -2966,6 +2883,7 @@ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2966
2883
 
2967
2884
 
2968
2885
  def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
2886
+ """Encode findings in input order as UTF-8 CSV using the columns selected by coverage and findings."""
2969
2887
  output = io.StringIO(newline="")
2970
2888
  writer = csv.writer(output)
2971
2889
  deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
@@ -3009,6 +2927,11 @@ def build_findings_export(
3009
2927
  schema_dir: Path | None = None,
3010
2928
  avit_template: Path | None = None,
3011
2929
  ) -> bytes:
2930
+ """Return bytes for the requested export of a sealed scan.
2931
+
2932
+ JSON preserves the sealed findings bytes. SARIF can use source_root to resolve
2933
+ locations. ServiceNow AVIT requires an application template.
2934
+ """
3012
2935
  if export_format not in EXPORT_PATHS:
3013
2936
  raise ContractError(f"unsupported export format: {export_format}")
3014
2937
  if export_format == "sarif":
@@ -3132,6 +3055,8 @@ def _write_sarif_projection_if_possible(
3132
3055
 
3133
3056
 
3134
3057
  class PreparedScanFinalization(NamedTuple):
3058
+ """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""
3059
+
3135
3060
  scan_dir: Path
3136
3061
  schema_dir: Path
3137
3062
  manifest: dict[str, Any]
@@ -3143,6 +3068,7 @@ class PreparedScanFinalization(NamedTuple):
3143
3068
 
3144
3069
 
3145
3070
  def manifest_is_sealed(scan: dict[str, Any]) -> bool:
3071
+ """Return whether the manifest records a seal time or sealed artifacts."""
3146
3072
  return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
3147
3073
 
3148
3074
 
@@ -3183,19 +3109,14 @@ def _prepare_scan_finalization(
3183
3109
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3184
3110
  _validate_contract_refs(scan)
3185
3111
  if draft_documents is None:
3186
- findings, findings_input_bytes = _read_scan_local_json_bytes(
3187
- scan_dir, scan["findingsRef"], scan["findingsRef"]
3188
- )
3189
- if "coverageRef" in scan:
3190
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3191
- scan_dir, scan["coverageRef"], scan["coverageRef"]
3192
- )
3193
- else:
3194
- coverage = review_state(scan)
3195
- coverage_input_bytes = _json_bytes(coverage)
3112
+ findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
3196
3113
  else:
3197
3114
  findings, coverage = copy.deepcopy(draft_documents[1:])
3198
- findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
3115
+ contents = {scan["findingsRef"]: _json_bytes(findings)}
3116
+ if "coverageRef" in scan:
3117
+ contents[scan["coverageRef"]] = _json_bytes(coverage)
3118
+ if "coverageRef" not in scan:
3119
+ _json_bytes(coverage)
3199
3120
  if not was_sealed:
3200
3121
  # Preserve legacy sealed bundles, but do not publish a completeness claim.
3201
3122
  coverage.pop("completeness", None)
@@ -3219,14 +3140,7 @@ def _prepare_scan_finalization(
3219
3140
  raise ContractError(
3220
3141
  f"coverage.mode: must match selected scan mode {expected_coverage_mode}"
3221
3142
  )
3222
- _validate_existing_seal(
3223
- scan_dir,
3224
- scan,
3225
- artifact_contents={
3226
- scan["findingsRef"]: findings_input_bytes,
3227
- **({scan["coverageRef"]: coverage_input_bytes} if "coverageRef" in scan else {}),
3228
- },
3229
- )
3143
+ _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
3230
3144
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
3231
3145
  _validate_target(_require_dict(scan, "target", "manifest.scan"))
3232
3146
  _validate_completion_binding(manifest, findings, coverage, completion_binding)
@@ -3258,9 +3172,19 @@ def _prepare_scan_finalization(
3258
3172
  if was_sealed:
3259
3173
  _validate_derived_finding_identities(manifest, findings)
3260
3174
  _validate_coverage(manifest, coverage, scan_dir)
3261
- _validate_canonical_schemas_before_projection(
3262
- manifest, findings_for_validation, coverage, schema_dir
3263
- )
3175
+ provisional_manifest = copy.deepcopy(manifest)
3176
+ provisional_manifest["scan"]["artifacts"] = [
3177
+ {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
3178
+ {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
3179
+ ]
3180
+ inline_review = {}
3181
+ if "coverageRef" not in scan:
3182
+ inline_review = {"mode": coverage["mode"], "review": review_summary(coverage)}
3183
+ provisional_manifest["scan"].update(inline_review)
3184
+ validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
3185
+ del provisional_manifest
3186
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
3187
+ validate_against_schema(coverage, schema_dir / "coverage.schema.json")
3264
3188
  _require_hardening_portfolio_file(scan_dir, scan)
3265
3189
  if finding_scope is not None:
3266
3190
  # Accepted worker/reducer files remain immutable; only the new parent
@@ -3306,9 +3230,8 @@ def _prepare_scan_finalization(
3306
3230
  else:
3307
3231
  findings_bytes = _contract_json_bytes("findings.json", findings)
3308
3232
  coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3309
- if "coverageRef" not in scan:
3310
- scan["mode"] = coverage["mode"]
3311
- scan["review"] = review_summary(coverage)
3233
+ if inline_review:
3234
+ scan.update(inline_review)
3312
3235
  scan.pop("reviewState", None)
3313
3236
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3314
3237
  _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
@@ -3510,8 +3433,11 @@ def main() -> int:
3510
3433
  )
3511
3434
  else:
3512
3435
  finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
3513
- except ContractError as exc:
3514
- parser.error(str(exc))
3436
+ except (ContractError, OSError) as exc:
3437
+ # Keep canonical paths readable and escape control characters at the terminal boundary.
3438
+ parser.error(
3439
+ "".join(char if char.isprintable() else ascii(char)[1:-1] for char in str(exc))
3440
+ )
3515
3441
  return 0
3516
3442
 
3517
3443
 
@@ -27,6 +27,11 @@ from workbench_constants import (
27
27
 
28
28
 
29
29
  def bounded_finding_details(value: Any) -> dict[str, Any]:
30
+ """Build the workbench preview of a stored finding, returning an empty dict for non-object input.
31
+
32
+ Budget for writeup text, diagnostics, and guidance alongside code evidence so a
33
+ large snippet cannot consume the whole preview.
34
+ """
30
35
  if not isinstance(value, dict):
31
36
  return {}
32
37
  prepared: dict[str, Any] = {}
@@ -251,6 +256,7 @@ def bounded_finding_section(
251
256
  priority_keys: tuple[str, ...],
252
257
  reserved_fields: tuple[tuple[tuple[str, ...], int], ...],
253
258
  ) -> Any:
259
+ """Apply each field group’s size cap before selecting fields in priority order under the section cap."""
254
260
  if not isinstance(value, dict):
255
261
  return bounded_json_value(value, [maximum_bytes])
256
262
  ordered: dict[str, Any] = {}
@@ -270,6 +276,12 @@ def bounded_finding_section(
270
276
 
271
277
 
272
278
  def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Any]:
279
+ """Return the preferred evidence key and the preview data to store under it.
280
+
281
+ Merge camelCase and snake_case catalogs by evidence ID, keeping the first
282
+ eligible snippet per ID. Return (None, None) if both keys are absent.
283
+ If neither value is a list, preserve the first supplied value.
284
+ """
273
285
  evidence_keys = [key for key in ("codeEvidence", "code_evidence") if key in value]
274
286
  if not evidence_keys:
275
287
  return None, None
@@ -315,6 +327,7 @@ def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Any
315
327
 
316
328
 
317
329
  def json_size(value: Any) -> int:
330
+ """Return the byte count of the compact, ASCII-escaped JSON representation."""
318
331
  # ASCII output gives byte length; strings can use the cached default encoder.
319
332
  return len(json.dumps(value, separators=None if isinstance(value, str) else (",", ":")))
320
333
 
@@ -326,6 +339,7 @@ def bounded_json_value(
326
339
  depth: int = 0,
327
340
  max_depth: int = 4,
328
341
  ) -> Any:
342
+ """Build a depth-limited preview while charging its JSON representation to the shared byte budget."""
329
343
  if budget[0] <= 0:
330
344
  return None
331
345
  if depth >= max_depth:
@@ -415,6 +429,7 @@ def bounded_json_value(
415
429
 
416
430
 
417
431
  def consume_json_budget(budget: list[int], size: int) -> bool:
432
+ """Deduct the requested size and return whether it fit, exhausting the budget on failure."""
418
433
  if budget[0] < size:
419
434
  budget[0] = 0
420
435
  return False
@@ -423,6 +438,11 @@ def consume_json_budget(budget: list[int], size: int) -> bool:
423
438
 
424
439
 
425
440
  def bounded_json_text(value: str, maximum_bytes: int) -> tuple[str, int]:
441
+ """Return a string prefix and its ASCII-escaped JSON size in bytes.
442
+
443
+ Count the surrounding quotes and escape sequences toward maximum_bytes.
444
+ If even the empty string exceeds the budget, return the empty string and 2.
445
+ """
426
446
  length = bisect_right(
427
447
  range(min(len(value), maximum_bytes) + 1), maximum_bytes, key=lambda n: json_size(value[:n])
428
448
  )
@@ -1,4 +1,5 @@
1
1
  #!/bin/sh
2
+ # Use LF line endings so POSIX can execute this script directly from Windows-built packages.
2
3
  set -eu
3
4
 
4
5
  PATH="${PATH:-/usr/bin:/bin}:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"