@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
@@ -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
@@ -59,6 +71,7 @@ _OPEN_EXISTING = 3
59
71
  _FILE_ATTRIBUTE_DIRECTORY = 0x00000010
60
72
  _FILE_ATTRIBUTE_NORMAL = 0x00000080
61
73
  _FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400
74
+ _REPARSE_TAG_NAME_SURROGATE = 0x20000000
62
75
  _FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
63
76
  _FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
64
77
 
@@ -66,6 +79,7 @@ _FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
66
79
  _FILE_RENAME_INFO_CLASS = 3
67
80
  _FILE_DISPOSITION_INFO_CLASS = 4
68
81
  _FILE_ATTRIBUTE_TAG_INFO_CLASS = 9
82
+ _FILE_ID_INFO_CLASS = 18
69
83
 
70
84
  _FILE_TYPE_DISK = 0x0001
71
85
  _FILE_NAME_OPENED = 0x00000008
@@ -78,6 +92,7 @@ _ERROR_FILE_EXISTS = 80
78
92
  _ERROR_INSUFFICIENT_BUFFER = 122
79
93
  _ERROR_ALREADY_EXISTS = 183
80
94
  _ERROR_DIRECTORY = 267
95
+ _OWNER_SECURITY_INFORMATION = 0x00000001
81
96
  _DACL_SECURITY_INFORMATION = 0x00000004
82
97
  _MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
83
98
  _COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
@@ -117,11 +132,30 @@ class _FileAttributeTagInfo(ctypes.Structure):
117
132
  ]
118
133
 
119
134
 
135
+ class _FileIdInfo(ctypes.Structure):
136
+ _fields_ = [("VolumeSerialNumber", ctypes.c_uint64), ("FileId", ctypes.c_ubyte * 16)]
137
+
138
+
139
+ class _ByHandleFileInformation(ctypes.Structure):
140
+ _fields_ = [
141
+ ("dwFileAttributes", wintypes.DWORD),
142
+ ("ftCreationTime", wintypes.FILETIME),
143
+ ("ftLastAccessTime", wintypes.FILETIME),
144
+ ("ftLastWriteTime", wintypes.FILETIME),
145
+ ("dwVolumeSerialNumber", wintypes.DWORD),
146
+ ("nFileSizeHigh", wintypes.DWORD),
147
+ ("nFileSizeLow", wintypes.DWORD),
148
+ ("nNumberOfLinks", wintypes.DWORD),
149
+ ("nFileIndexHigh", wintypes.DWORD),
150
+ ("nFileIndexLow", wintypes.DWORD),
151
+ ]
152
+
153
+
120
154
  class _SecurityAttributes(ctypes.Structure):
121
155
  _fields_ = [
122
- ("nLength", wintypes.DWORD),
123
- ("lpSecurityDescriptor", wintypes.LPVOID),
124
- ("bInheritHandle", wintypes.BOOL),
156
+ ("length", wintypes.DWORD),
157
+ ("descriptor", wintypes.LPVOID),
158
+ ("inherit", wintypes.BOOL),
125
159
  ]
126
160
 
127
161
 
@@ -169,6 +203,7 @@ class _OwnedHandle:
169
203
  if os.name == "nt":
170
204
  _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
171
205
  _advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
206
+ _ntdll = ctypes.WinDLL("ntdll")
172
207
 
173
208
  _GetFileSecurityW = _advapi32.GetFileSecurityW
174
209
  _GetFileSecurityW.argtypes = [
@@ -180,6 +215,10 @@ if os.name == "nt":
180
215
  ]
181
216
  _GetFileSecurityW.restype = wintypes.BOOL
182
217
 
218
+ _GetDriveTypeW = _kernel32.GetDriveTypeW
219
+ _GetDriveTypeW.argtypes = [wintypes.LPCWSTR]
220
+ _GetDriveTypeW.restype = wintypes.UINT
221
+
183
222
  _CreateFileW = _kernel32.CreateFileW
184
223
  _CreateFileW.argtypes = [
185
224
  wintypes.LPCWSTR,
@@ -212,6 +251,12 @@ if os.name == "nt":
212
251
  wintypes.DWORD,
213
252
  ]
214
253
  _GetFileInformationByHandleEx.restype = wintypes.BOOL
254
+ _GetFileInformationByHandle = _kernel32.GetFileInformationByHandle
255
+ _GetFileInformationByHandle.argtypes = [
256
+ wintypes.HANDLE,
257
+ ctypes.POINTER(_ByHandleFileInformation),
258
+ ]
259
+ _GetFileInformationByHandle.restype = wintypes.BOOL
215
260
 
