@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -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 +5 -2
  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/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
@@ -0,0 +1,7 @@
1
+ #!/bin/sh
2
+ # The trailing slash preserves directory names ending in newlines through substitution.
3
+ set -- "$(CDPATH= cd -P "${0%/*}/../origin" && printf '%s/' "${PWD%/}")${0##*/}" "$@"
4
+ case "$1" in
5
+ /*) exec "$@" ;;
6
+ *) exit 126 ;;
7
+ esac
@@ -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":
@@ -3054,7 +2977,14 @@ def _is_sealed_artifact(scan_dir: Path, relative_output: str, artifact_paths: li
3054
2977
  return False
3055
2978
 
3056
2979
 
3057
- def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
2980
+ def write_export_output(
2981
+ scan_dir: Path,
2982
+ output: Path,
2983
+ export_format: str,
2984
+ contents: bytes,
2985
+ *,
2986
+ replace_existing: bool = True,
2987
+ ) -> None:
3058
2988
  output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
3059
2989
  if export_format not in output_paths:
3060
2990
  raise ContractError(f"unsupported export format: {export_format}")
@@ -3085,6 +3015,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
3085
3015
  output.name,
3086
3016
  contents,
3087
3017
  external_name=True,
3018
+ replace_existing=replace_existing,
3088
3019
  owner_read_write=export_format == "md",
3089
3020
  )
3090
3021
  return
@@ -3109,7 +3040,11 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
3109
3040
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
3110
3041
  )
3111
3042
  write_scan_local_bytes(
3112
- scan_dir, relative_output, contents, owner_read_write=export_format == "md"
3043
+ scan_dir,
3044
+ relative_output,
3045
+ contents,
3046
+ owner_read_write=export_format == "md",
3047
+ replace_existing=replace_existing,
3113
3048
  )
3114
3049
 
3115
3050
 
@@ -3132,6 +3067,8 @@ def _write_sarif_projection_if_possible(
3132
3067
 
3133
3068
 
3134
3069
  class PreparedScanFinalization(NamedTuple):
3070
+ """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""
3071
+
3135
3072
  scan_dir: Path
3136
3073
  schema_dir: Path
3137
3074
  manifest: dict[str, Any]
@@ -3143,6 +3080,7 @@ class PreparedScanFinalization(NamedTuple):
3143
3080
 
3144
3081
 
3145
3082
  def manifest_is_sealed(scan: dict[str, Any]) -> bool:
3083
+ """Return whether the manifest records a seal time or sealed artifacts."""
3146
3084
  return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
3147
3085
 
3148
3086
 
@@ -3183,19 +3121,14 @@ def _prepare_scan_finalization(
3183
3121
  _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
3184
3122
  _validate_contract_refs(scan)
3185
3123
  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)
3124
+ findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
3196
3125
  else:
3197
3126
  findings, coverage = copy.deepcopy(draft_documents[1:])
3198
- findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
3127
+ contents = {scan["findingsRef"]: _json_bytes(findings)}
3128
+ if "coverageRef" in scan:
3129
+ contents[scan["coverageRef"]] = _json_bytes(coverage)
3130
+ if "coverageRef" not in scan:
3131
+ _json_bytes(coverage)
3199
3132
  if not was_sealed:
3200
3133
  # Preserve legacy sealed bundles, but do not publish a completeness claim.
3201
3134
  coverage.pop("completeness", None)
@@ -3219,14 +3152,7 @@ def _prepare_scan_finalization(
3219
3152
  raise ContractError(
3220
3153
  f"coverage.mode: must match selected scan mode {expected_coverage_mode}"
3221
3154
  )
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
- )
3155
+ _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
3230
3156
  scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
3231
3157
  _validate_target(_require_dict(scan, "target", "manifest.scan"))
3232
3158
  _validate_completion_binding(manifest, findings, coverage, completion_binding)
@@ -3258,9 +3184,19 @@ def _prepare_scan_finalization(
3258
3184
  if was_sealed:
3259
3185
  _validate_derived_finding_identities(manifest, findings)
3260
3186
  _validate_coverage(manifest, coverage, scan_dir)
3261
- _validate_canonical_schemas_before_projection(
3262
- manifest, findings_for_validation, coverage, schema_dir
3263
- )
3187
+ provisional_manifest = copy.deepcopy(manifest)
3188
+ provisional_manifest["scan"]["artifacts"] = [
3189
+ {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
3190
+ {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
3191
+ ]
3192
+ inline_review = {}
3193
+ if "coverageRef" not in scan:
3194
+ inline_review = {"mode": coverage["mode"], "review": review_summary(coverage)}
3195
+ provisional_manifest["scan"].update(inline_review)
3196
+ validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
3197
+ del provisional_manifest
3198
+ validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
3199
+ validate_against_schema(coverage, schema_dir / "coverage.schema.json")
3264
3200
  _require_hardening_portfolio_file(scan_dir, scan)
3265
3201
  if finding_scope is not None:
3266
3202
  # Accepted worker/reducer files remain immutable; only the new parent
@@ -3306,9 +3242,8 @@ def _prepare_scan_finalization(
3306
3242
  else:
3307
3243
  findings_bytes = _contract_json_bytes("findings.json", findings)
3308
3244
  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)
3245
+ if inline_review:
3246
+ scan.update(inline_review)
3312
3247
  scan.pop("reviewState", None)
3313
3248
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3314
3249
  _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
@@ -3442,6 +3377,7 @@ def main() -> int:
3442
3377
  parser.add_argument("--export-format", choices=[*sorted(EXPORT_PATHS), "md"])
3443
3378
  parser.add_argument("--avit-template", type=Path)
3444
3379
  parser.add_argument("--export-output", type=Path)
3380
+ parser.add_argument("--no-clobber", action="store_true")
3445
3381
  parser.add_argument("--export-metadata", action="store_true")
3446
3382
  parser.add_argument("--describe-threat-model", action="store_true")
3447
3383
  parser.add_argument("--write-threat-model", action="store_true")
@@ -3503,15 +3439,31 @@ def main() -> int:
3503
3439
  if args.export_output is None:
3504
3440
  sys.stdout.buffer.write(contents)
3505
3441
  else:
3506
- write_export_output(args.scan_dir, args.export_output, args.export_format, contents)
3442
+ try:
3443
+ write_export_output(
3444
+ args.scan_dir,
3445
+ args.export_output,
3446
+ args.export_format,
3447
+ contents,
3448
+ replace_existing=not args.no_clobber,
3449
+ )
3450
+ except FileExistsError:
3451
+ if not args.no_clobber:
3452
+ raise
3453
+ raise ContractError(
3454
+ f"{args.export_output} already exists. Use --output FILE to choose or replace a file."
3455
+ ) from None
3507
3456
  if args.export_metadata:
3508
3457
  sys.stdout.buffer.write(
3509
3458
  _json_bytes({**description, "path": str(args.export_output.absolute())})
3510
3459
  )
3511
3460
  else:
3512
3461
  finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
3513
- except ContractError as exc:
3514
- parser.error(str(exc))
3462
+ except (ContractError, OSError) as exc:
3463
+ # Keep canonical paths readable and escape control characters at the terminal boundary.
3464
+ parser.error(
3465
+ "".join(char if char.isprintable() else ascii(char)[1:-1] for char in str(exc))
3466
+ )
3515
3467
  return 0
3516
3468
 
3517
3469