@openai/codex-security 0.1.31 → 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 (514) hide show
  1. package/README.md +442 -2434
  2. package/_bundled_plugin/.app.json +5 -1
  3. package/_bundled_plugin/.codex-plugin/plugin.json +9 -5
  4. package/_bundled_plugin/.mcp.json +3 -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 +7 -214
  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 +5 -5
  25. package/_bundled_plugin/references/config-preflight.md +1 -5
  26. package/_bundled_plugin/references/core-scan.md +34 -10
  27. package/_bundled_plugin/references/final-report.md +13 -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 +3 -4
  31. package/_bundled_plugin/references/scan-contract.md +11 -6
  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 +2 -2
  36. package/_bundled_plugin/schemas/coverage.schema.json +23 -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 +83 -95
  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 +245 -356
  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 +29 -69
  50. package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
  51. package/_bundled_plugin/scripts/deep_scan_workbench.py +208 -363
  52. package/_bundled_plugin/scripts/filesystem_identity.py +1 -5
  53. package/_bundled_plugin/scripts/finalize_scan_contract.py +733 -375
  54. package/_bundled_plugin/scripts/finding_preview.py +81 -91
  55. package/_bundled_plugin/scripts/generate_in_scope_files.py +48 -102
  56. package/_bundled_plugin/scripts/generate_rank_input.py +117 -888
  57. package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -6
  58. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
  59. package/_bundled_plugin/scripts/rank_preview.py +43 -902
  60. package/_bundled_plugin/scripts/report_projection.py +143 -219
  61. package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
  62. package/_bundled_plugin/scripts/threat_model_projection.py +161 -0
  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 +59 -9
  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 +21 -6
  69. package/_bundled_plugin/scripts/workbench_cli.py +99 -190
  70. package/_bundled_plugin/scripts/workbench_constants.py +6 -14
  71. package/_bundled_plugin/scripts/workbench_db.py +524 -672
  72. package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
  73. package/_bundled_plugin/scripts/workbench_finding_index.py +20 -7
  74. package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
  75. package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
  76. package/_bundled_plugin/scripts/workbench_native_indexes.py +28 -18
  77. package/_bundled_plugin/scripts/workbench_progress.py +26 -92
  78. package/_bundled_plugin/scripts/workbench_publication.py +77 -116
  79. package/_bundled_plugin/scripts/workbench_remediation.py +14 -20
  80. package/_bundled_plugin/scripts/workbench_saved_results.py +1402 -263
  81. package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
  82. package/_bundled_plugin/scripts/workbench_scan_start.py +109 -52
  83. package/_bundled_plugin/scripts/workbench_scan_usage.py +30 -49
  84. package/_bundled_plugin/scripts/workbench_schema.py +71 -1370
  85. package/_bundled_plugin/scripts/workbench_source_excerpt.py +16 -7
  86. package/_bundled_plugin/scripts/workbench_target.py +526 -150
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1 -5
  88. package/_bundled_plugin/scripts/workbench_validation.py +19 -44
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
  90. package/_bundled_plugin/shared/workbench-migrations.json +397 -0
  91. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
  92. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
  93. package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
  94. package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
  95. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +6 -6
  96. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  97. package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
  98. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
  99. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
  100. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  104. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +13 -1
  105. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  106. package/_bundled_plugin/skills/track-findings/SKILL.md +46 -178
  107. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  108. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
  109. package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
  110. package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
  111. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
  112. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
  113. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
  114. package/bin/codex-security.mjs +9 -2
  115. package/dist/api.d.ts +63 -15
  116. package/dist/api.d.ts.map +1 -1
  117. package/dist/api.js +970 -553
  118. package/dist/api.js.map +1 -1
  119. package/dist/artifact-export.d.ts +70 -0
  120. package/dist/artifact-export.d.ts.map +1 -0
  121. package/dist/artifact-export.js +292 -0
  122. package/dist/artifact-export.js.map +1 -0
  123. package/dist/auth.d.ts +2 -6
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +27 -12
  126. package/dist/auth.js.map +1 -1
  127. package/dist/bulk-scan-discovery.d.ts +1 -0
  128. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  129. package/dist/bulk-scan-discovery.js +9 -9
  130. package/dist/bulk-scan-discovery.js.map +1 -1
  131. package/dist/classify-scan-severity.d.ts.map +1 -1
  132. package/dist/classify-scan-severity.js +2 -5
  133. package/dist/classify-scan-severity.js.map +1 -1
  134. package/dist/classify-severity.d.ts +28 -17
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +16 -35
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli-help.d.ts +3 -0
  139. package/dist/cli-help.d.ts.map +1 -0
  140. package/dist/cli-help.js +285 -0
  141. package/dist/cli-help.js.map +1 -0
  142. package/dist/cli-signals.d.ts +8 -0
  143. package/dist/cli-signals.d.ts.map +1 -0
  144. package/dist/cli-signals.js +28 -0
  145. package/dist/cli-signals.js.map +1 -0
  146. package/dist/cli.d.ts +22 -24
  147. package/dist/cli.d.ts.map +1 -1
  148. package/dist/cli.js +1660 -1556
  149. package/dist/cli.js.map +1 -1
  150. package/dist/cloud-publish.d.ts.map +1 -1
  151. package/dist/cloud-publish.js +11 -17
  152. package/dist/cloud-publish.js.map +1 -1
  153. package/dist/codeowners.d.ts +19 -0
  154. package/dist/codeowners.d.ts.map +1 -0
  155. package/dist/codeowners.js +138 -0
  156. package/dist/codeowners.js.map +1 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +1 -2
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/codex-sdk-environment.d.ts +3 -0
  161. package/dist/codex-sdk-environment.d.ts.map +1 -0
  162. package/dist/codex-sdk-environment.js +68 -0
  163. package/dist/codex-sdk-environment.js.map +1 -0
  164. package/dist/component-plan.d.ts +2 -5
  165. package/dist/component-plan.d.ts.map +1 -1
  166. package/dist/component-plan.js +38 -34
  167. package/dist/component-plan.js.map +1 -1
  168. package/dist/component-scan.d.ts +7 -5
  169. package/dist/component-scan.d.ts.map +1 -1
  170. package/dist/component-scan.js +54 -44
  171. package/dist/component-scan.js.map +1 -1
  172. package/dist/config.d.ts.map +1 -1
  173. package/dist/config.js +93 -104
  174. package/dist/config.js.map +1 -1
  175. package/dist/contract.d.ts +15 -2
  176. package/dist/contract.d.ts.map +1 -1
  177. package/dist/contract.js +124 -348
  178. package/dist/contract.js.map +1 -1
  179. package/dist/cost-model.d.ts +13 -6
  180. package/dist/cost-model.d.ts.map +1 -1
  181. package/dist/cost-model.js +75 -34
  182. package/dist/cost-model.js.map +1 -1
  183. package/dist/cost.d.ts +10 -2
  184. package/dist/cost.d.ts.map +1 -1
  185. package/dist/cost.js +116 -134
  186. package/dist/cost.js.map +1 -1
  187. package/dist/custom-validation-prompt.d.ts.map +1 -1
  188. package/dist/custom-validation-prompt.js +7 -6
  189. package/dist/custom-validation-prompt.js.map +1 -1
  190. package/dist/custom-validation.d.ts +1 -2
  191. package/dist/custom-validation.d.ts.map +1 -1
  192. package/dist/custom-validation.js +23 -16
  193. package/dist/custom-validation.js.map +1 -1
  194. package/dist/deduplication/checkpointed-review.d.ts +4 -2
  195. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  196. package/dist/deduplication/checkpointed-review.js +33 -20
  197. package/dist/deduplication/checkpointed-review.js.map +1 -1
  198. package/dist/deduplication/codex-review.d.ts +9 -1
  199. package/dist/deduplication/codex-review.d.ts.map +1 -1
  200. package/dist/deduplication/codex-review.js +129 -20
  201. package/dist/deduplication/codex-review.js.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.d.ts +5 -2
  203. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  204. package/dist/deduplication/deduplication-prompts.js +18 -4
  205. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.d.ts +26 -4
  207. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  208. package/dist/deduplication/deduplication-reviewer.js +59 -47
  209. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  210. package/dist/deduplication/deduplication.d.ts.map +1 -1
  211. package/dist/deduplication/deduplication.js +59 -113
  212. package/dist/deduplication/deduplication.js.map +1 -1
  213. package/dist/deduplication/diagnostics.d.ts +17 -0
  214. package/dist/deduplication/diagnostics.d.ts.map +1 -0
  215. package/dist/deduplication/diagnostics.js +5 -0
  216. package/dist/deduplication/diagnostics.js.map +1 -0
  217. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  218. package/dist/deduplication/finding-schema.js +7 -1
  219. package/dist/deduplication/finding-schema.js.map +1 -1
  220. package/dist/deduplication/local.d.ts +31 -0
  221. package/dist/deduplication/local.d.ts.map +1 -0
  222. package/dist/deduplication/local.js +166 -0
  223. package/dist/deduplication/local.js.map +1 -0
  224. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  225. package/dist/deduplication/records-protocol.js +12 -28
  226. package/dist/deduplication/records-protocol.js.map +1 -1
  227. package/dist/deduplication/records.d.ts +188 -12
  228. package/dist/deduplication/records.d.ts.map +1 -1
  229. package/dist/deduplication/records.js +34 -24
  230. package/dist/deduplication/records.js.map +1 -1
  231. package/dist/deduplication/review.d.ts +7 -0
  232. package/dist/deduplication/review.d.ts.map +1 -1
  233. package/dist/deduplication/review.js.map +1 -1
  234. package/dist/deduplication/scan.d.ts +9 -3
  235. package/dist/deduplication/scan.d.ts.map +1 -1
  236. package/dist/deduplication/scan.js +159 -44
  237. package/dist/deduplication/scan.js.map +1 -1
  238. package/dist/deep-config.d.ts +2 -1
  239. package/dist/deep-config.d.ts.map +1 -1
  240. package/dist/deep-config.js +7 -23
  241. package/dist/deep-config.js.map +1 -1
  242. package/dist/deep-progress.d.ts +2 -1
  243. package/dist/deep-progress.d.ts.map +1 -1
  244. package/dist/deep-progress.js +32 -47
  245. package/dist/deep-progress.js.map +1 -1
  246. package/dist/deep-scan.d.ts +20 -0
  247. package/dist/deep-scan.d.ts.map +1 -0
  248. package/dist/deep-scan.js +113 -0
  249. package/dist/deep-scan.js.map +1 -0
  250. package/dist/errors.d.ts +5 -2
  251. package/dist/errors.d.ts.map +1 -1
  252. package/dist/errors.js +7 -7
  253. package/dist/errors.js.map +1 -1
  254. package/dist/feedback.d.ts.map +1 -1
  255. package/dist/feedback.js +53 -21
  256. package/dist/feedback.js.map +1 -1
  257. package/dist/finding-catalogue.d.ts.map +1 -1
  258. package/dist/finding-catalogue.js +26 -30
  259. package/dist/finding-catalogue.js.map +1 -1
  260. package/dist/finding-normalization.d.ts +5 -0
  261. package/dist/finding-normalization.d.ts.map +1 -0
  262. package/dist/finding-normalization.js +120 -0
  263. package/dist/finding-normalization.js.map +1 -0
  264. package/dist/finding-retrieval.d.ts +9 -0
  265. package/dist/finding-retrieval.d.ts.map +1 -1
  266. package/dist/finding-retrieval.js.map +1 -1
  267. package/dist/finding-workflow.d.ts +13 -8
  268. package/dist/finding-workflow.d.ts.map +1 -1
  269. package/dist/finding-workflow.js +18 -13
  270. package/dist/finding-workflow.js.map +1 -1
  271. package/dist/findings-client.d.ts +2 -1
  272. package/dist/findings-client.d.ts.map +1 -1
  273. package/dist/findings-client.js +36 -9
  274. package/dist/findings-client.js.map +1 -1
  275. package/dist/findings-errors.d.ts +16 -0
  276. package/dist/findings-errors.d.ts.map +1 -0
  277. package/dist/findings-errors.js +24 -0
  278. package/dist/findings-errors.js.map +1 -0
  279. package/dist/findings-import.d.ts +1 -1
  280. package/dist/findings-import.d.ts.map +1 -1
  281. package/dist/findings-import.js +16 -44
  282. package/dist/findings-import.js.map +1 -1
  283. package/dist/github.d.ts.map +1 -1
  284. package/dist/github.js +9 -4
  285. package/dist/github.js.map +1 -1
  286. package/dist/import-scan.d.ts.map +1 -1
  287. package/dist/import-scan.js +49 -39
  288. package/dist/import-scan.js.map +1 -1
  289. package/dist/index.d.ts +11 -5
  290. package/dist/index.d.ts.map +1 -1
  291. package/dist/index.js +2 -1
  292. package/dist/index.js.map +1 -1
  293. package/dist/knowledge-base.d.ts +7 -1
  294. package/dist/knowledge-base.d.ts.map +1 -1
  295. package/dist/knowledge-base.js +115 -47
  296. package/dist/knowledge-base.js.map +1 -1
  297. package/dist/linear.d.ts.map +1 -1
  298. package/dist/linear.js +4 -10
  299. package/dist/linear.js.map +1 -1
  300. package/dist/mock-scan.d.ts.map +1 -1
  301. package/dist/mock-scan.js +0 -1
  302. package/dist/mock-scan.js.map +1 -1
  303. package/dist/models.d.ts +24 -2
  304. package/dist/models.d.ts.map +1 -1
  305. package/dist/models.js.map +1 -1
  306. package/dist/multiscan.d.ts +9 -3
  307. package/dist/multiscan.d.ts.map +1 -1
  308. package/dist/multiscan.js +225 -153
  309. package/dist/multiscan.js.map +1 -1
  310. package/dist/owner-evidence.d.ts +10 -2
  311. package/dist/owner-evidence.d.ts.map +1 -1
  312. package/dist/owner-evidence.js +69 -14
  313. package/dist/owner-evidence.js.map +1 -1
  314. package/dist/patch-tui.d.ts.map +1 -1
  315. package/dist/patch-tui.js +5 -6
  316. package/dist/patch-tui.js.map +1 -1
  317. package/dist/project-config-schema.d.ts +10 -0
  318. package/dist/project-config-schema.d.ts.map +1 -1
  319. package/dist/project-config-schema.js +1 -0
  320. package/dist/project-config-schema.js.map +1 -1
  321. package/dist/project-config.d.ts +1 -0
  322. package/dist/project-config.d.ts.map +1 -1
  323. package/dist/project-config.js +5 -3
  324. package/dist/project-config.js.map +1 -1
  325. package/dist/prompt-files.d.ts +0 -1
  326. package/dist/prompt-files.d.ts.map +1 -1
  327. package/dist/prompt-files.js +2 -4
  328. package/dist/prompt-files.js.map +1 -1
  329. package/dist/provider-profile.d.ts +21 -0
  330. package/dist/provider-profile.d.ts.map +1 -0
  331. package/dist/provider-profile.js +133 -0
  332. package/dist/provider-profile.js.map +1 -0
  333. package/dist/publication-events.d.ts +6 -8
  334. package/dist/publication-events.d.ts.map +1 -1
  335. package/dist/publication-events.js +40 -79
  336. package/dist/publication-events.js.map +1 -1
  337. package/dist/publication-store.d.ts.map +1 -1
  338. package/dist/publication-store.js +48 -76
  339. package/dist/publication-store.js.map +1 -1
  340. package/dist/publication.d.ts +1 -2
  341. package/dist/publication.d.ts.map +1 -1
  342. package/dist/publication.js +7 -16
  343. package/dist/publication.js.map +1 -1
  344. package/dist/publish.d.ts +1 -5
  345. package/dist/publish.d.ts.map +1 -1
  346. package/dist/publish.js +138 -199
  347. package/dist/publish.js.map +1 -1
  348. package/dist/record.d.ts +2 -0
  349. package/dist/record.d.ts.map +1 -0
  350. package/dist/record.js +4 -0
  351. package/dist/record.js.map +1 -0
  352. package/dist/request-metadata.d.ts +9 -0
  353. package/dist/request-metadata.d.ts.map +1 -0
  354. package/dist/request-metadata.js +13 -0
  355. package/dist/request-metadata.js.map +1 -0
  356. package/dist/result.d.ts +4 -1
  357. package/dist/result.d.ts.map +1 -1
  358. package/dist/result.js +7 -0
  359. package/dist/result.js.map +1 -1
  360. package/dist/runtime.d.ts +25 -17
  361. package/dist/runtime.d.ts.map +1 -1
  362. package/dist/runtime.js +619 -255
  363. package/dist/runtime.js.map +1 -1
  364. package/dist/saved-scan-bootstrap.d.ts +14 -0
  365. package/dist/saved-scan-bootstrap.d.ts.map +1 -0
  366. package/dist/saved-scan-bootstrap.js +261 -0
  367. package/dist/saved-scan-bootstrap.js.map +1 -0
  368. package/dist/saved-scan.d.ts +1 -1
  369. package/dist/saved-scan.d.ts.map +1 -1
  370. package/dist/saved-scan.js +16 -32
  371. package/dist/saved-scan.js.map +1 -1
  372. package/dist/scan-activity.d.ts.map +1 -1
  373. package/dist/scan-activity.js +19 -30
  374. package/dist/scan-activity.js.map +1 -1
  375. package/dist/scan-comparison.d.ts +31 -18
  376. package/dist/scan-comparison.d.ts.map +1 -1
  377. package/dist/scan-comparison.js +307 -347
  378. package/dist/scan-comparison.js.map +1 -1
  379. package/dist/scan-dashboard.d.ts +3 -1
  380. package/dist/scan-dashboard.d.ts.map +1 -1
  381. package/dist/scan-dashboard.js +351 -92
  382. package/dist/scan-dashboard.js.map +1 -1
  383. package/dist/scan-history-renderer.d.ts.map +1 -1
  384. package/dist/scan-history-renderer.js +55 -15
  385. package/dist/scan-history-renderer.js.map +1 -1
  386. package/dist/scan-inputs.d.ts +6 -0
  387. package/dist/scan-inputs.d.ts.map +1 -0
  388. package/dist/scan-inputs.js +71 -0
  389. package/dist/scan-inputs.js.map +1 -0
  390. package/dist/scan-logs.d.ts +2 -3
  391. package/dist/scan-logs.d.ts.map +1 -1
  392. package/dist/scan-logs.js +14 -12
  393. package/dist/scan-logs.js.map +1 -1
  394. package/dist/scan-sessions.d.ts +4 -0
  395. package/dist/scan-sessions.d.ts.map +1 -1
  396. package/dist/scan-sessions.js +18 -3
  397. package/dist/scan-sessions.js.map +1 -1
  398. package/dist/scan-settings.d.ts +5 -0
  399. package/dist/scan-settings.d.ts.map +1 -1
  400. package/dist/scan-settings.js +4 -0
  401. package/dist/scan-settings.js.map +1 -1
  402. package/dist/scan-skill-paths.d.ts +8 -0
  403. package/dist/scan-skill-paths.d.ts.map +1 -0
  404. package/dist/scan-skill-paths.js +47 -0
  405. package/dist/scan-skill-paths.js.map +1 -0
  406. package/dist/security-policy-cli.d.ts.map +1 -1
  407. package/dist/security-policy-cli.js +15 -33
  408. package/dist/security-policy-cli.js.map +1 -1
  409. package/dist/security-policy.d.ts +17 -9
  410. package/dist/security-policy.d.ts.map +1 -1
  411. package/dist/security-policy.js +131 -98
  412. package/dist/security-policy.js.map +1 -1
  413. package/dist/server/api.d.ts +0 -1
  414. package/dist/server/api.d.ts.map +1 -1
  415. package/dist/server/api.js +0 -1
  416. package/dist/server/api.js.map +1 -1
  417. package/dist/server/embeddings.d.ts +3 -1
  418. package/dist/server/embeddings.d.ts.map +1 -1
  419. package/dist/server/embeddings.js +11 -3
  420. package/dist/server/embeddings.js.map +1 -1
  421. package/dist/server/errors.d.ts +5 -2
  422. package/dist/server/errors.d.ts.map +1 -1
  423. package/dist/server/errors.js +7 -0
  424. package/dist/server/errors.js.map +1 -1
  425. package/dist/server/sqlite-store.d.ts +0 -2
  426. package/dist/server/sqlite-store.d.ts.map +1 -1
  427. package/dist/server/sqlite-store.js +55 -55
  428. package/dist/server/sqlite-store.js.map +1 -1
  429. package/dist/server/storage.d.ts +0 -2
  430. package/dist/server/storage.d.ts.map +1 -1
  431. package/dist/server/storage.js.map +1 -1
  432. package/dist/severity-store.js +20 -32
  433. package/dist/severity-store.js.map +1 -1
  434. package/dist/standalone-validation-prompt.d.ts +2 -0
  435. package/dist/standalone-validation-prompt.d.ts.map +1 -0
  436. package/dist/standalone-validation-prompt.js +10 -0
  437. package/dist/standalone-validation-prompt.js.map +1 -0
  438. package/dist/suggest-owners.d.ts +6 -5
  439. package/dist/suggest-owners.d.ts.map +1 -1
  440. package/dist/suggest-owners.js +15 -10
  441. package/dist/suggest-owners.js.map +1 -1
  442. package/dist/targets.d.ts +12 -0
  443. package/dist/targets.d.ts.map +1 -1
  444. package/dist/targets.js +124 -62
  445. package/dist/targets.js.map +1 -1
  446. package/dist/trusted-executable.d.ts +6 -1
  447. package/dist/trusted-executable.d.ts.map +1 -1
  448. package/dist/trusted-executable.js +28 -9
  449. package/dist/trusted-executable.js.map +1 -1
  450. package/dist/value.d.ts +2 -0
  451. package/dist/value.d.ts.map +1 -0
  452. package/dist/value.js +27 -0
  453. package/dist/value.js.map +1 -0
  454. package/dist/version.d.ts.map +1 -1
  455. package/dist/version.js +3 -6
  456. package/dist/version.js.map +1 -1
  457. package/dist/windows-path.d.ts.map +1 -1
  458. package/dist/windows-path.js +1 -2
  459. package/dist/windows-path.js.map +1 -1
  460. package/dist/workbench-arguments.d.ts +3 -0
  461. package/dist/workbench-arguments.d.ts.map +1 -0
  462. package/dist/workbench-arguments.js +15 -0
  463. package/dist/workbench-arguments.js.map +1 -0
  464. package/dist/worker-progress.d.ts +2 -0
  465. package/dist/worker-progress.d.ts.map +1 -1
  466. package/dist/worker-progress.js +40 -46
  467. package/dist/worker-progress.js.map +1 -1
  468. package/docs/cli.md +1778 -0
  469. package/docs/dedupe-records.md +24 -0
  470. package/docs/findings-service.md +402 -0
  471. package/package.json +23 -23
  472. package/schemas/project-config.schema.json +5 -0
  473. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
  474. package/_bundled_plugin/scripts/normalize_candidates.py +0 -338
  475. package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
  476. package/_bundled_plugin/scripts/workbench_findings.py +0 -221
  477. package/_bundled_plugin/scripts/workbench_severity.py +0 -119
  478. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
  479. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
  480. package/dist/server/dashboard/app.css +0 -2
  481. package/dist/server/dashboard/app.js +0 -66
  482. package/dist/server/dashboard/index.html +0 -18
  483. package/dist/server/dashboard-types.d.ts +0 -48
  484. package/dist/server/dashboard-types.d.ts.map +0 -1
  485. package/dist/server/dashboard-types.js +0 -2
  486. package/dist/server/dashboard-types.js.map +0 -1
  487. package/dist/server/dashboard.d.ts +0 -6
  488. package/dist/server/dashboard.d.ts.map +0 -1
  489. package/dist/server/dashboard.js +0 -59
  490. package/dist/server/dashboard.js.map +0 -1
  491. package/dist/server/findings-service.d.ts +0 -20
  492. package/dist/server/findings-service.d.ts.map +0 -1
  493. package/dist/server/findings-service.js +0 -31
  494. package/dist/server/findings-service.js.map +0 -1
  495. package/dist/server/index.d.ts +0 -2
  496. package/dist/server/index.d.ts.map +0 -1
  497. package/dist/server/index.js +0 -6
  498. package/dist/server/index.js.map +0 -1
  499. package/dist/server/routes.d.ts +0 -6
  500. package/dist/server/routes.d.ts.map +0 -1
  501. package/dist/server/routes.js +0 -86
  502. package/dist/server/routes.js.map +0 -1
  503. package/dist/server/serve.d.ts +0 -2
  504. package/dist/server/serve.d.ts.map +0 -1
  505. package/dist/server/serve.js +0 -28
  506. package/dist/server/serve.js.map +0 -1
  507. package/dist/server/server.d.ts +0 -10
  508. package/dist/server/server.d.ts.map +0 -1
  509. package/dist/server/server.js +0 -17
  510. package/dist/server/server.js.map +0 -1
  511. package/dist/server/validation.d.ts +0 -17
  512. package/dist/server/validation.d.ts.map +0 -1
  513. package/dist/server/validation.js +0 -53
  514. 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
