@openai/codex-security 0.8.3 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (534) hide show
  1. package/README.md +192 -151
  2. package/_bundled_plugin/.mcp.json +5 -1
  3. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  4. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  6. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  7. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  8. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  9. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  10. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/package.json +1 -0
  19. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  20. package/_bundled_plugin/mcp/server.mjs +2 -11
  21. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  22. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  23. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  24. package/_bundled_plugin/references/final-report.md +5 -3
  25. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  26. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  27. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  28. package/_bundled_plugin/references/scan-contract.md +27 -33
  29. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  30. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  31. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  32. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  33. package/_bundled_plugin/scripts/deep_scan_workbench.py +165 -342
  34. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  35. package/_bundled_plugin/scripts/finalize_scan_contract.py +153 -227
  36. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  37. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  38. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  39. package/_bundled_plugin/scripts/posix_scan_local_files.py +11 -0
  40. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  41. package/_bundled_plugin/scripts/report_projection.py +81 -43
  42. package/_bundled_plugin/scripts/review_state.py +8 -2
  43. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  44. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  45. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  46. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  47. package/_bundled_plugin/scripts/windows_scan_local_files.py +388 -17
  48. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  49. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  50. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  51. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  52. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  53. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  54. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  55. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  56. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  57. package/_bundled_plugin/scripts/workbench_cli.py +30 -12
  58. package/_bundled_plugin/scripts/workbench_constants.py +10 -0
  59. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  60. package/_bundled_plugin/scripts/workbench_db.py +369 -137
  61. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  62. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  63. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  64. package/_bundled_plugin/scripts/workbench_native_indexes.py +12 -12
  65. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  66. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  67. package/_bundled_plugin/scripts/workbench_remediation.py +13 -0
  68. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  69. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -55
  70. package/_bundled_plugin/scripts/workbench_scan_start.py +83 -24
  71. package/_bundled_plugin/scripts/workbench_scan_usage.py +644 -68
  72. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  73. package/_bundled_plugin/scripts/workbench_setup.py +13 -1
  74. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  75. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  76. package/_bundled_plugin/scripts/workbench_target.py +127 -56
  77. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  78. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  79. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -23
  80. package/_bundled_plugin/shared/workbench-migrations.json +34 -0
  81. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  82. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  83. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -1
  84. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -25
  85. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  86. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  87. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  88. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  90. package/dist/api.d.ts +39 -4
  91. package/dist/api.d.ts.map +1 -1
  92. package/dist/api.js +774 -292
  93. package/dist/api.js.map +1 -1
  94. package/dist/auth.d.ts.map +1 -1
  95. package/dist/auth.js +4 -6
  96. package/dist/auth.js.map +1 -1
  97. package/dist/bedrock-oss-pricing.d.ts +6 -0
  98. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  99. package/dist/bedrock-oss-pricing.js +58 -0
  100. package/dist/bedrock-oss-pricing.js.map +1 -0
  101. package/dist/bedrock-pricing.d.ts +15 -0
  102. package/dist/bedrock-pricing.d.ts.map +1 -0
  103. package/dist/bedrock-pricing.js +117 -0
  104. package/dist/bedrock-pricing.js.map +1 -0
  105. package/dist/blackduck-findings.d.ts.map +1 -1
  106. package/dist/blackduck-findings.js +35 -20
  107. package/dist/blackduck-findings.js.map +1 -1
  108. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  109. package/dist/bulk-scan-discovery.js +4 -4
  110. package/dist/bulk-scan-discovery.js.map +1 -1
  111. package/dist/checkmarx-evidence.d.ts +19 -0
  112. package/dist/checkmarx-evidence.d.ts.map +1 -0
  113. package/dist/checkmarx-evidence.js +36 -0
  114. package/dist/checkmarx-evidence.js.map +1 -0
  115. package/dist/checkmarx-findings.d.ts +4 -0
  116. package/dist/checkmarx-findings.d.ts.map +1 -0
  117. package/dist/checkmarx-findings.js +27 -0
  118. package/dist/checkmarx-findings.js.map +1 -0
  119. package/dist/checkmarx-one.d.ts +4 -0
  120. package/dist/checkmarx-one.d.ts.map +1 -0
  121. package/dist/checkmarx-one.js +53 -0
  122. package/dist/checkmarx-one.js.map +1 -0
  123. package/dist/checkmarx-repository.d.ts +12 -0
  124. package/dist/checkmarx-repository.d.ts.map +1 -0
  125. package/dist/checkmarx-repository.js +181 -0
  126. package/dist/checkmarx-repository.js.map +1 -0
  127. package/dist/checkmarx-xml.d.ts +12 -0
  128. package/dist/checkmarx-xml.d.ts.map +1 -0
  129. package/dist/checkmarx-xml.js +196 -0
  130. package/dist/checkmarx-xml.js.map +1 -0
  131. package/dist/classify-severity-records.d.ts +1 -9
  132. package/dist/classify-severity-records.d.ts.map +1 -1
  133. package/dist/classify-severity-records.js +3 -13
  134. package/dist/classify-severity-records.js.map +1 -1
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +2 -4
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli.d.ts +11 -5
  139. package/dist/cli.d.ts.map +1 -1
  140. package/dist/cli.js +1734 -1238
  141. package/dist/cli.js.map +1 -1
  142. package/dist/cloud-publish.js +2 -2
  143. package/dist/cloud-publish.js.map +1 -1
  144. package/dist/component-scan.d.ts +16 -3
  145. package/dist/component-scan.d.ts.map +1 -1
  146. package/dist/component-scan.js +27 -2
  147. package/dist/component-scan.js.map +1 -1
  148. package/dist/config.d.ts.map +1 -1
  149. package/dist/config.js +100 -66
  150. package/dist/config.js.map +1 -1
  151. package/dist/continuum-findings.d.ts.map +1 -1
  152. package/dist/continuum-findings.js +80 -12
  153. package/dist/continuum-findings.js.map +1 -1
  154. package/dist/contract-values.d.ts +2 -0
  155. package/dist/contract-values.d.ts.map +1 -1
  156. package/dist/contract-values.js +12 -9
  157. package/dist/contract-values.js.map +1 -1
  158. package/dist/cost-model.d.ts +13 -1
  159. package/dist/cost-model.d.ts.map +1 -1
  160. package/dist/cost-model.js +66 -112
  161. package/dist/cost-model.js.map +1 -1
  162. package/dist/cost.d.ts +42 -3
  163. package/dist/cost.d.ts.map +1 -1
  164. package/dist/cost.js +483 -104
  165. package/dist/cost.js.map +1 -1
  166. package/dist/custom-publish.d.ts +4 -0
  167. package/dist/custom-publish.d.ts.map +1 -1
  168. package/dist/custom-publish.js +40 -3
  169. package/dist/custom-publish.js.map +1 -1
  170. package/dist/deduplication/local.d.ts +2 -2
  171. package/dist/deduplication/local.d.ts.map +1 -1
  172. package/dist/deduplication/local.js +2 -2
  173. package/dist/deduplication/local.js.map +1 -1
  174. package/dist/deduplication/refusal.d.ts.map +1 -1
  175. package/dist/deduplication/refusal.js +25 -5
  176. package/dist/deduplication/refusal.js.map +1 -1
  177. package/dist/deduplication/scan.d.ts +3 -0
  178. package/dist/deduplication/scan.d.ts.map +1 -1
  179. package/dist/deduplication/scan.js +1 -1
  180. package/dist/deduplication/scan.js.map +1 -1
  181. package/dist/deep-config.d.ts +0 -1
  182. package/dist/deep-config.d.ts.map +1 -1
  183. package/dist/deep-config.js +22 -33
  184. package/dist/deep-config.js.map +1 -1
  185. package/dist/deep-scan-defaults.d.ts +2 -0
  186. package/dist/deep-scan-defaults.d.ts.map +1 -1
  187. package/dist/deep-scan-defaults.js +28 -1
  188. package/dist/deep-scan-defaults.js.map +1 -1
  189. package/dist/deep-scan.d.ts +2 -0
  190. package/dist/deep-scan.d.ts.map +1 -1
  191. package/dist/deep-scan.js +28 -4
  192. package/dist/deep-scan.js.map +1 -1
  193. package/dist/default-severity-rubric.d.ts +1 -1
  194. package/dist/default-severity-rubric.d.ts.map +1 -1
  195. package/dist/default-severity-rubric.js +1 -1
  196. package/dist/default-severity-rubric.js.map +1 -1
  197. package/dist/endor-findings.d.ts +3 -1
  198. package/dist/endor-findings.d.ts.map +1 -1
  199. package/dist/endor-findings.js +103 -45
  200. package/dist/endor-findings.js.map +1 -1
  201. package/dist/errors.d.ts +1 -1
  202. package/dist/errors.d.ts.map +1 -1
  203. package/dist/errors.js +8 -1
  204. package/dist/errors.js.map +1 -1
  205. package/dist/external-findings-import.d.ts +5 -3
  206. package/dist/external-findings-import.d.ts.map +1 -1
  207. package/dist/external-findings-import.js +7 -6
  208. package/dist/external-findings-import.js.map +1 -1
  209. package/dist/external-findings-local.d.ts +7 -5
  210. package/dist/external-findings-local.d.ts.map +1 -1
  211. package/dist/external-findings-local.js +337 -89
  212. package/dist/external-findings-local.js.map +1 -1
  213. package/dist/external-findings-publish.d.ts +8 -6
  214. package/dist/external-findings-publish.d.ts.map +1 -1
  215. package/dist/external-findings-publish.js +1318 -258
  216. package/dist/external-findings-publish.js.map +1 -1
  217. package/dist/external-findings-read.d.ts +20 -2
  218. package/dist/external-findings-read.d.ts.map +1 -1
  219. package/dist/external-findings-read.js +148 -66
  220. package/dist/external-findings-read.js.map +1 -1
  221. package/dist/external-findings.d.ts +15 -3
  222. package/dist/external-findings.d.ts.map +1 -1
  223. package/dist/external-findings.js +42 -1
  224. package/dist/external-findings.js.map +1 -1
  225. package/dist/external-import-contract.d.ts +5 -1
  226. package/dist/external-import-contract.d.ts.map +1 -1
  227. package/dist/external-import-contract.js +23 -9
  228. package/dist/external-import-contract.js.map +1 -1
  229. package/dist/external-import-models.d.ts +1 -1
  230. package/dist/external-import-models.d.ts.map +1 -1
  231. package/dist/external-import-models.js.map +1 -1
  232. package/dist/feedback.d.ts.map +1 -1
  233. package/dist/feedback.js +5 -4
  234. package/dist/feedback.js.map +1 -1
  235. package/dist/finding-prompt.d.ts +5 -0
  236. package/dist/finding-prompt.d.ts.map +1 -0
  237. package/dist/finding-prompt.js +32 -0
  238. package/dist/finding-prompt.js.map +1 -0
  239. package/dist/findings-client.d.ts +1 -0
  240. package/dist/findings-client.d.ts.map +1 -1
  241. package/dist/findings-client.js +27 -3
  242. package/dist/findings-client.js.map +1 -1
  243. package/dist/github-advisories.d.ts.map +1 -1
  244. package/dist/github-advisories.js +0 -2
  245. package/dist/github-advisories.js.map +1 -1
  246. package/dist/github-dependabot-findings.d.ts.map +1 -1
  247. package/dist/github-dependabot-findings.js +15 -4
  248. package/dist/github-dependabot-findings.js.map +1 -1
  249. package/dist/github-findings.d.ts +4 -1
  250. package/dist/github-findings.d.ts.map +1 -1
  251. package/dist/github-findings.js +55 -30
  252. package/dist/github-findings.js.map +1 -1
  253. package/dist/hosted-git-remotes.d.ts +5 -0
  254. package/dist/hosted-git-remotes.d.ts.map +1 -0
  255. package/dist/hosted-git-remotes.js +285 -0
  256. package/dist/hosted-git-remotes.js.map +1 -0
  257. package/dist/hosted-git-repository.d.ts +28 -0
  258. package/dist/hosted-git-repository.d.ts.map +1 -0
  259. package/dist/hosted-git-repository.js +222 -0
  260. package/dist/hosted-git-repository.js.map +1 -0
  261. package/dist/hosted-scan-protocol.js +2 -2
  262. package/dist/hosted-scan-protocol.js.map +1 -1
  263. package/dist/hosted-scan.d.ts.map +1 -1
  264. package/dist/hosted-scan.js +16 -11
  265. package/dist/hosted-scan.js.map +1 -1
  266. package/dist/hosted-scanner-http.d.ts +21 -0
  267. package/dist/hosted-scanner-http.d.ts.map +1 -0
  268. package/dist/hosted-scanner-http.js +204 -0
  269. package/dist/hosted-scanner-http.js.map +1 -0
  270. package/dist/hosted-scanner-v1.d.ts +6 -0
  271. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  272. package/dist/hosted-scanner-v1.js +60 -0
  273. package/dist/hosted-scanner-v1.js.map +1 -0
  274. package/dist/import-scan.d.ts.map +1 -1
  275. package/dist/import-scan.js +3 -0
  276. package/dist/import-scan.js.map +1 -1
  277. package/dist/index.d.ts +18 -7
  278. package/dist/index.d.ts.map +1 -1
  279. package/dist/index.js +10 -2
  280. package/dist/index.js.map +1 -1
  281. package/dist/inspector-findings.d.ts.map +1 -1
  282. package/dist/inspector-findings.js +47 -65
  283. package/dist/inspector-findings.js.map +1 -1
  284. package/dist/knowledge-base.d.ts.map +1 -1
  285. package/dist/knowledge-base.js +68 -5
  286. package/dist/knowledge-base.js.map +1 -1
  287. package/dist/local-git-metadata.d.ts +1 -1
  288. package/dist/local-git-metadata.d.ts.map +1 -1
  289. package/dist/local-git-metadata.js +1 -2
  290. package/dist/local-git-metadata.js.map +1 -1
  291. package/dist/multiscan.d.ts +6 -4
  292. package/dist/multiscan.d.ts.map +1 -1
  293. package/dist/multiscan.js +138 -65
  294. package/dist/multiscan.js.map +1 -1
  295. package/dist/native-json-findings.d.ts +2 -1
  296. package/dist/native-json-findings.d.ts.map +1 -1
  297. package/dist/native-json-findings.js +12 -2
  298. package/dist/native-json-findings.js.map +1 -1
  299. package/dist/opengrep-findings.d.ts +1 -0
  300. package/dist/opengrep-findings.d.ts.map +1 -1
  301. package/dist/opengrep-findings.js +17 -13
  302. package/dist/opengrep-findings.js.map +1 -1
  303. package/dist/operation-telemetry.d.ts +104 -0
  304. package/dist/operation-telemetry.d.ts.map +1 -0
  305. package/dist/operation-telemetry.js +293 -0
  306. package/dist/operation-telemetry.js.map +1 -0
  307. package/dist/plugin-python-probe.d.ts +4 -0
  308. package/dist/plugin-python-probe.d.ts.map +1 -0
  309. package/dist/plugin-python-probe.js +10 -0
  310. package/dist/plugin-python-probe.js.map +1 -0
  311. package/dist/private-finding-import.d.ts +97 -2
  312. package/dist/private-finding-import.d.ts.map +1 -1
  313. package/dist/private-finding-import.js +58 -34
  314. package/dist/private-finding-import.js.map +1 -1
  315. package/dist/provider-profile.d.ts +1 -1
  316. package/dist/provider-profile.d.ts.map +1 -1
  317. package/dist/provider-profile.js +8 -1
  318. package/dist/provider-profile.js.map +1 -1
  319. package/dist/publication-telemetry.d.ts +45 -0
  320. package/dist/publication-telemetry.d.ts.map +1 -0
  321. package/dist/publication-telemetry.js +50 -0
  322. package/dist/publication-telemetry.js.map +1 -0
  323. package/dist/publish.d.ts +4 -0
  324. package/dist/publish.d.ts.map +1 -1
  325. package/dist/publish.js +42 -2
  326. package/dist/publish.js.map +1 -1
  327. package/dist/reader-selection.d.ts +2 -0
  328. package/dist/reader-selection.d.ts.map +1 -1
  329. package/dist/reader-selection.js +8 -0
  330. package/dist/reader-selection.js.map +1 -1
  331. package/dist/remediation.d.ts +1 -4
  332. package/dist/remediation.d.ts.map +1 -1
  333. package/dist/remediation.js +3 -7
  334. package/dist/remediation.js.map +1 -1
  335. package/dist/request-metadata.d.ts +3 -0
  336. package/dist/request-metadata.d.ts.map +1 -1
  337. package/dist/request-metadata.js +9 -0
  338. package/dist/request-metadata.js.map +1 -1
  339. package/dist/result.d.ts +4 -0
  340. package/dist/result.d.ts.map +1 -1
  341. package/dist/result.js +1 -1
  342. package/dist/result.js.map +1 -1
  343. package/dist/retry-windows-rename.d.ts +8 -0
  344. package/dist/retry-windows-rename.d.ts.map +1 -0
  345. package/dist/retry-windows-rename.js +24 -0
  346. package/dist/retry-windows-rename.js.map +1 -0
  347. package/dist/runtime.d.ts +20 -0
  348. package/dist/runtime.d.ts.map +1 -1
  349. package/dist/runtime.js +313 -110
  350. package/dist/runtime.js.map +1 -1
  351. package/dist/saved-scan-bootstrap.d.ts +1 -0
  352. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  353. package/dist/saved-scan-bootstrap.js +18 -15
  354. package/dist/saved-scan-bootstrap.js.map +1 -1
  355. package/dist/scan-activity.d.ts.map +1 -1
  356. package/dist/scan-activity.js +141 -56
  357. package/dist/scan-activity.js.map +1 -1
  358. package/dist/scan-comparison.d.ts +10 -5
  359. package/dist/scan-comparison.d.ts.map +1 -1
  360. package/dist/scan-comparison.js +60 -15
  361. package/dist/scan-comparison.js.map +1 -1
  362. package/dist/scan-dashboard.d.ts +6 -6
  363. package/dist/scan-dashboard.d.ts.map +1 -1
  364. package/dist/scan-dashboard.js +75 -42
  365. package/dist/scan-dashboard.js.map +1 -1
  366. package/dist/scan-executor.d.ts +10 -1
  367. package/dist/scan-executor.d.ts.map +1 -1
  368. package/dist/scan-executor.js +22 -2
  369. package/dist/scan-executor.js.map +1 -1
  370. package/dist/scan-history-renderer.d.ts.map +1 -1
  371. package/dist/scan-history-renderer.js +9 -19
  372. package/dist/scan-history-renderer.js.map +1 -1
  373. package/dist/scan-logs.d.ts +12 -0
  374. package/dist/scan-logs.d.ts.map +1 -1
  375. package/dist/scan-logs.js +106 -77
  376. package/dist/scan-logs.js.map +1 -1
  377. package/dist/scan-measurement.d.ts +26 -0
  378. package/dist/scan-measurement.d.ts.map +1 -0
  379. package/dist/scan-measurement.js +77 -0
  380. package/dist/scan-measurement.js.map +1 -0
  381. package/dist/scan-progress.d.ts +1 -0
  382. package/dist/scan-progress.d.ts.map +1 -1
  383. package/dist/scan-progress.js +3 -0
  384. package/dist/scan-progress.js.map +1 -1
  385. package/dist/scan-sessions.d.ts.map +1 -1
  386. package/dist/scan-sessions.js +4 -1
  387. package/dist/scan-sessions.js.map +1 -1
  388. package/dist/scan-settings.d.ts +1 -1
  389. package/dist/scan-settings.d.ts.map +1 -1
  390. package/dist/scan-settings.js +1 -24
  391. package/dist/scan-settings.js.map +1 -1
  392. package/dist/scanner-import.d.ts +20 -2
  393. package/dist/scanner-import.d.ts.map +1 -1
  394. package/dist/scanner-import.js +200 -8
  395. package/dist/scanner-import.js.map +1 -1
  396. package/dist/scanner-repository-url.d.ts +4 -1
  397. package/dist/scanner-repository-url.d.ts.map +1 -1
  398. package/dist/scanner-repository-url.js +10 -6
  399. package/dist/scanner-repository-url.js.map +1 -1
  400. package/dist/security-policy.d.ts +1 -1
  401. package/dist/security-policy.d.ts.map +1 -1
  402. package/dist/security-policy.js.map +1 -1
  403. package/dist/semgrep-findings.d.ts +6 -3
  404. package/dist/semgrep-findings.d.ts.map +1 -1
  405. package/dist/semgrep-findings.js +107 -43
  406. package/dist/semgrep-findings.js.map +1 -1
  407. package/dist/semgrep-guardian-findings.d.ts +38 -0
  408. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  409. package/dist/semgrep-guardian-findings.js +165 -0
  410. package/dist/semgrep-guardian-findings.js.map +1 -0
  411. package/dist/semgrep-platform-collector.d.ts +26 -0
  412. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  413. package/dist/semgrep-platform-collector.js +108 -0
  414. package/dist/semgrep-platform-collector.js.map +1 -0
  415. package/dist/semgrep-platform-findings.d.ts +207 -6
  416. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  417. package/dist/semgrep-platform-findings.js +983 -103
  418. package/dist/semgrep-platform-findings.js.map +1 -1
  419. package/dist/semgrep-platform-v1.d.ts +6 -0
  420. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  421. package/dist/semgrep-platform-v1.js +83 -0
  422. package/dist/semgrep-platform-v1.js.map +1 -0
  423. package/dist/server/api.d.ts +1 -1
  424. package/dist/server/api.d.ts.map +1 -1
  425. package/dist/server/api.js.map +1 -1
  426. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  427. package/dist/server/embedding-tokenizer.d.ts +2 -0
  428. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  429. package/dist/server/embedding-tokenizer.js +322 -0
  430. package/dist/server/embedding-tokenizer.js.map +6 -0
  431. package/dist/server/embeddings.d.ts +16 -2
  432. package/dist/server/embeddings.d.ts.map +1 -1
  433. package/dist/server/embeddings.js +35 -5
  434. package/dist/server/embeddings.js.map +1 -1
  435. package/dist/session-lines.d.ts +5 -0
  436. package/dist/session-lines.d.ts.map +1 -0
  437. package/dist/session-lines.js +60 -0
  438. package/dist/session-lines.js.map +1 -0
  439. package/dist/severity-review.d.ts +3 -1
  440. package/dist/severity-review.d.ts.map +1 -1
  441. package/dist/severity-review.js +3 -2
  442. package/dist/severity-review.js.map +1 -1
  443. package/dist/skill-authentication.d.ts +1 -0
  444. package/dist/skill-authentication.d.ts.map +1 -1
  445. package/dist/skill-authentication.js +1 -0
  446. package/dist/skill-authentication.js.map +1 -1
  447. package/dist/snyk-findings.d.ts +7 -2
  448. package/dist/snyk-findings.d.ts.map +1 -1
  449. package/dist/snyk-findings.js +93 -70
  450. package/dist/snyk-findings.js.map +1 -1
  451. package/dist/snyk-rest-findings.d.ts +76 -0
  452. package/dist/snyk-rest-findings.d.ts.map +1 -0
  453. package/dist/snyk-rest-findings.js +1051 -0
  454. package/dist/snyk-rest-findings.js.map +1 -0
  455. package/dist/snyk-rest-v1.d.ts +28 -0
  456. package/dist/snyk-rest-v1.d.ts.map +1 -0
  457. package/dist/snyk-rest-v1.js +132 -0
  458. package/dist/snyk-rest-v1.js.map +1 -0
  459. package/dist/snyk-token-origin.d.ts +4 -0
  460. package/dist/snyk-token-origin.d.ts.map +1 -0
  461. package/dist/snyk-token-origin.js +82 -0
  462. package/dist/snyk-token-origin.js.map +1 -0
  463. package/dist/sonar-collector.d.ts.map +1 -1
  464. package/dist/sonar-collector.js +0 -3
  465. package/dist/sonar-collector.js.map +1 -1
  466. package/dist/sonar-import.d.ts.map +1 -1
  467. package/dist/sonar-import.js +2 -4
  468. package/dist/sonar-import.js.map +1 -1
  469. package/dist/target-drift.d.ts +9 -0
  470. package/dist/target-drift.d.ts.map +1 -0
  471. package/dist/target-drift.js +27 -0
  472. package/dist/target-drift.js.map +1 -0
  473. package/dist/targets.d.ts +2 -0
  474. package/dist/targets.d.ts.map +1 -1
  475. package/dist/targets.js +56 -20
  476. package/dist/targets.js.map +1 -1
  477. package/dist/tenable-findings.d.ts +9 -0
  478. package/dist/tenable-findings.d.ts.map +1 -0
  479. package/dist/tenable-findings.js +122 -0
  480. package/dist/tenable-findings.js.map +1 -0
  481. package/dist/terminal-stream.d.ts +13 -0
  482. package/dist/terminal-stream.d.ts.map +1 -0
  483. package/dist/terminal-stream.js +35 -0
  484. package/dist/terminal-stream.js.map +1 -0
  485. package/dist/trivy-findings.d.ts +19 -0
  486. package/dist/trivy-findings.d.ts.map +1 -0
  487. package/dist/trivy-findings.js +435 -0
  488. package/dist/trivy-findings.js.map +1 -0
  489. package/dist/trivy-import.d.ts +19 -0
  490. package/dist/trivy-import.d.ts.map +1 -0
  491. package/dist/trivy-import.js +151 -0
  492. package/dist/trivy-import.js.map +1 -0
  493. package/dist/validation-records.js +1 -1
  494. package/dist/validation-records.js.map +1 -1
  495. package/dist/veracode-findings.d.ts +2 -0
  496. package/dist/veracode-findings.d.ts.map +1 -1
  497. package/dist/veracode-findings.js +49 -11
  498. package/dist/veracode-findings.js.map +1 -1
  499. package/dist/vertex-pricing.d.ts +8 -0
  500. package/dist/vertex-pricing.d.ts.map +1 -0
  501. package/dist/vertex-pricing.js +20 -0
  502. package/dist/vertex-pricing.js.map +1 -0
  503. package/dist/windows-path.d.ts +1 -0
  504. package/dist/windows-path.d.ts.map +1 -1
  505. package/dist/windows-path.js +26 -1
  506. package/dist/windows-path.js.map +1 -1
  507. package/dist/wiz-findings.d.ts +4 -0
  508. package/dist/wiz-findings.d.ts.map +1 -1
  509. package/dist/wiz-findings.js +57 -3
  510. package/dist/wiz-findings.js.map +1 -1
  511. package/docs/classify-severity-records.md +27 -12
  512. package/docs/cli.md +497 -550
  513. package/docs/dedupe-records.md +44 -24
  514. package/docs/findings-service.md +66 -39
  515. package/docs/hosted-remediation.md +14 -7
  516. package/docs/hosted-scans.md +50 -42
  517. package/docs/telemetry.md +236 -0
  518. package/docs/validate-records.md +78 -44
  519. package/package.json +18 -15
  520. package/schemas/external-findings.schema.json +3 -1
  521. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  522. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  523. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  524. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  525. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  526. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  527. package/dist/external-imports-feature.d.ts +0 -6
  528. package/dist/external-imports-feature.d.ts.map +0 -1
  529. package/dist/external-imports-feature.js +0 -51
  530. package/dist/external-imports-feature.js.map +0 -1
  531. package/dist/finding-normalization.d.ts +0 -5
  532. package/dist/finding-normalization.d.ts.map +0 -1
  533. package/dist/finding-normalization.js +0 -155
  534. package/dist/finding-normalization.js.map +0 -1
