@openai/codex-security 0.8.2 → 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 (649) hide show
  1. package/README.md +201 -178
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +6 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +51 -14
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/core-scan.md +14 -5
  26. package/_bundled_plugin/references/default-severity-rubric.md +33 -0
  27. package/_bundled_plugin/references/final-report.md +5 -3
  28. package/_bundled_plugin/references/finding-detail-fields.md +19 -18
  29. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  30. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  31. package/_bundled_plugin/references/scan-contract.md +27 -33
  32. package/_bundled_plugin/references/threat-model.md +1 -0
  33. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  34. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  35. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  36. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  37. package/_bundled_plugin/scripts/deep_scan_workbench.py +188 -454
  38. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  39. package/_bundled_plugin/scripts/finalize_scan_contract.py +317 -377
  40. package/_bundled_plugin/scripts/finding_preview.py +25 -29
  41. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  42. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  43. package/_bundled_plugin/scripts/posix_scan_local_files.py +198 -0
  44. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  45. package/_bundled_plugin/scripts/report_projection.py +167 -178
  46. package/_bundled_plugin/scripts/review_state.py +8 -2
  47. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  48. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  49. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  50. package/_bundled_plugin/scripts/validate_scan_contract.py +9 -7
  51. package/_bundled_plugin/scripts/windows_scan_local_files.py +600 -72
  52. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  53. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  54. package/_bundled_plugin/scripts/workbench/retained_coverage.py +38 -75
  55. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  56. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  57. package/_bundled_plugin/scripts/workbench/saved_coverage.py +152 -248
  58. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  59. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  60. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  61. package/_bundled_plugin/scripts/workbench_cli.py +121 -14
  62. package/_bundled_plugin/scripts/workbench_constants.py +19 -0
  63. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  64. package/_bundled_plugin/scripts/workbench_db.py +550 -492
  65. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  66. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  67. package/_bundled_plugin/scripts/workbench_finding_workflows.py +90 -4
  68. package/_bundled_plugin/scripts/workbench_native_indexes.py +29 -33
  69. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  70. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  71. package/_bundled_plugin/scripts/workbench_remediation.py +508 -11
  72. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  73. package/_bundled_plugin/scripts/workbench_scan_history.py +139 -80
  74. package/_bundled_plugin/scripts/workbench_scan_start.py +84 -25
  75. package/_bundled_plugin/scripts/workbench_scan_usage.py +666 -117
  76. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  77. package/_bundled_plugin/scripts/workbench_setup.py +251 -0
  78. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  79. package/_bundled_plugin/scripts/workbench_source_scopes.py +33 -23
  80. package/_bundled_plugin/scripts/workbench_target.py +330 -66
  81. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  82. package/_bundled_plugin/scripts/workbench_validation.py +44 -12
  83. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -16
  84. package/_bundled_plugin/shared/workbench-migrations.json +53 -0
  85. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  86. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  87. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  88. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  89. package/_bundled_plugin/skills/cloud-findings/SKILL.md +6 -4
  90. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  91. package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -2
  92. package/_bundled_plugin/skills/publish-findings/SKILL.md +81 -45
  93. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  94. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +5 -24
  95. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  96. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +36 -9
  97. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  98. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  99. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +12 -6
  100. package/dist/api.d.ts +45 -5
  101. package/dist/api.d.ts.map +1 -1
  102. package/dist/api.js +1144 -411
  103. package/dist/api.js.map +1 -1
  104. package/dist/auth.d.ts.map +1 -1
  105. package/dist/auth.js +10 -7
  106. package/dist/auth.js.map +1 -1
  107. package/dist/bedrock-oss-pricing.d.ts +6 -0
  108. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  109. package/dist/bedrock-oss-pricing.js +58 -0
  110. package/dist/bedrock-oss-pricing.js.map +1 -0
  111. package/dist/bedrock-pricing.d.ts +15 -0
  112. package/dist/bedrock-pricing.d.ts.map +1 -0
  113. package/dist/bedrock-pricing.js +117 -0
  114. package/dist/bedrock-pricing.js.map +1 -0
  115. package/dist/blackduck-findings.d.ts +8 -0
  116. package/dist/blackduck-findings.d.ts.map +1 -0
  117. package/dist/blackduck-findings.js +320 -0
  118. package/dist/blackduck-findings.js.map +1 -0
  119. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  120. package/dist/bulk-scan-discovery.js +51 -36
  121. package/dist/bulk-scan-discovery.js.map +1 -1
  122. package/dist/checkmarx-evidence.d.ts +19 -0
  123. package/dist/checkmarx-evidence.d.ts.map +1 -0
  124. package/dist/checkmarx-evidence.js +36 -0
  125. package/dist/checkmarx-evidence.js.map +1 -0
  126. package/dist/checkmarx-findings.d.ts +4 -0
  127. package/dist/checkmarx-findings.d.ts.map +1 -0
  128. package/dist/checkmarx-findings.js +27 -0
  129. package/dist/checkmarx-findings.js.map +1 -0
  130. package/dist/checkmarx-one.d.ts +4 -0
  131. package/dist/checkmarx-one.d.ts.map +1 -0
  132. package/dist/checkmarx-one.js +53 -0
  133. package/dist/checkmarx-one.js.map +1 -0
  134. package/dist/checkmarx-repository.d.ts +12 -0
  135. package/dist/checkmarx-repository.d.ts.map +1 -0
  136. package/dist/checkmarx-repository.js +181 -0
  137. package/dist/checkmarx-repository.js.map +1 -0
  138. package/dist/checkmarx-xml.d.ts +12 -0
  139. package/dist/checkmarx-xml.d.ts.map +1 -0
  140. package/dist/checkmarx-xml.js +196 -0
  141. package/dist/checkmarx-xml.js.map +1 -0
  142. package/dist/classify-severity-records.d.ts +6 -9
  143. package/dist/classify-severity-records.d.ts.map +1 -1
  144. package/dist/classify-severity-records.js +9 -21
  145. package/dist/classify-severity-records.js.map +1 -1
  146. package/dist/classify-severity.d.ts +4 -1
  147. package/dist/classify-severity.d.ts.map +1 -1
  148. package/dist/classify-severity.js +30 -13
  149. package/dist/classify-severity.js.map +1 -1
  150. package/dist/cli.d.ts +14 -5
  151. package/dist/cli.d.ts.map +1 -1
  152. package/dist/cli.js +2112 -1266
  153. package/dist/cli.js.map +1 -1
  154. package/dist/cloud-publish.js +2 -2
  155. package/dist/cloud-publish.js.map +1 -1
  156. package/dist/codex-prompt.d.ts +2 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +6 -0
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/component-scan.d.ts +16 -3
  161. package/dist/component-scan.d.ts.map +1 -1
  162. package/dist/component-scan.js +32 -6
  163. package/dist/component-scan.js.map +1 -1
  164. package/dist/config.d.ts +2 -1
  165. package/dist/config.d.ts.map +1 -1
  166. package/dist/config.js +221 -65
  167. package/dist/config.js.map +1 -1
  168. package/dist/continuum-findings.d.ts +7 -0
  169. package/dist/continuum-findings.d.ts.map +1 -0
  170. package/dist/continuum-findings.js +225 -0
  171. package/dist/continuum-findings.js.map +1 -0
  172. package/dist/contract-values.d.ts +30 -0
  173. package/dist/contract-values.d.ts.map +1 -0
  174. package/dist/contract-values.js +78 -0
  175. package/dist/contract-values.js.map +1 -0
  176. package/dist/contract.d.ts +2 -20
  177. package/dist/contract.d.ts.map +1 -1
  178. package/dist/contract.js +58 -669
  179. package/dist/contract.js.map +1 -1
  180. package/dist/cost-model.d.ts +13 -1
  181. package/dist/cost-model.d.ts.map +1 -1
  182. package/dist/cost-model.js +66 -115
  183. package/dist/cost-model.js.map +1 -1
  184. package/dist/cost.d.ts +61 -4
  185. package/dist/cost.d.ts.map +1 -1
  186. package/dist/cost.js +2560 -100
  187. package/dist/cost.js.map +1 -1
  188. package/dist/custom-publish.d.ts +4 -0
  189. package/dist/custom-publish.d.ts.map +1 -1
  190. package/dist/custom-publish.js +40 -3
  191. package/dist/custom-publish.js.map +1 -1
  192. package/dist/custom-validation-prompt.d.ts +1 -1
  193. package/dist/custom-validation-prompt.d.ts.map +1 -1
  194. package/dist/custom-validation-prompt.js +5 -0
  195. package/dist/custom-validation-prompt.js.map +1 -1
  196. package/dist/custom-validation.d.ts +2 -0
  197. package/dist/custom-validation.d.ts.map +1 -1
  198. package/dist/custom-validation.js +4 -0
  199. package/dist/custom-validation.js.map +1 -1
  200. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  201. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.js +2 -2
  203. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  204. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  205. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.js +11 -4
  207. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  208. package/dist/deduplication/deduplication.js.map +1 -1
  209. package/dist/deduplication/finding-schema.d.ts +19 -1
  210. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  211. package/dist/deduplication/finding-schema.js +25 -0
  212. package/dist/deduplication/finding-schema.js.map +1 -1
  213. package/dist/deduplication/local.d.ts +2 -2
  214. package/dist/deduplication/local.d.ts.map +1 -1
  215. package/dist/deduplication/local.js +5 -10
  216. package/dist/deduplication/local.js.map +1 -1
  217. package/dist/deduplication/records.d.ts +8 -2
  218. package/dist/deduplication/records.d.ts.map +1 -1
  219. package/dist/deduplication/records.js +36 -8
  220. package/dist/deduplication/records.js.map +1 -1
  221. package/dist/deduplication/refusal.d.ts.map +1 -1
  222. package/dist/deduplication/refusal.js +25 -5
  223. package/dist/deduplication/refusal.js.map +1 -1
  224. package/dist/deduplication/scan.d.ts +3 -0
  225. package/dist/deduplication/scan.d.ts.map +1 -1
  226. package/dist/deduplication/scan.js +1 -1
  227. package/dist/deduplication/scan.js.map +1 -1
  228. package/dist/deep-config.d.ts +0 -1
  229. package/dist/deep-config.d.ts.map +1 -1
  230. package/dist/deep-config.js +22 -33
  231. package/dist/deep-config.js.map +1 -1
  232. package/dist/deep-scan-defaults.d.ts +2 -0
  233. package/dist/deep-scan-defaults.d.ts.map +1 -1
  234. package/dist/deep-scan-defaults.js +28 -1
  235. package/dist/deep-scan-defaults.js.map +1 -1
  236. package/dist/deep-scan.d.ts +13 -0
  237. package/dist/deep-scan.d.ts.map +1 -1
  238. package/dist/deep-scan.js +262 -7
  239. package/dist/deep-scan.js.map +1 -1
  240. package/dist/default-severity-rubric.d.ts +1 -2
  241. package/dist/default-severity-rubric.d.ts.map +1 -1
  242. package/dist/default-severity-rubric.js +2 -66
  243. package/dist/default-severity-rubric.js.map +1 -1
  244. package/dist/endor-findings.d.ts +3 -1
  245. package/dist/endor-findings.d.ts.map +1 -1
  246. package/dist/endor-findings.js +108 -80
  247. package/dist/endor-findings.js.map +1 -1
  248. package/dist/errors.d.ts +1 -1
  249. package/dist/errors.d.ts.map +1 -1
  250. package/dist/errors.js +9 -2
  251. package/dist/errors.js.map +1 -1
  252. package/dist/external-findings-import.d.ts +5 -3
  253. package/dist/external-findings-import.d.ts.map +1 -1
  254. package/dist/external-findings-import.js +11 -16
  255. package/dist/external-findings-import.js.map +1 -1
  256. package/dist/external-findings-local.d.ts +15 -4
  257. package/dist/external-findings-local.d.ts.map +1 -1
  258. package/dist/external-findings-local.js +619 -225
  259. package/dist/external-findings-local.js.map +1 -1
  260. package/dist/external-findings-publish.d.ts +20 -6
  261. package/dist/external-findings-publish.d.ts.map +1 -1
  262. package/dist/external-findings-publish.js +2356 -308
  263. package/dist/external-findings-publish.js.map +1 -1
  264. package/dist/external-findings-read.d.ts +28 -2
  265. package/dist/external-findings-read.d.ts.map +1 -1
  266. package/dist/external-findings-read.js +174 -81
  267. package/dist/external-findings-read.js.map +1 -1
  268. package/dist/external-findings.d.ts +17 -3
  269. package/dist/external-findings.d.ts.map +1 -1
  270. package/dist/external-findings.js +153 -1
  271. package/dist/external-findings.js.map +1 -1
  272. package/dist/external-import-contract.d.ts +33 -1
  273. package/dist/external-import-contract.d.ts.map +1 -1
  274. package/dist/external-import-contract.js +335 -51
  275. package/dist/external-import-contract.js.map +1 -1
  276. package/dist/external-import-models.d.ts +1 -1
  277. package/dist/external-import-models.d.ts.map +1 -1
  278. package/dist/external-import-models.js.map +1 -1
  279. package/dist/feedback.d.ts.map +1 -1
  280. package/dist/feedback.js +5 -4
  281. package/dist/feedback.js.map +1 -1
  282. package/dist/finding-prompt.d.ts +5 -0
  283. package/dist/finding-prompt.d.ts.map +1 -0
  284. package/dist/finding-prompt.js +32 -0
  285. package/dist/finding-prompt.js.map +1 -0
  286. package/dist/finding-retrieval.d.ts +3 -3
  287. package/dist/finding-retrieval.d.ts.map +1 -1
  288. package/dist/finding-retrieval.js.map +1 -1
  289. package/dist/finding-workflow.d.ts +6 -1
  290. package/dist/finding-workflow.d.ts.map +1 -1
  291. package/dist/finding-workflow.js +2 -2
  292. package/dist/finding-workflow.js.map +1 -1
  293. package/dist/findings-client.d.ts +1 -0
  294. package/dist/findings-client.d.ts.map +1 -1
  295. package/dist/findings-client.js +27 -3
  296. package/dist/findings-client.js.map +1 -1
  297. package/dist/git-remote.d.ts +4 -0
  298. package/dist/git-remote.d.ts.map +1 -1
  299. package/dist/git-remote.js +20 -0
  300. package/dist/git-remote.js.map +1 -1
  301. package/dist/github-advisories.d.ts +3 -12
  302. package/dist/github-advisories.d.ts.map +1 -1
  303. package/dist/github-advisories.js +9 -31
  304. package/dist/github-advisories.js.map +1 -1
  305. package/dist/github-dependabot-findings.d.ts.map +1 -1
  306. package/dist/github-dependabot-findings.js +22 -20
  307. package/dist/github-dependabot-findings.js.map +1 -1
  308. package/dist/github-findings.d.ts +4 -1
  309. package/dist/github-findings.d.ts.map +1 -1
  310. package/dist/github-findings.js +392 -79
  311. package/dist/github-findings.js.map +1 -1
  312. package/dist/github.d.ts +17 -7
  313. package/dist/github.d.ts.map +1 -1
  314. package/dist/github.js +43 -30
  315. package/dist/github.js.map +1 -1
  316. package/dist/host-protocol.d.ts +2 -2
  317. package/dist/host-protocol.d.ts.map +1 -1
  318. package/dist/host-protocol.js.map +1 -1
  319. package/dist/host-records-protocol.d.ts +10 -11
  320. package/dist/host-records-protocol.d.ts.map +1 -1
  321. package/dist/host-records-protocol.js +69 -9
  322. package/dist/host-records-protocol.js.map +1 -1
  323. package/dist/hosted-git-remotes.d.ts +5 -0
  324. package/dist/hosted-git-remotes.d.ts.map +1 -0
  325. package/dist/hosted-git-remotes.js +285 -0
  326. package/dist/hosted-git-remotes.js.map +1 -0
  327. package/dist/hosted-git-repository.d.ts +28 -0
  328. package/dist/hosted-git-repository.d.ts.map +1 -0
  329. package/dist/hosted-git-repository.js +222 -0
  330. package/dist/hosted-git-repository.js.map +1 -0
  331. package/dist/hosted-scan-protocol.js +2 -2
  332. package/dist/hosted-scan-protocol.js.map +1 -1
  333. package/dist/hosted-scan.d.ts +15 -0
  334. package/dist/hosted-scan.d.ts.map +1 -1
  335. package/dist/hosted-scan.js +71 -44
  336. package/dist/hosted-scan.js.map +1 -1
  337. package/dist/hosted-scanner-http.d.ts +21 -0
  338. package/dist/hosted-scanner-http.d.ts.map +1 -0
  339. package/dist/hosted-scanner-http.js +204 -0
  340. package/dist/hosted-scanner-http.js.map +1 -0
  341. package/dist/hosted-scanner-v1.d.ts +6 -0
  342. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  343. package/dist/hosted-scanner-v1.js +60 -0
  344. package/dist/hosted-scanner-v1.js.map +1 -0
  345. package/dist/import-scan.d.ts.map +1 -1
  346. package/dist/import-scan.js +3 -0
  347. package/dist/import-scan.js.map +1 -1
  348. package/dist/index.d.ts +24 -6
  349. package/dist/index.d.ts.map +1 -1
  350. package/dist/index.js +15 -1
  351. package/dist/index.js.map +1 -1
  352. package/dist/inspector-findings.d.ts.map +1 -1
  353. package/dist/inspector-findings.js +58 -81
  354. package/dist/inspector-findings.js.map +1 -1
  355. package/dist/knowledge-base.d.ts.map +1 -1
  356. package/dist/knowledge-base.js +86 -10
  357. package/dist/knowledge-base.js.map +1 -1
  358. package/dist/local-git-metadata.d.ts +5 -0
  359. package/dist/local-git-metadata.d.ts.map +1 -0
  360. package/dist/local-git-metadata.js +130 -0
  361. package/dist/local-git-metadata.js.map +1 -0
  362. package/dist/multiscan.d.ts +6 -4
  363. package/dist/multiscan.d.ts.map +1 -1
  364. package/dist/multiscan.js +160 -77
  365. package/dist/multiscan.js.map +1 -1
  366. package/dist/native-json-findings.d.ts +2 -1
  367. package/dist/native-json-findings.d.ts.map +1 -1
  368. package/dist/native-json-findings.js +12 -2
  369. package/dist/native-json-findings.js.map +1 -1
  370. package/dist/opengrep-findings.d.ts +1 -0
  371. package/dist/opengrep-findings.d.ts.map +1 -1
  372. package/dist/opengrep-findings.js +49 -31
  373. package/dist/opengrep-findings.js.map +1 -1
  374. package/dist/operation-telemetry.d.ts +104 -0
  375. package/dist/operation-telemetry.d.ts.map +1 -0
  376. package/dist/operation-telemetry.js +293 -0
  377. package/dist/operation-telemetry.js.map +1 -0
  378. package/dist/patch-tui.d.ts.map +1 -1
  379. package/dist/patch-tui.js +90 -35
  380. package/dist/patch-tui.js.map +1 -1
  381. package/dist/plugin-python-probe.d.ts +4 -0
  382. package/dist/plugin-python-probe.d.ts.map +1 -0
  383. package/dist/plugin-python-probe.js +10 -0
  384. package/dist/plugin-python-probe.js.map +1 -0
  385. package/dist/private-finding-import.d.ts +341 -0
  386. package/dist/private-finding-import.d.ts.map +1 -0
  387. package/dist/private-finding-import.js +411 -0
  388. package/dist/private-finding-import.js.map +1 -0
  389. package/dist/project-config.d.ts.map +1 -1
  390. package/dist/project-config.js +2 -2
  391. package/dist/project-config.js.map +1 -1
  392. package/dist/provider-profile.d.ts +11 -3
  393. package/dist/provider-profile.d.ts.map +1 -1
  394. package/dist/provider-profile.js +80 -11
  395. package/dist/provider-profile.js.map +1 -1
  396. package/dist/publication-telemetry.d.ts +45 -0
  397. package/dist/publication-telemetry.d.ts.map +1 -0
  398. package/dist/publication-telemetry.js +50 -0
  399. package/dist/publication-telemetry.js.map +1 -0
  400. package/dist/publication.js +7 -1
  401. package/dist/publication.js.map +1 -1
  402. package/dist/publish.d.ts +4 -0
  403. package/dist/publish.d.ts.map +1 -1
  404. package/dist/publish.js +42 -2
  405. package/dist/publish.js.map +1 -1
  406. package/dist/reader-selection.d.ts +15 -0
  407. package/dist/reader-selection.d.ts.map +1 -0
  408. package/dist/reader-selection.js +89 -0
  409. package/dist/reader-selection.js.map +1 -0
  410. package/dist/record.d.ts +6 -1
  411. package/dist/record.d.ts.map +1 -1
  412. package/dist/record.js +53 -2
  413. package/dist/record.js.map +1 -1
  414. package/dist/remediation.d.ts +3 -1
  415. package/dist/remediation.d.ts.map +1 -1
  416. package/dist/remediation.js +28 -2
  417. package/dist/remediation.js.map +1 -1
  418. package/dist/request-metadata.d.ts +3 -0
  419. package/dist/request-metadata.d.ts.map +1 -1
  420. package/dist/request-metadata.js +9 -0
  421. package/dist/request-metadata.js.map +1 -1
  422. package/dist/result.d.ts +6 -0
  423. package/dist/result.d.ts.map +1 -1
  424. package/dist/result.js +3 -1
  425. package/dist/result.js.map +1 -1
  426. package/dist/retry-windows-rename.d.ts +8 -0
  427. package/dist/retry-windows-rename.d.ts.map +1 -0
  428. package/dist/retry-windows-rename.js +24 -0
  429. package/dist/retry-windows-rename.js.map +1 -0
  430. package/dist/runtime.d.ts +22 -1
  431. package/dist/runtime.d.ts.map +1 -1
  432. package/dist/runtime.js +408 -162
  433. package/dist/runtime.js.map +1 -1
  434. package/dist/saved-scan-bootstrap.d.ts +1 -0
  435. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  436. package/dist/saved-scan-bootstrap.js +18 -15
  437. package/dist/saved-scan-bootstrap.js.map +1 -1
  438. package/dist/scan-activity.d.ts.map +1 -1
  439. package/dist/scan-activity.js +172 -64
  440. package/dist/scan-activity.js.map +1 -1
  441. package/dist/scan-comparison.d.ts +10 -5
  442. package/dist/scan-comparison.d.ts.map +1 -1
  443. package/dist/scan-comparison.js +68 -25
  444. package/dist/scan-comparison.js.map +1 -1
  445. package/dist/scan-dashboard.d.ts +7 -6
  446. package/dist/scan-dashboard.d.ts.map +1 -1
  447. package/dist/scan-dashboard.js +91 -79
  448. package/dist/scan-dashboard.js.map +1 -1
  449. package/dist/scan-executor.d.ts +12 -1
  450. package/dist/scan-executor.d.ts.map +1 -1
  451. package/dist/scan-executor.js +22 -2
  452. package/dist/scan-executor.js.map +1 -1
  453. package/dist/scan-history-renderer.d.ts.map +1 -1
  454. package/dist/scan-history-renderer.js +31 -28
  455. package/dist/scan-history-renderer.js.map +1 -1
  456. package/dist/scan-logs.d.ts +12 -0
  457. package/dist/scan-logs.d.ts.map +1 -1
  458. package/dist/scan-logs.js +106 -77
  459. package/dist/scan-logs.js.map +1 -1
  460. package/dist/scan-measurement.d.ts +26 -0
  461. package/dist/scan-measurement.d.ts.map +1 -0
  462. package/dist/scan-measurement.js +77 -0
  463. package/dist/scan-measurement.js.map +1 -0
  464. package/dist/scan-progress.d.ts +1 -0
  465. package/dist/scan-progress.d.ts.map +1 -1
  466. package/dist/scan-progress.js +3 -0
  467. package/dist/scan-progress.js.map +1 -1
  468. package/dist/scan-sessions.d.ts.map +1 -1
  469. package/dist/scan-sessions.js +4 -1
  470. package/dist/scan-sessions.js.map +1 -1
  471. package/dist/scan-settings.d.ts +1 -1
  472. package/dist/scan-settings.d.ts.map +1 -1
  473. package/dist/scan-settings.js +1 -24
  474. package/dist/scan-settings.js.map +1 -1
  475. package/dist/scanner-import.d.ts +64 -6
  476. package/dist/scanner-import.d.ts.map +1 -1
  477. package/dist/scanner-import.js +406 -48
  478. package/dist/scanner-import.js.map +1 -1
  479. package/dist/scanner-repository-url.d.ts +17 -0
  480. package/dist/scanner-repository-url.d.ts.map +1 -0
  481. package/dist/scanner-repository-url.js +71 -0
  482. package/dist/scanner-repository-url.js.map +1 -0
  483. package/dist/security-policy.d.ts +1 -1
  484. package/dist/security-policy.d.ts.map +1 -1
  485. package/dist/security-policy.js.map +1 -1
  486. package/dist/semgrep-findings.d.ts +6 -3
  487. package/dist/semgrep-findings.d.ts.map +1 -1
  488. package/dist/semgrep-findings.js +124 -88
  489. package/dist/semgrep-findings.js.map +1 -1
  490. package/dist/semgrep-guardian-findings.d.ts +38 -0
  491. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  492. package/dist/semgrep-guardian-findings.js +165 -0
  493. package/dist/semgrep-guardian-findings.js.map +1 -0
  494. package/dist/semgrep-platform-collector.d.ts +26 -0
  495. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  496. package/dist/semgrep-platform-collector.js +108 -0
  497. package/dist/semgrep-platform-collector.js.map +1 -0
  498. package/dist/semgrep-platform-findings.d.ts +213 -0
  499. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  500. package/dist/semgrep-platform-findings.js +1078 -0
  501. package/dist/semgrep-platform-findings.js.map +1 -0
  502. package/dist/semgrep-platform-v1.d.ts +6 -0
  503. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  504. package/dist/semgrep-platform-v1.js +83 -0
  505. package/dist/semgrep-platform-v1.js.map +1 -0
  506. package/dist/server/api.d.ts +1 -1
  507. package/dist/server/api.d.ts.map +1 -1
  508. package/dist/server/api.js.map +1 -1
  509. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  510. package/dist/server/embedding-tokenizer.d.ts +2 -0
  511. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  512. package/dist/server/embedding-tokenizer.js +322 -0
  513. package/dist/server/embedding-tokenizer.js.map +6 -0
  514. package/dist/server/embeddings.d.ts +16 -2
  515. package/dist/server/embeddings.d.ts.map +1 -1
  516. package/dist/server/embeddings.js +35 -5
  517. package/dist/server/embeddings.js.map +1 -1
  518. package/dist/session-lines.d.ts +5 -0
  519. package/dist/session-lines.d.ts.map +1 -0
  520. package/dist/session-lines.js +60 -0
  521. package/dist/session-lines.js.map +1 -0
  522. package/dist/severity-review.d.ts +3 -1
  523. package/dist/severity-review.d.ts.map +1 -1
  524. package/dist/severity-review.js +3 -2
  525. package/dist/severity-review.js.map +1 -1
  526. package/dist/severity-rubric.d.ts +20 -0
  527. package/dist/severity-rubric.d.ts.map +1 -0
  528. package/dist/severity-rubric.js +73 -0
  529. package/dist/severity-rubric.js.map +1 -0
  530. package/dist/severity-store.js +15 -5
  531. package/dist/severity-store.js.map +1 -1
  532. package/dist/skill-authentication.d.ts +1 -0
  533. package/dist/skill-authentication.d.ts.map +1 -1
  534. package/dist/skill-authentication.js +1 -0
  535. package/dist/skill-authentication.js.map +1 -1
  536. package/dist/snyk-findings.d.ts +7 -2
  537. package/dist/snyk-findings.d.ts.map +1 -1
  538. package/dist/snyk-findings.js +108 -84
  539. package/dist/snyk-findings.js.map +1 -1
  540. package/dist/snyk-rest-findings.d.ts +76 -0
  541. package/dist/snyk-rest-findings.d.ts.map +1 -0
  542. package/dist/snyk-rest-findings.js +1051 -0
  543. package/dist/snyk-rest-findings.js.map +1 -0
  544. package/dist/snyk-rest-v1.d.ts +28 -0
  545. package/dist/snyk-rest-v1.d.ts.map +1 -0
  546. package/dist/snyk-rest-v1.js +132 -0
  547. package/dist/snyk-rest-v1.js.map +1 -0
  548. package/dist/snyk-token-origin.d.ts +4 -0
  549. package/dist/snyk-token-origin.d.ts.map +1 -0
  550. package/dist/snyk-token-origin.js +82 -0
  551. package/dist/snyk-token-origin.js.map +1 -0
  552. package/dist/sonar-collector.d.ts +16 -0
  553. package/dist/sonar-collector.d.ts.map +1 -0
  554. package/dist/sonar-collector.js +380 -0
  555. package/dist/sonar-collector.js.map +1 -0
  556. package/dist/sonar-findings.d.ts +49 -0
  557. package/dist/sonar-findings.d.ts.map +1 -0
  558. package/dist/sonar-findings.js +288 -0
  559. package/dist/sonar-findings.js.map +1 -0
  560. package/dist/sonar-import.d.ts +111 -0
  561. package/dist/sonar-import.d.ts.map +1 -0
  562. package/dist/sonar-import.js +277 -0
  563. package/dist/sonar-import.js.map +1 -0
  564. package/dist/suggest-owners.d.ts.map +1 -1
  565. package/dist/suggest-owners.js +2 -1
  566. package/dist/suggest-owners.js.map +1 -1
  567. package/dist/target-drift.d.ts +9 -0
  568. package/dist/target-drift.d.ts.map +1 -0
  569. package/dist/target-drift.js +27 -0
  570. package/dist/target-drift.js.map +1 -0
  571. package/dist/targets.d.ts +5 -0
  572. package/dist/targets.d.ts.map +1 -1
  573. package/dist/targets.js +73 -31
  574. package/dist/targets.js.map +1 -1
  575. package/dist/tenable-findings.d.ts +9 -0
  576. package/dist/tenable-findings.d.ts.map +1 -0
  577. package/dist/tenable-findings.js +122 -0
  578. package/dist/tenable-findings.js.map +1 -0
  579. package/dist/terminal-columns.d.ts +4 -0
  580. package/dist/terminal-columns.d.ts.map +1 -0
  581. package/dist/terminal-columns.js +19 -0
  582. package/dist/terminal-columns.js.map +1 -0
  583. package/dist/terminal-stream.d.ts +13 -0
  584. package/dist/terminal-stream.d.ts.map +1 -0
  585. package/dist/terminal-stream.js +35 -0
  586. package/dist/terminal-stream.js.map +1 -0
  587. package/dist/trivy-findings.d.ts +19 -0
  588. package/dist/trivy-findings.d.ts.map +1 -0
  589. package/dist/trivy-findings.js +435 -0
  590. package/dist/trivy-findings.js.map +1 -0
  591. package/dist/trivy-import.d.ts +19 -0
  592. package/dist/trivy-import.d.ts.map +1 -0
  593. package/dist/trivy-import.js +151 -0
  594. package/dist/trivy-import.js.map +1 -0
  595. package/dist/validation-records.d.ts +0 -3
  596. package/dist/validation-records.d.ts.map +1 -1
  597. package/dist/validation-records.js +1 -17
  598. package/dist/validation-records.js.map +1 -1
  599. package/dist/veracode-findings.d.ts +9 -0
  600. package/dist/veracode-findings.d.ts.map +1 -0
  601. package/dist/veracode-findings.js +409 -0
  602. package/dist/veracode-findings.js.map +1 -0
  603. package/dist/vertex-pricing.d.ts +8 -0
  604. package/dist/vertex-pricing.d.ts.map +1 -0
  605. package/dist/vertex-pricing.js +20 -0
  606. package/dist/vertex-pricing.js.map +1 -0
  607. package/dist/windows-path.d.ts +1 -0
  608. package/dist/windows-path.d.ts.map +1 -1
  609. package/dist/windows-path.js +27 -1
  610. package/dist/windows-path.js.map +1 -1
  611. package/dist/wiz-csv.d.ts +2 -2
  612. package/dist/wiz-csv.d.ts.map +1 -1
  613. package/dist/wiz-csv.js +1 -3
  614. package/dist/wiz-csv.js.map +1 -1
  615. package/dist/wiz-findings.d.ts +14 -2
  616. package/dist/wiz-findings.d.ts.map +1 -1
  617. package/dist/wiz-findings.js +143 -50
  618. package/dist/wiz-findings.js.map +1 -1
  619. package/docs/classify-severity-records.md +28 -13
  620. package/docs/cli.md +623 -843
  621. package/docs/dedupe-records.md +54 -24
  622. package/docs/findings-service.md +87 -47
  623. package/docs/hosted-remediation.md +14 -7
  624. package/docs/hosted-scans.md +64 -41
  625. package/docs/telemetry.md +236 -0
  626. package/docs/validate-records.md +78 -44
  627. package/package.json +19 -17
  628. package/schemas/external-findings.schema.json +14 -1
  629. package/schemas/hosted-scan-v2.fixture.json +16 -1
  630. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  631. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  632. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  633. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  634. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  635. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  636. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  637. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  638. package/dist/deduplication/records-protocol.d.ts +0 -4
  639. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  640. package/dist/deduplication/records-protocol.js +0 -49
  641. package/dist/deduplication/records-protocol.js.map +0 -1
  642. package/dist/external-imports-feature.d.ts +0 -6
  643. package/dist/external-imports-feature.d.ts.map +0 -1
  644. package/dist/external-imports-feature.js +0 -51
  645. package/dist/external-imports-feature.js.map +0 -1
  646. package/dist/finding-normalization.d.ts +0 -5
  647. package/dist/finding-normalization.d.ts.map +0 -1
  648. package/dist/finding-normalization.js +0 -120
  649. package/dist/finding-normalization.js.map +0 -1
