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