@@ -15,7 +15,11 @@ import finalize_scan_contract as FINALIZER
15
15
 
16
16
 
17
17
  def validate_contract(scan_dir: Path) -> dict[str, Any]:
18
- """Return validated canonical documents for one sealed scan."""
18
+ """Validate the sealed artifacts and return the manifest, original findings, and review summary.
19
+
20
+ Legacy finding records are adapted for validation only. ContractError propagates
21
+ when a required artifact, digest, schema, or evidence check fails.
22
+ """
19
23
 
20
24
  scan_dir = FINALIZER._require_scan_directory(scan_dir.expanduser().resolve(strict=True))
21
25
  schema_dir = Path(__file__).resolve().parents[1] / "schemas"
@@ -46,6 +50,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
46
50
 
47
51
 
48
52
  def receipt(validated: dict[str, Any]) -> dict[str, Any]:
53
+ """Return the CLI success payload with paths to the validated manifest, findings, and report."""
49
54
  scan_dir = Path(validated["scanDir"])
50
55
  scan = validated["manifest"]["scan"]
51
56
  return {
@@ -58,6 +63,7 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:
58
63
 
59
64
 
60
65
  def main(argv: list[str] | None = None) -> int:
66
+ """Print the validation receipt on success or report a validation error to stderr and return 2."""
61
67
  parser = argparse.ArgumentParser(description=__doc__)
62
68
  parser.add_argument("--scan-dir", required=True, type=Path)
63
69
  args = parser.parse_args(argv)
@@ -25,10 +25,12 @@ import contextlib
25
25
  import ctypes
26
26
  import ctypes.wintypes as wintypes
27
27
  import errno
28
+ import functools
28
29
  import importlib
29
30
  import ntpath
30
31
  import os
31
32
  import secrets
33
+ import struct
32
34
  from collections.abc import Callable, Iterator
33
35
  from pathlib import Path, PurePosixPath
34
36
  from typing import BinaryIO
@@ -45,8 +47,18 @@ class WindowsScanLocalPathError(WindowsScanLocalFileError):
45
47
 
46
48
 
47
49
  # CreateFile access and sharing flags.
50
+ _DRIVE_FIXED = 3
48
51
  _DELETE = 0x00010000
52
+ _FILE_ADD_SUBDIRECTORY = 0x00000004
53
+ _FILE_DELETE_CHILD = 0x00000040
54
+ _CHANGE_ACL = 0x000C0000 # WRITE_DAC | WRITE_OWNER
55
+ _SET_REPARSE_POINT = 0x00000102 # FILE_WRITE_ATTRIBUTES | FILE_WRITE_DATA
56
+ _OUTPUT_RIGHTS = (
57
+ _DELETE | _FILE_ADD_SUBDIRECTORY | _FILE_DELETE_CHILD | _CHANGE_ACL | _SET_REPARSE_POINT
58
+ )
59
+ _FILE_TRAVERSE = 0x00000020
49
60
  _FILE_READ_ATTRIBUTES = 0x00000080
61
+ _READ_CONTROL = 0x00020000
50
62
  _GENERIC_READ = 0x80000000
51
63
  _GENERIC_WRITE = 0x40000000
52
64
  _FILE_SHARE_READ = 0x00000001
@@ -78,6 +90,7 @@ _ERROR_FILE_EXISTS = 80
78
90
  _ERROR_INSUFFICIENT_BUFFER = 122
79
91
  _ERROR_ALREADY_EXISTS = 183
80
92
  _ERROR_DIRECTORY = 267
93
+ _OWNER_SECURITY_INFORMATION = 0x00000001
81
94
  _DACL_SECURITY_INFORMATION = 0x00000004
82
95
  _MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
83
96
  _COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
@@ -119,9 +132,9 @@ class _FileAttributeTagInfo(ctypes.Structure):
119
132
 
120
133
  class _SecurityAttributes(ctypes.Structure):
121
134
  _fields_ = [
122
- ("nLength", wintypes.DWORD),
123
- ("lpSecurityDescriptor", wintypes.LPVOID),
124
- ("bInheritHandle", wintypes.BOOL),
135
+ ("length", wintypes.DWORD),
136
+ ("descriptor", wintypes.LPVOID),
137
+ ("inherit", wintypes.BOOL),
125
138
  ]
126
139
 
127
140
 
@@ -169,6 +182,7 @@ class _OwnedHandle:
169
182
  if os.name == "nt":
170
183
  _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
171
184
  _advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
185
+ _ntdll = ctypes.WinDLL("ntdll")
172
186
 
173
187
  _GetFileSecurityW = _advapi32.GetFileSecurityW
174
188
  _GetFileSecurityW.argtypes = [
@@ -180,6 +194,10 @@ if os.name == "nt":
180
194
  ]
181
195
  _GetFileSecurityW.restype = wintypes.BOOL
182
196
 
197
+ _GetDriveTypeW = _kernel32.GetDriveTypeW
198
+ _GetDriveTypeW.argtypes = [wintypes.LPCWSTR]
199
+ _GetDriveTypeW.restype = wintypes.UINT
200
+
183
201
  _CreateFileW = _kernel32.CreateFileW
184
202
  _CreateFileW.argtypes = [
185
203
  wintypes.LPCWSTR,
@@ -466,7 +484,8 @@ def _open_directory(
466
484
  try:
467
485
  handle = _create_file(
468
486
  path,
469
- access=_FILE_READ_ATTRIBUTES,
487
+ # Attribute-only handles do not participate in Win32 sharing checks.
488
+ access=_FILE_READ_ATTRIBUTES | (0 if movable else _FILE_TRAVERSE),
470
489
  share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | (_FILE_SHARE_DELETE if movable else 0),
471
490
  disposition=_OPEN_EXISTING,
472
491
  flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
@@ -496,25 +515,297 @@ def _create_directory(path: Path) -> None:
496
515
  _raise_last_error("CreateDirectoryW", path)
497
516
 
498
517
 
499
- def create_directory_with_same_dacl(path: Path, source: Path) -> None:
500
- """Create an archive replacement with the original directory's DACL."""
501
- _require_windows()
518
+ def _directory_security_descriptor(source: Path, information: int) -> ctypes.Array:
502
519
  source_path = _extended_path(source)
503
520
  size = wintypes.DWORD()
504
- _GetFileSecurityW(source_path, _DACL_SECURITY_INFORMATION, None, 0, ctypes.byref(size))
521
+ _GetFileSecurityW(source_path, information, None, 0, ctypes.byref(size))
505
522
  if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
506
523
  _raise_last_error("GetFileSecurityW", source)
507
524
  descriptor = ctypes.create_string_buffer(size.value)
508
- if not _GetFileSecurityW(
509
- source_path, _DACL_SECURITY_INFORMATION, descriptor, size.value, ctypes.byref(size)
510
- ):
525
+ if not _GetFileSecurityW(source_path, information, descriptor, size.value, ctypes.byref(size)):
511
526
  _raise_last_error("GetFileSecurityW", source)
512
- attributes = _SecurityAttributes(
513
- ctypes.sizeof(_SecurityAttributes), ctypes.cast(descriptor, wintypes.LPVOID), False
527
+ return descriptor
528
+
529
+
530
+ def _sid_text(sid: wintypes.LPVOID) -> str:
531
+ value = wintypes.LPWSTR()
532
+ if not _advapi32.ConvertSidToStringSidW(sid, ctypes.byref(value)):
533
+ _raise_last_error("ConvertSidToStringSidW")
534
+ try:
535
+ return value.value
536
+ finally:
537
+ _kernel32.LocalFree(value)
538
+
539
+
540
+ @functools.cache
541
+ def _current_user_sid() -> str:
542
+ token = wintypes.HANDLE(-4) # GetCurrentProcessToken pseudo-handle.
543
+ size = wintypes.DWORD()
544
+ _advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
545
+ if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
546
+ _raise_last_error("GetTokenInformation")
547
+ user = ctypes.create_string_buffer(size.value)
548
+ if not _advapi32.GetTokenInformation(token, 1, user, size, ctypes.byref(size)):
549
+ _raise_last_error("GetTokenInformation")
550
+ return _sid_text(wintypes.LPVOID.from_buffer(user))
551
+
552
+
553
+ def _output_directory_grants(handle: int, path: Path) -> int:
554
+ """Inspect the descriptor of the opened directory, even if its pathname changes."""
555
+ owner, acl, descriptor = wintypes.LPVOID(), wintypes.LPVOID(), wintypes.LPVOID()
556
+ status = _advapi32.GetSecurityInfo(
557
+ wintypes.HANDLE(handle),
558
+ 1,
559
+ _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
560
+ ctypes.byref(owner),
561
+ None,
562
+ ctypes.byref(acl),
563
+ None,
564
+ ctypes.byref(descriptor),
514
565
  )
515
- # Supply the descriptor at creation, without an inherited-access window.
516
- if not _CreateDirectoryW(_extended_path(path), ctypes.byref(attributes)):
517
- _raise_last_error("CreateDirectoryW", path)
566
+ if status:
567
+ raise ctypes.WinError(status)
568
+ try:
569
+ trusted = {
570
+ _current_user_sid(),
571
+ "S-1-5-18",
572
+ "S-1-5-32-544", # Current user, SYSTEM, Administrators.
573
+ "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464", # TrustedInstaller.
574
+ }
575
+ if _sid_text(owner) not in trusted:
576
+ raise _invalid_path(path, "Scan output directory must have a trusted owner.")
577
+ return _output_dacl_grants(acl, trusted, path)
578
+ finally:
579
+ _kernel32.LocalFree(descriptor)
580
+
581
+
582
+ def _authenticated_account(sid: wintypes.LPVOID, trustee: str) -> bool:
583
+ # The Guest account can have its own SID without Authenticated Users membership.
584
+ if not trustee.startswith("S-1-5-21-") or trustee.endswith("-501"):
585
+ return False
586
+ name_size, domain_size, sid_type = (ctypes.pointer(wintypes.DWORD()) for _ in range(3))
587
+ lookup = _advapi32.LookupAccountSidW
588
+ lookup(None, sid, None, name_size, None, domain_size, sid_type)
589
+ if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
590
+ return False
591
+ name = ctypes.create_unicode_buffer(name_size.contents.value)
592
+ domain = ctypes.create_unicode_buffer(domain_size.contents.value)
593
+ found = lookup(None, sid, name, name_size, domain, domain_size, sid_type)
594
+ return bool(found) and sid_type.contents.value == 1 # SidTypeUser
595
+
596
+
597
+ def _output_dacl_grants(acl: wintypes.LPVOID, trusted: set[str], path: Path) -> int:
598
+ if not acl.value: # A NULL DACL grants full access.
599
+ return _OUTPUT_RIGHTS
600
+ # Read ACEs in DACL order. A deny masks future grants for its trustee.
601
+ denied: dict[str, int] = {}
602
+ granted = 0
603
+ for index in range(wintypes.WORD.from_address(acl.value + 4).value): # ACL.AceCount
604
+ ace = wintypes.LPVOID()
605
+ if not _advapi32.GetAce(acl, index, ctypes.byref(ace)):
606
+ _raise_last_error("GetAce", path)
607
+ kind, flags, size = struct.unpack("<BBH", ctypes.string_at(ace, 4))
608
+ if flags & 8 or kind in {10, 12}: # INHERIT_ONLY or conditional deny.
609
+ continue
610
+ entry = ctypes.string_at(ace, size)
611
+ mask = struct.unpack_from("<I", entry, 4)[0]
612
+ if mask & 0x10000000: # GENERIC_ALL
613
+ mask |= _OUTPUT_RIGHTS
614
+ if mask & _GENERIC_WRITE:
615
+ mask |= _FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT
616
+ mask &= _OUTPUT_RIGHTS
617
+ if not mask:
618
+ continue
619
+ offset = 8 # ACE_HEADER and ACCESS_MASK precede the trustee SID.
620
+ if kind in {5, 6, 11}:
621
+ object_flags = struct.unpack_from("<I", entry, offset)[0]
622
+ offset += 4 + 16 * (object_flags & 3).bit_count()
623
+ if kind == 6 and object_flags & 1:
624
+ continue # This deny is scoped to a particular object type.
625
+ elif kind not in {0, 1, 9}:
626
+ raise _invalid_path(path, "Unable to evaluate scan output directory permissions.")
627
+ if len(entry) < offset + 8 or len(entry) < offset + 8 + 4 * entry[offset + 1]:
628
+ raise _invalid_path(path, "Invalid scan output directory trustee.")
629
+ sid = wintypes.LPVOID(ace.value + offset)
630
+ trustee = _sid_text(sid)
631
+ if trustee in trusted or trustee == "S-1-3-4": # OWNER RIGHTS applies to the checked owner.
632
+ continue
633
+ if kind in {1, 6}:
634
+ denied[trustee] = denied.get(trustee, 0) | mask
635
+ else:
636
+ blocked = denied.get(trustee, 0) | denied.get("S-1-1-0", 0)
637
+ authenticated = denied.get("S-1-5-11", 0)
638
+ if mask & authenticated and _authenticated_account(sid, trustee):
639
+ blocked |= authenticated
640
+ granted |= mask & ~blocked
641
+ if granted & _CHANGE_ACL:
642
+ granted |= _OUTPUT_RIGHTS
643
+ return granted
644
+
645
+
646
+ def _require_stable_output(path: Path, parent_grants: int, child_grants: int = 0) -> None:
647
+ can_remove = parent_grants & _FILE_DELETE_CHILD or child_grants & _DELETE
648
+ can_replace = parent_grants & (_FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT)
649
+ if can_remove and can_replace:
650
+ raise _invalid_path(path, "Scan output directory can be replaced by another user.")
651
+
652
+
653
+ @contextlib.contextmanager
654
+ def _checked_output_directory(path: Path) -> Iterator[tuple[int, int]]:
655
+ """Hold the checked canonical chain and expose its final directory handle and grants."""
656
+ parent_grants = 0
657
+ parent = None
658
+ with contextlib.ExitStack() as pins:
659
+ for directory in (*reversed(path.parents), path):
660
+ if parent is None:
661
+ handle = _create_file(
662
+ directory,
663
+ access=_FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL,
664
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
665
+ disposition=_OPEN_EXISTING,
666
+ flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
667
+ )
668
+ assert handle is not None
669
+ else:
670
+ error, child = _relative_output_directory(parent, directory.name)
671
+ if error:
672
+ raise WindowsScanLocalPathError(
673
+ error, ctypes.FormatError(error), str(directory)
674
+ )
675
+ handle = _OwnedHandle(child)
676
+ pins.enter_context(handle)
677
+ assert handle.value is not None
678
+ _verify_directory(handle.value, directory)
679
+ grants = _output_directory_grants(handle.value, directory)
680
+ _require_stable_output(directory, parent_grants, grants)
681
+ parent, parent_grants = handle.value, grants
682
+ yield parent, parent_grants
683
+
684
+
685
+ def require_windows_output_path(path: Path, *, writable_output: bool = False) -> None:
686
+ with _checked_output_directory(path) as (_, grants):
687
+ if writable_output and grants & _SET_REPARSE_POINT:
688
+ raise _invalid_path(
689
+ path, "Another user can turn the output directory into a reparse point when empty."
690
+ )
691
+
692
+
693
+ class _UnicodeString(ctypes.Structure):
694
+ _fields_ = [
695
+ ("length", wintypes.USHORT),
696
+ ("capacity", wintypes.USHORT),
697
+ ("text", wintypes.LPWSTR),
698
+ ]
699
+
700
+
701
+ class _ObjectAttributes(ctypes.Structure):
702
+ _fields_ = [
703
+ ("length", wintypes.ULONG),
704
+ ("root", wintypes.HANDLE),
705
+ ("name", ctypes.POINTER(_UnicodeString)),
706
+ ("attributes", wintypes.ULONG),
707
+ ("security", wintypes.LPVOID),
708
+ ("qos", wintypes.LPVOID),
709
+ ]
710
+
711
+
712
+ def _relative_output_directory(
713
+ parent: int, basename: str, descriptor=None
714
+ ) -> tuple[int, int | None]:
715
+ """Open or create one component relative to its checked parent without reparsing it."""
716
+ size = len(basename.encode("utf-16-le", errors="surrogatepass"))
717
+ if size >= 1 << 16: # UNICODE_STRING.Length is a byte count in a USHORT.
718
+ return 206, None
719
+ name = _UnicodeString(size, size, basename)
720
+ attributes = _ObjectAttributes(
721
+ ctypes.sizeof(_ObjectAttributes),
722
+ parent,
723
+ ctypes.pointer(name),
724
+ 0x40 | 0x1000, # OBJ_CASE_INSENSITIVE | OBJ_DONT_REPARSE
725
+ descriptor,
726
+ None,
727
+ )
728
+ handle = wintypes.HANDLE()
729
+ io_status = (ctypes.c_void_p * 2)() # IO_STATUS_BLOCK
730
+ status = _ntdll.NtCreateFile(
731
+ ctypes.byref(handle),
732
+ _FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL | 0x100000,
733
+ ctypes.byref(attributes),
734
+ ctypes.byref(io_status),
735
+ None,
736
+ _FILE_ATTRIBUTE_NORMAL,
737
+ _FILE_SHARE_READ | _FILE_SHARE_WRITE,
738
+ 1 if descriptor is None else 2, # FILE_OPEN or FILE_CREATE
739
+ 0x200021, # FILE_OPEN_REPARSE_POINT | FILE_SYNCHRONOUS_IO_NONALERT | FILE_DIRECTORY_FILE
740
+ None,
741
+ 0,
742
+ )
743
+ return (_ntdll.RtlNtStatusToDosError(status), None) if status < 0 else (0, handle.value)
744
+
745
+
746
+ def create_windows_output_directory(path: Path, descriptor: wintypes.LPVOID) -> int:
747
+ with _checked_output_directory(path.parent) as (parent, grants):
748
+ _require_stable_output(path, grants)
749
+ error, handle = _relative_output_directory(parent, path.name, descriptor)
750
+ if not error:
751
+ _close_handle(handle)
752
+ return error
753
+
754
+
755
+ def create_private_directory(path: Path, *, exist_ok: bool, scan_output: bool) -> Path:
756
+ """Create one Windows directory with a protected inheritable DACL."""
757
+ _require_windows()
758
+ # Older supported Python releases ignore mkdir's 0700 mode on Windows.
759
+ # Apply the same owner/SYSTEM/Administrators policy at creation so a
760
+ # writable parent never becomes an inheritance window.
761
+ volume = ctypes.create_unicode_buffer(32768)
762
+ flags = wintypes.DWORD()
763
+ if not _kernel32.GetVolumePathNameW(str(path.parent.resolve()), volume, len(volume)):
764
+ raise ctypes.WinError(ctypes.get_last_error())
765
+ if not _kernel32.GetVolumeInformationW(
766
+ volume, None, 0, None, None, ctypes.byref(flags), None, 0
767
+ ):
768
+ raise ctypes.WinError(ctypes.get_last_error())
769
+ if not flags.value & 0x8: # FILE_PERSISTENT_ACLS
770
+ raise ValueError("Select a directory on a Windows volume that supports ACLs.")
771
+
772
+ sid = _current_user_sid()
773
+ owner = "" if exist_ok else f"O:{sid}"
774
+ dacl = f"{owner}D:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;FA;;;{sid})"
775
+
776
+ descriptor = wintypes.LPVOID()
777
+ if not _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
778
+ dacl, 1, ctypes.byref(descriptor), None
779
+ ):
780
+ raise ctypes.WinError(ctypes.get_last_error())
781
+ try:
782
+ if scan_output:
783
+ error = create_windows_output_directory(path, descriptor)
784
+ else:
785
+ attributes = _SecurityAttributes(ctypes.sizeof(_SecurityAttributes), descriptor, False)
786
+ error = (
787
+ 0
788
+ if _CreateDirectoryW(str(path), ctypes.byref(attributes))
789
+ else ctypes.get_last_error()
790
+ )
791
+ if not error:
792
+ return path if exist_ok else verify_private_scan_root(path, descriptor)
793
+ if exist_ok and error == 183 and path.is_dir(): # ERROR_ALREADY_EXISTS
794
+ if scan_output:
795
+ require_windows_output_path(path)
796
+ return path
797
+ raise ctypes.WinError(error)
798
+ finally:
799
+ _kernel32.LocalFree(descriptor)
800
+
801
+
802
+ def create_directory_with_same_dacl(path: Path, source: Path) -> None:
803
+ """Create an archive replacement with the original directory's DACL."""
804
+ _require_windows()
805
+ descriptor = _directory_security_descriptor(source, _DACL_SECURITY_INFORMATION)
806
+ error = create_windows_output_directory(path, ctypes.cast(descriptor, wintypes.LPVOID))
807
+ if error:
808
+ raise WindowsScanLocalFileError(error, ctypes.FormatError(error), str(path))
518
809
 
519
810
 
520
811
  @contextlib.contextmanager
@@ -572,6 +863,37 @@ def _locked_parent(
572
863
  handle.close()
573
864
 
574
865
 
866
+ def _generated_directory_policy(descriptor: object) -> tuple[str, bool, frozenset[str]]:
867
+ # Let Windows normalize SID aliases, access masks and inheritance flags in
868
+ # both descriptors. ACE order is immaterial for our three allow grants.
869
+ sddl = wintypes.LPWSTR()
870
+ if not _advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
871
+ descriptor,
872
+ 1,
873
+ _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
874
+ ctypes.byref(sddl),
875
+ None,
876
+ ):
877
+ _raise_last_error("ConvertSecurityDescriptorToStringSecurityDescriptorW")
878
+ try:
879
+ owner, _, dacl = sddl.value.partition("D:")
880
+ flags, _, entries = dacl.partition("(")
881
+ return owner, "P" in flags, frozenset(entries.removesuffix(")").split(")("))
882
+ finally:
883
+ _kernel32.LocalFree(sddl)
884
+
885
+
886
+ def verify_private_scan_root(scan_dir: Path, expected_descriptor: object) -> Path:
887
+ """Verify the new directory's owner and protected grants while the path is pinned."""
888
+ with _locked_parent(scan_dir, ".security", create=False) as (root_path, _):
889
+ actual = _directory_security_descriptor(
890
+ root_path, _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION
891
+ )
892
+ if _generated_directory_policy(actual) != _generated_directory_policy(expected_descriptor):
893
+ raise _invalid_path(scan_dir, "new scan directory lacks its private owner or DACL")
894
+ return root_path
895
+
896
+
575
897
  def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
576
898
  """Return a canonical scan root and its identity while holding it fixed."""
577
899
 
@@ -580,6 +902,50 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
580
902
  return root_path, (metadata.st_dev, metadata.st_ino)
581
903
 
582
904
 
905
+ @contextlib.contextmanager
906
+ def pinned_root_git_marker(cwd: Path, metadata: Path) -> Iterator[Path | None]:
907
+ """Bind a canonical worktree beneath a fixed-drive root to its exact .git marker."""
908
+ if (
909
+ not cwd.is_absolute()
910
+ or not metadata.is_absolute()
911
+ or len(cwd.drive) != 2
912
+ or cwd.drive != metadata.drive
913
+ or len(cwd.parts) < 2
914
+ or len(metadata.parts) < 2
915
+ or _GetDriveTypeW(cwd.anchor) != _DRIVE_FIXED
916
+ ):
917
+ yield None
918
+ return
919
+ marker = None
920
+ with contextlib.ExitStack() as pins:
921
+ try:
922
+ for path in (cwd, metadata):
923
+ _validated_parts(PurePosixPath(*path.parts[1:]).as_posix())
924
+ # Pin each literal ancestor before opening the next component. Never resolve
925
+ # a repository-controlled reparse point to find the directory to be pinned.
926
+ for directory in (*reversed(path.parents), path):
927
+ handle = _open_directory(directory)
928
+ assert handle is not None
929
+ pins.enter_context(handle)
930
+ assert handle.value is not None
931
+ if _final_path(handle.value) != _extended_path(path):
932
+ raise ValueError("the selected Git directory spelling is not canonical")
933
+ if str(cwd / ".git") != str(metadata):
934
+ # The literal canonical root is already pinned before opening its regular file.
935
+ fd, leaf = open_read_fd_with_path(cwd, ".git", "Git metadata pointer")
936
+ pointer = pins.enter_context(os.fdopen(fd, "rb"))
937
+ if leaf != ".git":
938
+ raise ValueError("the root marker name does not match .git")
939
+ expected = f"gitdir: {metadata}".encode("utf-8")
940
+ value = pointer.read(len(expected) + 3).removesuffix(b"\n").removesuffix(b"\r")
941
+ if value.replace(b"/", b"\\") != expected:
942
+ raise ValueError("the root marker does not name the selected Git directory")
943
+ marker = Path(".git")
944
+ except (OSError, ValueError):
945
+ pins.close()
946
+ yield marker
947
+
948
+
583
949
  def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
584
950
  """Open a verified regular file and return an owned binary read descriptor."""
585
951
 
@@ -587,7 +953,11 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
587
953
 
588
954
 
589
955
  def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) -> tuple[int, str]:
590
- """Return the descriptor and its filename while the verified parents are held."""
956
+ """Return an owned read descriptor and the scan-relative path with the file's actual leaf name.
957
+
958
+ Verify the regular file while holding its parent directories. The caller must
959
+ close the returned descriptor.
960
+ """
591
961
 
592
962
  try:
593
963
  with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
@@ -636,6 +1006,7 @@ def file_change_time(descriptor: int) -> int:
636
1006
 
637
1007
 
638
1008
  def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:
1009
+ """Compare bytes from the current stream position to payload, requiring EOF after the final byte."""
639
1010
  offset = 0
640
1011
  while offset < len(payload):
641
1012
  chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))
@@ -1 +1 @@
1
- """Focused Codex Security workbench operation modules."""
1
+ """Persist workbench state, transfer scan ownership, and recover results from saved artifacts."""
@@ -12,18 +12,47 @@ RECOVERY_HANDOFF_TOKEN_PREFIX = "recovery_"
12
12
 
13
13
 
14
14
  def require_handoff_claim_token(value: str) -> str:
15
+ """Normalize the claim UUID, retaining the prefix that marks a recovery handoff."""
15
16
  recovery_token = value.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX)