@@ -14,10 +14,11 @@ import json
14
14
  import math
15
15
  import os
16
16
  import re
17
- import secrets
18
17
  import stat
19
18
  import struct
20
19
  import sys
20
+ from collections.abc import Callable, Iterator
21
+ from contextlib import contextmanager
21
22
  from datetime import datetime, timezone
22
23
  from pathlib import Path, PurePosixPath
23
24
  from typing import Any, NamedTuple, TextIO
@@ -28,6 +29,14 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
28
29
  import report_projection
29
30
  import servicenow_avit
30
31
  import threat_model_projection
32
+ from legacy_findings import (
33
+ _legacy_sealed_findings_for_validation,
34
+ _normalize_legacy_string_list_fields,
35
+ )
36
+ from posix_scan_local_files import (
37
+ descriptor_relative_writes_available as _descriptor_relative_writes_available,
38
+ )
39
+ from posix_scan_local_files import managed_fd, stage_write
31
40
  from review_state import checkpoint_review_state, review_state, review_summary
32
41
 
33
42
  SCHEMA_VERSION = "1.0"
@@ -461,24 +470,24 @@ def _scan_local_directory_error(message: str, error: OSError) -> ContractError:
461
470
  return ScanLocalIOError(message)
462
471
 
463
472
 
464
- def _require_scan_directory(scan_dir: Path) -> Path:
473
+ def _require_scan_directory(scan_dir: Path, context: str = "scan directory") -> Path:
465
474
  scan_dir = scan_dir.absolute()
