@openai/codex-security 0.2.0 → 0.4.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 (484) hide show
  1. package/README.md +437 -2692
  2. package/_bundled_plugin/.app.json +5 -1
  3. package/_bundled_plugin/.codex-plugin/plugin.json +4 -0
  4. package/_bundled_plugin/.mcp.json +2 -0
  5. package/_bundled_plugin/examples/completed-scan/coverage.json +0 -1
  6. package/_bundled_plugin/examples/completed-scan/report.md +28 -26
  7. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
  8. package/_bundled_plugin/mcp/helpers.mjs +1 -0
  9. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +6 -213
  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/permission-profile-preflight.mjs +556 -0
  20. package/_bundled_plugin/mcp/server.mjs +1 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  23. package/_bundled_plugin/preflight/capability-profiles.toml +0 -13
  24. package/_bundled_plugin/references/artifact-storage.md +2 -2
  25. package/_bundled_plugin/references/config-preflight.md +0 -4
  26. package/_bundled_plugin/references/core-scan.md +21 -9
  27. package/_bundled_plugin/references/final-report.md +11 -13
  28. package/_bundled_plugin/references/finding-detail-fields.md +90 -80
  29. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  30. package/_bundled_plugin/references/scan-artifacts.md +1 -2
  31. package/_bundled_plugin/references/scan-contract.md +9 -4
  32. package/_bundled_plugin/references/scan-prologue.md +12 -0
  33. package/_bundled_plugin/references/security-guidance.md +2 -2
  34. package/_bundled_plugin/references/standalone-validation.md +11 -0
  35. package/_bundled_plugin/references/threat-model.md +1 -1
  36. package/_bundled_plugin/schemas/coverage.schema.json +43 -170
  37. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +2 -24
  38. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +49 -25
  39. package/_bundled_plugin/schemas/findings.schema.json +159 -567
  40. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  41. package/_bundled_plugin/schemas/scan-manifest.schema.json +78 -220
  42. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +91 -83
  43. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +35 -64
  44. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +5 -2
  45. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +6 -55
  46. package/_bundled_plugin/schemas/tools/review-items.schema.json +2 -38
  47. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +169 -294
  48. package/_bundled_plugin/scripts/codex_profile.mjs +239 -0
  49. package/_bundled_plugin/scripts/codex_session.mjs +53 -0
  50. package/_bundled_plugin/scripts/config_preflight.py +26 -62
  51. package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
  52. package/_bundled_plugin/scripts/deep_scan_workbench.py +129 -150
  53. package/_bundled_plugin/scripts/finalize_scan_contract.py +321 -237
  54. package/_bundled_plugin/scripts/finding_preview.py +39 -9
  55. package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -77
  56. package/_bundled_plugin/scripts/generate_rank_input.py +115 -926
  57. package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -10
  58. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
  59. package/_bundled_plugin/scripts/rank_preview.py +42 -918
  60. package/_bundled_plugin/scripts/report_projection.py +150 -183
  61. package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
  62. package/_bundled_plugin/scripts/threat_model_projection.py +4 -7
  63. package/_bundled_plugin/scripts/validate_scan_contract.py +4 -34
  64. package/_bundled_plugin/scripts/validate_tracking_source.py +3 -13
  65. package/_bundled_plugin/scripts/windows_scan_local_files.py +48 -3
  66. package/_bundled_plugin/scripts/workbench/handoff.py +25 -50
  67. package/_bundled_plugin/scripts/workbench/runtime_toml.py +22 -0
  68. package/_bundled_plugin/scripts/workbench/storage.py +10 -6
  69. package/_bundled_plugin/scripts/workbench_cli.py +102 -184
  70. package/_bundled_plugin/scripts/workbench_db.py +463 -464
  71. package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +19 -1
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
  74. package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
  75. package/_bundled_plugin/scripts/workbench_native_indexes.py +27 -14
  76. package/_bundled_plugin/scripts/workbench_progress.py +14 -58
  77. package/_bundled_plugin/scripts/workbench_publication.py +234 -289
  78. package/_bundled_plugin/scripts/workbench_remediation.py +12 -0
  79. package/_bundled_plugin/scripts/workbench_saved_results.py +172 -49
  80. package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
  81. package/_bundled_plugin/scripts/workbench_scan_start.py +105 -41
  82. package/_bundled_plugin/scripts/workbench_scan_usage.py +194 -42
  83. package/_bundled_plugin/scripts/workbench_schema.py +37 -1151
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +11 -1
  85. package/_bundled_plugin/scripts/workbench_target.py +430 -142
  86. package/_bundled_plugin/scripts/workbench_validation.py +31 -28
  87. package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
  88. package/_bundled_plugin/shared/workbench-migrations.json +414 -0
  89. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
  90. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
  92. package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +3 -3
  94. package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
  95. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
  96. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
  97. package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
  98. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  99. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +15 -1
  100. package/_bundled_plugin/skills/threat-model/SKILL.md +1 -1
  101. package/_bundled_plugin/skills/track-findings/SKILL.md +48 -176
  102. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
  103. package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
  104. package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
  105. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
  106. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
  107. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
  108. package/bin/codex-security.mjs +9 -2
  109. package/dist/api.d.ts +63 -10
  110. package/dist/api.d.ts.map +1 -1
  111. package/dist/api.js +1015 -383
  112. package/dist/api.js.map +1 -1
  113. package/dist/artifact-export.d.ts +1 -1
  114. package/dist/artifact-export.d.ts.map +1 -1
  115. package/dist/artifact-export.js +28 -13
  116. package/dist/artifact-export.js.map +1 -1
  117. package/dist/auth.d.ts +2 -6
  118. package/dist/auth.d.ts.map +1 -1
  119. package/dist/auth.js +19 -9
  120. package/dist/auth.js.map +1 -1
  121. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  122. package/dist/bulk-scan-discovery.js +1 -0
  123. package/dist/bulk-scan-discovery.js.map +1 -1
  124. package/dist/classify-severity.d.ts +26 -9
  125. package/dist/classify-severity.d.ts.map +1 -1
  126. package/dist/classify-severity.js +13 -30
  127. package/dist/classify-severity.js.map +1 -1
  128. package/dist/cli-help.d.ts.map +1 -1
  129. package/dist/cli-help.js +17 -13
  130. package/dist/cli-help.js.map +1 -1
  131. package/dist/cli-signals.d.ts +8 -0
  132. package/dist/cli-signals.d.ts.map +1 -0
  133. package/dist/cli-signals.js +28 -0
  134. package/dist/cli-signals.js.map +1 -0
  135. package/dist/cli.d.ts +4 -3
  136. package/dist/cli.d.ts.map +1 -1
  137. package/dist/cli.js +1102 -905
  138. package/dist/cli.js.map +1 -1
  139. package/dist/cloud-publish.d.ts.map +1 -1
  140. package/dist/cloud-publish.js +10 -9
  141. package/dist/cloud-publish.js.map +1 -1
  142. package/dist/codeowners.d.ts +19 -0
  143. package/dist/codeowners.d.ts.map +1 -0
  144. package/dist/codeowners.js +138 -0
  145. package/dist/codeowners.js.map +1 -0
  146. package/dist/codex-sdk-environment.d.ts +1 -0
  147. package/dist/codex-sdk-environment.d.ts.map +1 -1
  148. package/dist/codex-sdk-environment.js +40 -2
  149. package/dist/codex-sdk-environment.js.map +1 -1
  150. package/dist/component-plan.d.ts +2 -5
  151. package/dist/component-plan.d.ts.map +1 -1
  152. package/dist/component-plan.js +39 -31
  153. package/dist/component-plan.js.map +1 -1
  154. package/dist/component-scan.d.ts +6 -5
  155. package/dist/component-scan.d.ts.map +1 -1
  156. package/dist/component-scan.js +25 -36
  157. package/dist/component-scan.js.map +1 -1
  158. package/dist/config.d.ts.map +1 -1
  159. package/dist/config.js +64 -74
  160. package/dist/config.js.map +1 -1
  161. package/dist/contract.d.ts +16 -3
  162. package/dist/contract.d.ts.map +1 -1
  163. package/dist/contract.js +91 -255
  164. package/dist/contract.js.map +1 -1
  165. package/dist/cost-model.d.ts +13 -6
  166. package/dist/cost-model.d.ts.map +1 -1
  167. package/dist/cost-model.js +14 -4
  168. package/dist/cost-model.js.map +1 -1
  169. package/dist/cost.d.ts +10 -2
  170. package/dist/cost.d.ts.map +1 -1
  171. package/dist/cost.js +102 -104
  172. package/dist/cost.js.map +1 -1
  173. package/dist/custom-validation-prompt.d.ts.map +1 -1
  174. package/dist/custom-validation-prompt.js +6 -5
  175. package/dist/custom-validation-prompt.js.map +1 -1
  176. package/dist/custom-validation.d.ts +1 -2
  177. package/dist/custom-validation.d.ts.map +1 -1
  178. package/dist/custom-validation.js +9 -3
  179. package/dist/custom-validation.js.map +1 -1
  180. package/dist/deduplication/checkpointed-review.d.ts +4 -2
  181. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  182. package/dist/deduplication/checkpointed-review.js +23 -9
  183. package/dist/deduplication/checkpointed-review.js.map +1 -1
  184. package/dist/deduplication/codex-review.d.ts +8 -6
  185. package/dist/deduplication/codex-review.d.ts.map +1 -1
  186. package/dist/deduplication/codex-review.js +128 -19
  187. package/dist/deduplication/codex-review.js.map +1 -1
  188. package/dist/deduplication/deduplication-prompts.d.ts +5 -2
  189. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  190. package/dist/deduplication/deduplication-prompts.js +18 -4
  191. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  192. package/dist/deduplication/deduplication-reviewer.d.ts +27 -5
  193. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  194. package/dist/deduplication/deduplication-reviewer.js +58 -48
  195. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  196. package/dist/deduplication/deduplication.d.ts.map +1 -1
  197. package/dist/deduplication/deduplication.js +19 -51
  198. package/dist/deduplication/deduplication.js.map +1 -1
  199. package/dist/deduplication/diagnostics.d.ts +17 -0
  200. package/dist/deduplication/diagnostics.d.ts.map +1 -0
  201. package/dist/deduplication/diagnostics.js +5 -0
  202. package/dist/deduplication/diagnostics.js.map +1 -0
  203. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  204. package/dist/deduplication/finding-schema.js +7 -1
  205. package/dist/deduplication/finding-schema.js.map +1 -1
  206. package/dist/deduplication/local.d.ts +31 -0
  207. package/dist/deduplication/local.d.ts.map +1 -0
  208. package/dist/deduplication/local.js +166 -0
  209. package/dist/deduplication/local.js.map +1 -0
  210. package/dist/deduplication/records-protocol.d.ts +3 -8
  211. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  212. package/dist/deduplication/records-protocol.js +11 -184
  213. package/dist/deduplication/records-protocol.js.map +1 -1
  214. package/dist/deduplication/records.d.ts +186 -11
  215. package/dist/deduplication/records.d.ts.map +1 -1
  216. package/dist/deduplication/records.js +10 -18
  217. package/dist/deduplication/records.js.map +1 -1
  218. package/dist/deduplication/scan.d.ts +9 -3
  219. package/dist/deduplication/scan.d.ts.map +1 -1
  220. package/dist/deduplication/scan.js +158 -39
  221. package/dist/deduplication/scan.js.map +1 -1
  222. package/dist/deep-config.d.ts +2 -1
  223. package/dist/deep-config.d.ts.map +1 -1
  224. package/dist/deep-config.js +4 -4
  225. package/dist/deep-config.js.map +1 -1
  226. package/dist/deep-progress.d.ts +17 -1
  227. package/dist/deep-progress.d.ts.map +1 -1
  228. package/dist/deep-progress.js +19 -17
  229. package/dist/deep-progress.js.map +1 -1
  230. package/dist/deep-scan.d.ts +20 -0
  231. package/dist/deep-scan.d.ts.map +1 -0
  232. package/dist/deep-scan.js +113 -0
  233. package/dist/deep-scan.js.map +1 -0
  234. package/dist/errors.d.ts +2 -0
  235. package/dist/errors.d.ts.map +1 -1
  236. package/dist/errors.js +2 -0
  237. package/dist/errors.js.map +1 -1
  238. package/dist/executable-path.d.ts +2 -0
  239. package/dist/executable-path.d.ts.map +1 -0
  240. package/dist/executable-path.js +12 -0
  241. package/dist/executable-path.js.map +1 -0
  242. package/dist/feedback.d.ts +1 -4
  243. package/dist/feedback.d.ts.map +1 -1
  244. package/dist/feedback.js +54 -22
  245. package/dist/feedback.js.map +1 -1
  246. package/dist/finding-catalogue.d.ts.map +1 -1
  247. package/dist/finding-catalogue.js +4 -8
  248. package/dist/finding-catalogue.js.map +1 -1
  249. package/dist/finding-normalization.d.ts +5 -0
  250. package/dist/finding-normalization.d.ts.map +1 -0
  251. package/dist/finding-normalization.js +120 -0
  252. package/dist/finding-normalization.js.map +1 -0
  253. package/dist/finding-retrieval.d.ts +9 -0
  254. package/dist/finding-retrieval.d.ts.map +1 -1
  255. package/dist/finding-retrieval.js.map +1 -1
  256. package/dist/finding-workflow.d.ts +13 -8
  257. package/dist/finding-workflow.d.ts.map +1 -1
  258. package/dist/finding-workflow.js +14 -6
  259. package/dist/finding-workflow.js.map +1 -1
  260. package/dist/findings-client.d.ts +2 -1
  261. package/dist/findings-client.d.ts.map +1 -1
  262. package/dist/findings-client.js +36 -9
  263. package/dist/findings-client.js.map +1 -1
  264. package/dist/findings-errors.d.ts +16 -0
  265. package/dist/findings-errors.d.ts.map +1 -0
  266. package/dist/findings-errors.js +24 -0
  267. package/dist/findings-errors.js.map +1 -0
  268. package/dist/findings-import.d.ts +1 -1
  269. package/dist/findings-import.d.ts.map +1 -1
  270. package/dist/findings-import.js +12 -30
  271. package/dist/findings-import.js.map +1 -1
  272. package/dist/github.d.ts.map +1 -1
  273. package/dist/github.js +7 -1
  274. package/dist/github.js.map +1 -1
  275. package/dist/host-protocol.d.ts +19 -0
  276. package/dist/host-protocol.d.ts.map +1 -0
  277. package/dist/host-protocol.js +270 -0
  278. package/dist/host-protocol.js.map +1 -0
  279. package/dist/hosted-scan-protocol.d.ts +4 -0
  280. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  281. package/dist/hosted-scan-protocol.js +25 -0
  282. package/dist/hosted-scan-protocol.js.map +1 -0
  283. package/dist/hosted-scan.d.ts +117 -0
  284. package/dist/hosted-scan.d.ts.map +1 -0
  285. package/dist/hosted-scan.js +260 -0
  286. package/dist/hosted-scan.js.map +1 -0
  287. package/dist/import-scan.d.ts.map +1 -1
  288. package/dist/import-scan.js +48 -38
  289. package/dist/import-scan.js.map +1 -1
  290. package/dist/index.d.ts +11 -4
  291. package/dist/index.d.ts.map +1 -1
  292. package/dist/index.js +2 -1
  293. package/dist/index.js.map +1 -1
  294. package/dist/knowledge-base.d.ts +7 -1
  295. package/dist/knowledge-base.d.ts.map +1 -1
  296. package/dist/knowledge-base.js +114 -46
  297. package/dist/knowledge-base.js.map +1 -1
  298. package/dist/linear.d.ts.map +1 -1
  299. package/dist/linear.js +2 -7
  300. package/dist/linear.js.map +1 -1
  301. package/dist/mock-scan.d.ts.map +1 -1
  302. package/dist/mock-scan.js +0 -1
  303. package/dist/mock-scan.js.map +1 -1
  304. package/dist/models.d.ts +0 -2
  305. package/dist/models.d.ts.map +1 -1
  306. package/dist/models.js.map +1 -1
  307. package/dist/multiscan.d.ts +9 -3
  308. package/dist/multiscan.d.ts.map +1 -1
  309. package/dist/multiscan.js +240 -135
  310. package/dist/multiscan.js.map +1 -1
  311. package/dist/owner-evidence.d.ts +10 -2
  312. package/dist/owner-evidence.d.ts.map +1 -1
  313. package/dist/owner-evidence.js +67 -8
  314. package/dist/owner-evidence.js.map +1 -1
  315. package/dist/patch-tui.d.ts.map +1 -1
  316. package/dist/patch-tui.js +3 -2
  317. package/dist/patch-tui.js.map +1 -1
  318. package/dist/project-config.js +3 -3
  319. package/dist/project-config.js.map +1 -1
  320. package/dist/provider-profile.d.ts +21 -0
  321. package/dist/provider-profile.d.ts.map +1 -0
  322. package/dist/provider-profile.js +133 -0
  323. package/dist/provider-profile.js.map +1 -0
  324. package/dist/publication-events.d.ts +6 -8
  325. package/dist/publication-events.d.ts.map +1 -1
  326. package/dist/publication-events.js +25 -50
  327. package/dist/publication-events.js.map +1 -1
  328. package/dist/publication-store.d.ts.map +1 -1
  329. package/dist/publication-store.js +95 -109
  330. package/dist/publication-store.js.map +1 -1
  331. package/dist/publication.d.ts +1 -4
  332. package/dist/publication.d.ts.map +1 -1
  333. package/dist/publication.js +2 -13
  334. package/dist/publication.js.map +1 -1
  335. package/dist/publish.d.ts +1 -5
  336. package/dist/publish.d.ts.map +1 -1
  337. package/dist/publish.js +109 -160
  338. package/dist/publish.js.map +1 -1
  339. package/dist/request-metadata.d.ts +9 -0
  340. package/dist/request-metadata.d.ts.map +1 -0
  341. package/dist/request-metadata.js +13 -0
  342. package/dist/request-metadata.js.map +1 -0
  343. package/dist/runtime.d.ts +20 -6
  344. package/dist/runtime.d.ts.map +1 -1
  345. package/dist/runtime.js +407 -148
  346. package/dist/runtime.js.map +1 -1
  347. package/dist/saved-scan-bootstrap.d.ts +14 -0
  348. package/dist/saved-scan-bootstrap.d.ts.map +1 -0
  349. package/dist/saved-scan-bootstrap.js +261 -0
  350. package/dist/saved-scan-bootstrap.js.map +1 -0
  351. package/dist/saved-scan.d.ts +1 -1
  352. package/dist/saved-scan.d.ts.map +1 -1
  353. package/dist/saved-scan.js +6 -12
  354. package/dist/saved-scan.js.map +1 -1
  355. package/dist/scan-activity.js +11 -8
  356. package/dist/scan-activity.js.map +1 -1
  357. package/dist/scan-comparison.d.ts +28 -15
  358. package/dist/scan-comparison.d.ts.map +1 -1
  359. package/dist/scan-comparison.js +276 -281
  360. package/dist/scan-comparison.js.map +1 -1
  361. package/dist/scan-dashboard.d.ts +3 -0
  362. package/dist/scan-dashboard.d.ts.map +1 -1
  363. package/dist/scan-dashboard.js +345 -77
  364. package/dist/scan-dashboard.js.map +1 -1
  365. package/dist/scan-executor.d.ts +104 -0
  366. package/dist/scan-executor.d.ts.map +1 -0
  367. package/dist/scan-executor.js +62 -0
  368. package/dist/scan-executor.js.map +1 -0
  369. package/dist/scan-history-renderer.d.ts.map +1 -1
  370. package/dist/scan-history-renderer.js +54 -13
  371. package/dist/scan-history-renderer.js.map +1 -1
  372. package/dist/scan-inputs.d.ts +6 -0
  373. package/dist/scan-inputs.d.ts.map +1 -0
  374. package/dist/scan-inputs.js +71 -0
  375. package/dist/scan-inputs.js.map +1 -0
  376. package/dist/scan-logs.d.ts +2 -3
  377. package/dist/scan-logs.d.ts.map +1 -1
  378. package/dist/scan-logs.js +12 -6
  379. package/dist/scan-logs.js.map +1 -1
  380. package/dist/scan-sessions.d.ts +4 -0
  381. package/dist/scan-sessions.d.ts.map +1 -1
  382. package/dist/scan-sessions.js +17 -0
  383. package/dist/scan-sessions.js.map +1 -1
  384. package/dist/scan-skill-paths.d.ts +8 -0
  385. package/dist/scan-skill-paths.d.ts.map +1 -0
  386. package/dist/scan-skill-paths.js +47 -0
  387. package/dist/scan-skill-paths.js.map +1 -0
  388. package/dist/security-policy-cli.d.ts.map +1 -1
  389. package/dist/security-policy-cli.js +7 -27
  390. package/dist/security-policy-cli.js.map +1 -1
  391. package/dist/security-policy.d.ts +9 -5
  392. package/dist/security-policy.d.ts.map +1 -1
  393. package/dist/security-policy.js +33 -14
  394. package/dist/security-policy.js.map +1 -1
  395. package/dist/server/api.d.ts +0 -1
  396. package/dist/server/api.d.ts.map +1 -1
  397. package/dist/server/api.js +0 -1
  398. package/dist/server/api.js.map +1 -1
  399. package/dist/server/embeddings.d.ts +3 -1
  400. package/dist/server/embeddings.d.ts.map +1 -1
  401. package/dist/server/embeddings.js +10 -3
  402. package/dist/server/embeddings.js.map +1 -1
  403. package/dist/server/errors.d.ts +5 -2
  404. package/dist/server/errors.d.ts.map +1 -1
  405. package/dist/server/errors.js +7 -0
  406. package/dist/server/errors.js.map +1 -1
  407. package/dist/server/sqlite-store.d.ts +0 -2
  408. package/dist/server/sqlite-store.d.ts.map +1 -1
  409. package/dist/server/sqlite-store.js +54 -44
  410. package/dist/server/sqlite-store.js.map +1 -1
  411. package/dist/server/storage.d.ts +0 -2
  412. package/dist/server/storage.d.ts.map +1 -1
  413. package/dist/server/storage.js.map +1 -1
  414. package/dist/severity-store.js +19 -24
  415. package/dist/severity-store.js.map +1 -1
  416. package/dist/standalone-validation-prompt.d.ts +2 -0
  417. package/dist/standalone-validation-prompt.d.ts.map +1 -0
  418. package/dist/standalone-validation-prompt.js +10 -0
  419. package/dist/standalone-validation-prompt.js.map +1 -0
  420. package/dist/suggest-owners.d.ts +4 -2
  421. package/dist/suggest-owners.d.ts.map +1 -1
  422. package/dist/suggest-owners.js +11 -5
  423. package/dist/suggest-owners.js.map +1 -1
  424. package/dist/targets.d.ts +11 -0
  425. package/dist/targets.d.ts.map +1 -1
  426. package/dist/targets.js +123 -72
  427. package/dist/targets.js.map +1 -1
  428. package/dist/trusted-executable.d.ts +2 -2
  429. package/dist/trusted-executable.d.ts.map +1 -1
  430. package/dist/trusted-executable.js +8 -6
  431. package/dist/trusted-executable.js.map +1 -1
  432. package/dist/value.js +7 -0
  433. package/dist/value.js.map +1 -1
  434. package/dist/version.js.map +1 -1
  435. package/dist/workbench-arguments.d.ts +3 -0
  436. package/dist/workbench-arguments.d.ts.map +1 -0
  437. package/dist/workbench-arguments.js +15 -0
  438. package/dist/workbench-arguments.js.map +1 -0
  439. package/dist/worker-progress.d.ts +44 -11
  440. package/dist/worker-progress.d.ts.map +1 -1
  441. package/dist/worker-progress.js +48 -49
  442. package/dist/worker-progress.js.map +1 -1
  443. package/docs/cli.md +1788 -0
  444. package/docs/findings-service.md +402 -0
  445. package/docs/hosted-scans.md +242 -0
  446. package/package.json +23 -22
  447. package/schemas/hosted-scan-v2.fixture.json +145 -0
  448. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
  449. package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
  450. package/_bundled_plugin/scripts/workbench_findings.py +0 -221
  451. package/_bundled_plugin/scripts/workbench_severity.py +0 -122
  452. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
  453. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
  454. package/dist/server/dashboard/app.css +0 -2
  455. package/dist/server/dashboard/app.js +0 -66
  456. package/dist/server/dashboard/index.html +0 -18
  457. package/dist/server/dashboard-types.d.ts +0 -48
  458. package/dist/server/dashboard-types.d.ts.map +0 -1
  459. package/dist/server/dashboard-types.js +0 -2
  460. package/dist/server/dashboard-types.js.map +0 -1
  461. package/dist/server/dashboard.d.ts +0 -6
  462. package/dist/server/dashboard.d.ts.map +0 -1
  463. package/dist/server/dashboard.js +0 -59
  464. package/dist/server/dashboard.js.map +0 -1
  465. package/dist/server/index.d.ts +0 -2
  466. package/dist/server/index.d.ts.map +0 -1
  467. package/dist/server/index.js +0 -6
  468. package/dist/server/index.js.map +0 -1
  469. package/dist/server/routes.d.ts +0 -7
  470. package/dist/server/routes.d.ts.map +0 -1
  471. package/dist/server/routes.js +0 -98
  472. package/dist/server/routes.js.map +0 -1
  473. package/dist/server/serve.d.ts +0 -2
  474. package/dist/server/serve.d.ts.map +0 -1
  475. package/dist/server/serve.js +0 -28
  476. package/dist/server/serve.js.map +0 -1
  477. package/dist/server/server.d.ts +0 -10
  478. package/dist/server/server.d.ts.map +0 -1
  479. package/dist/server/server.js +0 -16
  480. package/dist/server/server.js.map +0 -1
  481. package/dist/server/validation.d.ts +0 -17
  482. package/dist/server/validation.d.ts.map +0 -1
  483. package/dist/server/validation.js +0 -53
  484. package/dist/server/validation.js.map +0 -1