@@ -16,14 +15,18 @@ import os
16
15
  import re
17
16
  import secrets
18
17
  import stat
18
+ import struct
19
19
  import sys
20
- import time
21
- from collections.abc import Iterator
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
@@ -73,6 +78,13 @@ EXPORT_PATHS = {
73
78
  "json": "exports/findings.json",
74
79
  "sarif": "exports/results.sarif",
75
80
  }
81
+ THREAT_MODEL_EXPORT_PATH = "exports/threatmodel.md"
82
+ _LEGACY_THREAT_MODEL_PATHS = (
83
+ "threatmodel.md",
84
+ "THREAT_MODEL.md",
85
+ "artifacts/01_context/threat_model.md",
86
+ "threat_model.md",
87
+ )
76
88
  WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
77
89
  r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
78
90
  re.IGNORECASE,
@@ -83,8 +95,16 @@ class ContractError(ValueError):
83
95
  """Raised when a completed scan does not satisfy the additive contract."""
84
96
 
85
97
 
98
+ class MissingScanLocalFileError(ContractError):
99
+ """Raised when a scan-local file or its containing directory is absent."""
100
+
101
+
86
102
  class RecoverableContractError(ContractError):
87
- """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."""
88
108
 
89
109
 
90
110
  def _reject_non_finite_json(value: str) -> None:
@@ -115,31 +135,213 @@ def _generate_report_projection(
115
135
  findings: dict[str, Any],
116
136
  coverage: dict[str, Any],
117
137
  ) -> bytes:
118
- script = Path(__file__).resolve().parent / "report_projection.py"
119
- spec = importlib.util.spec_from_file_location("codex_security_report_projection", script)
120
- if spec is None or spec.loader is None:
121
- raise ContractError(f"could not load report projection helper: {script}")
122
- module = importlib.util.module_from_spec(spec)
123
- spec.loader.exec_module(module)
124
- attempts = (
125
- getattr(sys.modules.get("workbench_constants"), "SQLITE_RETRY_ATTEMPTS", 1)
126
- if coverage.get("mode") == "deep_repository"
127
- else 1
128
- )
129
- for attempt in range(attempts):
130
- try:
131
- return module.generate_report_markdown(manifest, findings, coverage)
132
- except OSError as exc:
133
- if attempt == attempts - 1:
134
- raise RecoverableContractError(f"report projection failed: {exc}") from exc
135
- time.sleep(0.05 * (2**attempt))
136
- except ValueError as exc:
137
- raise ContractError(f"report projection failed: {exc}") from exc
138
- raise AssertionError("Report projection retry loop exhausted unexpectedly.")
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
142
+
143
+
144
+ def threat_model_provenance(manifest: dict[str, Any]) -> dict[str, Any]:
145
+ if manifest.get("documentType") == "codex-security.policy-draft":
146
+ scope = manifest.get("scope")
147
+ return {
148
+ "source": "policy",
149
+ "target": manifest.get("repository"),
150
+ "revision": manifest.get("revision"),
151
+ "scanScope": {"includePaths": [scope], "excludePaths": []} if scope else None,
152
+ "status": manifest.get("status", "completed"),
153
+ "provisional": manifest.get("status", "completed") != "completed",
154
+ }
155
+ scan = _require_dict(manifest, "scan", "manifest")
156
+ target = _require_dict(scan, "target", "manifest.scan") if "target" in scan else {}
157
+ status = scan.get("status")
158
+ if status == "completed" and not scan.get("sealedAt"):
159
+ status = "draft"
160
+ return {
161
+ "source": "scan",
162
+ "scanId": scan.get("id"),
163
+ "target": target.get("displayName"),
164
+ "revision": target.get("revision") or target.get("headRevision"),
165
+ "snapshotDigest": target.get("snapshotDigest"),
166
+ "scanScope": scan.get("scope"),
167
+ "status": status,
168
+ "provisional": scan.get("status") != "completed" or not scan.get("sealedAt"),
169
+ }
139
170
 
140
171
 
141
- def _validate_report_output_paths(scan_dir: Path) -> None:
142
- _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
172
+ def _render_threat_model(model: dict[str, Any], provenance: dict[str, Any]) -> bytes:
173
+ try:
174
+ return threat_model_projection.render_threat_model(model, provenance)
175
+ except (TypeError, ValueError) as exc:
176
+ raise ContractError(f"threat model projection failed: {exc}") from exc
177
+
178
+
179
+ def _read_saved_threat_model(
180
+ scan_dir: Path, *, validate_seal: bool = True, schema_dir: Path | None = None
181
+ ) -> tuple[dict[str, Any], bytes] | None:
182
+ """Read canonical content first; old documents are a read-only compatibility path."""
183
+ scan_dir = _require_scan_directory(scan_dir)
184
+ saved_provenance: dict[str, Any] | None = None
185
+ sealed_artifact_paths: set[str] | None = None
186
+ scan_manifest_path = scan_dir / "scan-manifest.json"
187
+ filename = (
188
+ "scan-manifest.json"
189
+ if scan_manifest_path.exists() or scan_manifest_path.is_symlink()
190
+ else "policy-draft.json"
191
+ )
192
+ manifest_path = scan_dir / filename
193
+ if manifest_path.exists() or manifest_path.is_symlink():
194
+ manifest = _read_scan_local_json(scan_dir, filename, filename)
195
+ scan = (
196
+ _require_dict(manifest, "scan", "manifest")
197
+ if filename == "scan-manifest.json"
198
+ else manifest
199
+ )
200
+ if (
201
+ validate_seal
202
+ and filename == "scan-manifest.json"
203
+ and (scan.get("sealedAt") is not None or scan.get("artifacts"))
204
+ ):
205
+ if "threatModel" not in scan:
206
+ _validate_manifest(manifest)
207
+ recorded_paths = {
208
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
209
+ for artifact in scan["artifacts"]
210
+ }
211
+ if recorded_paths.isdisjoint(_LEGACY_THREAT_MODEL_PATHS):
212
+ validate_against_schema(
213
+ manifest,
214
+ (schema_dir or Path(__file__).resolve().parent.parent / "schemas")
215
+ / "scan-manifest.schema.json",
216
+ )
217
+ return None
218
+ manifest, _, _, _ = _read_sealed_scan(scan_dir, schema_dir, "threat model export")
219
+ scan = manifest["scan"]
220
+ sealed_artifact_paths = {
221
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
222
+ for artifact in scan["artifacts"]
223
+ }
224
+ provenance = threat_model_provenance(manifest)
225
+ saved_provenance = provenance
226
+ if "threatModel" in scan:
227
+ model = _require_dict(
228
+ scan,
229
+ "threatModel",
230
+ "manifest.scan" if filename == "scan-manifest.json" else "policy draft",
231
+ )
232
+ contents = _render_threat_model(model, provenance)
233
+ path = scan_dir / "threatmodel.md"
234
+ current_path = None
235
+ try:
236
+ descriptor = open_scan_local_file_descriptor(
237
+ scan_dir, "threatmodel.md", "Saved threat model"
238
+ )
239
+ with os.fdopen(descriptor, "rb") as handle:
240
+ if handle.read() == contents:
241
+ current_path = str(path)
242
+ except (ContractError, OSError):
243
+ # An unavailable projection does not invalidate the canonical model.
244
+ pass
245
+ return {
246
+ "threatModel": model,
247
+ "provenance": provenance,
248
+ "path": current_path,
249
+ }, contents
250
+ for filename in _LEGACY_THREAT_MODEL_PATHS:
251
+ if sealed_artifact_paths is not None and filename not in sealed_artifact_paths:
252
+ continue
253
+ path = scan_dir / filename
254
+ if not path.exists() and not path.is_symlink():
255
+ continue
256
+ descriptor, filename = _open_scan_local_file_with_path(
257
+ scan_dir,
258
+ filename,
259
+ "Saved threat model",
260
+ resolve_spelling=sealed_artifact_paths is None,
261
+ )
262
+ path = scan_dir / filename
263
+ with os.fdopen(descriptor, "rb") as handle:
264
+ contents = handle.read()
265
+ try:
266
+ body = contents.decode("utf-8")
267
+ except UnicodeDecodeError as exc:
268
+ raise ContractError(f"{filename}: expected UTF-8 Markdown") from exc
269
+ if body.strip():
270
+ return {
271
+ "threatModel": {"format": "markdown", "content": body},
272
+ "provenance": saved_provenance
273
+ or {"source": filename, "status": "unknown", "provisional": True},
274
+ "path": str(path),
275
+ }, contents
276
+ return None
277
+
278
+
279
+ def describe_threat_model(scan_dir: Path, schema_dir: Path | None = None) -> dict[str, Any]:
280
+ saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
281
+ if saved is None:
282
+ raise ContractError("No saved threat model is available for this result.")
283
+ return saved[0]
284
+
285
+
286
+ def build_threat_model_export(scan_dir: Path, schema_dir: Path | None = None) -> bytes:
287
+ saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
288
+ if saved is None:
289
+ raise ContractError("No saved threat model is available for this result.")
290
+ return saved[1]
291
+
292
+
293
+ def write_threat_model_projection_if_possible(
294
+ scan_dir: Path, manifest: dict[str, Any] | None = None
295
+ ) -> str | None:
296
+ """A convenience document failure must not discard saved canonical content."""
297
+ try:
298
+ saved_manifest = manifest
299
+ if saved_manifest is None and (scan_dir / "scan-manifest.json").exists():
300
+ saved_manifest = _read_scan_local_json(
301
+ scan_dir, "scan-manifest.json", "scan-manifest.json"
302
+ )
303
+ if (
304
+ saved_manifest is not None
305
+ and saved_manifest.get("documentType") != "codex-security.policy-draft"
306
+ ):
307
+ scan = _require_dict(saved_manifest, "scan", "manifest")
308
+ artifacts = (
309
+ _require_list(scan, "artifacts", "manifest.scan") if "artifacts" in scan else []
310
+ )
311
+ for index, artifact in enumerate(artifacts):
312
+ if not isinstance(artifact, dict):
313
+ continue
314
+ context = f"manifest.scan.artifacts[{index}]"
315
+ path = _require_portable_relative_path(
316
+ _require_str(artifact, "path", context), f"{context}.path"
317
+ )
318
+ if path.lower() == "threatmodel.md":
319
+ return None
320
+ if manifest is None:
321
+ saved = _read_saved_threat_model(scan_dir, validate_seal=False)
322
+ if saved is None:
323
+ return None
324
+ contents = saved[1]
325
+ else:
326
+ scan = (
327
+ manifest
328
+ if manifest.get("documentType") == "codex-security.policy-draft"
329
+ else _require_dict(manifest, "scan", "manifest")
330
+ )
331
+ model = scan.get("threatModel")
332
+ if not isinstance(model, dict):
333
+ return None
334
+ contents = _render_threat_model(model, threat_model_provenance(manifest))
335
+ write_scan_local_bytes(scan_dir, "threatmodel.md", contents, owner_read_write=True)
336
+ return None
337
+ except (ContractError, OSError) as exc:
338
+ warning = (
339
+ f"Automatic threat model save failed: {exc}. "
340
+ "Saved canonical content can be exported with `codex-security export "
341
+ "<result-dir> --artifact threat-model`."
342
+ )
343
+ print(f"codex-security: warning: {warning}", file=sys.stderr)
344
+ return warning
143
345
 