466
475
  try:
467
476
  metadata = scan_dir.lstat()
468
477
  except OSError as exc:
469
478
  raise _scan_local_directory_error(
470
- "scan directory: expected an existing non-symlink directory", exc
479
+ f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
471
480
  ) from exc
472
481
  if not stat.S_ISDIR(metadata.st_mode):
473
- raise ContractError("scan directory: expected an existing non-symlink directory")
482
+ raise ContractError(f"{context}: expected an existing non-symlink directory")
474
483
  try:
475
484
  resolved = scan_dir.resolve(strict=True)
476
485
  except OSError as exc:
477
486
  raise _scan_local_directory_error(
478
- "scan directory: expected an existing non-symlink directory", exc
487
+ f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
479
488
  ) from exc
480
489
  if os.path.normcase(resolved) != os.path.normcase(scan_dir):
481
- raise ContractError("scan directory: expected a canonical non-symlink directory")
490
+ raise ContractError(f"{context}: expected a canonical non-symlink directory")
482
491
  return resolved
483
492
 
484
493
 
@@ -500,15 +509,6 @@ def _is_windows() -> bool:
500
509
  return os.name == "nt"
501
510
 
502
511
 
503
- def _descriptor_relative_writes_available() -> bool:
504
- # os.replace accepts src_dir_fd/dst_dir_fd wherever descriptor-relative
505
- # os.rename is supported, but Python lists only os.rename in supports_dir_fd.
506
- required_operations = (os.mkdir, os.open, os.rename, os.stat, os.unlink)
507
- return hasattr(os, "O_NOFOLLOW") and all(
508
- operation in os.supports_dir_fd for operation in required_operations
509
- )
510
-
511
-
512
512
  def _windows_scan_local_files() -> Any:
513
513
  """Load the Win32 backend and shared stream comparison lazily."""
514
514
  import windows_scan_local_files
@@ -534,13 +534,12 @@ def _open_verified_scan_directory(
534
534
  raise _scan_local_directory_error(
535
535
  "scan directory: expected an existing non-symlink directory", exc
536
536
  ) from exc
537
- opened = os.fstat(descriptor)
538
- opened_identity = (opened.st_dev, opened.st_ino)
539
- if opened_identity != observed_identity or (
540
- expected_root_identity is not None and opened_identity != expected_root_identity
541
- ):
537
+ try:
538
+ if not os.path.samestat(expected, os.fstat(descriptor)):
539
+ raise ContractError("scan directory: changed while it was being opened")
540
+ except BaseException:
542
541
  os.close(descriptor)
543
- raise ContractError("scan directory: changed while it was being opened")
542
+ raise
544
543
  return descriptor
545
544
 
546
545
 
@@ -560,23 +559,41 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
560
559
  os.close(descriptor)
561
560
 
562
561
 
563
- def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create: bool) -> int:
562
+ def _open_scan_local_directory(
563
+ root_fd: int,
564
+ parts: tuple[str, ...],
565
+ *,
566
+ create: bool,
567
+ owner_read_write: bool = False,
568
+ sync_parents: bool = False,
569
+ ) -> int:
564
570
  descriptor = os.dup(root_fd)