@@ -8,7 +8,6 @@ import copy
8
8
  import csv
9
9
  import errno
10
10
  import hashlib
11
- import importlib.util
12
11
  import io
13
12
  import json
14
13
  import math
@@ -18,12 +17,16 @@ import secrets
18
17
  import stat
19
18
  import struct
20
19
  import sys
21
- import time
22
20
  from datetime import datetime, timezone
23
21
  from pathlib import Path, PurePosixPath
24
- from typing import Any, TextIO
22
+ from typing import Any, NamedTuple, TextIO
25
23
  from urllib.parse import quote, urlsplit
26
24
 
25
+ # Keep sibling helpers importable when Python starts in isolated mode.
26
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
27
+ import report_projection
28
+ import threat_model_projection
29
+
27
30
  SCHEMA_VERSION = "1.0"
28
31
  PRODUCER_NAME = "codex-security-plugin"
29
32
  FINGERPRINT_ALGORITHM = "codex-security/v1"
@@ -60,8 +63,10 @@ SARIF_SECURITY_SCORES = {
60
63
  }
61
64
  SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9._/-]*$")
62
65
  RFC3339_RE = re.compile(
63
- r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$"
66
+ r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.(?P<fraction>\d+))?(?:[Zz]|[+-]\d{2}:\d{2})$",
67
+ re.ASCII,
64
68
  )