16
17
  token = value.removeprefix(RECOVERY_HANDOFF_TOKEN_PREFIX) if recovery_token else value
17
18
  normalized = require_uuid(token, "claim-token")
18
19
  return f"{RECOVERY_HANDOFF_TOKEN_PREFIX}{normalized}" if recovery_token else normalized
19
20
 
20
21
 
22
+ def require_tokenless_scan_owner(
23
+ connection: sqlite3.Connection,
24
+ scan: sqlite3.Row,
25
+ model_thread_id: str | None,
26
+ ) -> None:
27
+ """Check model callers against a recorded owner. Trusted local callers omit model_thread_id."""
28
+ if model_thread_id is None or scan["handoff_claim_token"] is not None:
29
+ return
30
+ if scan["handoff_status"] == "pending":
31
+ raise SystemExit(
32
+ "This Codex Security scan handoff has not been delivered. "
33
+ "Claim the pending Codex Security scan handoff before continuing."
34
+ )
35
+ owner = scan["continuation_thread_id"] or scan["deep_scan_owner_thread_id"]
36
+ if owner is None:
37
+ owner = connection.execute(
38
+ "SELECT thread_id FROM workspaces WHERE id = ?", (scan["workspace_id"],)
39
+ ).fetchone()[0]
40
+ if owner is None:
41
+ # Only a completed import is intentionally ownerless among registered scans.
42
+ completed_import = scan["launch_kind"] == "import" and scan["status"] == "complete"
43
+ if scan["recipe_json"] is not None and not completed_import:
44
+ raise SystemExit("This scan is awaiting its owning Codex thread.")
45
+ elif owner != model_thread_id:
46
+ raise SystemExit("This scan requires its owning Codex thread.")
47
+
48
+
21
49
  def require_current_continuation(
22
50
  scan: sqlite3.Row,
23
51
  claim_token: str | None,
24
52
  *,
25
53
  error_message: str,
26
54
  ) -> None:
55
+ """Require the current claim token, allowing a tokenless continuation for legacy delivered scans."""
27
56
  if (
28
57
  scan["handoff_status"] == "delivered"
29
58
  and scan["handoff_claim_token"] is None
@@ -41,6 +70,7 @@ def validate_handoff_delivery_thread(
41
70
  requesting_thread_id: str,
42
71
  claim_token: str,
43
72
  ) -> None:
73
+ """Require the owning thread for delivery unless the caller presents a recovery claim token."""
44
74
  if owning_thread_id != requesting_thread_id and not claim_token.startswith(
45
75
  RECOVERY_HANDOFF_TOKEN_PREFIX
46
76
  ):
@@ -54,6 +84,12 @@ def claim_handoff_delivery(
54
84
  connection: sqlite3.Connection,
55
85
  args: argparse.Namespace,
56
86
  ) -> dict[str, Any]:
87
+ """Claim a pending handoff and return the current workspace state.
88
+
89
+ The first claim wins. When take_over_stale is requested, replacing an expired
90
+ claim also clears the continuation and deep scan owner. Retrying the same claim
91
+ or losing a competing claim returns the workspace state without changing ownership.
92
+ """
57
93
  scan_id = require_uuid(args.scan_id, "scan-id")
58
94
  claim_token = require_handoff_claim_token(args.claim_token)
59
95
  timestamp = wb.now()
@@ -102,6 +138,7 @@ def release_handoff_delivery(
102
138
  connection: sqlite3.Connection,
103
139
  args: argparse.Namespace,
104
140
  ) -> dict[str, Any]:
141
+ """Release a matching pending claim, detach its continuation, and return the workspace state."""
105
142
  scan_id = require_uuid(args.scan_id, "scan-id")
106
143
  claim_token = require_handoff_claim_token(args.claim_token)
107
144
  timestamp = wb.now()
@@ -126,6 +163,11 @@ def attach_scan_continuation_thread(
126
163
  connection: sqlite3.Connection,
127
164
  args: argparse.Namespace,
128
165
  ) -> dict[str, Any]:
166
+ """Bind the claimed scan to a continuation and return its workspace state.
167
+
168
+ An immediate transaction serializes ownership changes. Reattaching the same
169
+ thread is idempotent. A different thread or mismatched claim token raises SystemExit.
170
+ """
129
171
  scan_id = require_uuid(args.scan_id, "scan-id")
130
172
  claim_token = require_handoff_claim_token(args.claim_token)
131
173
  thread_id = optional_text(args.thread_id, maximum=512)
@@ -165,6 +207,11 @@ def mark_handoff_delivered(
165
207
  connection: sqlite3.Connection,
166
208
  args: argparse.Namespace,
167
209
  ) -> dict[str, Any]:
210
+ """Record delivery for the pending claim and return the workspace state.
211
+
212
+ For standard scans this resets preflight progress. The same claim can confirm
213
+ delivery again. A conflicting claim or invalid requesting thread raises SystemExit.
214
+ """
168
215
  scan_id = require_uuid(args.scan_id, "scan-id")
169
216
  claim_token = require_handoff_claim_token(args.claim_token)
170
217
  thread_id = optional_text(args.thread_id, maximum=512)