144
346
 
145
347
  def _json_bytes(payload: Any) -> bytes:
@@ -192,22 +394,6 @@ def _require_safe_json_string(value: str, context: str) -> None:
192
394
  raise ContractError(f"{context}: expected well-formed Unicode JSON strings") from exc
193
395
 
194
396
 
195
- def _sha256_text(value: str) -> str:
196
- return hashlib.sha256(value.encode("utf-8")).hexdigest()
197
-
198
-
199
- def _sha256_bytes(value: bytes) -> str:
200
- return hashlib.sha256(value).hexdigest()
201
-
202
-
203
- def _sha256_file(path: Path) -> str:
204
- digest = hashlib.sha256()
205
- with path.open("rb") as handle:
206
- for chunk in iter(lambda: handle.read(1024 * 1024), b""):
207
- digest.update(chunk)
208
- return digest.hexdigest()
209
-
210
-
211
397
  def _require_dict(payload: dict[str, Any], key: str, context: str) -> dict[str, Any]:
212
398
  value = payload.get(key)
213
399
  if not isinstance(value, dict):
@@ -294,10 +480,6 @@ def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path:
294
480
  raise ContractError(f"{relative_path}: expected a regular file")
295
481
 
296
482
 
297
- def _descriptor_relative_reads_available() -> bool:
298
- return os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")
299
-
300
-
301
483
  def _is_windows() -> bool:
302
484
  return os.name == "nt"
303
485
 
@@ -311,22 +493,11 @@ def _descriptor_relative_writes_available() -> bool:
311
493
  )
312
494
 
313
495
 
314
- _WINDOWS_SCAN_LOCAL_FILES: Any | None = None
315
-
316
-
317
496
  def _windows_scan_local_files() -> Any:
318
497
  """Load the Win32 backend and shared stream comparison lazily."""
498
+ import windows_scan_local_files
319
499
 
320
- global _WINDOWS_SCAN_LOCAL_FILES
321
- if _WINDOWS_SCAN_LOCAL_FILES is None:
322
- script = Path(__file__).resolve().with_name("windows_scan_local_files.py")
323
- spec = importlib.util.spec_from_file_location("codex_security_windows_scan_files", script)
324
- if spec is None or spec.loader is None:
325
- raise ContractError(f"could not load Windows scan-local file helper: {script}")
326
- module = importlib.util.module_from_spec(spec)
327
- spec.loader.exec_module(module)
328
- _WINDOWS_SCAN_LOCAL_FILES = module
329
- return _WINDOWS_SCAN_LOCAL_FILES
500
+ return windows_scan_local_files
330
501
 
331
502
 
332
503
  def _open_verified_scan_directory(
@@ -379,6 +550,7 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
379
550
  try:
380
551
  os.mkdir(part, mode=0o700, dir_fd=descriptor)
381
552
  except FileExistsError:
553
+ # The open below verifies that an existing entry is a real directory.
382
554
  pass
383
555
  next_descriptor = os.open(
384
556
  part,
@@ -393,15 +565,35 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
393
565
  raise
394
566
 
395
567
 
396
- def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
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]
572
+
573
+
574
+ def _open_scan_local_file_with_path(
575
+ scan_dir: Path,
576
+ relative_path: str,
577
+ context: str,
578
+ *,
579
+ resolve_spelling: bool = False,
580
+ portable: bool = True,
581
+ ) -> tuple[int, str]:
397
582
  scan_dir = _require_scan_directory(scan_dir)
398
- relative_path = _require_portable_relative_path(relative_path, context)
399
- if not _descriptor_relative_reads_available():
583
+ validate_path = _require_portable_relative_path if portable else _require_safe_relative_path
584
+ relative_path = validate_path(relative_path, context)
585
+ if not (os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")):
400
586
  if not _is_windows():
401
587
  raise ContractError("scan-local input requires descriptor-relative file operations")
402
588
  try:
403
- return _windows_scan_local_files().open_read_fd(scan_dir, relative_path, context)
589
+ backend = _windows_scan_local_files()
590
+ if resolve_spelling:
591
+ return backend.open_read_fd_with_path(scan_dir, relative_path, context)
592
+ return backend.open_read_fd(scan_dir, relative_path, context), relative_path
404
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
405
597
  raise ContractError(str(exc)) from exc
406
598
  root_fd: int | None = None
407
599
  parent_fd: int | None = None
@@ -417,6 +609,10 @@ def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context:
417
609
  dir_fd=parent_fd,
418
610
  )
419
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
420
616
  if exc.errno == errno.ELOOP:
421
617
  try:
422
618
  link_target = Path(os.readlink(parts[-1], dir_fd=parent_fd))
@@ -432,9 +628,22 @@ def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context:
432
628
  metadata = os.fstat(descriptor)
433
629
  if not stat.S_ISREG(metadata.st_mode):
434
630
  raise ContractError(f"{context}: expected a regular non-symlink file")
631
+ if resolve_spelling:
632
+ names = os.listdir(parent_fd)
633
+ if parts[-1] not in names:
634
+ for name in names:
635
+ if name.casefold() != parts[-1].casefold():
636
+ continue
637
+ try:
638
+ entry = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
639
+ except FileNotFoundError:
640
+ continue
641
+ if os.path.samestat(metadata, entry):
642
+ relative_path = PurePosixPath(relative_path).with_name(name).as_posix()
643
+ break
435
644
  result = descriptor
436
645
  descriptor = None
437
- return result
646
+ return result, relative_path
438
647
  finally:
439
648
  if descriptor is not None:
440
649
  os.close(descriptor)
@@ -449,7 +658,13 @@ def _require_scan_local_file(scan_dir: Path, relative_path: str, context: str) -
449
658
  os.close(descriptor)
450
659
 
451
660
 
452
- 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] = []
453
668
  for index, finding in enumerate(findings.get("findings", [])):
454
669
  if not isinstance(finding, dict):
455
670
  continue
@@ -458,11 +673,18 @@ def _require_derived_writeup_files(scan_dir: Path, findings: dict[str, Any]) ->
458
673
  continue
459
674
  report_path = writeup.get("reportPath")
460
675
  if isinstance(report_path, str):
461
- _require_scan_local_file(
462
- scan_dir,
463
- report_path,
464
- f"findings[{index}].writeup.reportPath",
465
- )
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
466
688
 
467
689
 
468
690
  def _require_hardening_portfolio_file(scan_dir: Path, scan: dict[str, Any]) -> None:
@@ -478,16 +700,17 @@ def _require_hardening_portfolio_file(scan_dir: Path, scan: dict[str, Any]) -> N
478
700
  )
479
701
 
480
702
 
481
- def _read_scan_local_json_bytes(
703
+ def _read_scan_local_json_with_metadata(
482
704
  scan_dir: Path, relative_path: str, context: str
483
- ) -> tuple[dict[str, Any], bytes]:
705
+ ) -> tuple[dict[str, Any], bytes, os.stat_result]:
484
706
  descriptor = open_scan_local_file_descriptor(scan_dir, relative_path, context)
485
707
  try:
486
708
  with os.fdopen(descriptor, "rb") as handle:
487
709
  descriptor = -1
488
710
  raw = handle.read()
711
+ metadata = os.fstat(handle.fileno())
489
712
  try:
490
- payload = _loads_json(raw.decode("utf-8"))
713
+ payload = _loads_json(raw.decode("utf-8-sig"))
491
714
  except (UnicodeDecodeError, ValueError) as exc:
492
715
  raise ContractError(f"{context}: invalid JSON: {exc}") from exc
493
716
  if not isinstance(payload, dict):