69
+ REMOTE_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f-\x9f\u2028\u2029]")
65
70
  GITHUB_HASH_BLOCK_SIZE = 100
66
71
  GITHUB_HASH_MOD = 37
67
72
  GITHUB_HASH_MASK = (1 << 64) - 1
@@ -90,8 +95,16 @@ class ContractError(ValueError):
90
95
  """Raised when a completed scan does not satisfy the additive contract."""
91
96
 
92
97
 
98
+ class MissingScanLocalFileError(ContractError):
99
+ """Raised when a scan-local file or its containing directory is absent."""
100
+
101
+
93
102
  class RecoverableContractError(ContractError):
94
- """Raised when report projection can safely be retried before publication."""
103
+ """Raised when scan completion can safely be retried before publication."""
104
+
105
+
106
+ class SealedArtifactError(ContractError):
107
+ """Raised when an export would overwrite a sealed scan artifact."""
95
108
 
96
109
 
97
110
  def _reject_non_finite_json(value: str) -> None:
@@ -122,37 +135,10 @@ def _generate_report_projection(
122
135
  findings: dict[str, Any],
123
136
  coverage: dict[str, Any],
124
137
  ) -> bytes:
125
- script = Path(__file__).resolve().parent / "report_projection.py"
126
- spec = importlib.util.spec_from_file_location("codex_security_report_projection", script)
127
- if spec is None or spec.loader is None:
128
- raise ContractError(f"could not load report projection helper: {script}")
129
- module = importlib.util.module_from_spec(spec)
130
- spec.loader.exec_module(module)
131
- attempts = (
132
- getattr(sys.modules.get("workbench_constants"), "SQLITE_RETRY_ATTEMPTS", 1)
133
- if coverage.get("mode") == "deep_repository"
134
- else 1
135
- )
136
- for attempt in range(attempts):
137
- try:
138
- return module.generate_report_markdown(manifest, findings, coverage)
139
- except OSError as exc:
140
- if attempt == attempts - 1:
141
- raise RecoverableContractError(f"report projection failed: {exc}") from exc
142
- time.sleep(0.05 * (2**attempt))
143
- except ValueError as exc:
144
- raise ContractError(f"report projection failed: {exc}") from exc
145
- raise AssertionError("Report projection retry loop exhausted unexpectedly.")
146
-
147
-
148
- def _threat_model_renderer() -> Any:
149
- script = Path(__file__).resolve().with_name("threat_model_projection.py")
150
- spec = importlib.util.spec_from_file_location("codex_security_threat_model_projection", script)
151
- if spec is None or spec.loader is None:
152
- raise ContractError(f"could not load threat model projection helper: {script}")
153
- module = importlib.util.module_from_spec(spec)
154
- spec.loader.exec_module(module)
155
- return module
138
+ try:
139
+ return report_projection.generate_report_markdown(manifest, findings, coverage)
140
+ except ValueError as exc:
141
+ raise ContractError(f"report projection failed: {exc}") from exc
156
142
 
157
143
 
158
144
  def threat_model_provenance(manifest: dict[str, Any]) -> dict[str, Any]:
@@ -185,7 +171,7 @@ def threat_model_provenance(manifest: dict[str, Any]) -> dict[str, Any]:
185
171
 
186
172
  def _render_threat_model(model: dict[str, Any], provenance: dict[str, Any]) -> bytes:
187
173
  try:
188
- return _threat_model_renderer().render_threat_model(model, provenance)
174
+ return threat_model_projection.render_threat_model(model, provenance)
189
175
  except (TypeError, ValueError) as exc:
190
176
  raise ContractError(f"threat model projection failed: {exc}") from exc
191
177
 
@@ -429,7 +415,9 @@ def _require_str(payload: dict[str, Any], key: str, context: str) -> str:
429
415
  return value
430
416
 
431
417
 
432
- def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
418
+ def _require_safe_relative_path(value: object, context: str, *, allow_dot: bool = False) -> str:
419
+ if not isinstance(value, str) or not value:
420
+ raise ContractError(f"{context}: expected a safe repository-relative POSIX path")
433
421
  try:
434
422
  value.encode("utf-8")
435
423
  except UnicodeEncodeError as exc:
@@ -437,8 +425,7 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
437
425
  path = PurePosixPath(value)
438
426
  normalized = path.as_posix()
439
427
  if (
440
- not value.strip()
441
- or (normalized == "." and not allow_dot)
428
+ (normalized == "." and not allow_dot)
442
429
  or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
443
430
  or "\\" in value
444
431
  or "\0" in value
@@ -452,7 +439,7 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
452
439
 
453
440
  def _require_portable_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
454
441
  normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
455
- if any(_windows_unsafe_path_component(part) for part in value.split("/")):
442
+ if not value.strip() or any(_windows_unsafe_path_component(part) for part in value.split("/")):
456
443
  raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
457
444
  return normalized
458
445
 
@@ -507,22 +494,11 @@ def _descriptor_relative_writes_available() -> bool:
507
494
  )
508
495
 
509
496
 
510
- _WINDOWS_SCAN_LOCAL_FILES: Any | None = None
511
-
512
-
513
497
  def _windows_scan_local_files() -> Any:
514
498
  """Load the Win32 backend and shared stream comparison lazily."""
499
+ import windows_scan_local_files
515
500
 
516
- global _WINDOWS_SCAN_LOCAL_FILES
517
- if _WINDOWS_SCAN_LOCAL_FILES is None:
518
- script = Path(__file__).resolve().with_name("windows_scan_local_files.py")
519
- spec = importlib.util.spec_from_file_location("codex_security_windows_scan_files", script)
520
- if spec is None or spec.loader is None:
521
- raise ContractError(f"could not load Windows scan-local file helper: {script}")
522
- module = importlib.util.module_from_spec(spec)
523
- spec.loader.exec_module(module)
524
- _WINDOWS_SCAN_LOCAL_FILES = module
525
- return _WINDOWS_SCAN_LOCAL_FILES
501
+ return windows_scan_local_files
526
502
 
527
503
 
528
504
  def _open_verified_scan_directory(
@@ -575,6 +551,7 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
575
551
  try:
576
552
  os.mkdir(part, mode=0o700, dir_fd=descriptor)
577
553
  except FileExistsError:
554
+ # The open below verifies that an existing entry is a real directory.
578
555
  pass
579
556
  next_descriptor = os.open(
580
557
  part,
@@ -589,15 +566,23 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
589
566
  raise
590
567
 
591
568
 
592
- def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
593
- return _open_scan_local_file_with_path(scan_dir, relative_path, context)[0]
569
+ def open_scan_local_file_descriptor(
570
+ scan_dir: Path, relative_path: str, context: str, *, portable: bool = True
571
+ ) -> int:
572
+ return _open_scan_local_file_with_path(scan_dir, relative_path, context, portable=portable)[0]
594
573
 
595
574
 
596
575
  def _open_scan_local_file_with_path(
597
- scan_dir: Path, relative_path: str, context: str, *, resolve_spelling: bool = False
576
+ scan_dir: Path,
577
+ relative_path: str,
578
+ context: str,
579
+ *,
580
+ resolve_spelling: bool = False,
581
+ portable: bool = True,
598
582
  ) -> tuple[int, str]:
599
583
  scan_dir = _require_scan_directory(scan_dir)
600
- relative_path = _require_portable_relative_path(relative_path, context)
584
+ validate_path = _require_portable_relative_path if portable else _require_safe_relative_path
585
+ relative_path = validate_path(relative_path, context)
601
586
  if not (os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")):
602
587
  if not _is_windows():
603
588
  raise ContractError("scan-local input requires descriptor-relative file operations")
@@ -607,6 +592,9 @@ def _open_scan_local_file_with_path(
607
592
  return backend.open_read_fd_with_path(scan_dir, relative_path, context)
608
593
  return backend.open_read_fd(scan_dir, relative_path, context), relative_path
609
594
  except OSError as exc:
595
+ # The Windows backend retains native ERROR_FILE/PATH_NOT_FOUND codes.
596
+ if exc.errno in {2, 3}:
597
+ raise MissingScanLocalFileError(str(exc)) from exc
610
598
  raise ContractError(str(exc)) from exc
611
599
  root_fd: int | None = None
612
600
  parent_fd: int | None = None
@@ -622,6 +610,10 @@ def _open_scan_local_file_with_path(
622
610
  dir_fd=parent_fd,
623
611
  )
624
612
  except OSError as exc:
613
+ if exc.errno == errno.ENOENT:
614
+ raise MissingScanLocalFileError(
615
+ f"{context}: expected a file inside the scan directory"
616
+ ) from exc
625
617
  if exc.errno == errno.ELOOP:
626
618
  try:
627
619
  link_target = Path(os.readlink(parts[-1], dir_fd=parent_fd))
@@ -667,7 +659,13 @@ def _require_scan_local_file(scan_dir: Path, relative_path: str, context: str) -
667
659
  os.close(descriptor)
668
660
 
669
661
 
670
- def _require_derived_writeup_files(scan_dir: Path, findings: dict[str, Any]) -> None:
662
+ def _prepare_derived_writeups(
663
+ scan_dir: Path,
664
+ findings: dict[str, Any],
665
+ *,
666
+ allow_missing: bool = False,
667
+ ) -> list[str]:
668
+ warnings: list[str] = []
671
669
  for index, finding in enumerate(findings.get("findings", [])):
672
670
  if not isinstance(finding, dict):
673
671
  continue
@@ -676,11 +674,18 @@ def _require_derived_writeup_files(scan_dir: Path, findings: dict[str, Any]) ->
676
674
  continue
677
675
  report_path = writeup.get("reportPath")
678
676
  if isinstance(report_path, str):
679
- _require_scan_local_file(
680
- scan_dir,
681
- report_path,
682
- f"findings[{index}].writeup.reportPath",
683
- )
677
+ try:
678
+ _require_scan_local_file(
679
+ scan_dir,
680
+ report_path,
681
+ f"findings[{index}].writeup.reportPath",
682
+ )
683
+ except MissingScanLocalFileError as exc:
684
+ if not allow_missing:
685
+ raise
686
+ finding.pop("writeup")
687
+ warnings.append(f"Skipped missing writeup for finding {index + 1}: {exc}.")
688
+ return warnings
684
689
 
685
690
 
686
691
  def _require_hardening_portfolio_file(scan_dir: Path, scan: dict[str, Any]) -> None:
@@ -706,7 +711,7 @@ def _read_scan_local_json_with_metadata(
706
711
  raw = handle.read()
707
712
  metadata = os.fstat(handle.fileno())
708
713
  try:
709
- payload = _loads_json(raw.decode("utf-8"))
714
+ payload = _loads_json(raw.decode("utf-8-sig"))
710
715
  except (UnicodeDecodeError, ValueError) as exc:
711
716
  raise ContractError(f"{context}: invalid JSON: {exc}") from exc
712
717
  if not isinstance(payload, dict):
@@ -823,6 +828,7 @@ def write_scan_local_bytes(
823
828
  ):
824
829
  return
825
830
  except OSError:
831
+ # A failed content comparison still allows an atomic replacement.
826
832
  pass
827
833
  finally:
828
834
  if existing_fd >= 0:
@@ -843,6 +849,7 @@ def write_scan_local_bytes(
843
849
  try:
844
850
  os.unlink(temp_name, dir_fd=parent_fd)
845
851
  except FileNotFoundError:
852
+ # The temporary file is already gone, so cleanup is complete.
846
853
  pass
847
854
  if parent_fd is not None:
848
855
  os.close(parent_fd)
@@ -886,8 +893,10 @@ def _write_scan_local_json(scan_dir: Path, relative_path: str, payload: Any) ->
886
893
 
887
894
 
888
895
  def _validate_remote(remote: str, context: str) -> None:
896
+ if REMOTE_CONTROL_RE.search(remote):
897
+ raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
889
898
  parsed = urlsplit(remote)
890
- if not parsed.scheme or not parsed.netloc:
899
+ if "\\" in remote or not parsed.scheme or not parsed.netloc:
891
900
  raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
892
901
  if parsed.username or parsed.password or parsed.query or parsed.fragment:
893
902
  raise ContractError(
@@ -895,11 +904,19 @@ def _validate_remote(remote: str, context: str) -> None:
895
904
  )
896
905
 
897
906
 
907
+ def parse_timestamp(value: str) -> datetime:
908
+ match = RFC3339_RE.fullmatch(value)
909
+ if match and (fraction := match.group("fraction")):
910
+ start, end = match.span("fraction")
911
+ value = value[:start] + fraction[:6].ljust(6, "0") + value[end:]
912
+ return datetime.fromisoformat(value.upper().replace("Z", "+00:00"))
913
+
914
+
898
915
  def _validate_date_time(value: str, context: str) -> None:
899
916
  if not RFC3339_RE.fullmatch(value):
900
917
  raise ContractError(f"{context}: expected an RFC 3339 timestamp")
901
918
  try:
902
- parsed = datetime.fromisoformat(value[:-1] + "+00:00" if value[-1] in "Zz" else value)
919
+ parsed = parse_timestamp(value)
903
920
  except ValueError as exc:
904
921
  raise ContractError(f"{context}: expected an RFC 3339 timestamp") from exc
905
922
  if parsed.tzinfo is None:
@@ -945,7 +962,7 @@ def _stable_id(prefix: str, *parts: str) -> str:
945
962
 
946
963
 
947
964
  def _validate_location(location: dict[str, Any], context: str) -> None:
948
- _require_safe_relative_path(_require_str(location, "path", context), f"{context}.path")
965
+ _require_safe_relative_path(location.get("path"), f"{context}.path")
949
966
  start = location.get("startLine")
950
967
  end = location.get("endLine", start)
951
968
  if not isinstance(start, int) or start < 1:
@@ -1137,14 +1154,14 @@ def _recover_unsealed_findings(
1137
1154
  continue
1138
1155
  try:
1139
1156
  _validate_schema_node(
1140
- finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}"
1157
+ finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}", schema
1141
1158
  )
1142
1159
  except ContractError as exc:
1143
1160
  finding.pop(auxiliary)
1144
1161
  warnings.append(
1145
1162
  f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
1146
1163
  )
1147
- _validate_schema_node(finding, finding_schema, context)
1164
+ _validate_schema_node(finding, finding_schema, context, schema)
1148
1165
  except ContractError as exc:
1149
1166
  warning = f"Skipped malformed finding {index + 1}: {exc}."
1150
1167
  warnings.append(warning)
@@ -1203,19 +1220,12 @@ def _recover_unsealed_coverage(
1203
1220
  ) -> None:
1204
1221
  schema = _read_json(schema_dir / "coverage.schema.json")
1205
1222
  properties = _require_dict(schema, "properties", "coverage.schema")
1206
- completeness = coverage.get("completeness")
1207
- partial = completeness not in ("complete", "partial", "unknown")
1208
- if partial:
1209
- warnings.append("Recovered malformed coverage completeness; marked coverage as partial.")
1210
1223
  if (
1211
1224
  coverage.get("mode") == "deep_repository"
1212
1225
  and coverage.get("inventoryStrategy") != "repository"
1213
1226
  ):
1214
1227
  coverage["inventoryStrategy"] = "repository"
1215
- warnings.append(
1216
- "Recovered malformed Deep Scan inventory strategy; marked coverage as partial."
1217
- )
1218
- partial = True
1228
+ warnings.append("Recovered malformed Deep Scan inventory strategy.")
1219
1229
 
1220
1230
  surface_ids: set[str] = set()
1221
1231
  for field, label in (
@@ -1229,7 +1239,6 @@ def _recover_unsealed_coverage(
1229
1239
  if not isinstance(items, list):
1230
1240
  warnings.append(f"Skipped malformed {label} records: expected an array.")
1231
1241
  coverage[field] = []
1232
- partial = True
1233
1242
  continue
1234
1243
 
1235
1244
  recovered: list[dict[str, Any]] = []
@@ -1283,19 +1292,14 @@ def _recover_unsealed_coverage(
1283
1292
  recovered_receipts.append(normalized_ref)
1284
1293
 
1285
1294
  item["receiptRefs"] = recovered_receipts
1286
- if surface_recovered or item["disposition"] == "needs_follow_up":
1287
- if not surface_recovered and completeness != "partial":
1288
- warnings.append(
1289
- f"Coverage surface {index + 1} requires follow-up; "
1290
- "marked coverage as partial."
1291
- )
1295
+ if surface_recovered:
1292
1296
  item["disposition"] = "needs_follow_up"
1293
- partial = True
1294
1297
 
1298
+ if field == "deferred":
1299
+ _validate_deferred_paths(item, context)
1295
1300
  _validate_schema_node(item, item_schema, context)
1296
1301
  except ContractError as exc:
1297
1302
  warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
1298
- partial = True
1299
1303
  continue
1300
1304
 
1301
1305
  if field == "surfaces":
@@ -1311,7 +1315,6 @@ def _recover_unsealed_coverage(
1311
1315
  {"id": f"discarded-finding-{index}", "reason": warning}
1312
1316
  for index, warning in enumerate(discarded_findings, 1)
1313
1317
  )
1314
- partial = True
1315
1318
 
1316
1319
  if "resolvedDeferred" in coverage:
1317
1320
  try:
@@ -1324,14 +1327,6 @@ def _recover_unsealed_coverage(
1324
1327
  except ContractError as exc:
1325
1328
  coverage.pop("resolvedDeferred")
1326
1329
  warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
1327
- partial = True
1328
-
1329
- if coverage["deferred"] and completeness != "partial":
1330
- if not discarded_findings:
1331
- warnings.append("Coverage has deferred review work; marked coverage as partial.")
1332
- partial = True
1333
- if partial:
1334
- coverage["completeness"] = "partial"
1335
1330
 
1336
1331
 
1337
1332
  def _recover_unsealed_hardening(
@@ -1489,17 +1484,6 @@ def _normalize_unsealed_open_questions(coverage: dict[str, Any]) -> None:
1489
1484
  coverage["openQuestions"] = normalized
1490
1485
 
1491
1486
 
1492
- def _normalize_unsealed_deep_repository_inventory_strategy(
1493
- coverage: dict[str, Any],
1494
- *,
1495
- expected_coverage_mode: str | None,
1496
- ) -> None:
1497
- """Label whole-repository Deep scans as using the repository inventory."""
1498
-
1499
- if expected_coverage_mode == "deep_repository":
1500
- coverage["inventoryStrategy"] = "repository"
1501
-
1502
-
1503
1487
  def _validate_completion_binding(
1504
1488
  manifest: dict[str, Any],
1505
1489
  findings: dict[str, Any],
@@ -1543,6 +1527,14 @@ def _validate_completion_binding(
1543
1527
  raise ContractError(f"coverage.{key}: must match the workbench scan")
1544
1528
 
1545
1529
 
1530
+ def path_within_scope(path: str, scope: str) -> bool:
1531
+ candidate = PurePosixPath(path)
1532
+ requested = PurePosixPath(scope)
1533
+ if candidate.is_absolute() or ".." in candidate.parts:
1534
+ return False
1535
+ return candidate.is_relative_to(requested)
1536
+
1537
+
1546
1538
  def _validate_finding(finding: dict[str, Any], context: str) -> None:
1547
1539
  for key in ("findingId", "occurrenceId", "ruleId", "title", "summary", "remediation"):
1548
1540
  _require_str(finding, key, context)
@@ -1600,6 +1592,11 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1600
1592
  raise ContractError(f"{evidence_context}.id: duplicate code-evidence id")
1601
1593
  evidence_ids.add(evidence_id)
1602
1594
  _require_str(evidence, "code", evidence_context)
1595
+ if evidence_key == "codeEvidence":
1596
+ _require_safe_relative_path(
1597
+ evidence.get("path"),
1598
+ f"{evidence_context}.path",
1599
+ )
1603
1600
 
1604
1601
  referenced_sections = [
1605
1602
  (section_name, finding.get(section_name))
@@ -1660,13 +1657,21 @@ def _validate_resolved_deferred(coverage: dict[str, Any]) -> None:
1660
1657
  resolved.add(closure_id)
1661
1658
 
1662
1659
 
1660
+ def _validate_deferred_paths(deferred: dict[str, Any], context: str) -> None:
1661
+ if "paths" not in deferred:
1662
+ return
1663
+ for index, path in enumerate(_require_list(deferred, "paths", context)):
1664
+ if not isinstance(path, str):
1665
+ raise ContractError(f"{context}.paths[{index}]: expected a string")
1666
+ _require_safe_relative_path(path, f"{context}.paths[{index}]", allow_dot=True)
1667
+
1668
+
1663
1669
  def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_dir: Path) -> None:
1664
1670
  scan = _require_dict(manifest, "scan", "manifest")
1665
1671
  scan_id = _require_str(scan, "id", "manifest.scan")
1666
1672
  if coverage.get("scanId") != scan_id:
1667
1673
  raise ContractError("coverage.scanId: must match manifest scan id")
1668
1674
  _require_str(coverage, "mode", "coverage")
1669
- completeness = _require_str(coverage, "completeness", "coverage")
1670
1675
  _require_str(coverage, "inventoryStrategy", "coverage")
1671
1676
  scope = _require_dict(scan, "scope", "manifest.scan")
1672
1677
  if coverage.get("includePaths") != scope.get("includePaths"):
@@ -1674,7 +1679,6 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1674
1679
  if coverage.get("excludePaths") != scope.get("excludePaths"):
1675
1680
  raise ContractError("coverage.excludePaths: must match manifest scope")
1676
1681
  surface_ids: set[str] = set()
1677
- has_needs_follow_up = False
1678
1682
  for index, surface in enumerate(_require_list(coverage, "surfaces", "coverage")):
1679
1683
  context = f"coverage.surfaces[{index}]"
1680
1684
  if not isinstance(surface, dict):
@@ -1687,7 +1691,6 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1687
1691
  disposition = _require_str(surface, "disposition", context)
1688
1692
  if disposition not in DISPOSITIONS:
1689
1693
  raise ContractError(f"{context}.disposition: unsupported disposition: {disposition}")
1690
- has_needs_follow_up = has_needs_follow_up or disposition == "needs_follow_up"
1691
1694
  receipt_refs = surface.get("receiptRefs", [])
1692
1695
  if not isinstance(receipt_refs, list):
1693
1696
  raise ContractError(f"{context}.receiptRefs: expected an array")
@@ -1708,9 +1711,10 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1708
1711
  for field in ("explicitExclusions", "deferred"):
1709
1712
  if not isinstance(coverage.get(field, []), list):
1710
1713
  raise ContractError(f"coverage.{field}: expected an array")
1714
+ for index, deferred in enumerate(coverage.get("deferred", [])):
1715
+ if isinstance(deferred, dict):
1716
+ _validate_deferred_paths(deferred, f"coverage.deferred[{index}]")
1711
1717
  _validate_resolved_deferred(coverage)
1712
- if completeness == "complete" and (has_needs_follow_up or coverage.get("deferred")):
1713
- raise ContractError("coverage.completeness: complete coverage cannot have deferred work")
1714
1718
  _require_safe_json_value(coverage, "coverage.json")
1715
1719
 
1716
1720
 
@@ -1789,16 +1793,22 @@ def _validate_findings(manifest: dict[str, Any], findings: dict[str, Any]) -> No
1789
1793
  _require_safe_json_value(findings, "findings.json")
1790
1794
 
1791
1795
 
1796
+ _SCHEMA_TYPES = {
1797
+ "array": list,
1798
+ "boolean": bool,
1799
+ "integer": int,
1800
+ "number": (int, float),
1801
+ "object": dict,
1802
+ "string": str,
1803
+ }
1804
+
1805
+
1792
1806
  def _schema_type_matches(value: Any, expected: str) -> bool:
1793
- return {
1794
- "array": isinstance(value, list),
1795
- "boolean": isinstance(value, bool),
1796
- "integer": isinstance(value, int) and not isinstance(value, bool),
1797
- "number": isinstance(value, (int, float)) and not isinstance(value, bool),
1798
- "object": isinstance(value, dict),
1799
- "string": isinstance(value, str),
1800
- "null": value is None,
1801
- }[expected]
1807
+ if expected == "null":
1808
+ return value is None
1809
+ return isinstance(value, _SCHEMA_TYPES[expected]) and (
1810
+ expected not in ("integer", "number") or not isinstance(value, bool)
1811
+ )
1802
1812
 
1803
1813
 
1804
1814
  def _schema_values_equal(left: Any, right: Any) -> bool:
@@ -1869,6 +1879,8 @@ def _validate_schema_node(
1869
1879
  context,
1870
1880
  root_schema,
1871
1881
  )
1882
+ if len(schema) == 1:
1883
+ return
1872
1884
  expected = schema.get("type")
1873
1885
  if isinstance(expected, list):
1874
1886
  if not any(_schema_type_matches(value, item) for item in expected):
@@ -1884,7 +1896,9 @@ def _validate_schema_node(
1884
1896
  if isinstance(value, str):
1885
1897
  if schema.get("minLength", 0) and len(value) < schema["minLength"]:
1886
1898
  raise ContractError(f"{context}: string is too short")
1887
- if "pattern" in schema and not re.fullmatch(schema["pattern"], value):
1899
+ if "maxLength" in schema and len(value) > schema["maxLength"]:
1900
+ raise ContractError(f"{context}: string is too long")
1901
+ if "pattern" in schema and not re.search(schema["pattern"], value):
1888
1902
  raise ContractError(f"{context}: string does not match schema pattern")
1889
1903
  if schema.get("format") == "date-time":
1890
1904
  _validate_date_time(value, context)
@@ -1942,6 +1956,8 @@ def _validate_schema_node(
1942
1956
  additional_properties = schema.get("additionalProperties", True)
1943
1957
  for key, item in value.items():
1944
1958
  item_schema = properties.get(key)
1959
+ if item_schema is False:
1960
+ raise ContractError(f"{context}.{key}: unexpected schema property")
1945
1961
  if isinstance(item_schema, dict):
1946
1962
  _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
1947
1963
  elif additional_properties is False:
@@ -1960,6 +1976,38 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1960
1976
  _validate_schema_node(payload, schema, schema_path.stem, schema)
1961
1977
 
1962
1978
 
1979
+ def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> None:
1980
+ """Use the model's current finding contract for new completed results."""
1981
+
1982
+ draft = _read_json(schema_dir / "tools" / "scan-draft.schema.json")
1983
+ common = _read_json(schema_dir / "definitions" / "artifact-common.schema.json")
1984
+ documents = {document["$id"]: document for document in (draft, common)}
1985
+
1986
+ def resolve(node: Any) -> Any:
1987
+ if isinstance(node, list):
1988
+ return [resolve(item) for item in node]
1989
+ if not isinstance(node, dict):
1990
+ return node
1991
+ resolved = {key: resolve(value) for key, value in node.items() if key != "$ref"}
1992
+ if "$ref" in node:
1993
+ document_id, fragment = node["$ref"].split("#", 1)
1994
+ referenced = _resolve_schema_reference(
1995
+ documents[document_id], f"#{fragment}", "finding schema"
1996
+ )
1997
+ resolved = {**resolve(referenced), **resolved}
1998
+ return resolved
1999
+
2000
+ finding_schema = resolve(draft["$defs"]["finding"])
2001
+ for index, finding in enumerate(findings["findings"]):
2002
+ # These fields belong to the host, not the authored finding contract.
2003
+ authored = {
2004
+ key: value
2005
+ for key, value in finding.items()
2006
+ if key not in {"findingId", "occurrenceId", "fingerprints"}
2007
+ }
2008
+ _validate_schema_node(authored, finding_schema, f"findings.findings[{index}]")
2009
+
2010
+
1963
2011
  def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
1964
2012
  for refs_field in ("evidenceRefs", "evidence_refs"):
1965
2013
  refs = section.get(refs_field)
@@ -2085,29 +2133,20 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
2085
2133
  continue
2086
2134
  _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
2087
2135
  for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
2088
- if field not in attack_path:
2089
- continue
2090
2136
  detail = attack_path.get(field)
2091
- if detail is None:
2092
- attack_path.pop(field)
2093
- continue
2094
- if not isinstance(detail, (str, dict)):
2095
- attack_path.pop(field)
2096
- continue
2097
- if isinstance(detail, str):
2098
- if detail == "":
2099
- attack_path.pop(field)
2100
- continue
2101
- detail_scalar_fields = ("summary", "source", "sink", "outcome")
2102
- if field == "reachability":
2103
- detail_scalar_fields += ("attacker", "entrypoint")
2104
- _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
2105
- _normalize_legacy_string_list_fields(
2106
- detail, ("evidenceRefs", "evidence_refs", "transformations")
2107
- )
2108
- _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
2109
- if field == "reachability":
2110
- _normalize_legacy_string_list_fields(detail, ("preconditions",))
2137
+ if isinstance(detail, dict):
2138
+ detail_scalar_fields = ("summary", "source", "sink", "outcome")
2139
+ if field == "reachability":
2140
+ detail_scalar_fields += ("attacker", "entrypoint")
2141
+ _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
2142
+ _normalize_legacy_string_list_fields(
2143
+ detail, ("evidenceRefs", "evidence_refs", "transformations")
2144
+ )
2145
+ _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
2146
+ if field == "reachability":
2147
+ _normalize_legacy_string_list_fields(detail, ("preconditions",))
2148
+ elif not isinstance(detail, str) or detail == "":
2149
+ attack_path.pop(field, None)
2111
2150
  for field in ("impact", "likelihood"):
2112
2151
  detail = attack_path.get(field)
2113
2152
  if isinstance(detail, dict):
@@ -2271,7 +2310,7 @@ def _open_source_file(source_root: Path, relative_path: str) -> TextIO | None:
2271
2310
  file_fd: int | None = None
2272
2311
  try:
2273
2312
  file_fd = open_scan_local_file_descriptor(
2274
- source_root, relative_path, f"source file {relative_path}"
2313
+ source_root, relative_path, f"source file {relative_path}", portable=False
2275
2314
  )
2276
2315
  handle = os.fdopen(file_fd, "r", encoding="utf-8", errors="replace")
2277
2316
  file_fd = None
@@ -2456,7 +2495,7 @@ def _github_line_hash_cache(
2456
2495
  return line_hash_cache
2457
2496
 
2458
2497
 
2459
- def _sarif_location(location: dict[str, Any], location_id: int | None = None) -> dict[str, Any]:
2498
+ def _sarif_location(location: dict[str, Any]) -> dict[str, Any]:
2460
2499
  sarif_location: dict[str, Any] = {
2461
2500
  "physicalLocation": {
2462
2501
  "artifactLocation": {
@@ -2468,8 +2507,6 @@ def _sarif_location(location: dict[str, Any], location_id: int | None = None) ->
2468
2507
  },
2469
2508
  }
2470
2509
  }
2471
- if location_id is not None:
2472
- sarif_location["id"] = location_id
2473
2510
  if location.get("role"):
2474
2511
  sarif_location["message"] = {"text": location["role"]}
2475
2512
  return sarif_location
@@ -2498,7 +2535,7 @@ def _sarif_result(
2498
2535
  line_hash = _github_primary_location_line_hash(finding, source_root, line_hash_cache)
2499
2536
  if line_hash is not None:
2500
2537
  partial_fingerprints["primaryLocationLineHash"] = line_hash
2501
- result = {
2538
+ return {
2502
2539
  "ruleId": finding["ruleId"],
2503
2540
  "ruleIndex": rule_index,
2504
2541
  "level": SARIF_LEVELS[finding["severity"]["level"]],
@@ -2507,7 +2544,6 @@ def _sarif_result(
2507
2544
  "partialFingerprints": partial_fingerprints,
2508
2545
  "properties": properties,
2509
2546
  }
2510
- return result
2511
2547
 
2512
2548
 
2513
2549
  def build_sarif(
@@ -2573,9 +2609,23 @@ def _artifact_record(
2573
2609
  }
2574
2610
 
2575
2611
 
2576
- def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
2577
- refs = {ref for surface in coverage["surfaces"] for ref in surface.get("receiptRefs", [])}
2578
- return sorted(refs)
2612
+ def _supplementary_artifact_refs(scan: dict[str, Any], coverage: dict[str, Any]) -> dict[str, str]:
2613
+ refs = {
2614
+ ref: "coverage receipt"
2615
+ for surface in coverage["surfaces"]
2616
+ for ref in surface.get("receiptRefs", [])
2617
+ }
2618
+ extensions = scan.get("extensions")
2619
+ imported = extensions.get("import") if isinstance(extensions, dict) else None
2620
+ if isinstance(imported, dict) and "sourceRef" in imported:
2621
+ context = "manifest.scan.extensions.import"
2622
+ ref = _require_portable_relative_path(
2623
+ _require_str(imported, "sourceRef", context), f"{context}.sourceRef"
2624
+ )
2625
+ if not ref.startswith("artifacts/"):
2626
+ raise ContractError(f"{context}.sourceRef: expected a file under artifacts/")
2627
+ refs.setdefault(ref, "import source")
2628
+ return {ref: refs[ref] for ref in sorted(refs)}
2579
2629
 
2580
2630
 
2581
2631
  def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
@@ -2583,9 +2633,9 @@ def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str,
2583
2633
  _require_portable_relative_path(artifact["path"], "sealed artifact path")
2584
2634
  for artifact in scan["artifacts"]
2585
2635
  }
2586
- for ref in _coverage_receipt_refs(coverage):
2636
+ for ref, context in _supplementary_artifact_refs(scan, coverage).items():
2587
2637
  if ref not in artifact_paths:
2588
- raise ContractError(f"coverage receipt is missing from sealed artifacts: {ref}")
2638
+ raise ContractError(f"{context} is missing from sealed artifacts: {ref}")
2589
2639
 
2590
2640
 
2591
2641
  def _validate_existing_seal(
@@ -2625,16 +2675,9 @@ def _validate_existing_seal(
2625
2675
  raise ContractError(f"{context}: sealed artifact changed or is missing")
2626
2676
 
2627
2677
 
2628
- def _read_sealed_scan(
2629
- scan_dir: Path, schema_dir: Path | None, required_for: str
2630
- ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], bytes]:
2631
- scan_dir = _require_scan_directory(scan_dir)
2632
- schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2633
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2634
- scan = _require_dict(manifest, "scan", "manifest")
2635
- _validate_contract_refs(scan)
2636
- if scan.get("sealedAt") is None or scan.get("artifacts") is None:
2637
- raise ContractError(f"manifest.scan: {required_for} requires a sealed scan")
2678
+ def _read_sealed_artifacts(
2679
+ scan_dir: Path, scan: dict[str, Any]
2680
+ ) -> tuple[dict[str, Any], dict[str, Any], bytes]:
2638
2681
  findings, findings_bytes = _read_scan_local_json_bytes(
2639
2682
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2640
2683
  )
@@ -2649,6 +2692,20 @@ def _read_sealed_scan(
2649
2692
  scan["coverageRef"]: coverage_bytes,
2650
2693
  },
2651
2694
  )
2695
+ return findings, coverage, findings_bytes
2696
+
2697
+
2698
+ def _read_sealed_scan(
2699
+ scan_dir: Path, schema_dir: Path | None, required_for: str
2700
+ ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], bytes]:
2701
+ scan_dir = _require_scan_directory(scan_dir)
2702
+ schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2703
+ manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2704
+ scan = _require_dict(manifest, "scan", "manifest")
2705
+ _validate_contract_refs(scan)
2706
+ if scan.get("sealedAt") is None or scan.get("artifacts") is None:
2707
+ raise ContractError(f"manifest.scan: {required_for} requires a sealed scan")
2708
+ findings, coverage, findings_bytes = _read_sealed_artifacts(scan_dir, scan)
2652
2709
  _validate_manifest(manifest)
2653
2710
  findings_for_validation = _legacy_sealed_findings_for_validation(findings)
2654
2711
  _validate_findings(manifest, findings_for_validation)
@@ -2675,9 +2732,8 @@ def build_sarif_projection(
2675
2732
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2676
2733
  sarif = build_sarif(manifest, findings, source_root)
2677
2734
  execution_successful = manifest["scan"]["status"] == "completed"
2678
- if not execution_successful or coverage["completeness"] != "complete":
2735
+ if not execution_successful or coverage["deferred"]:
2679
2736
  run = sarif["runs"][0]
2680
- run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2681
2737
  run["invocations"] = [
2682
2738
  {
2683
2739
  "executionSuccessful": execution_successful,
@@ -2749,25 +2805,10 @@ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2749
2805
  def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
2750
2806
  output = io.StringIO(newline="")
2751
2807
  writer = csv.writer(output)
2752
- deep_scan = coverage.get("mode") == "deep_repository" or (
2753
- coverage.get("mode") == "scoped_path"
2754
- and any(
2755
- isinstance(finding.get("extensions"), dict)
2756
- and any(
2757
- isinstance(finding["extensions"].get(field), str)
2758
- and finding["extensions"][field].strip()
2759
- for field in ("candidateId", "reportId")
2760
- )
2761
- for finding in findings["findings"]
2762
- )
2763
- )
2808
+ deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
2764
2809
  writer.writerow(finding_csv_columns(deep_scan))
2765
2810
  for finding in findings["findings"]:
2766
- locations = finding["locations"]
2767
- location = next(
2768
- (candidate for candidate in locations if candidate.get("role") == "root_control"),
2769
- locations[0],
2770
- )
2811
+ location = _sarif_primary_location(finding)
2771
2812
  writer.writerow(
2772
2813
  (
2773
2814
  csv_cell(finding["occurrenceId"]),
@@ -2867,7 +2908,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2867
2908
  raise ContractError(f"{relative_output}: unable to inspect export output") from exc
2868
2909
  for artifact_path in artifact_paths:
2869
2910
  if artifact_path == relative_output:
2870
- raise ContractError(
2911
+ raise SealedArtifactError(
2871
2912
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2872
2913
  )
2873
2914
  if output_metadata is None:
@@ -2880,7 +2921,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2880
2921
  finally:
2881
2922
  os.close(descriptor)
2882
2923
  if os.path.samestat(output_metadata, artifact_metadata):
2883
- raise ContractError(
2924
+ raise SealedArtifactError(
2884
2925
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2885
2926
  )
2886
2927
  write_scan_local_bytes(
@@ -2901,15 +2942,15 @@ def _write_sarif_projection_if_possible(
2901
2942
  )
2902
2943
 
2903
2944
 
2904
- PreparedScanFinalization = tuple[
2905
- Path,
2906
- Path,
2907
- dict[str, Any],
2908
- dict[str, Any],
2909
- dict[str, Any],
2910
- bool,
2911
- bytes,
2912
- ]
2945
+ class PreparedScanFinalization(NamedTuple):
2946
+ scan_dir: Path
2947
+ schema_dir: Path
2948
+ manifest: dict[str, Any]
2949
+ findings: dict[str, Any]
2950
+ coverage: dict[str, Any]
2951
+ was_sealed: bool
2952
+ report_markdown_bytes: bytes
2953
+ warnings: list[str]
2913
2954
 
2914
2955
 
2915
2956
  def _prepare_scan_finalization(
@@ -2918,11 +2959,14 @@ def _prepare_scan_finalization(
2918
2959
  *,
2919
2960
  expected_coverage_mode: str | None = None,
2920
2961
  completion_binding: dict[str, Any] | None = None,
2921
- completion_warnings: list[str] | None = None,
2962
+ recover_unsealed: bool = False,
2963
+ allow_missing_writeups: bool = False,
2922
2964
  draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
2965
+ finding_scope: list[tuple[str, bool]] | None = None,
2923
2966
  ) -> PreparedScanFinalization:
2924
- """Read, populate, and validate a scan without writing any output files."""
2967
+ """Prepare validated documents and warnings without writing any output files."""
2925
2968
 
2969
+ warnings: list[str] = []
2926
2970
  scan_dir = _require_scan_directory(scan_dir)
2927
2971
  schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2928
2972
  manifest = (
@@ -2948,11 +2992,12 @@ def _prepare_scan_finalization(
2948
2992
  findings, coverage = copy.deepcopy(draft_documents[1:])
2949
2993
  findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
2950
2994
  if not was_sealed:
2995
+ # Preserve legacy sealed bundles, but do not publish a completeness claim.
2996
+ coverage.pop("completeness", None)
2951
2997
  _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
2952
- _normalize_unsealed_deep_repository_inventory_strategy(
2953
- coverage,
2954
- expected_coverage_mode=expected_coverage_mode,
2955
- )
2998
+ # Label whole-repository Deep scans as using the repository inventory.
2999
+ if expected_coverage_mode == "deep_repository":
3000
+ coverage["inventoryStrategy"] = "repository"
2956
3001
  _normalize_unsealed_open_questions(coverage)
2957
3002
 
2958
3003
  if manifest.get("schemaVersion") != SCHEMA_VERSION:
@@ -2983,25 +3028,70 @@ def _prepare_scan_finalization(
2983
3028
  findings_for_validation = (
2984
3029
  _legacy_sealed_findings_for_validation(findings) if was_sealed else findings
2985
3030
  )
2986
- if not was_sealed and completion_warnings is not None:
3031
+ discarded_findings: list[str] = []
3032
+ if not was_sealed and scan["status"] == "completed":
3033
+ try:
3034
+ _populate_unsealed_finding_identities(manifest, findings)
3035
+ _validate_findings(manifest, findings)
3036
+ _validate_current_findings(findings, schema_dir)
3037
+ except ContractError as exc:
3038
+ raise RecoverableContractError(
3039
+ "Scan result contains invalid findings; repair the finding records "
3040
+ f"before completion. {exc}"
3041
+ ) from exc
3042
+ elif not was_sealed and recover_unsealed:
2987
3043
  discarded_findings = _recover_unsealed_findings(
2988
- manifest, findings, schema_dir, scan_dir, completion_warnings
3044
+ manifest, findings, schema_dir, scan_dir, warnings
2989
3045
  )
2990
- _recover_unsealed_coverage(
2991
- coverage, schema_dir, scan_dir, completion_warnings, discarded_findings
2992
- )
2993
- _recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
2994
3046
  elif not was_sealed:
2995
3047
  _populate_unsealed_finding_identities(manifest, findings)
2996
- _validate_findings(manifest, findings_for_validation)
3048
+ if not was_sealed and recover_unsealed:
3049
+ _recover_unsealed_coverage(coverage, schema_dir, scan_dir, warnings, discarded_findings)
3050
+ _recover_unsealed_hardening(manifest, scan_dir, warnings)
3051
+ if was_sealed or scan["status"] != "completed":
3052
+ _validate_findings(manifest, findings_for_validation)
2997
3053
  if was_sealed:
2998
3054
  _validate_derived_finding_identities(manifest, findings)
2999
3055
  _validate_coverage(manifest, coverage, scan_dir)
3000
3056
  _validate_canonical_schemas_before_projection(
3001
3057
  manifest, findings_for_validation, coverage, schema_dir
3002
3058
  )
3003
- _require_derived_writeup_files(scan_dir, findings)
3004
3059
  _require_hardening_portfolio_file(scan_dir, scan)
3060
+ if finding_scope is not None:
3061
+ # Accepted worker/reducer files remain immutable; only the new parent
3062
+ # projection is scoped, after the existing validation of every finding.
3063
+ scoped_findings = []
3064
+ excluded_findings = []
3065
+ for finding in findings["findings"]:
3066
+ in_scope = any(
3067
+ PurePosixPath(location["path"]) == PurePosixPath(path)
3068
+ if is_file
3069
+ else path_within_scope(location["path"], path)
3070
+ for location in finding["locations"]
3071
+ for path, is_file in finding_scope
3072
+ )
3073
+ (scoped_findings if in_scope else excluded_findings).append(finding)
3074
+ if was_sealed and len(scoped_findings) != len(findings["findings"]):
3075
+ raise ContractError(
3076
+ "The sealed Deep scan contains findings outside its requested paths; "
3077
+ "start a new scan to produce scoped results."
3078
+ )
3079
+ if not was_sealed:
3080
+ # Excluded findings still require safe writeups, but missing optional
3081
+ # links should only produce warnings for findings in the final report.
3082
+ _prepare_derived_writeups(
3083
+ scan_dir,
3084
+ {"findings": excluded_findings},
3085
+ allow_missing=allow_missing_writeups,
3086
+ )
3087
+ findings["findings"] = scoped_findings
3088
+ warnings.extend(
3089
+ _prepare_derived_writeups(
3090
+ scan_dir,
3091
+ findings,
3092
+ allow_missing=allow_missing_writeups and not was_sealed,
3093
+ )
3094
+ )
3005
3095
  if was_sealed:
3006
3096
  _validate_sealed_coverage_receipts(scan, coverage)
3007
3097
  _validate_manifest(manifest)
@@ -3018,20 +3108,21 @@ def _prepare_scan_finalization(
3018
3108
  _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
3019
3109
  *[
3020
3110
  _artifact_record(scan_dir, ref, "application/octet-stream")
3021
- for ref in _coverage_receipt_refs(coverage)
3111
+ for ref in _supplementary_artifact_refs(scan, coverage)
3022
3112
  ],
3023
3113
  ]
3024
3114
  _validate_manifest(manifest)
3025
3115
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
3026
3116
  _contract_json_bytes("scan-manifest.json", manifest)
3027
- return (
3028
- scan_dir,
3029
- schema_dir,
3030
- manifest,
3031
- findings,
3032
- coverage,
3033
- was_sealed,
3034
- report_markdown_bytes,
3117
+ return PreparedScanFinalization(
3118
+ scan_dir=scan_dir,
3119
+ schema_dir=schema_dir,
3120
+ manifest=manifest,
3121
+ findings=findings,
3122
+ coverage=coverage,
3123
+ was_sealed=was_sealed,
3124
+ report_markdown_bytes=report_markdown_bytes,
3125
+ warnings=warnings,
3035
3126
  )
3036
3127
 
3037
3128
 
@@ -3043,33 +3134,25 @@ def _write_prepared_scan_finalization(
3043
3134
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
3044
3135
  """Write a previously validated scan finalization result."""
3045
3136
 
3046
- (
3047
- scan_dir,
3048
- schema_dir,
3049
- manifest,
3050
- findings,
3051
- coverage,
3052
- was_sealed,
3053
- report_markdown_bytes,
3054
- ) = prepared
3055
- scan = _require_dict(manifest, "scan", "manifest")
3056
- if not was_sealed:
3057
- _write_scan_local_json(scan_dir, "findings.json", findings)
3058
- _write_scan_local_json(scan_dir, "coverage.json", coverage)
3059
- write_scan_local_bytes(scan_dir, "report.md", report_markdown_bytes)
3137
+ scan_dir = prepared.scan_dir
3138
+ scan = _require_dict(prepared.manifest, "scan", "manifest")
3139
+ if not prepared.was_sealed:
3140
+ _write_scan_local_json(scan_dir, "findings.json", prepared.findings)
3141
+ _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
3142
+ write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
3060
3143
  _remove_scan_local_file_if_exists(scan_dir, "report.html")
3061
- if not was_sealed:
3062
- _write_scan_local_json(scan_dir, "scan-manifest.json", manifest)
3144
+ if not prepared.was_sealed:
3145
+ _write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
3063
3146
  _validate_existing_seal(scan_dir, scan)
3064
- _write_sarif_projection_if_possible(scan_dir, source_root, schema_dir)
3065
- warning = write_threat_model_projection_if_possible(scan_dir, manifest)
3147
+ _write_sarif_projection_if_possible(scan_dir, source_root, prepared.schema_dir)
3148
+ warning = write_threat_model_projection_if_possible(scan_dir, prepared.manifest)
3066
3149
  if (
3067
3150
  warning is not None
3068
3151
  and projection_warnings is not None
3069
3152
  and warning not in projection_warnings
3070
3153
  ):
3071
3154
  projection_warnings.append(warning)
3072
- return manifest, findings, coverage
3155
+ return prepared.manifest, prepared.findings, prepared.coverage
3073
3156
 
3074
3157
 
3075
3158
  def finalize_scan(
@@ -3109,6 +3192,7 @@ def main() -> int:
3109
3192
  parser.add_argument("--write-threat-model", action="store_true")
3110
3193
  args = parser.parse_args()
3111
3194
  try:
3195
+ args.scan_dir = args.scan_dir.resolve()
3112
3196
  if args.describe_threat_model:
3113
3197
  sys.stdout.buffer.write(
3114
3198
  _json_bytes(describe_threat_model(args.scan_dir, args.schema_dir))