216
261
  _GetFileType = _kernel32.GetFileType
217
262
  _GetFileType.argtypes = [wintypes.HANDLE]
@@ -424,9 +469,11 @@ def _verify_handle_path(handle: int, expected_path: Path, *, opened_name: bool =
424
469
  raise _invalid_path(expected_path, "opened file resolved outside its verified scan path")
425
470
 
426
471
 
427
- def _verify_directory(handle: int, expected_path: Path) -> None:
472
+ def _verify_directory(handle: int, expected_path: Path, checkout: bool = False) -> None:
428
473
  info = _attributes(handle)
429
- if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
474
+ if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT and (
475
+ not checkout or not info.ReparseTag or info.ReparseTag & _REPARSE_TAG_NAME_SURROGATE
476
+ ):
430
477
  raise _invalid_path(expected_path, "scan-local directories must not be reparse points")
431
478
  if not info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY:
432
479
  raise _invalid_path(expected_path, "expected a scan-local directory")
@@ -462,11 +509,13 @@ def _open_directory(
462
509
  missing_ok: bool = False,
463
510
  missing_is_path_error: bool = True,
464
511
  movable: bool = False,
512
+ checkout: bool = False,
465
513
  ) -> _OwnedHandle | None:
466
514
  try:
467
515
  handle = _create_file(
468
516
  path,
469
- access=_FILE_READ_ATTRIBUTES,
517
+ # Attribute-only handles do not participate in Win32 sharing checks.
518
+ access=_FILE_READ_ATTRIBUTES | (0 if movable else _FILE_TRAVERSE),
470
519
  share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | (_FILE_SHARE_DELETE if movable else 0),
471
520
  disposition=_OPEN_EXISTING,
472
521
  flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
@@ -481,7 +530,7 @@ def _open_directory(
481
530
  if handle is not None:
482
531
  try:
483
532
  assert handle.value is not None
484
- _verify_directory(handle.value, path)
533
+ _verify_directory(handle.value, path, checkout)
485
534
  except BaseException:
486
535
  handle.close()
487
536
  raise
@@ -496,25 +545,398 @@ def _create_directory(path: Path) -> None:
496
545
  _raise_last_error("CreateDirectoryW", path)
497
546
 
498
547
 
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()
548
+ def _directory_security_descriptor(source: Path, information: int) -> ctypes.Array:
502
549
  source_path = _extended_path(source)
503
550
  size = wintypes.DWORD()
504
- _GetFileSecurityW(source_path, _DACL_SECURITY_INFORMATION, None, 0, ctypes.byref(size))
551
+ _GetFileSecurityW(source_path, information, None, 0, ctypes.byref(size))
505
552
  if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
506
553
  _raise_last_error("GetFileSecurityW", source)
507
554
  descriptor = ctypes.create_string_buffer(size.value)
508
- if not _GetFileSecurityW(
509
- source_path, _DACL_SECURITY_INFORMATION, descriptor, size.value, ctypes.byref(size)
510
- ):
555
+ if not _GetFileSecurityW(source_path, information, descriptor, size.value, ctypes.byref(size)):
511
556
  _raise_last_error("GetFileSecurityW", source)
512
- attributes = _SecurityAttributes(
513
- ctypes.sizeof(_SecurityAttributes), ctypes.cast(descriptor, wintypes.LPVOID), False
557
+ return descriptor
558
+
559
+
560
+ def _sid_text(sid: wintypes.LPVOID) -> str:
561
+ value = wintypes.LPWSTR()
562
+ if not _advapi32.ConvertSidToStringSidW(sid, ctypes.byref(value)):
563
+ _raise_last_error("ConvertSidToStringSidW")
564
+ try:
565
+ return value.value
566
+ finally:
567
+ _kernel32.LocalFree(value)
568
+
569
+
570
+ @functools.cache
571
+ def _current_user_sid() -> str:
572
+ token = wintypes.HANDLE(-4) # GetCurrentProcessToken pseudo-handle.
573
+ size = wintypes.DWORD()
574
+ _advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
575
+ if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
576
+ _raise_last_error("GetTokenInformation")
577
+ user = ctypes.create_string_buffer(size.value)
578
+ if not _advapi32.GetTokenInformation(token, 1, user, size, ctypes.byref(size)):
579
+ _raise_last_error("GetTokenInformation")
580
+ return _sid_text(wintypes.LPVOID.from_buffer(user))
581
+
582
+
583
+ def _output_directory_grants(handle: int, path: Path, *, expected_descriptor=None) -> int:
584
+ """Inspect the descriptor of the opened directory, even if its pathname changes."""
585
+ owner, acl, descriptor = wintypes.LPVOID(), wintypes.LPVOID(), wintypes.LPVOID()
586
+ status = _advapi32.GetSecurityInfo(
587
+ wintypes.HANDLE(handle),
588
+ 1,
589
+ _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
590
+ ctypes.byref(owner),
591
+ None,
592
+ ctypes.byref(acl),
593
+ None,
594
+ ctypes.byref(descriptor),
514
595
  )
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)
596
+ if status:
597
+ raise ctypes.WinError(status)
598
+ try:
599
+ if expected_descriptor is not None and _generated_directory_policy(
600
+ descriptor
601
+ ) != _generated_directory_policy(expected_descriptor):
602
+ raise _invalid_path(path, "new scan directory lacks its private owner or DACL")
603
+ trusted = {
604
+ _current_user_sid(),
605
+ "S-1-5-18",
606
+ "S-1-5-32-544", # Current user, SYSTEM, Administrators.
607
+ "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464", # TrustedInstaller.
608
+ }
609
+ if _sid_text(owner) not in trusted:
610
+ raise _invalid_path(path, "Scan output directory must have a trusted owner.")
611
+ return _output_dacl_grants(acl, trusted, path)
612
+ finally:
613
+ _kernel32.LocalFree(descriptor)
614
+
615
+
616
+ def _authenticated_account(sid: wintypes.LPVOID, trustee: str) -> bool:
617
+ # The Guest account can have its own SID without Authenticated Users membership.
618
+ if not trustee.startswith("S-1-5-21-") or trustee.endswith("-501"):
619
+ return False
620
+ name_size, domain_size, sid_type = (ctypes.pointer(wintypes.DWORD()) for _ in range(3))
621
+ lookup = _advapi32.LookupAccountSidW
622
+ lookup(None, sid, None, name_size, None, domain_size, sid_type)
623
+ if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
624
+ return False
625
+ name = ctypes.create_unicode_buffer(name_size.contents.value)
626
+ domain = ctypes.create_unicode_buffer(domain_size.contents.value)
627
+ found = lookup(None, sid, name, name_size, domain, domain_size, sid_type)
628
+ return bool(found) and sid_type.contents.value == 1 # SidTypeUser
629
+
630
+
631
+ def _output_dacl_grants(acl: wintypes.LPVOID, trusted: set[str], path: Path) -> int:
632
+ if not acl.value: # A NULL DACL grants full access.
633
+ return _OUTPUT_RIGHTS
634
+ # Read ACEs in DACL order. A deny masks future grants for its trustee.
635
+ denied: dict[str, int] = {}
636
+ granted = 0
637
+ for index in range(wintypes.WORD.from_address(acl.value + 4).value): # ACL.AceCount
638
+ ace = wintypes.LPVOID()
639
+ if not _advapi32.GetAce(acl, index, ctypes.byref(ace)):
640
+ _raise_last_error("GetAce", path)
641
+ kind, flags, size = struct.unpack("<BBH", ctypes.string_at(ace, 4))
642
+ if flags & 8 or kind in {10, 12}: # INHERIT_ONLY or conditional deny.
643
+ continue
644
+ entry = ctypes.string_at(ace, size)
645
+ mask = struct.unpack_from("<I", entry, 4)[0]
646
+ if mask & 0x10000000: # GENERIC_ALL
647
+ mask |= _OUTPUT_RIGHTS
648
+ if mask & _GENERIC_WRITE:
649
+ mask |= _FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT
650
+ mask &= _OUTPUT_RIGHTS
651
+ if not mask:
652
+ continue
653
+ offset = 8 # ACE_HEADER and ACCESS_MASK precede the trustee SID.
654
+ if kind in {5, 6, 11}:
655
+ object_flags = struct.unpack_from("<I", entry, offset)[0]
656
+ offset += 4 + 16 * (object_flags & 3).bit_count()
657
+ if kind == 6 and object_flags & 1:
658
+ continue # This deny is scoped to a particular object type.
659
+ elif kind not in {0, 1, 9}:
660
+ raise _invalid_path(path, "Unable to evaluate scan output directory permissions.")
661
+ if len(entry) < offset + 8 or len(entry) < offset + 8 + 4 * entry[offset + 1]:
662
+ raise _invalid_path(path, "Invalid scan output directory trustee.")
663
+ sid = wintypes.LPVOID(ace.value + offset)
664
+ trustee = _sid_text(sid)
665
+ if trustee in trusted or trustee == "S-1-3-4": # OWNER RIGHTS applies to the checked owner.
666
+ continue
667
+ if kind in {1, 6}:
668
+ denied[trustee] = denied.get(trustee, 0) | mask
669
+ else:
670
+ blocked = denied.get(trustee, 0) | denied.get("S-1-1-0", 0)
671
+ authenticated = denied.get("S-1-5-11", 0)
672
+ if mask & authenticated and _authenticated_account(sid, trustee):
673
+ blocked |= authenticated
674
+ granted |= mask & ~blocked
675
+ if granted & _CHANGE_ACL:
676
+ granted |= _OUTPUT_RIGHTS
677
+ return granted
678
+
679
+
680
+ def _require_stable_output(path: Path, parent_grants: int, child_grants: int = 0) -> None:
681
+ can_remove = parent_grants & _FILE_DELETE_CHILD or child_grants & _DELETE
682
+ can_replace = parent_grants & (_FILE_ADD_SUBDIRECTORY | _SET_REPARSE_POINT)
683
+ if can_remove and can_replace:
684
+ raise _invalid_path(path, "Scan output directory can be replaced by another user.")
685
+
686
+
687
+ @contextlib.contextmanager
688
+ def _checked_output_directory(path: Path) -> Iterator[tuple[int | None, int, int]]:
689
+ """Hold the checked chain and expose its parent, final directory handle and grants."""
690
+ parent_grants = 0
691
+ parent = None
692
+ with contextlib.ExitStack() as pins:
693
+ for directory in (*reversed(path.parents), path):
694
+ if parent is None:
695
+ handle = _create_file(
696
+ directory,
697
+ access=_FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL,
698
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
699
+ disposition=_OPEN_EXISTING,
700
+ flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
701
+ )
702
+ assert handle is not None
703
+ else:
704
+ error, child = _relative_output_directory(parent, directory.name)
705
+ if error:
706
+ raise WindowsScanLocalPathError(
707
+ error, ctypes.FormatError(error), str(directory)
708
+ )
709
+ handle = _OwnedHandle(child)
710
+ pins.enter_context(handle)
711
+ assert handle.value is not None
712
+ _verify_directory(handle.value, directory)
713
+ grants = _output_directory_grants(handle.value, directory)
714
+ _require_stable_output(directory, parent_grants, grants)
715
+ containing, parent, parent_grants = parent, handle.value, grants
716
+ yield containing, parent, parent_grants
717
+
718
+
719
+ def require_windows_output_path(path: Path, *, writable_output: bool = False) -> None:
720
+ with _checked_output_directory(path) as (_, _, grants):
721
+ if writable_output and grants & _SET_REPARSE_POINT:
722
+ raise _invalid_path(
723
+ path, "Another user can turn the output directory into a reparse point when empty."
724
+ )
725
+
726
+
727
+ DEEP_RESUME_DIRECTORY = ".codex-security-resume"
728
+
729
+
730
+ def deep_resume_output_identity(scan_dir: Path) -> list[int]:
731
+ """Bind the output and its protected child while every directory is pinned."""
732
+ retained = scan_dir / DEEP_RESUME_DIRECTORY
733
+ with _checked_output_directory(retained) as (parent, child, grants):
734
+ assert parent is not None
735
+ return _pinned_resume_identity(parent, child, retained, grants)
736
+
737
+
738
+ def _full_directory_id(handle: int, path: Path) -> tuple[int, int] | None:
739
+ info = _FileIdInfo()
740
+ if not _GetFileInformationByHandleEx(
741
+ handle, _FILE_ID_INFO_CLASS, ctypes.byref(info), ctypes.sizeof(info)
742
+ ):
743
+ if ctypes.get_last_error() in {50, 87}: # ERROR_NOT_SUPPORTED or ERROR_INVALID_PARAMETER.
744
+ return None
745
+ _raise_last_error("GetFileInformationByHandleEx(FileIdInfo)", path)
746
+ file_id = int.from_bytes(info.FileId, "little")
747
+ if not file_id:
748
+ raise _invalid_path(path, "The resume directory has no stable file identity.")
749
+ return info.VolumeSerialNumber, file_id
750
+
751
+
752
+ def _resume_directory_id(handle: int, path: Path) -> tuple[int, int]:
753
+ if (identity := _full_directory_id(handle, path)) is not None:
754
+ return identity
755
+ # Some filesystems expose only the legacy 64-bit file index.
756
+ legacy = _ByHandleFileInformation()
757
+ if not _GetFileInformationByHandle(handle, ctypes.byref(legacy)):
758
+ _raise_last_error("GetFileInformationByHandle", path)
759
+ file_id = (legacy.nFileIndexHigh << 32) | legacy.nFileIndexLow
760
+ if not file_id:
761
+ raise _invalid_path(path, "The resume directory has no stable file identity.")
762
+ return legacy.dwVolumeSerialNumber, file_id
763
+
764
+
765
+ @contextlib.contextmanager
766
+ def pinned_resume_checkout(target: Path) -> Iterator[tuple[int, int] | None]:
767
+ """Keep the canonical checkout fixed while reading its full native identity and snapshot."""
768
+ with contextlib.ExitStack() as pins:
769
+ for directory in (*reversed(target.parents), target):
770
+ # A source provider directory may carry a reparse tag without redirecting its name.
771
+ handle = _open_directory(directory, checkout=True)
772
+ assert handle is not None
773
+ pins.enter_context(handle)
774
+ assert handle.value is not None
775
+ yield _full_directory_id(handle.value, target)
776
+
777
+
778
+ def _pinned_resume_identity(parent: int, child: int, retained: Path, grants: int) -> list[int]:
779
+ # A nonreplaceable, protected child keeps the scan root nonempty after
780
+ # the sandbox receives Modify there. The caller holds both directories.
781
+ if grants:
782
+ raise _invalid_path(retained, "The retained resume directory must be protected.")
783
+ return [*_resume_directory_id(parent, retained.parent), *_resume_directory_id(child, retained)]
784
+
785
+
786
+ class _UnicodeString(ctypes.Structure):
787
+ _fields_ = [
788
+ ("length", wintypes.USHORT),
789
+ ("capacity", wintypes.USHORT),
790
+ ("text", wintypes.LPWSTR),
791
+ ]
792
+
793
+
794
+ class _ObjectAttributes(ctypes.Structure):
795
+ _fields_ = [
796
+ ("length", wintypes.ULONG),
797
+ ("root", wintypes.HANDLE),
798
+ ("name", ctypes.POINTER(_UnicodeString)),
799
+ ("attributes", wintypes.ULONG),
800
+ ("security", wintypes.LPVOID),
801
+ ("qos", wintypes.LPVOID),
802
+ ]
803
+
804
+
805
+ def _relative_output_directory(
806
+ parent: int, basename: str, descriptor=None, *, rollback_handle: bool = False
807
+ ) -> tuple[int, int | None]:
808
+ """Open or create one component relative to its checked parent without reparsing it."""
809
+ size = len(basename.encode("utf-16-le", errors="surrogatepass"))
810
+ if size >= 1 << 16: # UNICODE_STRING.Length is a byte count in a USHORT.
811
+ return 206, None
812
+ name = _UnicodeString(size, size, basename)
813
+ attributes = _ObjectAttributes(
814
+ ctypes.sizeof(_ObjectAttributes),
815
+ parent,
816
+ ctypes.pointer(name),
817
+ 0x40 | 0x1000, # OBJ_CASE_INSENSITIVE | OBJ_DONT_REPARSE
818
+ descriptor,
819
+ None,
820
+ )
821
+ handle = wintypes.HANDLE()
822
+ io_status = (ctypes.c_void_p * 2)() # IO_STATUS_BLOCK
823
+ status = _ntdll.NtCreateFile(
824
+ ctypes.byref(handle),
825
+ _FILE_TRAVERSE
826
+ | _FILE_READ_ATTRIBUTES
827
+ | _READ_CONTROL
828
+ | 0x100000
829
+ | (_DELETE if rollback_handle else 0),
830
+ ctypes.byref(attributes),
831
+ ctypes.byref(io_status),
832
+ None,
833
+ _FILE_ATTRIBUTE_NORMAL,
834
+ 0 if rollback_handle else _FILE_SHARE_READ | _FILE_SHARE_WRITE,
835
+ 1 if descriptor is None else 2, # FILE_OPEN or FILE_CREATE
836
+ 0x200021, # FILE_OPEN_REPARSE_POINT | FILE_SYNCHRONOUS_IO_NONALERT | FILE_DIRECTORY_FILE
837
+ None,
838
+ 0,
839
+ )
840
+ return (_ntdll.RtlNtStatusToDosError(status), None) if status < 0 else (0, handle.value)
841
+
842
+
843
+ def create_windows_output_directory(path: Path, descriptor: wintypes.LPVOID) -> int:
844
+ with _checked_output_directory(path.parent) as (_, parent, grants):
845
+ _require_stable_output(path, grants)
846
+ error, handle = _relative_output_directory(parent, path.name, descriptor)
847
+ if not error:
848
+ _close_handle(handle)
849
+ return error
850
+
851
+
852
+ @contextlib.contextmanager
853
+ def _private_directory_descriptor(path: Path, *, explicit_owner: bool) -> Iterator[wintypes.LPVOID]:
854
+ _require_windows()
855
+ # Older supported Python releases ignore mkdir's 0700 mode on Windows.
856
+ # Apply the same owner/SYSTEM/Administrators policy at creation so a
857
+ # writable parent never becomes an inheritance window.
858
+ volume = ctypes.create_unicode_buffer(32768)
859
+ flags = wintypes.DWORD()
860
+ if not _kernel32.GetVolumePathNameW(str(path.parent.resolve()), volume, len(volume)):
861
+ raise ctypes.WinError(ctypes.get_last_error())
862
+ if not _kernel32.GetVolumeInformationW(
863
+ volume, None, 0, None, None, ctypes.byref(flags), None, 0
864
+ ):
865
+ raise ctypes.WinError(ctypes.get_last_error())
866
+ if not flags.value & 0x8: # FILE_PERSISTENT_ACLS
867
+ raise ValueError("Select a directory on a Windows volume that supports ACLs.")
868
+
869
+ sid = _current_user_sid()
870
+ owner = f"O:{sid}" if explicit_owner else ""
871
+ dacl = f"{owner}D:P(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;FA;;;{sid})"
872
+
873
+ descriptor = wintypes.LPVOID()
874
+ if not _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
875
+ dacl, 1, ctypes.byref(descriptor), None
876
+ ):
877
+ raise ctypes.WinError(ctypes.get_last_error())
878
+ try:
879
+ yield descriptor
880
+ finally:
881
+ _kernel32.LocalFree(descriptor)
882
+
883
+
884
+ def create_private_directory(path: Path, *, exist_ok: bool, scan_output: bool) -> Path:
885
+ """Create one Windows directory with a protected inheritable DACL."""
886
+ with _private_directory_descriptor(path, explicit_owner=not exist_ok) as descriptor:
887
+ if scan_output:
888
+ error = create_windows_output_directory(path, descriptor)
889
+ else:
890
+ attributes = _SecurityAttributes(ctypes.sizeof(_SecurityAttributes), descriptor, False)
891
+ error = (
892
+ 0
893
+ if _CreateDirectoryW(str(path), ctypes.byref(attributes))
894
+ else ctypes.get_last_error()
895
+ )
896
+ if not error:
897
+ return path if exist_ok else verify_private_scan_root(path, descriptor)
898
+ if exist_ok and error == 183 and path.is_dir(): # ERROR_ALREADY_EXISTS
899
+ if scan_output:
900
+ require_windows_output_path(path)
901
+ return path
902
+ raise ctypes.WinError(error)
903
+
904
+
905
+ @contextlib.contextmanager
906
+ def create_deep_resume_output(scan_dir: Path, committed: Callable[[], bool]) -> Iterator[list[int]]:
907
+ """Retain the exact creation handle through verification and database commit."""
908
+ retained = scan_dir / DEEP_RESUME_DIRECTORY
909
+ with (
910
+ _private_directory_descriptor(retained, explicit_owner=True) as descriptor,
911
+ _checked_output_directory(scan_dir) as (_, parent, grants),
912
+ ):
913
+ _require_stable_output(retained, grants)
914
+ error, child = _relative_output_directory(
915
+ parent, retained.name, descriptor, rollback_handle=True
916
+ )
917
+ if error:
918
+ raise ctypes.WinError(error)
919
+ assert child is not None
920
+ with _OwnedHandle(child):
921
+ try:
922
+ _verify_directory(child, retained)
923
+ child_grants = _output_directory_grants(
924
+ child, retained, expected_descriptor=descriptor
925
+ )
926
+ yield _pinned_resume_identity(parent, child, retained, child_grants)
927
+ except BaseException:
928
+ if not committed():
929
+ _mark_handle_for_deletion(child)
930
+ raise
931
+
932
+
933
+ def create_directory_with_same_dacl(path: Path, source: Path) -> None:
934
+ """Create an archive replacement with the original directory's DACL."""
935
+ _require_windows()
936
+ descriptor = _directory_security_descriptor(source, _DACL_SECURITY_INFORMATION)
937
+ error = create_windows_output_directory(path, ctypes.cast(descriptor, wintypes.LPVOID))
938
+ if error:
939
+ raise WindowsScanLocalFileError(error, ctypes.FormatError(error), str(path))
518
940
 
519
941
 
520
942
  @contextlib.contextmanager
@@ -572,6 +994,37 @@ def _locked_parent(
572
994
  handle.close()
573
995
 
574
996
 
997
+ def _generated_directory_policy(descriptor: object) -> tuple[str, bool, frozenset[str]]:
998
+ # Let Windows normalize SID aliases, access masks and inheritance flags in
999
+ # both descriptors. ACE order is immaterial for our three allow grants.
1000
+ sddl = wintypes.LPWSTR()
1001
+ if not _advapi32.ConvertSecurityDescriptorToStringSecurityDescriptorW(
1002
+ descriptor,
1003
+ 1,
1004
+ _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION,
1005
+ ctypes.byref(sddl),
1006
+ None,
1007
+ ):
1008
+ _raise_last_error("ConvertSecurityDescriptorToStringSecurityDescriptorW")
1009
+ try:
1010
+ owner, _, dacl = sddl.value.partition("D:")
1011
+ flags, _, entries = dacl.partition("(")
1012
+ return owner, "P" in flags, frozenset(entries.removesuffix(")").split(")("))
1013
+ finally:
1014
+ _kernel32.LocalFree(sddl)
1015
+
1016
+
1017
+ def verify_private_scan_root(scan_dir: Path, expected_descriptor: object) -> Path:
1018
+ """Verify the new directory's owner and protected grants while the path is pinned."""
1019
+ with _locked_parent(scan_dir, ".security", create=False) as (root_path, _):
1020
+ actual = _directory_security_descriptor(
1021
+ root_path, _OWNER_SECURITY_INFORMATION | _DACL_SECURITY_INFORMATION
1022
+ )
1023
+ if _generated_directory_policy(actual) != _generated_directory_policy(expected_descriptor):
1024
+ raise _invalid_path(scan_dir, "new scan directory lacks its private owner or DACL")
1025
+ return root_path
1026
+
1027
+
575
1028
  def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
576
1029
  """Return a canonical scan root and its identity while holding it fixed."""
577
1030
 
@@ -580,6 +1033,110 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
580
1033
  return root_path, (metadata.st_dev, metadata.st_ino)
581
1034
 
582
1035
 
1036
+ @contextlib.contextmanager
1037
+ def pinned_root_git_marker(
1038
+ cwd: Path, metadata: Path, *, work_tree: Path | None = None
1039
+ ) -> Iterator[Path | None]:
1040
+ """Return a short explicit worktree marker while its cwd and Git metadata are pinned."""
1041
+ if work_tree is None:
1042
+ work_tree = cwd
1043
+ if (
1044
+ not cwd.is_absolute()
1045
+ or not metadata.is_absolute()
1046
+ or len(cwd.drive) != 2
1047
+ or len(metadata.drive) != 2
1048
+ or len(work_tree.parts) < 2
1049
+ or cwd.parts[: len(work_tree.parts)] != work_tree.parts
1050
+ or len(metadata.parts) < 2
1051
+ or _GetDriveTypeW(cwd.anchor) != _DRIVE_FIXED
1052
+ or _GetDriveTypeW(metadata.anchor) != _DRIVE_FIXED
1053
+ ):
1054
+ yield None
1055
+ return
1056
+ marker = None
1057
+ with contextlib.ExitStack() as pins:
1058
+ try:
1059
+ for path in (cwd, metadata):
1060
+ _validated_parts(PurePosixPath(*path.parts[1:]).as_posix())
1061
+ # Pin each literal ancestor before opening the next component. Never resolve
1062
+ # a repository-controlled reparse point to find the directory to be pinned.
1063
+ for directory in (*reversed(path.parents), path):
1064
+ handle = _open_directory(directory)
1065
+ assert handle is not None
1066
+ pins.enter_context(handle)
1067
+ assert handle.value is not None
1068
+ if _final_path(handle.value) != _extended_path(path):
1069
+ raise ValueError("the selected Git directory spelling is not canonical")
1070
+ root_marker = work_tree / ".git"
1071
+ reference = Path(os.path.relpath(root_marker, cwd))
1072
+ if str(root_marker) != str(metadata):
1073
+ # The literal canonical root is already pinned before opening its regular file.
1074
+ fd, leaf = open_read_fd_with_path(work_tree, ".git", "Git metadata pointer")
1075
+ pointer = pins.enter_context(os.fdopen(fd, "rb"))
1076
+ if leaf != ".git":
1077
+ raise ValueError("the root marker name does not match .git")
1078
+ expected = f"gitdir: {metadata}".encode("utf-8")
1079
+ value = pointer.read(len(expected) + 3).removesuffix(b"\n").removesuffix(b"\r")
1080
+ if value.replace(b"/", b"\\") != expected:
1081
+ raise ValueError("the root marker does not name the selected Git directory")
1082
+ # A deep scope can make the relative spelling longer than the gitfile itself.
1083
+ if len(os.fsencode(root_marker)) < len(os.fsencode(reference)):
1084
+ reference = root_marker
1085
+ marker = reference
1086
+ except (OSError, ValueError):
1087
+ pins.close()
1088
+ yield marker
1089
+
1090
+
1091
+ def pin_replay_metadata(
1092
+ pins: contextlib.ExitStack, metadata: Path | None, scratch: Path
1093
+ ) -> Path | None:
1094
+ """Bind the selected metadata and fresh private Windows scratch before copying into it."""
1095
+ if os.name != "nt" or metadata is None:
1096
+ return None
1097
+ try:
1098
+ with contextlib.ExitStack() as checked:
1099
+ checked.enter_context(_locked_parent(metadata, "HEAD", create=False))
1100
+ checked.enter_context(_locked_parent(scratch.parent, scratch.name, create=False))
1101
+ directory = _create_file(
1102
+ scratch,
1103
+ access=_FILE_TRAVERSE | _FILE_READ_ATTRIBUTES | _READ_CONTROL,
1104
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
1105
+ disposition=_OPEN_EXISTING,
1106
+ flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
1107
+ )
1108
+ assert directory is not None and directory.value is not None
1109
+ checked.enter_context(directory)
1110
+ _verify_directory(directory.value, scratch)
1111
+ if _output_directory_grants(directory.value, scratch):
1112
+ return None
1113
+ pins.enter_context(checked.pop_all())
1114
+ except (OSError, ValueError):
1115
+ return None
1116
+ return metadata
1117
+
1118
+
1119
+ @contextlib.contextmanager
1120
+ def pinned_replay_gitfile(checkout: Path, metadata: Path) -> Iterator[Path]:
1121
+ """Keep Git's short metadata pointer outside the replay and immutable while Git uses it."""
1122
+ with _locked_parent(checkout, ".git", create=False):
1123
+ # Git reads this path relative to its unchanged worktree cwd. Both volumes'
1124
+ # literal ancestors are pinned, including the temporary directory above checkout.
1125
+ marker = checkout.parent / "reviewed.git"
1126
+ handle = _create_file(
1127
+ marker,
1128
+ access=_GENERIC_WRITE | _FILE_READ_ATTRIBUTES,
1129
+ share=_FILE_SHARE_READ,
1130
+ disposition=_CREATE_NEW,
1131
+ flags=_FILE_ATTRIBUTE_NORMAL | _FILE_FLAG_OPEN_REPARSE_POINT,
1132
+ )
1133
+ assert handle is not None and handle.value is not None
1134
+ with handle:
1135
+ _verify_regular_file(handle.value, marker)
1136
+ _write_all(handle.value, f"gitdir: {metadata.as_posix()}\n".encode("utf-8"))
1137
+ yield Path("..") / marker.name
1138
+
1139
+
583
1140
  def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
584
1141
  """Open a verified regular file and return an owned binary read descriptor."""
585
1142
 
@@ -587,7 +1144,11 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
587
1144
 
588
1145
 
589
1146
  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."""
1147
+ """Return an owned read descriptor and the scan-relative path with the file's actual leaf name.
1148
+
1149
+ Verify the regular file while holding its parent directories. The caller must
1150
+ close the returned descriptor.
1151
+ """
591
1152
 
592
1153
  try:
593
1154
  with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
@@ -636,6 +1197,7 @@ def file_change_time(descriptor: int) -> int:
636
1197
 
637
1198
 
638
1199
  def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:
1200
+ """Compare bytes from the current stream position to payload, requiring EOF after the final byte."""
639
1201
  offset = 0
640
1202
  while offset < len(payload):
641
1203
  chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))