565
571
  try:
566
572
  for part in parts:
573
+ if sync_parents:
574
+ os.fsync(descriptor)
567
575
  if create:
568
576
  try:
569
577
  os.mkdir(part, mode=0o700, dir_fd=descriptor)
570
578
  except FileExistsError:
571
579
  # The open below verifies that an existing entry is a real directory.
572
580
  pass
573
- next_descriptor = os.open(
581
+ else:
582
+ if owner_read_write:
583
+ mode = os.stat(part, dir_fd=descriptor, follow_symlinks=False).st_mode
584
+ if mode & stat.S_IRWXU != stat.S_IRWXU:
585
+ os.rmdir(part, dir_fd=descriptor)
586
+ raise ScanLocalIOError(
587
+ f"{part}: process umask prevents owner access to the new directory"
588
+ )
589
+ parent_descriptor = descriptor
590
+ descriptor = os.open(
574
591
  part,
575
592
  os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
576
- dir_fd=descriptor,
593
+ dir_fd=parent_descriptor,
577
594
  )
578
- os.close(descriptor)
579
- descriptor = next_descriptor
595
+ # If closing the parent fails, cleanup now owns the child.
596
+ os.close(parent_descriptor)
580
597
  return descriptor
581
598
  except BaseException:
582
599
  os.close(descriptor)
@@ -611,7 +628,9 @@ def _open_scan_local_file_with_path(
611
628
  except OSError as exc:
612
629
  # The Windows backend retains native ERROR_FILE/PATH_NOT_FOUND codes.
613
630
  if exc.errno in {2, 3}:
614
- raise MissingScanLocalFileError(str(exc)) from exc
631
+ raise MissingScanLocalFileError(
632
+ f"{context}: expected a file inside the scan directory"
633
+ ) from exc
615
634
  raise ContractError(str(exc)) from exc
616
635
  root_fd: int | None = None
617
636
  parent_fd: int | None = None
@@ -766,6 +785,42 @@ def _sha256_scan_local_file(scan_dir: Path, relative_path: str, context: str) ->
766
785
  return digest.hexdigest()
767
786
 
768
787
 
788
+ def scan_local_file_version(descriptor: int) -> tuple[os.stat_result, int]:
789
+ metadata = os.fstat(descriptor)
790
+ changed = (
791
+ _windows_scan_local_files().file_change_time(descriptor)
792
+ if _is_windows()
793
+ else metadata.st_ctime_ns
794
+ )
795
+ return metadata, changed
796
+
797
+
798
+ def _scan_local_write_path(
799
+ scan_dir: Path, relative_path: str, external_name: bool
800
+ ) -> tuple[Path, str]:
801
+ scan_dir = _require_scan_directory(
802
+ scan_dir, "export output directory" if external_name else "scan directory"
803
+ )
804
+ if external_name:
805
+ if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
806
+ raise ContractError("external output path: expected a safe file name")
807
+ else:
808
+ relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
809
+ return scan_dir, relative_path
810
+
811
+
812
+ @contextmanager
813
+ def _windows_write_errors(backend: Any, relative_path: str) -> Iterator[None]:
814
+ try:
815
+ yield
816
+ except FileExistsError:
817
+ raise
818
+ except backend.WindowsScanLocalPathError as exc:
819
+ raise ContractError(f"{relative_path}: {exc}") from exc
820
+ except OSError as exc:
821
+ raise ScanLocalIOError(f"{relative_path}: {exc}") from exc
822
+
823
+
769
824
  def write_scan_local_bytes(
770
825
  scan_dir: Path,
771
826
  relative_path: str,
@@ -774,111 +829,101 @@ def write_scan_local_bytes(
774
829
  external_name: bool = False,
775
830
  expected_root_identity: tuple[int, int] | None = None,
776
831
  owner_read_write: bool = False,
832
+ replace_existing: bool = True,
777
833
  ) -> None:
778
- scan_dir = _require_scan_directory(scan_dir)
779
- if external_name:
780
- if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
781
- raise ContractError("external output path: expected a safe file name")
782
- else:
783
- relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
784
- path = scan_dir / relative_path
834
+ if _is_windows() and not _descriptor_relative_writes_available():
835
+ scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
836
+ backend = _windows_scan_local_files()
837
+ with _windows_write_errors(backend, relative_path):
838
+ backend.atomic_write(
839
+ scan_dir,
840
+ relative_path,
841
+ payload,
842
+ expected_root_identity=expected_root_identity,
843
+ replace_existing=replace_existing,
844
+ )
845
+ return
846
+ with stage_scan_local_bytes(
847
+ scan_dir,
848
+ relative_path,
849
+ payload,
850
+ external_name=external_name,
851
+ expected_root_identity=expected_root_identity,
852
+ owner_read_write=owner_read_write,
853
+ replace_existing=replace_existing,
854
+ ) as publish:
855
+ publish()
856
+
857
+
858
+ @contextmanager
859
+ def stage_scan_local_bytes(
860
+ scan_dir: Path,
861
+ relative_path: str,
862
+ payload: bytes,
863
+ *,
864
+ external_name: bool = False,
865
+ expected_root_identity: tuple[int, int] | None = None,
866
+ owner_read_write: bool = False,
867
+ replace_existing: bool = False,
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
+ """
874
+ scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
785
875
  if not _descriptor_relative_writes_available():
786
876
  if not _is_windows():
787
877
  raise ContractError("scan-local output requires descriptor-relative file operations")
788
878
  backend = _windows_scan_local_files()
789
- try:
790
- backend.atomic_write(
879
+ with _windows_write_errors(backend, relative_path):
880
+ with backend.stage_write(
791
881
  scan_dir,
792
882
  relative_path,
793
883
  payload,
794
884
  expected_root_identity=expected_root_identity,
795
- )
796
- except backend.WindowsScanLocalPathError as exc:
797
- raise ContractError(f"{relative_path}: {exc}") from exc
798
- except OSError as exc:
799
- raise ScanLocalIOError(f"{relative_path}: {exc}") from exc
885
+ replace_existing=replace_existing,
886
+ ) as publish:
887
+ yield publish
800
888
  return
801
- root_fd: int | None = None
802
- parent_fd: int | None = None
803
- temp_name: str | None = None
804
- try:
805
- root_fd = _open_verified_scan_directory(scan_dir, expected_root_identity)
889
+ with managed_fd(_open_verified_scan_directory(scan_dir, expected_root_identity)) as root_fd:
806
890
  parts = PurePosixPath(relative_path).parts
807
891
  try:
808
- parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=True)
892
+ parent_fd = _open_scan_local_directory(
893
+ root_fd, parts[:-1], create=True, owner_read_write=owner_read_write
894
+ )
809
895
  except OSError as exc:
810
896
  raise _scan_local_directory_error(
811
897
  f"{relative_path}: expected a path inside the scan directory", exc
812
898
  ) from exc
813
- # The held descriptor is the authority for the validated parent. A
814
- # concurrent rename cannot redirect later operations through a
815
- # replacement path or link.
816
- try:
817
- metadata = os.stat(parts[-1], dir_fd=parent_fd, follow_symlinks=False)
818
- except FileNotFoundError:
819
- pass
820
- else:
821
- if not stat.S_ISREG(metadata.st_mode):
822
- raise ContractError(f"{relative_path}: expected a regular non-symlink file")
823
- try:
824
- existing_fd = os.open(
825
- parts[-1],
826
- os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
827
- dir_fd=parent_fd,
828
- )
829
- except OSError as exc:
830
- if exc.errno not in {errno.ENOENT, errno.EACCES, errno.EPERM}:
831
- raise
832
- else:
833
- try:
834
- opened = os.fstat(existing_fd)
835
- if not stat.S_ISREG(opened.st_mode):
836
- raise ContractError(f"{relative_path}: expected a regular non-symlink file")
837
- if (opened.st_dev, opened.st_ino) != (
838
- metadata.st_dev,
839
- metadata.st_ino,
840
- ):
841
- raise ContractError(f"{relative_path}: changed while it was being opened")
842
- if expected_root_identity is not None and opened.st_size == len(payload):
843
- try:
844
- with os.fdopen(existing_fd, "rb") as handle:
845
- existing_fd = -1
846
- if _windows_scan_local_files().stream_matches_payload(
847
- handle, payload
848
- ):
849
- return
850
- except OSError:
851
- # A failed content comparison still allows an atomic replacement.
852
- pass
853
- finally:
854
- if existing_fd >= 0:
855
- os.close(existing_fd)
856
- temp_name = f".{path.name}.{secrets.token_hex(8)}.tmp"
857
- temp_fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
858
- with os.fdopen(temp_fd, "wb") as handle:
859
- if owner_read_write:
860
- # Generated Markdown must remain editable under a restrictive umask.
861
- os.fchmod(handle.fileno(), 0o600)
862
- handle.write(payload)
863
- handle.flush()
864
- os.fsync(handle.fileno())
865
- os.replace(temp_name, parts[-1], src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
866
- temp_name = None
867
- finally:
868
- try:
869
- if temp_name is not None and parent_fd is not None:
870
- try:
871
- os.unlink(temp_name, dir_fd=parent_fd)
872
- except FileNotFoundError:
873
- # The temporary file is already gone, so cleanup is complete.
874
- pass
875
- finally:
876
- try:
877
- if parent_fd is not None:
878
- os.close(parent_fd)
879
- finally:
880
- if root_fd is not None:
881
- os.close(root_fd)
899
+
900
+ with managed_fd(parent_fd):
901
+
902
+ def check_parent(directory: Path) -> None:
903
+ # Admission can follow an archive while the staged parent stays open.
904
+ root = os.fstat(root_fd)
905
+ with (
906
+ managed_fd(
907
+ _open_verified_scan_directory(directory, (root.st_dev, root.st_ino))
908
+ ) as current,
909
+ managed_fd(
910
+ _open_scan_local_directory(current, parts[:-1], create=False)
911
+ ) as parent,
912
+ ):
913
+ if not os.path.samestat(os.fstat(parent_fd), os.fstat(parent)):
914
+ raise ContractError(f"{relative_path}: parent changed before publication")
915
+
916
+ with stage_write(
917
+ parent_fd,
918
+ relative_path,
919
+ payload,
920
+ owner_read_write=owner_read_write,
921
+ replace_existing=replace_existing,
922
+ compare_existing=expected_root_identity is not None,
923
+ check_parent=check_parent,
924
+ contract_error=ContractError,
925
+ ) as publish:
926
+ yield publish
882
927
 
883
928
 
884
929
  def _remove_scan_local_file_if_exists(scan_dir: Path, relative_path: str) -> None:
@@ -923,7 +968,9 @@ def _validate_remote(remote: str, context: str) -> None:
923
968
  parsed = urlsplit(remote)
924
969
  except ValueError as exc:
925
970
  # urlsplit rejects authorities with unbalanced brackets.
926
- 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
927
974
  if "\\" in remote or not parsed.scheme or not parsed.netloc:
928
975
  raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
929
976
  if "@" in parsed.netloc or parsed.query or parsed.fragment:
@@ -1087,6 +1134,48 @@ def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
1087
1134
  )
1088
1135
 
1089
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
+
1090
1179
  def _recover_unsealed_findings(
1091
1180
  manifest: dict[str, Any],
1092
1181
  findings: dict[str, Any],
@@ -1121,11 +1210,23 @@ def _recover_unsealed_findings(
1121
1210
  discarded: list[str] = []
1122
1211
  finding_positions: dict[str, int] = {}
1123
1212
  writeup_paths: set[str] = set()
1213
+ evidence_schema = None
1124
1214
  for index, finding in enumerate(_require_list(findings, "findings", "findings")):
1125
1215
  context = f"findings.findings[{index}]"
1216
+ evidence_warnings: list[str] = []
1126
1217
  try:
1127
1218
  if not isinstance(finding, dict):
1128
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
+ )
1129
1230
  compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
1130
1231
  "findings"
1131
1232
  ]
@@ -1140,6 +1241,10 @@ def _recover_unsealed_findings(
1140
1241
  if "instance" in identity:
1141
1242
  fields.append((identity, "instance", f"{context}.identity", "instance"))
1142
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")
1143
1248
  for parent, field, field_context, label in fields:
1144
1249
  value = _require_str(parent, field, field_context)
1145
1250
  if SLUG_RE.fullmatch(value):
@@ -1253,6 +1358,7 @@ def _recover_unsealed_findings(
1253
1358
 
1254
1359
  if "writeup" in finding:
1255
1360
  writeup_paths.add(finding["writeup"]["reportPath"])
1361
+ warnings.extend(evidence_warnings)
1256
1362
  if normalized_fields:
1257
1363
  warnings.append(
1258
1364
  f"Recovered finding {index + 1}: normalized {', '.join(normalized_fields)}."
@@ -1842,6 +1948,18 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1842
1948
  _require_safe_json_value(coverage, "coverage.json")
1843
1949
 
1844
1950
 
1951
+ def _require_unique_artifact_path(artifact: Any, context: str, collision_keys: set[str]) -> str:
1952
+ if not isinstance(artifact, dict):
1953
+ raise ContractError(f"{context}: expected an object")
1954
+ value = _require_str(artifact, "path", context)
1955
+ path = _require_portable_relative_path(value, f"{context}.path")
1956
+ collision_key = path.lower()
1957
+ if collision_key in collision_keys:
1958
+ raise ContractError(f"{context}.path: duplicate artifact path")
1959
+ collision_keys.add(collision_key)
1960
+ return path
1961
+
1962
+
1845
1963
  def _validate_manifest(manifest: dict[str, Any]) -> None:
1846
1964
  if manifest.get("documentType") != "codex-security.scan-manifest":
1847
1965
  raise ContractError("manifest.documentType: expected codex-security.scan-manifest")
@@ -1873,16 +1991,8 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
1873
1991
  artifact_collision_keys: set[str] = set()
1874
1992
  for index, artifact in enumerate(artifacts):
1875
1993
  context = f"manifest.scan.artifacts[{index}]"
1876
- if not isinstance(artifact, dict):
1877
- raise ContractError(f"{context}: expected an object")
1878
- path = _require_portable_relative_path(
1879
- _require_str(artifact, "path", context), f"{context}.path"
1880
- )
1881
- collision_key = path.lower()
1882
- if collision_key in artifact_collision_keys:
1883
- raise ContractError(f"{context}.path: duplicate artifact path")
1994
+ path = _require_unique_artifact_path(artifact, context, artifact_collision_keys)
1884
1995
  artifact_paths.add(path)
1885
- artifact_collision_keys.add(collision_key)
1886
1996
  _require_str(artifact, "sha256", context)
1887
1997
  _require_str(artifact, "mediaType", context)
1888
1998
  for required_path in ("findings.json", *(["coverage.json"] if "coverageRef" in scan else [])):
@@ -2117,9 +2227,7 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
2117
2227
  _validate_schema_node(payload, schema, schema_path.stem, schema)
2118
2228
 
2119
2229
 
2120
- def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> None:
2121
- """Use the model's current finding contract for new completed results."""
2122
-
2230
+ def _current_finding_definition(schema_dir: Path, name: str) -> dict[str, Any]:
2123
2231
  draft = _read_json(schema_dir / "tools" / "scan-draft.schema.json")
2124
2232
  common = _read_json(schema_dir / "definitions" / "artifact-common.schema.json")
2125
2233
  documents = {document["$id"]: document for document in (draft, common)}
@@ -2138,7 +2246,12 @@ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> No
2138
2246
  resolved = {**resolve(referenced), **resolved}
2139
2247
  return resolved
2140
2248
 
2141
- 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")
2142
2255
  for index, finding in enumerate(findings["findings"]):
2143
2256
  # These fields belong to the host, not the authored finding contract.
2144
2257
  authored = {
@@ -2149,174 +2262,6 @@ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> No
2149
2262
  _validate_schema_node(authored, finding_schema, f"findings.findings[{index}]")
2150
2263
 
2151
2264
 
2152
- def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
2153
- for refs_field in ("evidenceRefs", "evidence_refs"):
2154
- refs = section.get(refs_field)
2155
- if isinstance(refs, list):
2156
- section[refs_field] = [
2157
- ref for ref in refs if isinstance(ref, str) and ref.strip() and ref in evidence_ids
2158
- ]
2159
-
2160
-
2161
- def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
2162
- for field in fields:
2163
- if field not in section:
2164
- continue
2165
- value = section[field]
2166
- if isinstance(value, str):
2167
- normalized = [value] if value.strip() else []
2168
- elif isinstance(value, list):
2169
- normalized = [item for item in value if isinstance(item, str) and item.strip()]
2170
- else:
2171
- normalized = []
2172
- if normalized:
2173
- section[field] = normalized
2174
- else:
2175
- section.pop(field)
2176
-
2177
-
2178
- def _remove_unsupported_legacy_scalar_fields(
2179
- section: dict[str, Any], fields: tuple[str, ...]
2180
- ) -> None:
2181
- for field in fields:
2182
- if field in section and (not isinstance(section[field], str) or section[field] == ""):
2183
- section.pop(field)
2184
-
2185
-
2186
- def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str, Any]:
2187
- compatible = copy.deepcopy(findings)
2188
- finding_items = compatible.get("findings")
2189
- if not isinstance(finding_items, list):
2190
- return compatible
2191
- for finding in finding_items:
2192
- if not isinstance(finding, dict):
2193
- continue
2194
- canonical_evidence = finding.get("codeEvidence")
2195
- canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
2196
- evidence_ids = {
2197
- evidence["id"]
2198
- for evidence in canonical_evidence
2199
- if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
2200
- }
2201
- legacy_evidence = finding.get("code_evidence")
2202
- if isinstance(legacy_evidence, list):
2203
- compatible_legacy_evidence = []
2204
- for evidence in legacy_evidence:
2205
- if not isinstance(evidence, dict):
2206
- continue
2207
- evidence_id = evidence.get("id")
2208
- evidence_code = evidence.get("code")
2209
- if (
2210
- not isinstance(evidence_id, str)
2211
- or not evidence_id.strip()
2212
- or not isinstance(evidence_code, str)
2213
- or not evidence_code.strip()
2214
- ):
2215
- continue
2216
- if evidence_id in evidence_ids:
2217
- continue
2218
- evidence_ids.add(evidence_id)
2219
- compatible_legacy_evidence.append(evidence)
2220
- finding["code_evidence"] = compatible_legacy_evidence
2221
- elif "code_evidence" in finding:
2222
- finding.pop("code_evidence")
2223
- for section_name, list_fields in (
2224
- ("rootCause", ("evidenceRefs", "evidence_refs")),
2225
- ("root_cause", ("evidenceRefs", "evidence_refs")),
2226
- (
2227
- "validation",
2228
- (
2229
- "assertions",
2230
- "counterEvidence",
2231
- "evidence",
2232
- "evidenceRefs",
2233
- "evidence_refs",
2234
- "limitations",
2235
- ),
2236
- ),
2237
- (
2238
- "attackPath",
2239
- (
2240
- "assumptions",
2241
- "blindspots",
2242
- "controls",
2243
- "evidenceRefs",
2244
- "evidence_refs",
2245
- "limitations",
2246
- "preconditions",
2247
- "steps",
2248
- ),
2249
- ),
2250
- ):
2251
- section = finding.get(section_name)
2252
- if not isinstance(section, dict):
2253
- continue
2254
- _normalize_legacy_string_list_fields(section, list_fields)
2255
- _filter_unknown_legacy_evidence_refs(section, evidence_ids)
2256
- legacy_root_cause = finding.get("root_cause")
2257
- if isinstance(legacy_root_cause, dict):
2258
- _remove_unsupported_legacy_scalar_fields(
2259
- legacy_root_cause, ("summary", "code", "language")
2260
- )
2261
- elif (
2262
- "root_cause" in finding
2263
- and legacy_root_cause is not None
2264
- and (not isinstance(legacy_root_cause, str) or legacy_root_cause == "")
2265
- ):
2266
- finding.pop("root_cause")
2267
- validation = finding.get("validation")
2268
- if isinstance(validation, dict):
2269
- _remove_unsupported_legacy_scalar_fields(
2270
- validation, ("method", "status", "summary", "disposition", "result")
2271
- )
2272
- attack_path = finding.get("attackPath")
2273
- if not isinstance(attack_path, dict):
2274
- continue
2275
- _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
2276
- for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
2277
- detail = attack_path.get(field)
2278
- if isinstance(detail, dict):
2279
- detail_scalar_fields = ("summary", "source", "sink", "outcome")
2280
- if field == "reachability":
2281
- detail_scalar_fields += ("attacker", "entrypoint")
2282
- _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
2283
- _normalize_legacy_string_list_fields(
2284
- detail, ("evidenceRefs", "evidence_refs", "transformations")
2285
- )
2286
- _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
2287
- if field == "reachability":
2288
- _normalize_legacy_string_list_fields(detail, ("preconditions",))
2289
- elif not isinstance(detail, str) or detail == "":
2290
- attack_path.pop(field, None)
2291
- for field in ("impact", "likelihood"):
2292
- detail = attack_path.get(field)
2293
- if isinstance(detail, dict):
2294
- _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
2295
- elif detail is not None and (not isinstance(detail, str) or detail == ""):
2296
- attack_path.pop(field)
2297
- return compatible
2298
-
2299
-
2300
- def _validate_canonical_schemas_before_projection(
2301
- manifest: dict[str, Any],
2302
- findings: dict[str, Any],
2303
- coverage: dict[str, Any],
2304
- schema_dir: Path,
2305
- ) -> None:
2306
- provisional_manifest = copy.deepcopy(manifest)
2307
- provisional_scan = _require_dict(provisional_manifest, "scan", "manifest")
2308
- provisional_scan["artifacts"] = [
2309
- {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
2310
- {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
2311
- ]
2312
- if "coverageRef" not in provisional_scan:
2313
- provisional_scan["mode"] = coverage["mode"]
2314
- provisional_scan["review"] = review_summary(coverage)
2315
- validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
2316
- validate_against_schema(findings, schema_dir / "findings.schema.json")
2317
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2318
-
2319
-
2320
2265
  def _validate_contract_refs(scan: dict[str, Any]) -> None:
2321
2266
  for field, expected in (
2322
2267
  ("coverageRef", "coverage.json"),
@@ -2520,23 +2465,17 @@ def _finding_evidence_strength(finding: dict[str, Any]) -> int:
2520
2465
  section = finding.get(section_name)
2521
2466
  if not isinstance(section, dict):
2522
2467
  continue
2523
- for evidence_name in ("codeEvidence", "code_evidence"):
2524
- embedded = section.get(evidence_name)
2525
- if not isinstance(embedded, list):
2468
+ for item in report_projection.embedded_code_evidence(section):
2469
+ code = item["code"]
2470
+ if code in seen_codes:
2526
2471
  continue
2527
- for item in embedded:
2528
- if not isinstance(item, dict):
2529
- continue
2530
- code = item.get("code")
2531
- if not isinstance(code, str) or not code.strip() or code in seen_codes:
2472
+ evidence_id = item.get("id")
2473
+ if isinstance(evidence_id, str) and evidence_id.strip():
2474
+ if evidence_id in seen_ids:
2532
2475
  continue
2533
- evidence_id = item.get("id")
2534
- if isinstance(evidence_id, str) and evidence_id.strip():
2535
- if evidence_id in seen_ids:
2536
- continue
2537
- seen_ids.add(evidence_id)
2538
- seen_codes.add(code)
2539
- strength += 1
2476
+ seen_ids.add(evidence_id)
2477
+ seen_codes.add(code)
2478
+ strength += 1
2540
2479
  code = section.get("code")
2541
2480
  if isinstance(code, str) and code.strip() and code not in seen_codes:
2542
2481
  seen_codes.add(code)
@@ -2776,15 +2715,7 @@ def _validate_existing_seal(
2776
2715
  artifact_collision_keys: set[str] = set()
2777
2716
  for index, artifact in enumerate(artifacts):
2778
2717
  context = f"manifest.scan.artifacts[{index}]"
2779
- if not isinstance(artifact, dict):
2780
- raise ContractError(f"{context}: expected an object")
2781
- path = _require_portable_relative_path(
2782
- _require_str(artifact, "path", context), f"{context}.path"
2783
- )
2784
- collision_key = path.lower()
2785
- if collision_key in artifact_collision_keys:
2786
- raise ContractError(f"{context}.path: duplicate artifact path")
2787
- artifact_collision_keys.add(collision_key)
2718
+ path = _require_unique_artifact_path(artifact, context, artifact_collision_keys)
2788
2719
  expected_sha256 = _require_str(artifact, "sha256", context)
2789
2720
  contents = (artifact_contents or {}).get(path)
2790
2721
  actual_sha256 = (
@@ -2796,9 +2727,9 @@ def _validate_existing_seal(
2796
2727
  raise ContractError(f"{context}: sealed artifact changed or is missing")
2797
2728
 
2798
2729
 
2799
- def _read_sealed_artifacts(
2730
+ def _read_scan_artifacts(
2800
2731
  scan_dir: Path, scan: dict[str, Any]
2801
- ) -> tuple[dict[str, Any], dict[str, Any], bytes]:
2732
+ ) -> tuple[dict[str, Any], dict[str, Any], dict[str, bytes]]:
2802
2733
  findings, findings_bytes = _read_scan_local_json_bytes(
2803
2734
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2804
2735
  )
@@ -2810,8 +2741,15 @@ def _read_sealed_artifacts(
2810
2741
  contents[scan["coverageRef"]] = coverage_bytes
2811
2742
  else:
2812
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)
2813
2751
  _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
2814
- return findings, coverage, findings_bytes
2752
+ return findings, coverage, contents[scan["findingsRef"]]
2815
2753
 
2816
2754
 
2817
2755
  def _read_sealed_scan(
@@ -2840,6 +2778,7 @@ def _read_sealed_scan(
2840
2778
  def build_sarif_projection(
2841
2779
  scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
2842
2780
  ) -> dict[str, Any]:
2781
+ """Build SARIF for a sealed scan, using the optional source directory to resolve locations."""
2843
2782
  if source_root is not None:
2844
2783
  try:
2845
2784
  source_root = source_root.resolve(strict=True)
@@ -2898,38 +2837,30 @@ def _has_identity_text(value: Any) -> bool:
2898
2837
  )
2899
2838
 
2900
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
+
2901
2848
  def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2902
- provenance = finding.get("provenance")
2903
- if isinstance(provenance, dict) and _has_identity_text(value := provenance.get("candidateId")):
2904
- return value
2905
- extensions = finding.get("extensions")
2906
- if not isinstance(extensions, dict):
2907
- return None
2908
2849
  return next(
2909
- (
2910
- value
2911
- for field in ("candidateId", "reportId", "ledgerRowId")
2912
- if _has_identity_text(value := extensions.get(field))
2913
- ),
2914
- None,
2850
+ (value for value in _candidate_id_values(finding) if _has_identity_text(value)), None
2915
2851
  )
2916
2852
 
2917
2853
 
2918
2854
  def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
2919
- candidate_id = finding_candidate_id(finding)
2920
- if candidate_id is not None:
2921
- return candidate_id
2922
2855
  # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
2923
- for metadata, fields in (
2924
- (finding.get("provenance"), ("candidateId",)),
2925
- (finding.get("extensions"), ("candidateId", "reportId", "ledgerRowId")),
2926
- ):
2927
- if isinstance(metadata, dict):
2928
- for field in fields:
2929
- value = metadata.get(field)
2930
- if isinstance(value, str) and value.strip():
2931
- return value
2932
- 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
+ )
2933
2864
 
2934
2865
 
2935
2866
  def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
@@ -2952,6 +2883,7 @@ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2952
2883
 
2953
2884
 
2954
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."""
2955
2887
  output = io.StringIO(newline="")
2956
2888
  writer = csv.writer(output)
2957
2889
  deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
@@ -2995,6 +2927,11 @@ def build_findings_export(
2995
2927
  schema_dir: Path | None = None,
2996
2928
  avit_template: Path | None = None,
2997
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
+ """
2998
2935
  if export_format not in EXPORT_PATHS:
2999
2936
  raise ContractError(f"unsupported export format: {export_format}")
3000
2937
  if export_format == "sarif":
@@ -3118,6 +3055,8 @@ def _write_sarif_projection_if_possible(
3118
3055
 
3119
3056
 
3120
3057
  class PreparedScanFinalization(NamedTuple):
3058
+ """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""
3059
+
3121
3060
  scan_dir: Path
3122
3061
  schema_dir: Path
3123
3062
  manifest: dict[str, Any]
@@ -3129,6 +3068,7 @@ class PreparedScanFinalization(NamedTuple):
3129
3068
 
3130
3069
 
3131
3070
  def manifest_is_sealed(scan: dict[str, Any]) -> bool:
3071
+ """Return whether the manifest records a seal time or sealed artifacts."""
3132
3072
  return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
3133
3073
 
3134
3074
 
@@ -3169,19 +3109,14 @@ def _prepare_scan_finalization(
3169
3109
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3170
3110
  _validate_contract_refs(scan)
3171
3111
  if draft_documents is None:
3172
- findings, findings_input_bytes = _read_scan_local_json_bytes(
3173
- scan_dir, scan["findingsRef"], scan["findingsRef"]
3174
- )
3175
- if "coverageRef" in scan:
3176
- coverage, coverage_input_bytes = _read_scan_local_json_bytes(
3177
- scan_dir, scan["coverageRef"], scan["coverageRef"]
3178
- )
3179
- else:
3180
- coverage = review_state(scan)
3181
- coverage_input_bytes = _json_bytes(coverage)
3112
+ findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
3182
3113
  else:
3183
3114
  findings, coverage = copy.deepcopy(draft_documents[1:])
3184
- 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)
3185
3120
  if not was_sealed:
3186
3121
  # Preserve legacy sealed bundles, but do not publish a completeness claim.
3187
3122
  coverage.pop("completeness", None)
@@ -3205,14 +3140,7 @@ def _prepare_scan_finalization(
3205
3140
  raise ContractError(
3206
3141
  f"coverage.mode: must match selected scan mode {expected_coverage_mode}"
3207
3142
  )
3208
- _validate_existing_seal(
3209
- scan_dir,
3210
- scan,
3211
- artifact_contents={
3212
- scan["findingsRef"]: findings_input_bytes,
3213
- **({scan["coverageRef"]: coverage_input_bytes} if "coverageRef" in scan else {}),
3214
- },
3215
- )
3143
+ _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
3216
3144
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
3217
3145
  _validate_target(_require_dict(scan, "target", "manifest.scan"))
3218
3146
  _validate_completion_binding(manifest, findings, coverage, completion_binding)
@@ -3244,9 +3172,19 @@ def _prepare_scan_finalization(
3244
3172
  if was_sealed:
3245
3173
  _validate_derived_finding_identities(manifest, findings)
3246
3174
  _validate_coverage(manifest, coverage, scan_dir)
3247
- _validate_canonical_schemas_before_projection(
3248
- manifest, findings_for_validation, coverage, schema_dir
3249
- )
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")
3250
3188
  _require_hardening_portfolio_file(scan_dir, scan)
3251
3189
  if finding_scope is not None:
3252
3190
  # Accepted worker/reducer files remain immutable; only the new parent
@@ -3292,9 +3230,8 @@ def _prepare_scan_finalization(
3292
3230
  else:
3293
3231
  findings_bytes = _contract_json_bytes("findings.json", findings)
3294
3232
  coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3295
- if "coverageRef" not in scan:
3296
- scan["mode"] = coverage["mode"]
3297
- scan["review"] = review_summary(coverage)
3233
+ if inline_review:
3234
+ scan.update(inline_review)
3298
3235
  scan.pop("reviewState", None)
3299
3236
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3300
3237
  _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
@@ -3496,8 +3433,11 @@ def main() -> int:
3496
3433
  )
3497
3434
  else:
3498
3435
  finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
3499
- except ContractError as exc:
3500
- 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
+ )
3501
3441
  return 0
3502
3442
 
3503
3443