@@ -496,6 +719,13 @@ def _read_scan_local_json_bytes(
496
719
  finally:
497
720
  if descriptor >= 0:
498
721
  os.close(descriptor)
722
+ return payload, raw, metadata
723
+
724
+
725
+ def _read_scan_local_json_bytes(
726
+ scan_dir: Path, relative_path: str, context: str
727
+ ) -> tuple[dict[str, Any], bytes]:
728
+ payload, raw, _ = _read_scan_local_json_with_metadata(scan_dir, relative_path, context)
499
729
  return payload, raw
500
730
 
501
731
 
@@ -525,6 +755,7 @@ def write_scan_local_bytes(
525
755
  *,
526
756
  external_name: bool = False,
527
757
  expected_root_identity: tuple[int, int] | None = None,
758
+ owner_read_write: bool = False,
528
759
  ) -> None:
529
760
  scan_dir = _require_scan_directory(scan_dir)
530
761
  if external_name:
@@ -596,6 +827,7 @@ def write_scan_local_bytes(
596
827
  ):
597
828
  return
598
829
  except OSError:
830
+ # A failed content comparison still allows an atomic replacement.
599
831
  pass
600
832
  finally:
601
833
  if existing_fd >= 0:
@@ -603,6 +835,9 @@ def write_scan_local_bytes(
603
835
  temp_name = f".{path.name}.{secrets.token_hex(8)}.tmp"
604
836
  temp_fd = os.open(temp_name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
605
837
  with os.fdopen(temp_fd, "wb") as handle:
838
+ if owner_read_write:
839
+ # Generated Markdown must remain editable under a restrictive umask.
840
+ os.fchmod(handle.fileno(), 0o600)
606
841
  handle.write(payload)
607
842
  handle.flush()
608
843
  os.fsync(handle.fileno())
@@ -613,6 +848,7 @@ def write_scan_local_bytes(
613
848
  try:
614
849
  os.unlink(temp_name, dir_fd=parent_fd)
615
850
  except FileNotFoundError:
851
+ # The temporary file is already gone, so cleanup is complete.
616
852
  pass
617
853
  if parent_fd is not None:
618
854
  os.close(parent_fd)
@@ -656,8 +892,10 @@ def _write_scan_local_json(scan_dir: Path, relative_path: str, payload: Any) ->
656
892
 
657
893
 
658
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")
659
897
  parsed = urlsplit(remote)
660
- if not parsed.scheme or not parsed.netloc:
898
+ if "\\" in remote or not parsed.scheme or not parsed.netloc:
661
899
  raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
662
900
  if parsed.username or parsed.password or parsed.query or parsed.fragment:
663
901
  raise ContractError(
@@ -665,11 +903,19 @@ def _validate_remote(remote: str, context: str) -> None:
665
903
  )
666
904
 
667
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
+
668
914
  def _validate_date_time(value: str, context: str) -> None:
669
915
  if not RFC3339_RE.fullmatch(value):
670
916
  raise ContractError(f"{context}: expected an RFC 3339 timestamp")
671
917
  try:
672
- parsed = datetime.fromisoformat(value[:-1] + "+00:00" if value[-1] in "Zz" else value)
918
+ parsed = parse_timestamp(value)
673
919
  except ValueError as exc:
674
920
  raise ContractError(f"{context}: expected an RFC 3339 timestamp") from exc
675
921
  if parsed.tzinfo is None:
@@ -689,11 +935,7 @@ def _validate_target(target: dict[str, Any]) -> None:
689
935
  _validate_remote(remote, "scan.target.remote")
690
936
  if kind == "git_revision":
691
937
  _require_str(target, "revision", "scan.target")
692
- elif kind == "git_worktree":
693
- _require_str(target, "snapshotDigest", "scan.target")
694
- elif kind == "git_diff":
695
- _require_str(target, "snapshotDigest", "scan.target")
696
- elif kind == "directory_snapshot":
938
+ elif kind in ("git_worktree", "git_diff", "directory_snapshot"):
697
939
  _require_str(target, "snapshotDigest", "scan.target")
698
940
 
699
941
 
@@ -711,11 +953,11 @@ def _fingerprint(target_id: str, finding: dict[str, Any]) -> str:
711
953
  if not SLUG_RE.fullmatch(rule_id):
712
954
  raise ContractError("finding.ruleId: expected a stable lowercase rule slug")
713
955
  material = "\0".join((FINGERPRINT_ALGORITHM, target_id, rule_id, anchor, instance))
714
- return f"{FINGERPRINT_ALGORITHM}:sha256:{_sha256_text(material)}"
956
+ return f"{FINGERPRINT_ALGORITHM}:sha256:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"
715
957
 
716
958
 
717
959
  def _stable_id(prefix: str, *parts: str) -> str:
718
- return f"{prefix}_{_sha256_text(chr(0).join(parts))[:24]}"
960
+ return f"{prefix}_{hashlib.sha256(chr(0).join(parts).encode('utf-8')).hexdigest()[:24]}"
719
961
 
720
962
 
721
963
  def _validate_location(location: dict[str, Any], context: str) -> None:
@@ -911,14 +1153,14 @@ def _recover_unsealed_findings(
911
1153
  continue
912
1154
  try:
913
1155
  _validate_schema_node(
914
- finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}"
1156
+ finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}", schema
915
1157
  )
916
1158
  except ContractError as exc:
917
1159
  finding.pop(auxiliary)
918
1160
  warnings.append(
919
1161
  f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
920
1162
  )
921
- _validate_schema_node(finding, finding_schema, context)
1163
+ _validate_schema_node(finding, finding_schema, context, schema)
922
1164
  except ContractError as exc:
923
1165
  warning = f"Skipped malformed finding {index + 1}: {exc}."
924
1166
  warnings.append(warning)
@@ -977,19 +1219,12 @@ def _recover_unsealed_coverage(
977
1219
  ) -> None:
978
1220
  schema = _read_json(schema_dir / "coverage.schema.json")
979
1221
  properties = _require_dict(schema, "properties", "coverage.schema")
980
- completeness = coverage.get("completeness")
981
- partial = completeness not in ("complete", "partial", "unknown")
982
- if partial:
983
- warnings.append("Recovered malformed coverage completeness; marked coverage as partial.")
984
1222
  if (
985
1223
  coverage.get("mode") == "deep_repository"
986
1224
  and coverage.get("inventoryStrategy") != "repository"
987
1225
  ):
988
1226
  coverage["inventoryStrategy"] = "repository"
989
- warnings.append(
990
- "Recovered malformed Deep Scan inventory strategy; marked coverage as partial."
991
- )
992
- partial = True
1227
+ warnings.append("Recovered malformed Deep Scan inventory strategy.")
993
1228
 
994
1229
  surface_ids: set[str] = set()
995
1230
  for field, label in (
@@ -1003,7 +1238,6 @@ def _recover_unsealed_coverage(
1003
1238
  if not isinstance(items, list):
1004
1239
  warnings.append(f"Skipped malformed {label} records: expected an array.")
1005
1240
  coverage[field] = []
1006
- partial = True
1007
1241
  continue
1008
1242
 
1009
1243
  recovered: list[dict[str, Any]] = []
@@ -1057,19 +1291,14 @@ def _recover_unsealed_coverage(
1057
1291
  recovered_receipts.append(normalized_ref)
1058
1292
 
1059
1293
  item["receiptRefs"] = recovered_receipts
1060
- if surface_recovered or item["disposition"] == "needs_follow_up":
1061
- if not surface_recovered and completeness != "partial":
1062
- warnings.append(
1063
- f"Coverage surface {index + 1} requires follow-up; "
1064
- "marked coverage as partial."
1065
- )
1294
+ if surface_recovered:
1066
1295
  item["disposition"] = "needs_follow_up"
1067
- partial = True
1068
1296
 
1297
+ if field == "deferred":
1298
+ _validate_deferred_paths(item, context)
1069
1299
  _validate_schema_node(item, item_schema, context)
1070
1300
  except ContractError as exc:
1071
1301
  warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
1072
- partial = True
1073
1302
  continue
1074
1303
 
1075
1304
  if field == "surfaces":
@@ -1085,14 +1314,18 @@ def _recover_unsealed_coverage(
1085
1314
  {"id": f"discarded-finding-{index}", "reason": warning}
1086
1315
  for index, warning in enumerate(discarded_findings, 1)
1087
1316
  )
1088
- partial = True
1089
1317
 
1090
- if coverage["deferred"] and completeness != "partial":
1091
- if not discarded_findings:
1092
- warnings.append("Coverage has deferred review work; marked coverage as partial.")
1093
- partial = True
1094
- if partial:
1095
- coverage["completeness"] = "partial"
1318
+ if "resolvedDeferred" in coverage:
1319
+ try:
1320
+ _validate_schema_node(
1321
+ coverage["resolvedDeferred"],
1322
+ properties["resolvedDeferred"],
1323
+ "coverage.resolvedDeferred",
1324
+ )
1325
+ _validate_resolved_deferred(coverage)
1326
+ except ContractError as exc:
1327
+ coverage.pop("resolvedDeferred")
1328
+ warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
1096
1329
 
1097
1330
 
1098
1331
  def _recover_unsealed_hardening(
@@ -1162,11 +1395,14 @@ def _populate_unsealed_manifest_envelope(
1162
1395
  scan["completedAt"] = completion_binding["completedAt"]
1163
1396
  scan["producer"] = copy.deepcopy(completion_binding["producer"])
1164
1397
 
1165
- target = scan.get("target")
1398
+ target = scan.setdefault("target", {})
1166
1399
  if isinstance(target, dict):
1400
+ allowed_kinds = completion_binding["allowedTargetKinds"]
1401
+ if len(allowed_kinds) == 1:
1402
+ target.setdefault("kind", allowed_kinds[0])
1167
1403
  _populate_unsealed_target_binding(target, completion_binding["target"])
1168
1404
 
1169
- scope = scan.get("scope")
1405
+ scope = scan.setdefault("scope", {})
1170
1406
  if isinstance(scope, dict):
1171
1407
  scope.update(copy.deepcopy(completion_binding["scope"]))
1172
1408
 
@@ -1247,17 +1483,6 @@ def _normalize_unsealed_open_questions(coverage: dict[str, Any]) -> None:
1247
1483
  coverage["openQuestions"] = normalized
1248
1484
 
1249
1485
 
1250
- def _normalize_unsealed_deep_repository_inventory_strategy(
1251
- coverage: dict[str, Any],
1252
- *,
1253
- expected_coverage_mode: str | None,
1254
- ) -> None:
1255
- """Label whole-repository Deep scans as using the repository inventory."""
1256
-
1257
- if expected_coverage_mode == "deep_repository":
1258
- coverage["inventoryStrategy"] = "repository"
1259
-
1260
-
1261
1486
  def _validate_completion_binding(
1262
1487
  manifest: dict[str, Any],
1263
1488
  findings: dict[str, Any],
@@ -1301,6 +1526,14 @@ def _validate_completion_binding(
1301
1526
  raise ContractError(f"coverage.{key}: must match the workbench scan")
1302
1527
 
1303
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
+
1304
1537
  def _validate_finding(finding: dict[str, Any], context: str) -> None:
1305
1538
  for key in ("findingId", "occurrenceId", "ruleId", "title", "summary", "remediation"):
1306
1539
  _require_str(finding, key, context)
@@ -1358,6 +1591,11 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1358
1591
  raise ContractError(f"{evidence_context}.id: duplicate code-evidence id")
1359
1592
  evidence_ids.add(evidence_id)
1360
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
+ )
1361
1599
 
1362
1600
  referenced_sections = [
1363
1601
  (section_name, finding.get(section_name))
@@ -1394,13 +1632,45 @@ def _validate_finding(finding: dict[str, Any], context: str) -> None:
1394
1632
  raise ContractError(f"{context}.extensions: expected an object")
1395
1633
 
1396
1634
 
1635
+ def _validate_resolved_deferred(coverage: dict[str, Any]) -> None:
1636
+ if "resolvedDeferred" not in coverage:
1637
+ return
1638
+ active = {
1639
+ identity
1640
+ for row in coverage.get("deferred", [])
1641
+ if isinstance(row, dict)
1642
+ for identity in (row.get("id"), row.get("candidateId"))
1643
+ if isinstance(identity, str)
1644
+ }
1645
+ resolved: set[str] = set()
1646
+ for index, closure in enumerate(_require_list(coverage, "resolvedDeferred", "coverage")):
1647
+ context = f"coverage.resolvedDeferred[{index}]"
1648
+ if not isinstance(closure, dict):
1649
+ raise ContractError(f"{context}: expected an object")
1650
+ closure_id = _require_str(closure, "id", context)
1651
+ _require_str(closure, "reason", context)
1652
+ if closure_id in resolved:
1653
+ raise ContractError(f"{context}.id: duplicate resolved deferred id")
1654
+ if closure_id in active:
1655
+ raise ContractError(f"{context}.id: deferred work is still active")
1656
+ resolved.add(closure_id)
1657
+
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
+
1397
1668
  def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_dir: Path) -> None:
1398
1669
  scan = _require_dict(manifest, "scan", "manifest")
1399
1670
  scan_id = _require_str(scan, "id", "manifest.scan")
1400
1671
  if coverage.get("scanId") != scan_id:
1401
1672
  raise ContractError("coverage.scanId: must match manifest scan id")
1402
1673
  _require_str(coverage, "mode", "coverage")
1403
- completeness = _require_str(coverage, "completeness", "coverage")
1404
1674
  _require_str(coverage, "inventoryStrategy", "coverage")
1405
1675
  scope = _require_dict(scan, "scope", "manifest.scan")
1406
1676
  if coverage.get("includePaths") != scope.get("includePaths"):
@@ -1408,7 +1678,6 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1408
1678
  if coverage.get("excludePaths") != scope.get("excludePaths"):
1409
1679
  raise ContractError("coverage.excludePaths: must match manifest scope")
1410
1680
  surface_ids: set[str] = set()
1411
- has_needs_follow_up = False
1412
1681
  for index, surface in enumerate(_require_list(coverage, "surfaces", "coverage")):
1413
1682
  context = f"coverage.surfaces[{index}]"
1414
1683
  if not isinstance(surface, dict):
@@ -1421,7 +1690,6 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1421
1690
  disposition = _require_str(surface, "disposition", context)
1422
1691
  if disposition not in DISPOSITIONS:
1423
1692
  raise ContractError(f"{context}.disposition: unsupported disposition: {disposition}")
1424
- has_needs_follow_up = has_needs_follow_up or disposition == "needs_follow_up"
1425
1693
  receipt_refs = surface.get("receiptRefs", [])
1426
1694
  if not isinstance(receipt_refs, list):
1427
1695
  raise ContractError(f"{context}.receiptRefs: expected an array")
@@ -1442,8 +1710,10 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
1442
1710
  for field in ("explicitExclusions", "deferred"):
1443
1711
  if not isinstance(coverage.get(field, []), list):
1444
1712
  raise ContractError(f"coverage.{field}: expected an array")
1445
- if completeness == "complete" and (has_needs_follow_up or coverage.get("deferred")):
1446
- raise ContractError("coverage.completeness: complete coverage cannot have deferred work")
1713
+ for index, deferred in enumerate(coverage.get("deferred", [])):
1714
+ if isinstance(deferred, dict):
1715
+ _validate_deferred_paths(deferred, f"coverage.deferred[{index}]")
1716
+ _validate_resolved_deferred(coverage)
1447
1717
  _require_safe_json_value(coverage, "coverage.json")
1448
1718
 
1449
1719
 
@@ -1522,16 +1792,22 @@ def _validate_findings(manifest: dict[str, Any], findings: dict[str, Any]) -> No
1522
1792
  _require_safe_json_value(findings, "findings.json")
1523
1793
 
1524
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
+
1525
1805
  def _schema_type_matches(value: Any, expected: str) -> bool:
1526
- return {
1527
- "array": isinstance(value, list),
1528
- "boolean": isinstance(value, bool),
1529
- "integer": isinstance(value, int) and not isinstance(value, bool),
1530
- "number": isinstance(value, (int, float)) and not isinstance(value, bool),
1531
- "object": isinstance(value, dict),
1532
- "string": isinstance(value, str),
1533
- "null": value is None,
1534
- }[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
+ )
1535
1811
 
1536
1812
 
1537
1813
  def _schema_values_equal(left: Any, right: Any) -> bool:
@@ -1581,6 +1857,17 @@ def _validate_schema_node(
1581
1857
  root_schema: dict[str, Any] | None = None,
1582
1858
  ) -> None:
1583
1859
  root_schema = schema if root_schema is None else root_schema
1860
+ alternatives = schema.get("anyOf")
1861
+ if isinstance(alternatives, list):
1862
+ errors = []
1863
+ for alternative in alternatives:
1864
+ try:
1865
+ _validate_schema_node(value, alternative, context, root_schema)
1866
+ break
1867
+ except ContractError as exc:
1868
+ errors.append(str(exc))
1869
+ else:
1870
+ raise ContractError(f"{context}: no schema alternative matched: {'; '.join(errors)}")
1584
1871
  reference = schema.get("$ref")
1585
1872
  if reference is not None:
1586
1873
  if not isinstance(reference, str):
@@ -1591,6 +1878,8 @@ def _validate_schema_node(
1591
1878
  context,
1592
1879
  root_schema,
1593
1880
  )
1881
+ if len(schema) == 1:
1882
+ return
1594
1883
  expected = schema.get("type")
1595
1884
  if isinstance(expected, list):
1596
1885
  if not any(_schema_type_matches(value, item) for item in expected):
@@ -1606,7 +1895,9 @@ def _validate_schema_node(
1606
1895
  if isinstance(value, str):
1607
1896
  if schema.get("minLength", 0) and len(value) < schema["minLength"]:
1608
1897
  raise ContractError(f"{context}: string is too short")
1609
- 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):
1610
1901
  raise ContractError(f"{context}: string does not match schema pattern")
1611
1902
  if schema.get("format") == "date-time":
1612
1903
  _validate_date_time(value, context)
@@ -1664,6 +1955,8 @@ def _validate_schema_node(
1664
1955
  additional_properties = schema.get("additionalProperties", True)
1665
1956
  for key, item in value.items():
1666
1957
  item_schema = properties.get(key)
1958
+ if item_schema is False:
1959
+ raise ContractError(f"{context}.{key}: unexpected schema property")
1667
1960
  if isinstance(item_schema, dict):
1668
1961
  _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
1669
1962
  elif additional_properties is False:
@@ -1682,6 +1975,38 @@ def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
1682
1975
  _validate_schema_node(payload, schema, schema_path.stem, schema)
1683
1976
 
1684
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
+
1685
2010
  def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
1686
2011
  for refs_field in ("evidenceRefs", "evidence_refs"):
1687
2012
  refs = section.get(refs_field)
@@ -1726,7 +2051,7 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1726
2051
  continue
1727
2052
  canonical_evidence = finding.get("codeEvidence")
1728
2053
  canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
1729
- canonical_evidence_ids = {
2054
+ evidence_ids = {
1730
2055
  evidence["id"]
1731
2056
  for evidence in canonical_evidence
1732
2057
  if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
@@ -1734,7 +2059,6 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1734
2059
  legacy_evidence = finding.get("code_evidence")
1735
2060
  if isinstance(legacy_evidence, list):
1736
2061
  compatible_legacy_evidence = []
1737
- seen_evidence_ids = set(canonical_evidence_ids)
1738
2062
  for evidence in legacy_evidence:
1739
2063
  if not isinstance(evidence, dict):
1740
2064
  continue
@@ -1747,22 +2071,13 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1747
2071
  or not evidence_code.strip()
1748
2072
  ):
1749
2073
  continue
1750
- if evidence_id in seen_evidence_ids:
2074
+ if evidence_id in evidence_ids:
1751
2075
  continue
1752
- seen_evidence_ids.add(evidence_id)
2076
+ evidence_ids.add(evidence_id)
1753
2077
  compatible_legacy_evidence.append(evidence)
1754
2078
  finding["code_evidence"] = compatible_legacy_evidence
1755
2079
  elif "code_evidence" in finding:
1756
2080
  finding.pop("code_evidence")
1757
- compatible_legacy_evidence = finding.get("code_evidence")
1758
- compatible_legacy_evidence = (
1759
- compatible_legacy_evidence if isinstance(compatible_legacy_evidence, list) else []
1760
- )
1761
- evidence_ids = canonical_evidence_ids | {
1762
- evidence["id"]
1763
- for evidence in compatible_legacy_evidence
1764
- if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
1765
- }
1766
2081
  for section_name, list_fields in (
1767
2082
  ("rootCause", ("evidenceRefs", "evidence_refs")),
1768
2083
  ("root_cause", ("evidenceRefs", "evidence_refs")),
@@ -1817,29 +2132,20 @@ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str
1817
2132
  continue
1818
2133
  _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
1819
2134
  for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
1820
- if field not in attack_path:
1821
- continue
1822
2135
  detail = attack_path.get(field)
1823
- if detail is None:
1824
- attack_path.pop(field)
1825
- continue
1826
- if not isinstance(detail, (str, dict)):
1827
- attack_path.pop(field)
1828
- continue
1829
- if isinstance(detail, str):
1830
- if detail == "":
1831
- attack_path.pop(field)
1832
- continue
1833
- detail_scalar_fields = ("summary", "source", "sink", "outcome")
1834
- if field == "reachability":
1835
- detail_scalar_fields += ("attacker", "entrypoint")
1836
- _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
1837
- _normalize_legacy_string_list_fields(
1838
- detail, ("evidenceRefs", "evidence_refs", "transformations")
1839
- )
1840
- _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
1841
- if field == "reachability":
1842
- _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)
1843
2149
  for field in ("impact", "likelihood"):
1844
2150
  detail = attack_path.get(field)
1845
2151
  if isinstance(detail, dict):
@@ -1937,12 +2243,6 @@ def _sarif_finding_message(finding: dict[str, Any]) -> str:
1937
2243
  return "\n\n".join(details)
1938
2244
 
1939
2245
 
1940
- def _utf16_code_units(value: str) -> Iterator[int]:
1941
- encoded = value.encode("utf-16-le")
1942
- for index in range(0, len(encoded), 2):
1943
- yield int.from_bytes(encoded[index : index + 2], "little")
1944
-
1945
-
1946
2246
  def _github_line_hashes(
1947
2247
  handle: TextIO,
1948
2248
  requested_lines: set[int] | None = None,
@@ -1995,7 +2295,7 @@ def _github_line_hashes(
1995
2295
  update_hash(current)
1996
2296
 
1997
2297
  while chunk := handle.read(SOURCE_READ_CHUNK_SIZE):
1998
- for code_unit in _utf16_code_units(chunk):
2298
+ for (code_unit,) in struct.iter_unpack("<H", chunk.encode("utf-16-le")):
1999
2299
  process_character(code_unit)
2000
2300
  process_character(GITHUB_HASH_EOF)
2001
2301
  for _ in range(GITHUB_HASH_BLOCK_SIZE):
@@ -2009,7 +2309,7 @@ def _open_source_file(source_root: Path, relative_path: str) -> TextIO | None:
2009
2309
  file_fd: int | None = None
2010
2310
  try:
2011
2311
  file_fd = open_scan_local_file_descriptor(
2012
- source_root, relative_path, f"source file {relative_path}"
2312
+ source_root, relative_path, f"source file {relative_path}", portable=False
2013
2313
  )
2014
2314
  handle = os.fdopen(file_fd, "r", encoding="utf-8", errors="replace")
2015
2315
  file_fd = None
@@ -2194,7 +2494,7 @@ def _github_line_hash_cache(
2194
2494
  return line_hash_cache
2195
2495
 
2196
2496
 
2197
- 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]:
2198
2498
  sarif_location: dict[str, Any] = {
2199
2499
  "physicalLocation": {
2200
2500
  "artifactLocation": {
@@ -2206,8 +2506,6 @@ def _sarif_location(location: dict[str, Any], location_id: int | None = None) ->
2206
2506
  },
2207
2507
  }
2208
2508
  }
2209
- if location_id is not None:
2210
- sarif_location["id"] = location_id
2211
2509
  if location.get("role"):
2212
2510
  sarif_location["message"] = {"text": location["role"]}
2213
2511
  return sarif_location
@@ -2236,7 +2534,7 @@ def _sarif_result(
2236
2534
  line_hash = _github_primary_location_line_hash(finding, source_root, line_hash_cache)
2237
2535
  if line_hash is not None:
2238
2536
  partial_fingerprints["primaryLocationLineHash"] = line_hash
2239
- result = {
2537
+ return {
2240
2538
  "ruleId": finding["ruleId"],
2241
2539
  "ruleIndex": rule_index,
2242
2540
  "level": SARIF_LEVELS[finding["severity"]["level"]],
@@ -2245,7 +2543,6 @@ def _sarif_result(
2245
2543
  "partialFingerprints": partial_fingerprints,
2246
2544
  "properties": properties,
2247
2545
  }
2248
- return result
2249
2546
 
2250
2547
 
2251
2548
  def build_sarif(
@@ -2294,23 +2591,6 @@ def build_sarif(
2294
2591
  }
2295
2592
 
2296
2593
 
2297
- def _validate_sarif(sarif: dict[str, Any]) -> None:
2298
- if sarif.get("version") != "2.1.0":
2299
- raise ContractError("SARIF: expected version 2.1.0")
2300
- runs = sarif.get("runs")
2301
- if not isinstance(runs, list) or len(runs) != 1:
2302
- raise ContractError("SARIF: expected exactly one run")
2303
- run = runs[0]
2304
- if not isinstance(run, dict):
2305
- raise ContractError("SARIF: expected a run object")
2306
- rule_ids = [rule["id"] for rule in run["tool"]["driver"]["rules"]]
2307
- for result in run["results"]:
2308
- if result["ruleId"] not in rule_ids:
2309
- raise ContractError("SARIF: result references an unknown rule")
2310
- if not result.get("partialFingerprints"):
2311
- raise ContractError("SARIF: result is missing partialFingerprints")
2312
-
2313
-
2314
2594
  def _artifact_record(
2315
2595
  scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
2316
2596
  ) -> dict[str, str]:
@@ -2321,16 +2601,30 @@ def _artifact_record(
2321
2601
  "mediaType": media_type,
2322
2602
  "path": relative_path,
2323
2603
  "sha256": (
2324
- _sha256_bytes(contents)
2604
+ hashlib.sha256(contents).hexdigest()
2325
2605
  if contents is not None
2326
2606
  else _sha256_scan_local_file(scan_dir, relative_path, relative_path)
2327
2607
  ),
2328
2608
  }
2329
2609
 
2330
2610
 
2331
- def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
2332
- refs = {ref for surface in coverage["surfaces"] for ref in surface.get("receiptRefs", [])}
2333
- 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)}
2334
2628
 
2335
2629
 
2336
2630
  def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
@@ -2338,9 +2632,9 @@ def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str,
2338
2632
  _require_portable_relative_path(artifact["path"], "sealed artifact path")
2339
2633
  for artifact in scan["artifacts"]
2340
2634
  }
2341
- for ref in _coverage_receipt_refs(coverage):
2635
+ for ref, context in _supplementary_artifact_refs(scan, coverage).items():
2342
2636
  if ref not in artifact_paths:
2343
- raise ContractError(f"coverage receipt is missing from sealed artifacts: {ref}")
2637
+ raise ContractError(f"{context} is missing from sealed artifacts: {ref}")
2344
2638
 
2345
2639
 
2346
2640
  def _validate_existing_seal(
@@ -2357,7 +2651,6 @@ def _validate_existing_seal(
2357
2651
  raise ContractError("manifest.scan.sealedAt: must match completedAt")
2358
2652
  if not isinstance(artifacts, list) or not artifacts:
2359
2653
  raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
2360
- artifact_paths: set[str] = set()
2361
2654
  artifact_collision_keys: set[str] = set()
2362
2655
  for index, artifact in enumerate(artifacts):
2363
2656
  context = f"manifest.scan.artifacts[{index}]"
@@ -2369,12 +2662,11 @@ def _validate_existing_seal(
2369
2662
  collision_key = path.lower()
2370
2663
  if collision_key in artifact_collision_keys:
2371
2664
  raise ContractError(f"{context}.path: duplicate artifact path")
2372
- artifact_paths.add(path)
2373
2665
  artifact_collision_keys.add(collision_key)
2374
2666
  expected_sha256 = _require_str(artifact, "sha256", context)
2375
2667
  contents = (artifact_contents or {}).get(path)
2376
2668
  actual_sha256 = (
2377
- _sha256_bytes(contents)
2669
+ hashlib.sha256(contents).hexdigest()
2378
2670
  if contents is not None
2379
2671
  else _sha256_scan_local_file(scan_dir, path, context)
2380
2672
  )
@@ -2382,16 +2674,9 @@ def _validate_existing_seal(
2382
2674
  raise ContractError(f"{context}: sealed artifact changed or is missing")
2383
2675
 
2384
2676
 
2385
- def _read_sealed_scan(
2386
- scan_dir: Path, schema_dir: Path | None, required_for: str
2387
- ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], bytes]:
2388
- scan_dir = _require_scan_directory(scan_dir)
2389
- schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2390
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2391
- scan = _require_dict(manifest, "scan", "manifest")
2392
- _validate_contract_refs(scan)
2393
- if scan.get("sealedAt") is None or scan.get("artifacts") is None:
2394
- 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]:
2395
2680
  findings, findings_bytes = _read_scan_local_json_bytes(
2396
2681
  scan_dir, scan["findingsRef"], scan["findingsRef"]
2397
2682
  )
@@ -2406,6 +2691,20 @@ def _read_sealed_scan(
2406
2691
  scan["coverageRef"]: coverage_bytes,
2407
2692
  },
2408
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)
2409
2708
  _validate_manifest(manifest)
2410
2709
  findings_for_validation = _legacy_sealed_findings_for_validation(findings)
2411
2710
  _validate_findings(manifest, findings_for_validation)
@@ -2432,9 +2731,8 @@ def build_sarif_projection(
2432
2731
  manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
2433
2732
  sarif = build_sarif(manifest, findings, source_root)
2434
2733
  execution_successful = manifest["scan"]["status"] == "completed"
2435
- if not execution_successful or coverage["completeness"] != "complete":
2734
+ if not execution_successful or coverage["deferred"]:
2436
2735
  run = sarif["runs"][0]
2437
- run["properties"]["codexSecurityCoverageCompleteness"] = coverage["completeness"]
2438
2736
  run["invocations"] = [
2439
2737
  {
2440
2738
  "executionSuccessful": execution_successful,
@@ -2444,7 +2742,6 @@ def build_sarif_projection(
2444
2742
  ],
2445
2743
  }
2446
2744
  ]
2447
- _validate_sarif(sarif)
2448
2745
  return sarif
2449
2746
 
2450
2747
 
@@ -2455,13 +2752,9 @@ def write_sarif_projection(
2455
2752
  _write_scan_local_json(scan_dir, "exports/results.sarif", sarif)
2456
2753
 
2457
2754
 
2458
- def write_sarif_output(scan_dir: Path, output: Path, sarif: dict[str, Any]) -> None:
2459
- write_export_output(scan_dir, output, "sarif", _json_bytes(sarif))
2460
-
2461
-
2462
2755
  def csv_cell(value: Any) -> Any:
2463
2756
  if isinstance(value, str) and (
2464
- value.startswith(("\t", "\r", "\n"))
2757
+ value.startswith(("'", "\t", "\r", "\n"))
2465
2758
  or value.lstrip().startswith(("=", "+", "-", "@", "=", "+", "-", "@"))
2466
2759
  ):
2467
2760
  return f"'{value}"
@@ -2489,45 +2782,32 @@ def finding_candidate_id(finding: dict[str, Any]) -> str | None:
2489
2782
  )
2490
2783
 
2491
2784
 
2785
+ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
2786
+ return (
2787
+ "occurrence_id",
2788
+ "finding_id",
2789
+ *(("candidate_id",) if deep_scan else ()),
2790
+ "title",
2791
+ "summary",
2792
+ "severity",
2793
+ "confidence",
2794
+ "status",
2795
+ "close_reason",
2796
+ "note",
2797
+ "remediation",
2798
+ "path",
2799
+ "start_line",
2800
+ "end_line",
2801
+ )
2802
+
2803
+
2492
2804
  def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
2493
2805
  output = io.StringIO(newline="")
2494
2806
  writer = csv.writer(output)
2495
- deep_scan = coverage.get("mode") == "deep_repository" or (
2496
- coverage.get("mode") == "scoped_path"
2497
- and any(
2498
- isinstance(finding.get("extensions"), dict)
2499
- and any(
2500
- isinstance(finding["extensions"].get(field), str)
2501
- and finding["extensions"][field].strip()
2502
- for field in ("candidateId", "reportId")
2503
- )
2504
- for finding in findings["findings"]
2505
- )
2506
- )
2507
- writer.writerow(
2508
- (
2509
- "occurrence_id",
2510
- "finding_id",
2511
- *(("candidate_id",) if deep_scan else ()),
2512
- "title",
2513
- "summary",
2514
- "severity",
2515
- "confidence",
2516
- "status",
2517
- "close_reason",
2518
- "note",
2519
- "remediation",
2520
- "path",
2521
- "start_line",
2522
- "end_line",
2523
- )
2524
- )
2807
+ deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
2808
+ writer.writerow(finding_csv_columns(deep_scan))
2525
2809
  for finding in findings["findings"]:
2526
- locations = finding["locations"]
2527
- location = next(
2528
- (candidate for candidate in locations if candidate.get("role") == "root_control"),
2529
- locations[0],
2530
- )
2810
+ location = _sarif_primary_location(finding)
2531
2811
  writer.writerow(
2532
2812
  (
2533
2813
  csv_cell(finding["occurrenceId"]),
@@ -2570,7 +2850,8 @@ def build_findings_export(
2570
2850
 
2571
2851
 
2572
2852
  def write_export_output(scan_dir: Path, output: Path, export_format: str, contents: bytes) -> None:
2573
- if export_format not in EXPORT_PATHS:
2853
+ output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
2854
+ if export_format not in output_paths:
2574
2855
  raise ContractError(f"unsupported export format: {export_format}")
2575
2856
  scan_dir = _require_scan_directory(scan_dir)
2576
2857
  output = Path(os.path.abspath(output))
@@ -2594,13 +2875,22 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2594
2875
  relative_output = output.relative_to(ancestor).as_posix()
2595
2876
  break
2596
2877
  else:
2597
- write_scan_local_bytes(output.parent, output.name, contents, external_name=True)
2878
+ write_scan_local_bytes(
2879
+ output.parent,
2880
+ output.name,
2881
+ contents,
2882
+ external_name=True,
2883
+ owner_read_write=export_format == "md",
2884
+ )
2598
2885
  return
2599
- if relative_output != EXPORT_PATHS[export_format]:
2886
+ if relative_output != output_paths[export_format]:
2600
2887
  raise ContractError(f"{export_format.upper()} output path cannot overwrite a scan artifact")
2601
- manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2602
- scan = _require_dict(manifest, "scan", "manifest")
2603
- artifacts = _require_list(scan, "artifacts", "manifest.scan")
2888
+ if (scan_dir / "scan-manifest.json").exists():
2889
+ manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
2890
+ scan = _require_dict(manifest, "scan", "manifest")
2891
+ artifacts = scan.get("artifacts", [])
2892
+ else:
2893
+ artifacts = []
2604
2894
  artifact_paths = [
2605
2895
  _require_portable_relative_path(
2606
2896
  _require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
@@ -2617,7 +2907,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2617
2907
  raise ContractError(f"{relative_output}: unable to inspect export output") from exc
2618
2908
  for artifact_path in artifact_paths:
2619
2909
  if artifact_path == relative_output:
2620
- raise ContractError(
2910
+ raise SealedArtifactError(
2621
2911
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2622
2912
  )
2623
2913
  if output_metadata is None:
@@ -2630,10 +2920,12 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
2630
2920
  finally:
2631
2921
  os.close(descriptor)
2632
2922
  if os.path.samestat(output_metadata, artifact_metadata):
2633
- raise ContractError(
2923
+ raise SealedArtifactError(
2634
2924
  f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
2635
2925
  )
2636
- write_scan_local_bytes(scan_dir, relative_output, contents)
2926
+ write_scan_local_bytes(
2927
+ scan_dir, relative_output, contents, owner_read_write=export_format == "md"
2928
+ )
2637
2929
 
2638
2930
 
2639
2931
  def _write_sarif_projection_if_possible(
@@ -2649,15 +2941,15 @@ def _write_sarif_projection_if_possible(
2649
2941
  )
2650
2942
 
2651
2943
 
2652
- PreparedScanFinalization = tuple[
2653
- Path,
2654
- Path,
2655
- dict[str, Any],
2656
- dict[str, Any],
2657
- dict[str, Any],
2658
- bool,
2659
- bytes,
2660
- ]
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]
2661
2953
 
2662
2954
 
2663
2955
  def _prepare_scan_finalization(
@@ -2666,11 +2958,14 @@ def _prepare_scan_finalization(
2666
2958
  *,
2667
2959
  expected_coverage_mode: str | None = None,
2668
2960
  completion_binding: dict[str, Any] | None = None,
2669
- completion_warnings: list[str] | None = None,
2961
+ recover_unsealed: bool = False,
2962
+ allow_missing_writeups: bool = False,
2670
2963
  draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
2964
+ finding_scope: list[tuple[str, bool]] | None = None,
2671
2965
  ) -> PreparedScanFinalization:
2672
- """Read, populate, and validate a scan without writing any output files."""
2966
+ """Prepare validated documents and warnings without writing any output files."""
2673
2967
 
2968
+ warnings: list[str] = []
2674
2969
  scan_dir = _require_scan_directory(scan_dir)
2675
2970
  schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
2676
2971
  manifest = (
@@ -2696,11 +2991,12 @@ def _prepare_scan_finalization(
2696
2991
  findings, coverage = copy.deepcopy(draft_documents[1:])
2697
2992
  findings_input_bytes, coverage_input_bytes = _json_bytes(findings), _json_bytes(coverage)
2698
2993
  if not was_sealed:
2994
+ # Preserve legacy sealed bundles, but do not publish a completeness claim.
2995
+ coverage.pop("completeness", None)
2699
2996
  _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
2700
- _normalize_unsealed_deep_repository_inventory_strategy(
2701
- coverage,
2702
- expected_coverage_mode=expected_coverage_mode,
2703
- )
2997
+ # Label whole-repository Deep scans as using the repository inventory.
2998
+ if expected_coverage_mode == "deep_repository":
2999
+ coverage["inventoryStrategy"] = "repository"
2704
3000
  _normalize_unsealed_open_questions(coverage)
2705
3001
 
2706
3002
  if manifest.get("schemaVersion") != SCHEMA_VERSION:
@@ -2731,103 +3027,131 @@ def _prepare_scan_finalization(
2731
3027
  findings_for_validation = (
2732
3028
  _legacy_sealed_findings_for_validation(findings) if was_sealed else findings
2733
3029
  )
2734
- if was_sealed:
2735
- _validate_findings(manifest, findings_for_validation)
2736
- _validate_derived_finding_identities(manifest, findings)
2737
- elif 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:
2738
3042
  discarded_findings = _recover_unsealed_findings(
2739
- manifest, findings, schema_dir, scan_dir, completion_warnings
3043
+ manifest, findings, schema_dir, scan_dir, warnings
2740
3044
  )
2741
- _recover_unsealed_coverage(
2742
- coverage, schema_dir, scan_dir, completion_warnings, discarded_findings
2743
- )
2744
- _recover_unsealed_hardening(manifest, scan_dir, completion_warnings)
2745
- else:
3045
+ elif not was_sealed:
2746
3046
  _populate_unsealed_finding_identities(manifest, findings)
2747
- _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)
3052
+ if was_sealed:
3053
+ _validate_derived_finding_identities(manifest, findings)
2748
3054
  _validate_coverage(manifest, coverage, scan_dir)
2749
3055
  _validate_canonical_schemas_before_projection(
2750
3056
  manifest, findings_for_validation, coverage, schema_dir
2751
3057
  )
2752
- _require_derived_writeup_files(scan_dir, findings)
2753
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
+ )
2754
3094
  if was_sealed:
2755
3095
  _validate_sealed_coverage_receipts(scan, coverage)
2756
3096
  _validate_manifest(manifest)
2757
3097
  validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2758
- validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2759
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2760
3098
  report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2761
- _validate_report_output_paths(scan_dir)
2762
- return (
2763
- scan_dir,
2764
- schema_dir,
2765
- manifest,
2766
- findings,
2767
- coverage,
2768
- was_sealed,
2769
- report_markdown_bytes,
2770
- )
2771
-
2772
- findings_bytes = _contract_json_bytes("findings.json", findings)
2773
- coverage_bytes = _contract_json_bytes("coverage.json", coverage)
2774
- report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
2775
- _validate_report_output_paths(scan_dir)
2776
- scan["artifacts"] = [
2777
- _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
2778
- _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
2779
- *[
2780
- _artifact_record(scan_dir, ref, "application/octet-stream")
2781
- for ref in _coverage_receipt_refs(coverage)
2782
- ],
2783
- ]
2784
- _validate_sealed_coverage_receipts(scan, coverage)
2785
- _validate_manifest(manifest)
2786
- validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
2787
- validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
2788
- validate_against_schema(coverage, schema_dir / "coverage.schema.json")
2789
- _contract_json_bytes("scan-manifest.json", manifest)
2790
- return (
2791
- scan_dir,
2792
- schema_dir,
2793
- manifest,
2794
- findings,
2795
- coverage,
2796
- was_sealed,
2797
- report_markdown_bytes,
3099
+ _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3100
+ else:
3101
+ findings_bytes = _contract_json_bytes("findings.json", findings)
3102
+ coverage_bytes = _contract_json_bytes("coverage.json", coverage)
3103
+ report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
3104
+ _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
3105
+ scan["artifacts"] = [
3106
+ _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
3107
+ _artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes),
3108
+ *[
3109
+ _artifact_record(scan_dir, ref, "application/octet-stream")
3110
+ for ref in _supplementary_artifact_refs(scan, coverage)
3111
+ ],
3112
+ ]
3113
+ _validate_manifest(manifest)
3114
+ validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
3115
+ _contract_json_bytes("scan-manifest.json", manifest)
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,
2798
3125
  )
2799
3126
 
2800
3127
 
2801
3128
  def _write_prepared_scan_finalization(
2802
3129
  prepared: PreparedScanFinalization,
2803
3130
  source_root: Path | None = None,
3131
+ *,
3132
+ projection_warnings: list[str] | None = None,
2804
3133
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
2805
3134
  """Write a previously validated scan finalization result."""
2806
3135
 
2807
- (
2808
- scan_dir,
2809
- schema_dir,
2810
- manifest,
2811
- findings,
2812
- coverage,
2813
- was_sealed,
2814
- report_markdown_bytes,
2815
- ) = prepared
2816
- scan = _require_dict(manifest, "scan", "manifest")
2817
- if was_sealed:
2818
- write_scan_local_bytes(scan_dir, "report.md", report_markdown_bytes)
2819
- _remove_scan_local_file_if_exists(scan_dir, "report.html")
2820
- _write_sarif_projection_if_possible(scan_dir, source_root, schema_dir)
2821
- return manifest, findings, coverage
2822
-
2823
- _write_scan_local_json(scan_dir, "findings.json", findings)
2824
- _write_scan_local_json(scan_dir, "coverage.json", coverage)
2825
- 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)
2826
3142
  _remove_scan_local_file_if_exists(scan_dir, "report.html")
2827
- _write_scan_local_json(scan_dir, "scan-manifest.json", manifest)
2828
- _validate_existing_seal(scan_dir, scan)
2829
- _write_sarif_projection_if_possible(scan_dir, source_root, schema_dir)
2830
- return manifest, findings, coverage
3143
+ if not prepared.was_sealed:
3144
+ _write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
3145
+ _validate_existing_seal(scan_dir, scan)
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)
3148
+ if (
3149
+ warning is not None
3150
+ and projection_warnings is not None
3151
+ and warning not in projection_warnings
3152
+ ):
3153
+ projection_warnings.append(warning)
3154
+ return prepared.manifest, prepared.findings, prepared.coverage
2831
3155
 
2832
3156
 
2833
3157
  def finalize_scan(
@@ -2837,6 +3161,7 @@ def finalize_scan(
2837
3161
  *,
2838
3162
  expected_coverage_mode: str | None = None,
2839
3163
  completion_binding: dict[str, Any] | None = None,
3164
+ projection_warnings: list[str] | None = None,
2840
3165
  ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
2841
3166
  prepared = _prepare_scan_finalization(
2842
3167
  scan_dir,
@@ -2844,7 +3169,9 @@ def finalize_scan(
2844
3169
  expected_coverage_mode=expected_coverage_mode,
2845
3170
  completion_binding=completion_binding,
2846
3171
  )
2847
- return _write_prepared_scan_finalization(prepared, source_root)
3172
+ return _write_prepared_scan_finalization(
3173
+ prepared, source_root, projection_warnings=projection_warnings
3174
+ )
2848
3175
 
2849
3176
 
2850
3177
  def main() -> int:
@@ -2854,30 +3181,61 @@ def main() -> int:
2854
3181
  parser.add_argument("--source-root", type=Path)
2855
3182
  parser.add_argument("--sarif-only", action="store_true")
2856
3183
  parser.add_argument("--sarif-output", type=Path)
2857
- parser.add_argument("--export-format", choices=sorted(EXPORT_PATHS))
3184
+ parser.add_argument(
3185
+ "--export-artifact", choices=("findings", "threat-model"), default="findings"
3186
+ )
3187
+ parser.add_argument("--export-format", choices=[*sorted(EXPORT_PATHS), "md"])
2858
3188
  parser.add_argument("--export-output", type=Path)
3189
+ parser.add_argument("--export-metadata", action="store_true")
3190
+ parser.add_argument("--describe-threat-model", action="store_true")
3191
+ parser.add_argument("--write-threat-model", action="store_true")
2859
3192
  args = parser.parse_args()
2860
3193
  try:
3194
+ args.scan_dir = args.scan_dir.resolve()
3195
+ if args.describe_threat_model:
3196
+ sys.stdout.buffer.write(
3197
+ _json_bytes(describe_threat_model(args.scan_dir, args.schema_dir))
3198
+ )
3199
+ return 0
3200
+ if args.write_threat_model:
3201
+ write_threat_model_projection_if_possible(args.scan_dir)
3202
+ return 0
3203
+ if args.export_artifact == "threat-model" and args.export_format is None:
3204
+ args.export_format = "md"
3205
+ if args.export_metadata and (
3206
+ args.export_artifact != "threat-model" or args.export_output is None
3207
+ ):
3208
+ parser.error("--export-metadata requires a threat-model export with --export-output")
2861
3209
  if args.sarif_only and args.export_format is not None:
2862
3210
  parser.error("--sarif-only cannot be combined with --export-format")
2863
3211
  if args.export_output is not None and args.export_format is None:
2864
3212
  parser.error("--export-output requires --export-format")
2865
3213
  if args.sarif_output is not None and not args.sarif_only:
2866
3214
  parser.error("--sarif-output requires --sarif-only")
3215
+ if args.sarif_only:
3216
+ args.export_format, args.export_output = "sarif", args.sarif_output
2867
3217
  if args.export_format is not None:
2868
- contents = build_findings_export(
2869
- args.scan_dir, args.export_format, args.source_root, args.schema_dir
2870
- )
3218
+ if args.export_artifact == "threat-model":
3219
+ if args.export_format != "md":
3220
+ parser.error("threat-model exports require --export-format md")
3221
+ if args.source_root is not None:
3222
+ parser.error("source-root is only supported for SARIF exports")
3223
+ saved = _read_saved_threat_model(args.scan_dir, schema_dir=args.schema_dir)
3224
+ if saved is None:
3225
+ raise ContractError("No saved threat model is available for this result.")
3226
+ description, contents = saved
3227
+ else:
3228
+ contents = build_findings_export(
3229
+ args.scan_dir, args.export_format, args.source_root, args.schema_dir
3230
+ )
2871
3231
  if args.export_output is None:
2872
3232
  sys.stdout.buffer.write(contents)
2873
3233
  else:
2874
3234
  write_export_output(args.scan_dir, args.export_output, args.export_format, contents)
2875
- elif args.sarif_only:
2876
- sarif = build_sarif_projection(args.scan_dir, args.source_root, args.schema_dir)
2877
- if args.sarif_output is None:
2878
- sys.stdout.buffer.write(_json_bytes(sarif))
2879
- else:
2880
- write_sarif_output(args.scan_dir, args.sarif_output, sarif)
3235
+ if args.export_metadata:
3236
+ sys.stdout.buffer.write(
3237
+ _json_bytes({**description, "path": str(args.export_output.absolute())})
3238
+ )
2881
3239
  else:
2882
3240
  finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
2883
3241
  except ContractError as exc: