@openai/codex-security 0.8.2 → 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 (649) hide show
  1. package/README.md +201 -178
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +6 -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 +51 -14
  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/core-scan.md +14 -5
  26. package/_bundled_plugin/references/default-severity-rubric.md +33 -0
  27. package/_bundled_plugin/references/final-report.md +5 -3
  28. package/_bundled_plugin/references/finding-detail-fields.md +19 -18
  29. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  30. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  31. package/_bundled_plugin/references/scan-contract.md +27 -33
  32. package/_bundled_plugin/references/threat-model.md +1 -0
  33. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  34. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  35. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  36. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  37. package/_bundled_plugin/scripts/deep_scan_workbench.py +188 -454
  38. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  39. package/_bundled_plugin/scripts/finalize_scan_contract.py +317 -377
  40. package/_bundled_plugin/scripts/finding_preview.py +25 -29
  41. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  42. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  43. package/_bundled_plugin/scripts/posix_scan_local_files.py +198 -0
  44. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  45. package/_bundled_plugin/scripts/report_projection.py +167 -178
  46. package/_bundled_plugin/scripts/review_state.py +8 -2
  47. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  48. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  49. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  50. package/_bundled_plugin/scripts/validate_scan_contract.py +9 -7
  51. package/_bundled_plugin/scripts/windows_scan_local_files.py +600 -72
  52. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  53. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  54. package/_bundled_plugin/scripts/workbench/retained_coverage.py +38 -75
  55. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  56. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  57. package/_bundled_plugin/scripts/workbench/saved_coverage.py +152 -248
  58. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  59. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  60. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  61. package/_bundled_plugin/scripts/workbench_cli.py +121 -14
  62. package/_bundled_plugin/scripts/workbench_constants.py +19 -0
  63. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  64. package/_bundled_plugin/scripts/workbench_db.py +550 -492
  65. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  66. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  67. package/_bundled_plugin/scripts/workbench_finding_workflows.py +90 -4
  68. package/_bundled_plugin/scripts/workbench_native_indexes.py +29 -33
  69. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  70. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  71. package/_bundled_plugin/scripts/workbench_remediation.py +508 -11
  72. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  73. package/_bundled_plugin/scripts/workbench_scan_history.py +139 -80
  74. package/_bundled_plugin/scripts/workbench_scan_start.py +84 -25
  75. package/_bundled_plugin/scripts/workbench_scan_usage.py +666 -117
  76. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  77. package/_bundled_plugin/scripts/workbench_setup.py +251 -0
  78. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  79. package/_bundled_plugin/scripts/workbench_source_scopes.py +33 -23
  80. package/_bundled_plugin/scripts/workbench_target.py +330 -66
  81. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  82. package/_bundled_plugin/scripts/workbench_validation.py +44 -12
  83. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -16
  84. package/_bundled_plugin/shared/workbench-migrations.json +53 -0
  85. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  86. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  87. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  88. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  89. package/_bundled_plugin/skills/cloud-findings/SKILL.md +6 -4
  90. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  91. package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -2
  92. package/_bundled_plugin/skills/publish-findings/SKILL.md +81 -45
  93. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  94. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +5 -24
  95. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  96. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +36 -9
  97. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  98. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  99. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +12 -6
  100. package/dist/api.d.ts +45 -5
  101. package/dist/api.d.ts.map +1 -1
  102. package/dist/api.js +1144 -411
  103. package/dist/api.js.map +1 -1
  104. package/dist/auth.d.ts.map +1 -1
  105. package/dist/auth.js +10 -7
  106. package/dist/auth.js.map +1 -1
  107. package/dist/bedrock-oss-pricing.d.ts +6 -0
  108. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  109. package/dist/bedrock-oss-pricing.js +58 -0
  110. package/dist/bedrock-oss-pricing.js.map +1 -0
  111. package/dist/bedrock-pricing.d.ts +15 -0
  112. package/dist/bedrock-pricing.d.ts.map +1 -0
  113. package/dist/bedrock-pricing.js +117 -0
  114. package/dist/bedrock-pricing.js.map +1 -0
  115. package/dist/blackduck-findings.d.ts +8 -0
  116. package/dist/blackduck-findings.d.ts.map +1 -0
  117. package/dist/blackduck-findings.js +320 -0
  118. package/dist/blackduck-findings.js.map +1 -0
  119. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  120. package/dist/bulk-scan-discovery.js +51 -36
  121. package/dist/bulk-scan-discovery.js.map +1 -1
  122. package/dist/checkmarx-evidence.d.ts +19 -0
  123. package/dist/checkmarx-evidence.d.ts.map +1 -0
  124. package/dist/checkmarx-evidence.js +36 -0
  125. package/dist/checkmarx-evidence.js.map +1 -0
  126. package/dist/checkmarx-findings.d.ts +4 -0
  127. package/dist/checkmarx-findings.d.ts.map +1 -0
  128. package/dist/checkmarx-findings.js +27 -0
  129. package/dist/checkmarx-findings.js.map +1 -0
  130. package/dist/checkmarx-one.d.ts +4 -0
  131. package/dist/checkmarx-one.d.ts.map +1 -0
  132. package/dist/checkmarx-one.js +53 -0
  133. package/dist/checkmarx-one.js.map +1 -0
  134. package/dist/checkmarx-repository.d.ts +12 -0
  135. package/dist/checkmarx-repository.d.ts.map +1 -0
  136. package/dist/checkmarx-repository.js +181 -0
  137. package/dist/checkmarx-repository.js.map +1 -0
  138. package/dist/checkmarx-xml.d.ts +12 -0
  139. package/dist/checkmarx-xml.d.ts.map +1 -0
  140. package/dist/checkmarx-xml.js +196 -0
  141. package/dist/checkmarx-xml.js.map +1 -0
  142. package/dist/classify-severity-records.d.ts +6 -9
  143. package/dist/classify-severity-records.d.ts.map +1 -1
  144. package/dist/classify-severity-records.js +9 -21
  145. package/dist/classify-severity-records.js.map +1 -1
  146. package/dist/classify-severity.d.ts +4 -1
  147. package/dist/classify-severity.d.ts.map +1 -1
  148. package/dist/classify-severity.js +30 -13
  149. package/dist/classify-severity.js.map +1 -1
  150. package/dist/cli.d.ts +14 -5
  151. package/dist/cli.d.ts.map +1 -1
  152. package/dist/cli.js +2112 -1266
  153. package/dist/cli.js.map +1 -1
  154. package/dist/cloud-publish.js +2 -2
  155. package/dist/cloud-publish.js.map +1 -1
  156. package/dist/codex-prompt.d.ts +2 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +6 -0
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/component-scan.d.ts +16 -3
  161. package/dist/component-scan.d.ts.map +1 -1
  162. package/dist/component-scan.js +32 -6
  163. package/dist/component-scan.js.map +1 -1
  164. package/dist/config.d.ts +2 -1
  165. package/dist/config.d.ts.map +1 -1
  166. package/dist/config.js +221 -65
  167. package/dist/config.js.map +1 -1
  168. package/dist/continuum-findings.d.ts +7 -0
  169. package/dist/continuum-findings.d.ts.map +1 -0
  170. package/dist/continuum-findings.js +225 -0
  171. package/dist/continuum-findings.js.map +1 -0
  172. package/dist/contract-values.d.ts +30 -0
  173. package/dist/contract-values.d.ts.map +1 -0
  174. package/dist/contract-values.js +78 -0
  175. package/dist/contract-values.js.map +1 -0
  176. package/dist/contract.d.ts +2 -20
  177. package/dist/contract.d.ts.map +1 -1
  178. package/dist/contract.js +58 -669
  179. package/dist/contract.js.map +1 -1
  180. package/dist/cost-model.d.ts +13 -1
  181. package/dist/cost-model.d.ts.map +1 -1
  182. package/dist/cost-model.js +66 -115
  183. package/dist/cost-model.js.map +1 -1
  184. package/dist/cost.d.ts +61 -4
  185. package/dist/cost.d.ts.map +1 -1
  186. package/dist/cost.js +2560 -100
  187. package/dist/cost.js.map +1 -1
  188. package/dist/custom-publish.d.ts +4 -0
  189. package/dist/custom-publish.d.ts.map +1 -1
  190. package/dist/custom-publish.js +40 -3
  191. package/dist/custom-publish.js.map +1 -1
  192. package/dist/custom-validation-prompt.d.ts +1 -1
  193. package/dist/custom-validation-prompt.d.ts.map +1 -1
  194. package/dist/custom-validation-prompt.js +5 -0
  195. package/dist/custom-validation-prompt.js.map +1 -1
  196. package/dist/custom-validation.d.ts +2 -0
  197. package/dist/custom-validation.d.ts.map +1 -1
  198. package/dist/custom-validation.js +4 -0
  199. package/dist/custom-validation.js.map +1 -1
  200. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  201. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.js +2 -2
  203. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  204. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  205. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.js +11 -4
  207. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  208. package/dist/deduplication/deduplication.js.map +1 -1
  209. package/dist/deduplication/finding-schema.d.ts +19 -1
  210. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  211. package/dist/deduplication/finding-schema.js +25 -0
  212. package/dist/deduplication/finding-schema.js.map +1 -1
  213. package/dist/deduplication/local.d.ts +2 -2
  214. package/dist/deduplication/local.d.ts.map +1 -1
  215. package/dist/deduplication/local.js +5 -10
  216. package/dist/deduplication/local.js.map +1 -1
  217. package/dist/deduplication/records.d.ts +8 -2
  218. package/dist/deduplication/records.d.ts.map +1 -1
  219. package/dist/deduplication/records.js +36 -8
  220. package/dist/deduplication/records.js.map +1 -1
  221. package/dist/deduplication/refusal.d.ts.map +1 -1
  222. package/dist/deduplication/refusal.js +25 -5
  223. package/dist/deduplication/refusal.js.map +1 -1
  224. package/dist/deduplication/scan.d.ts +3 -0
  225. package/dist/deduplication/scan.d.ts.map +1 -1
  226. package/dist/deduplication/scan.js +1 -1
  227. package/dist/deduplication/scan.js.map +1 -1
  228. package/dist/deep-config.d.ts +0 -1
  229. package/dist/deep-config.d.ts.map +1 -1
  230. package/dist/deep-config.js +22 -33
  231. package/dist/deep-config.js.map +1 -1
  232. package/dist/deep-scan-defaults.d.ts +2 -0
  233. package/dist/deep-scan-defaults.d.ts.map +1 -1
  234. package/dist/deep-scan-defaults.js +28 -1
  235. package/dist/deep-scan-defaults.js.map +1 -1
  236. package/dist/deep-scan.d.ts +13 -0
  237. package/dist/deep-scan.d.ts.map +1 -1
  238. package/dist/deep-scan.js +262 -7
  239. package/dist/deep-scan.js.map +1 -1
  240. package/dist/default-severity-rubric.d.ts +1 -2
  241. package/dist/default-severity-rubric.d.ts.map +1 -1
  242. package/dist/default-severity-rubric.js +2 -66
  243. package/dist/default-severity-rubric.js.map +1 -1
  244. package/dist/endor-findings.d.ts +3 -1
  245. package/dist/endor-findings.d.ts.map +1 -1
  246. package/dist/endor-findings.js +108 -80
  247. package/dist/endor-findings.js.map +1 -1
  248. package/dist/errors.d.ts +1 -1
  249. package/dist/errors.d.ts.map +1 -1
  250. package/dist/errors.js +9 -2
  251. package/dist/errors.js.map +1 -1
  252. package/dist/external-findings-import.d.ts +5 -3
  253. package/dist/external-findings-import.d.ts.map +1 -1
  254. package/dist/external-findings-import.js +11 -16
  255. package/dist/external-findings-import.js.map +1 -1
  256. package/dist/external-findings-local.d.ts +15 -4
  257. package/dist/external-findings-local.d.ts.map +1 -1
  258. package/dist/external-findings-local.js +619 -225
  259. package/dist/external-findings-local.js.map +1 -1
  260. package/dist/external-findings-publish.d.ts +20 -6
  261. package/dist/external-findings-publish.d.ts.map +1 -1
  262. package/dist/external-findings-publish.js +2356 -308
  263. package/dist/external-findings-publish.js.map +1 -1
  264. package/dist/external-findings-read.d.ts +28 -2
  265. package/dist/external-findings-read.d.ts.map +1 -1
  266. package/dist/external-findings-read.js +174 -81
  267. package/dist/external-findings-read.js.map +1 -1
  268. package/dist/external-findings.d.ts +17 -3
  269. package/dist/external-findings.d.ts.map +1 -1
  270. package/dist/external-findings.js +153 -1
  271. package/dist/external-findings.js.map +1 -1
  272. package/dist/external-import-contract.d.ts +33 -1
  273. package/dist/external-import-contract.d.ts.map +1 -1
  274. package/dist/external-import-contract.js +335 -51
  275. package/dist/external-import-contract.js.map +1 -1
  276. package/dist/external-import-models.d.ts +1 -1
  277. package/dist/external-import-models.d.ts.map +1 -1
  278. package/dist/external-import-models.js.map +1 -1
  279. package/dist/feedback.d.ts.map +1 -1
  280. package/dist/feedback.js +5 -4
  281. package/dist/feedback.js.map +1 -1
  282. package/dist/finding-prompt.d.ts +5 -0
  283. package/dist/finding-prompt.d.ts.map +1 -0
  284. package/dist/finding-prompt.js +32 -0
  285. package/dist/finding-prompt.js.map +1 -0
  286. package/dist/finding-retrieval.d.ts +3 -3
  287. package/dist/finding-retrieval.d.ts.map +1 -1
  288. package/dist/finding-retrieval.js.map +1 -1
  289. package/dist/finding-workflow.d.ts +6 -1
  290. package/dist/finding-workflow.d.ts.map +1 -1
  291. package/dist/finding-workflow.js +2 -2
  292. package/dist/finding-workflow.js.map +1 -1
  293. package/dist/findings-client.d.ts +1 -0
  294. package/dist/findings-client.d.ts.map +1 -1
  295. package/dist/findings-client.js +27 -3
  296. package/dist/findings-client.js.map +1 -1
  297. package/dist/git-remote.d.ts +4 -0
  298. package/dist/git-remote.d.ts.map +1 -1
  299. package/dist/git-remote.js +20 -0
  300. package/dist/git-remote.js.map +1 -1
  301. package/dist/github-advisories.d.ts +3 -12
  302. package/dist/github-advisories.d.ts.map +1 -1
  303. package/dist/github-advisories.js +9 -31
  304. package/dist/github-advisories.js.map +1 -1
  305. package/dist/github-dependabot-findings.d.ts.map +1 -1
  306. package/dist/github-dependabot-findings.js +22 -20
  307. package/dist/github-dependabot-findings.js.map +1 -1
  308. package/dist/github-findings.d.ts +4 -1
  309. package/dist/github-findings.d.ts.map +1 -1
  310. package/dist/github-findings.js +392 -79
  311. package/dist/github-findings.js.map +1 -1
  312. package/dist/github.d.ts +17 -7
  313. package/dist/github.d.ts.map +1 -1
  314. package/dist/github.js +43 -30
  315. package/dist/github.js.map +1 -1
  316. package/dist/host-protocol.d.ts +2 -2
  317. package/dist/host-protocol.d.ts.map +1 -1
  318. package/dist/host-protocol.js.map +1 -1
  319. package/dist/host-records-protocol.d.ts +10 -11
  320. package/dist/host-records-protocol.d.ts.map +1 -1
  321. package/dist/host-records-protocol.js +69 -9
  322. package/dist/host-records-protocol.js.map +1 -1
  323. package/dist/hosted-git-remotes.d.ts +5 -0
  324. package/dist/hosted-git-remotes.d.ts.map +1 -0
  325. package/dist/hosted-git-remotes.js +285 -0
  326. package/dist/hosted-git-remotes.js.map +1 -0
  327. package/dist/hosted-git-repository.d.ts +28 -0
  328. package/dist/hosted-git-repository.d.ts.map +1 -0
  329. package/dist/hosted-git-repository.js +222 -0
  330. package/dist/hosted-git-repository.js.map +1 -0
  331. package/dist/hosted-scan-protocol.js +2 -2
  332. package/dist/hosted-scan-protocol.js.map +1 -1
  333. package/dist/hosted-scan.d.ts +15 -0
  334. package/dist/hosted-scan.d.ts.map +1 -1
  335. package/dist/hosted-scan.js +71 -44
  336. package/dist/hosted-scan.js.map +1 -1
  337. package/dist/hosted-scanner-http.d.ts +21 -0
  338. package/dist/hosted-scanner-http.d.ts.map +1 -0
  339. package/dist/hosted-scanner-http.js +204 -0
  340. package/dist/hosted-scanner-http.js.map +1 -0
  341. package/dist/hosted-scanner-v1.d.ts +6 -0
  342. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  343. package/dist/hosted-scanner-v1.js +60 -0
  344. package/dist/hosted-scanner-v1.js.map +1 -0
  345. package/dist/import-scan.d.ts.map +1 -1
  346. package/dist/import-scan.js +3 -0
  347. package/dist/import-scan.js.map +1 -1
  348. package/dist/index.d.ts +24 -6
  349. package/dist/index.d.ts.map +1 -1
  350. package/dist/index.js +15 -1
  351. package/dist/index.js.map +1 -1
  352. package/dist/inspector-findings.d.ts.map +1 -1
  353. package/dist/inspector-findings.js +58 -81
  354. package/dist/inspector-findings.js.map +1 -1
  355. package/dist/knowledge-base.d.ts.map +1 -1
  356. package/dist/knowledge-base.js +86 -10
  357. package/dist/knowledge-base.js.map +1 -1
  358. package/dist/local-git-metadata.d.ts +5 -0
  359. package/dist/local-git-metadata.d.ts.map +1 -0
  360. package/dist/local-git-metadata.js +130 -0
  361. package/dist/local-git-metadata.js.map +1 -0
  362. package/dist/multiscan.d.ts +6 -4
  363. package/dist/multiscan.d.ts.map +1 -1
  364. package/dist/multiscan.js +160 -77
  365. package/dist/multiscan.js.map +1 -1
  366. package/dist/native-json-findings.d.ts +2 -1
  367. package/dist/native-json-findings.d.ts.map +1 -1
  368. package/dist/native-json-findings.js +12 -2
  369. package/dist/native-json-findings.js.map +1 -1
  370. package/dist/opengrep-findings.d.ts +1 -0
  371. package/dist/opengrep-findings.d.ts.map +1 -1
  372. package/dist/opengrep-findings.js +49 -31
  373. package/dist/opengrep-findings.js.map +1 -1
  374. package/dist/operation-telemetry.d.ts +104 -0
  375. package/dist/operation-telemetry.d.ts.map +1 -0
  376. package/dist/operation-telemetry.js +293 -0
  377. package/dist/operation-telemetry.js.map +1 -0
  378. package/dist/patch-tui.d.ts.map +1 -1
  379. package/dist/patch-tui.js +90 -35
  380. package/dist/patch-tui.js.map +1 -1
  381. package/dist/plugin-python-probe.d.ts +4 -0
  382. package/dist/plugin-python-probe.d.ts.map +1 -0
  383. package/dist/plugin-python-probe.js +10 -0
  384. package/dist/plugin-python-probe.js.map +1 -0
  385. package/dist/private-finding-import.d.ts +341 -0
  386. package/dist/private-finding-import.d.ts.map +1 -0
  387. package/dist/private-finding-import.js +411 -0
  388. package/dist/private-finding-import.js.map +1 -0
  389. package/dist/project-config.d.ts.map +1 -1
  390. package/dist/project-config.js +2 -2
  391. package/dist/project-config.js.map +1 -1
  392. package/dist/provider-profile.d.ts +11 -3
  393. package/dist/provider-profile.d.ts.map +1 -1
  394. package/dist/provider-profile.js +80 -11
  395. package/dist/provider-profile.js.map +1 -1
  396. package/dist/publication-telemetry.d.ts +45 -0
  397. package/dist/publication-telemetry.d.ts.map +1 -0
  398. package/dist/publication-telemetry.js +50 -0
  399. package/dist/publication-telemetry.js.map +1 -0
  400. package/dist/publication.js +7 -1
  401. package/dist/publication.js.map +1 -1
  402. package/dist/publish.d.ts +4 -0
  403. package/dist/publish.d.ts.map +1 -1
  404. package/dist/publish.js +42 -2
  405. package/dist/publish.js.map +1 -1
  406. package/dist/reader-selection.d.ts +15 -0
  407. package/dist/reader-selection.d.ts.map +1 -0
  408. package/dist/reader-selection.js +89 -0
  409. package/dist/reader-selection.js.map +1 -0
  410. package/dist/record.d.ts +6 -1
  411. package/dist/record.d.ts.map +1 -1
  412. package/dist/record.js +53 -2
  413. package/dist/record.js.map +1 -1
  414. package/dist/remediation.d.ts +3 -1
  415. package/dist/remediation.d.ts.map +1 -1
  416. package/dist/remediation.js +28 -2
  417. package/dist/remediation.js.map +1 -1
  418. package/dist/request-metadata.d.ts +3 -0
  419. package/dist/request-metadata.d.ts.map +1 -1
  420. package/dist/request-metadata.js +9 -0
  421. package/dist/request-metadata.js.map +1 -1
  422. package/dist/result.d.ts +6 -0
  423. package/dist/result.d.ts.map +1 -1
  424. package/dist/result.js +3 -1
  425. package/dist/result.js.map +1 -1
  426. package/dist/retry-windows-rename.d.ts +8 -0
  427. package/dist/retry-windows-rename.d.ts.map +1 -0
  428. package/dist/retry-windows-rename.js +24 -0
  429. package/dist/retry-windows-rename.js.map +1 -0
  430. package/dist/runtime.d.ts +22 -1
  431. package/dist/runtime.d.ts.map +1 -1
  432. package/dist/runtime.js +408 -162
  433. package/dist/runtime.js.map +1 -1
  434. package/dist/saved-scan-bootstrap.d.ts +1 -0
  435. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  436. package/dist/saved-scan-bootstrap.js +18 -15
  437. package/dist/saved-scan-bootstrap.js.map +1 -1
  438. package/dist/scan-activity.d.ts.map +1 -1
  439. package/dist/scan-activity.js +172 -64
  440. package/dist/scan-activity.js.map +1 -1
  441. package/dist/scan-comparison.d.ts +10 -5
  442. package/dist/scan-comparison.d.ts.map +1 -1
  443. package/dist/scan-comparison.js +68 -25
  444. package/dist/scan-comparison.js.map +1 -1
  445. package/dist/scan-dashboard.d.ts +7 -6
  446. package/dist/scan-dashboard.d.ts.map +1 -1
  447. package/dist/scan-dashboard.js +91 -79
  448. package/dist/scan-dashboard.js.map +1 -1
  449. package/dist/scan-executor.d.ts +12 -1
  450. package/dist/scan-executor.d.ts.map +1 -1
  451. package/dist/scan-executor.js +22 -2
  452. package/dist/scan-executor.js.map +1 -1
  453. package/dist/scan-history-renderer.d.ts.map +1 -1
  454. package/dist/scan-history-renderer.js +31 -28
  455. package/dist/scan-history-renderer.js.map +1 -1
  456. package/dist/scan-logs.d.ts +12 -0
  457. package/dist/scan-logs.d.ts.map +1 -1
  458. package/dist/scan-logs.js +106 -77
  459. package/dist/scan-logs.js.map +1 -1
  460. package/dist/scan-measurement.d.ts +26 -0
  461. package/dist/scan-measurement.d.ts.map +1 -0
  462. package/dist/scan-measurement.js +77 -0
  463. package/dist/scan-measurement.js.map +1 -0
  464. package/dist/scan-progress.d.ts +1 -0
  465. package/dist/scan-progress.d.ts.map +1 -1
  466. package/dist/scan-progress.js +3 -0
  467. package/dist/scan-progress.js.map +1 -1
  468. package/dist/scan-sessions.d.ts.map +1 -1
  469. package/dist/scan-sessions.js +4 -1
  470. package/dist/scan-sessions.js.map +1 -1
  471. package/dist/scan-settings.d.ts +1 -1
  472. package/dist/scan-settings.d.ts.map +1 -1
  473. package/dist/scan-settings.js +1 -24
  474. package/dist/scan-settings.js.map +1 -1
  475. package/dist/scanner-import.d.ts +64 -6
  476. package/dist/scanner-import.d.ts.map +1 -1
  477. package/dist/scanner-import.js +406 -48
  478. package/dist/scanner-import.js.map +1 -1
  479. package/dist/scanner-repository-url.d.ts +17 -0
  480. package/dist/scanner-repository-url.d.ts.map +1 -0
  481. package/dist/scanner-repository-url.js +71 -0
  482. package/dist/scanner-repository-url.js.map +1 -0
  483. package/dist/security-policy.d.ts +1 -1
  484. package/dist/security-policy.d.ts.map +1 -1
  485. package/dist/security-policy.js.map +1 -1
  486. package/dist/semgrep-findings.d.ts +6 -3
  487. package/dist/semgrep-findings.d.ts.map +1 -1
  488. package/dist/semgrep-findings.js +124 -88
  489. package/dist/semgrep-findings.js.map +1 -1
  490. package/dist/semgrep-guardian-findings.d.ts +38 -0
  491. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  492. package/dist/semgrep-guardian-findings.js +165 -0
  493. package/dist/semgrep-guardian-findings.js.map +1 -0
  494. package/dist/semgrep-platform-collector.d.ts +26 -0
  495. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  496. package/dist/semgrep-platform-collector.js +108 -0
  497. package/dist/semgrep-platform-collector.js.map +1 -0
  498. package/dist/semgrep-platform-findings.d.ts +213 -0
  499. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  500. package/dist/semgrep-platform-findings.js +1078 -0
  501. package/dist/semgrep-platform-findings.js.map +1 -0
  502. package/dist/semgrep-platform-v1.d.ts +6 -0
  503. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  504. package/dist/semgrep-platform-v1.js +83 -0
  505. package/dist/semgrep-platform-v1.js.map +1 -0
  506. package/dist/server/api.d.ts +1 -1
  507. package/dist/server/api.d.ts.map +1 -1
  508. package/dist/server/api.js.map +1 -1
  509. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  510. package/dist/server/embedding-tokenizer.d.ts +2 -0
  511. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  512. package/dist/server/embedding-tokenizer.js +322 -0
  513. package/dist/server/embedding-tokenizer.js.map +6 -0
  514. package/dist/server/embeddings.d.ts +16 -2
  515. package/dist/server/embeddings.d.ts.map +1 -1
  516. package/dist/server/embeddings.js +35 -5
  517. package/dist/server/embeddings.js.map +1 -1
  518. package/dist/session-lines.d.ts +5 -0
  519. package/dist/session-lines.d.ts.map +1 -0
  520. package/dist/session-lines.js +60 -0
  521. package/dist/session-lines.js.map +1 -0
  522. package/dist/severity-review.d.ts +3 -1
  523. package/dist/severity-review.d.ts.map +1 -1
  524. package/dist/severity-review.js +3 -2
  525. package/dist/severity-review.js.map +1 -1
  526. package/dist/severity-rubric.d.ts +20 -0
  527. package/dist/severity-rubric.d.ts.map +1 -0
  528. package/dist/severity-rubric.js +73 -0
  529. package/dist/severity-rubric.js.map +1 -0
  530. package/dist/severity-store.js +15 -5
  531. package/dist/severity-store.js.map +1 -1
  532. package/dist/skill-authentication.d.ts +1 -0
  533. package/dist/skill-authentication.d.ts.map +1 -1
  534. package/dist/skill-authentication.js +1 -0
  535. package/dist/skill-authentication.js.map +1 -1
  536. package/dist/snyk-findings.d.ts +7 -2
  537. package/dist/snyk-findings.d.ts.map +1 -1
  538. package/dist/snyk-findings.js +108 -84
  539. package/dist/snyk-findings.js.map +1 -1
  540. package/dist/snyk-rest-findings.d.ts +76 -0
  541. package/dist/snyk-rest-findings.d.ts.map +1 -0
  542. package/dist/snyk-rest-findings.js +1051 -0
  543. package/dist/snyk-rest-findings.js.map +1 -0
  544. package/dist/snyk-rest-v1.d.ts +28 -0
  545. package/dist/snyk-rest-v1.d.ts.map +1 -0
  546. package/dist/snyk-rest-v1.js +132 -0
  547. package/dist/snyk-rest-v1.js.map +1 -0
  548. package/dist/snyk-token-origin.d.ts +4 -0
  549. package/dist/snyk-token-origin.d.ts.map +1 -0
  550. package/dist/snyk-token-origin.js +82 -0
  551. package/dist/snyk-token-origin.js.map +1 -0
  552. package/dist/sonar-collector.d.ts +16 -0
  553. package/dist/sonar-collector.d.ts.map +1 -0
  554. package/dist/sonar-collector.js +380 -0
  555. package/dist/sonar-collector.js.map +1 -0
  556. package/dist/sonar-findings.d.ts +49 -0
  557. package/dist/sonar-findings.d.ts.map +1 -0
  558. package/dist/sonar-findings.js +288 -0
  559. package/dist/sonar-findings.js.map +1 -0
  560. package/dist/sonar-import.d.ts +111 -0
  561. package/dist/sonar-import.d.ts.map +1 -0
  562. package/dist/sonar-import.js +277 -0
  563. package/dist/sonar-import.js.map +1 -0
  564. package/dist/suggest-owners.d.ts.map +1 -1
  565. package/dist/suggest-owners.js +2 -1
  566. package/dist/suggest-owners.js.map +1 -1
  567. package/dist/target-drift.d.ts +9 -0
  568. package/dist/target-drift.d.ts.map +1 -0
  569. package/dist/target-drift.js +27 -0
  570. package/dist/target-drift.js.map +1 -0
  571. package/dist/targets.d.ts +5 -0
  572. package/dist/targets.d.ts.map +1 -1
  573. package/dist/targets.js +73 -31
  574. package/dist/targets.js.map +1 -1
  575. package/dist/tenable-findings.d.ts +9 -0
  576. package/dist/tenable-findings.d.ts.map +1 -0
  577. package/dist/tenable-findings.js +122 -0
  578. package/dist/tenable-findings.js.map +1 -0
  579. package/dist/terminal-columns.d.ts +4 -0
  580. package/dist/terminal-columns.d.ts.map +1 -0
  581. package/dist/terminal-columns.js +19 -0
  582. package/dist/terminal-columns.js.map +1 -0
  583. package/dist/terminal-stream.d.ts +13 -0
  584. package/dist/terminal-stream.d.ts.map +1 -0
  585. package/dist/terminal-stream.js +35 -0
  586. package/dist/terminal-stream.js.map +1 -0
  587. package/dist/trivy-findings.d.ts +19 -0
  588. package/dist/trivy-findings.d.ts.map +1 -0
  589. package/dist/trivy-findings.js +435 -0
  590. package/dist/trivy-findings.js.map +1 -0
  591. package/dist/trivy-import.d.ts +19 -0
  592. package/dist/trivy-import.d.ts.map +1 -0
  593. package/dist/trivy-import.js +151 -0
  594. package/dist/trivy-import.js.map +1 -0
  595. package/dist/validation-records.d.ts +0 -3
  596. package/dist/validation-records.d.ts.map +1 -1
  597. package/dist/validation-records.js +1 -17
  598. package/dist/validation-records.js.map +1 -1
  599. package/dist/veracode-findings.d.ts +9 -0
  600. package/dist/veracode-findings.d.ts.map +1 -0
  601. package/dist/veracode-findings.js +409 -0
  602. package/dist/veracode-findings.js.map +1 -0
  603. package/dist/vertex-pricing.d.ts +8 -0
  604. package/dist/vertex-pricing.d.ts.map +1 -0
  605. package/dist/vertex-pricing.js +20 -0
  606. package/dist/vertex-pricing.js.map +1 -0
  607. package/dist/windows-path.d.ts +1 -0
  608. package/dist/windows-path.d.ts.map +1 -1
  609. package/dist/windows-path.js +27 -1
  610. package/dist/windows-path.js.map +1 -1
  611. package/dist/wiz-csv.d.ts +2 -2
  612. package/dist/wiz-csv.d.ts.map +1 -1
  613. package/dist/wiz-csv.js +1 -3
  614. package/dist/wiz-csv.js.map +1 -1
  615. package/dist/wiz-findings.d.ts +14 -2
  616. package/dist/wiz-findings.d.ts.map +1 -1
  617. package/dist/wiz-findings.js +143 -50
  618. package/dist/wiz-findings.js.map +1 -1
  619. package/docs/classify-severity-records.md +28 -13
  620. package/docs/cli.md +623 -843
  621. package/docs/dedupe-records.md +54 -24
  622. package/docs/findings-service.md +87 -47
  623. package/docs/hosted-remediation.md +14 -7
  624. package/docs/hosted-scans.md +64 -41
  625. package/docs/telemetry.md +236 -0
  626. package/docs/validate-records.md +78 -44
  627. package/package.json +19 -17
  628. package/schemas/external-findings.schema.json +14 -1
  629. package/schemas/hosted-scan-v2.fixture.json +16 -1
  630. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  631. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  632. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  633. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  634. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  635. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  636. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  637. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  638. package/dist/deduplication/records-protocol.d.ts +0 -4
  639. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  640. package/dist/deduplication/records-protocol.js +0 -49
  641. package/dist/deduplication/records-protocol.js.map +0 -1
  642. package/dist/external-imports-feature.d.ts +0 -6
  643. package/dist/external-imports-feature.d.ts.map +0 -1
  644. package/dist/external-imports-feature.js +0 -51
  645. package/dist/external-imports-feature.js.map +0 -1
  646. package/dist/finding-normalization.d.ts +0 -5
  647. package/dist/finding-normalization.d.ts.map +0 -1
  648. package/dist/finding-normalization.js +0 -120
  649. package/dist/finding-normalization.js.map +0 -1
@@ -25,11 +25,13 @@ 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
32
- from collections.abc import Iterator
33
+ import struct
34
+ from collections.abc import Callable, Iterator
33
35
  from pathlib import Path, PurePosixPath
34
36
  from typing import BinaryIO
35
37
 
@@ -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}
@@ -100,6 +113,16 @@ _RESERVED_DEVICE_NAMES = {
100
113
  }
101
114
 
102
115
 
116
+ class _FileBasicInfo(ctypes.Structure):
117
+ _fields_ = [
118
+ ("CreationTime", ctypes.c_int64),
119
+ ("LastAccessTime", ctypes.c_int64),
120
+ ("LastWriteTime", ctypes.c_int64),
121
+ ("ChangeTime", ctypes.c_int64),
122
+ ("FileAttributes", wintypes.DWORD),
123
+ ]
124
+
125
+
103
126
  class _FileAttributeTagInfo(ctypes.Structure):
104
127
  _fields_ = [
105
128
  ("FileAttributes", wintypes.DWORD),
@@ -109,9 +132,9 @@ class _FileAttributeTagInfo(ctypes.Structure):
109
132
 
110
133
  class _SecurityAttributes(ctypes.Structure):
111
134
  _fields_ = [
112
- ("nLength", wintypes.DWORD),
113
- ("lpSecurityDescriptor", wintypes.LPVOID),
114
- ("bInheritHandle", wintypes.BOOL),
135
+ ("length", wintypes.DWORD),
136
+ ("descriptor", wintypes.LPVOID),
137
+ ("inherit", wintypes.BOOL),
115
138
  ]
116
139
 
117
140
 
@@ -159,6 +182,7 @@ class _OwnedHandle:
159
182
  if os.name == "nt":
160
183
  _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
161
184
  _advapi32 = ctypes.WinDLL("advapi32", use_last_error=True)
185
+ _ntdll = ctypes.WinDLL("ntdll")
162
186
 
163
187
  _GetFileSecurityW = _advapi32.GetFileSecurityW
164
188
  _GetFileSecurityW.argtypes = [
@@ -170,6 +194,10 @@ if os.name == "nt":
170
194
  ]
171
195
  _GetFileSecurityW.restype = wintypes.BOOL
172
196
 
197
+ _GetDriveTypeW = _kernel32.GetDriveTypeW
198
+ _GetDriveTypeW.argtypes = [wintypes.LPCWSTR]
199
+ _GetDriveTypeW.restype = wintypes.UINT
200
+
173
201
  _CreateFileW = _kernel32.CreateFileW
174
202
  _CreateFileW.argtypes = [
175
203
  wintypes.LPCWSTR,
@@ -182,6 +210,10 @@ if os.name == "nt":
182
210
  ]
183
211
  _CreateFileW.restype = wintypes.HANDLE
184
212
 
213
+ _ReOpenFile = _kernel32.ReOpenFile
214
+ _ReOpenFile.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD]
215
+ _ReOpenFile.restype = wintypes.HANDLE
216
+
185
217
  _CreateDirectoryW = _kernel32.CreateDirectoryW
186
218
  _CreateDirectoryW.argtypes = [wintypes.LPCWSTR, wintypes.LPVOID]
187
219
  _CreateDirectoryW.restype = wintypes.BOOL
@@ -443,13 +475,18 @@ def _canonical_scan_directory(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
443
475
 
444
476
 
445
477
  def _open_directory(
446
- path: Path, *, missing_ok: bool = False, missing_is_path_error: bool = True
478
+ path: Path,
479
+ *,
480
+ missing_ok: bool = False,
481
+ missing_is_path_error: bool = True,
482
+ movable: bool = False,
447
483
  ) -> _OwnedHandle | None:
448
484
  try:
449
485
  handle = _create_file(
450
486
  path,
451
- access=_FILE_READ_ATTRIBUTES,
452
- share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
487
+ # Attribute-only handles do not participate in Win32 sharing checks.
488
+ access=_FILE_READ_ATTRIBUTES | (0 if movable else _FILE_TRAVERSE),
489
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | (_FILE_SHARE_DELETE if movable else 0),
453
490
  disposition=_OPEN_EXISTING,
454
491
  flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
455
492
  missing_ok=missing_ok,
@@ -478,25 +515,297 @@ def _create_directory(path: Path) -> None:
478
515
  _raise_last_error("CreateDirectoryW", path)
479
516
 
480
517
 
481
- def create_directory_with_same_dacl(path: Path, source: Path) -> None:
482
- """Create an archive replacement with the original directory's DACL."""
483
- _require_windows()
518
+ def _directory_security_descriptor(source: Path, information: int) -> ctypes.Array:
484
519
  source_path = _extended_path(source)
485
520
  size = wintypes.DWORD()
486
- _GetFileSecurityW(source_path, _DACL_SECURITY_INFORMATION, None, 0, ctypes.byref(size))
521
+ _GetFileSecurityW(source_path, information, None, 0, ctypes.byref(size))
487
522
  if ctypes.get_last_error() != _ERROR_INSUFFICIENT_BUFFER:
488
523
  _raise_last_error("GetFileSecurityW", source)
489
524
  descriptor = ctypes.create_string_buffer(size.value)
490
- if not _GetFileSecurityW(
491
- source_path, _DACL_SECURITY_INFORMATION, descriptor, size.value, ctypes.byref(size)
492
- ):
525
+ if not _GetFileSecurityW(source_path, information, descriptor, size.value, ctypes.byref(size)):
493
526
  _raise_last_error("GetFileSecurityW", source)
494
- attributes = _SecurityAttributes(
495
- 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),
496
565
  )
497
- # Supply the descriptor at creation, without an inherited-access window.
498
- if not _CreateDirectoryW(_extended_path(path), ctypes.byref(attributes)):
499
- _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))
500
809
 
501
810
 
502
811
  @contextlib.contextmanager
@@ -554,6 +863,37 @@ def _locked_parent(
554
863
  handle.close()
555
864
 
556
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
+
557
897
  def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
558
898
  """Return a canonical scan root and its identity while holding it fixed."""
559
899
 
@@ -562,6 +902,50 @@ def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
562
902
  return root_path, (metadata.st_dev, metadata.st_ino)
563
903
 
564
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
+
565
949
  def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
566
950
  """Open a verified regular file and return an owned binary read descriptor."""
567
951
 
@@ -569,7 +953,11 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
569
953
 
570
954
 
571
955
  def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) -> tuple[int, str]:
572
- """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
+ """
573
961
 
574
962
  try:
575
963
  with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
@@ -606,7 +994,19 @@ def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) ->
606
994
  ) from exc
607
995
 
608
996
 
997
+ def file_change_time(descriptor: int) -> int:
998
+ """Return the filesystem change time. Python's Windows st_ctime is creation time."""
999
+ assert _msvcrt is not None
1000
+ info = _FileBasicInfo()
1001
+ if not _GetFileInformationByHandleEx(
1002
+ _msvcrt.get_osfhandle(descriptor), 0, ctypes.byref(info), ctypes.sizeof(info)
1003
+ ):
1004
+ _raise_last_error("GetFileInformationByHandleEx(FileBasicInfo)")
1005
+ return info.ChangeTime
1006
+
1007
+
609
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."""
610
1010
  offset = 0
611
1011
  while offset < len(payload):
612
1012
  chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))
@@ -632,7 +1032,7 @@ def _write_all(handle: int, payload: bytes) -> None:
632
1032
  _raise_last_error("FlushFileBuffers")
633
1033
 
634
1034
 
635
- def _rename_handle(handle: int, destination_path: Path) -> None:
1035
+ def _rename_handle(handle: int, destination_path: Path, replace_existing: bool) -> None:
636
1036
  encoded_name = _extended_path(destination_path).encode("utf-16-le")
637
1037
  file_name_offset = _FileRenameInfo.FileName.offset
638
1038
  buffer_size = max(
@@ -641,7 +1041,7 @@ def _rename_handle(handle: int, destination_path: Path) -> None:
641
1041
  )
642
1042
  buffer = ctypes.create_string_buffer(buffer_size)
643
1043
  info = ctypes.cast(buffer, ctypes.POINTER(_FileRenameInfo)).contents
644
- info.FlagsOrReplaceIfExists = 1
1044
+ info.FlagsOrReplaceIfExists = int(replace_existing)
645
1045
  # The fully qualified destination uses a null RootDirectory. Verified
646
1046
  # directory handles remain open to prevent ancestor replacement.
647
1047
  info.RootDirectory = None
@@ -653,6 +1053,8 @@ def _rename_handle(handle: int, destination_path: Path) -> None:
653
1053
  buffer,
654
1054
  buffer_size,
655
1055
  ):
1056
+ if not replace_existing and ctypes.get_last_error() in _COLLISION_ERRORS:
1057
+ raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination_path))
656
1058
  _raise_last_error("SetFileInformationByHandle(FileRenameInfo)")
657
1059
 
658
1060
 
@@ -667,7 +1069,7 @@ def _mark_handle_for_deletion(handle: int) -> None:
667
1069
  _raise_last_error("SetFileInformationByHandle(FileDispositionInfo)")
668
1070
 
669
1071
 
670
- def _validate_existing_output(path: Path) -> None:
1072
+ def _validate_existing_output(path: Path) -> bool:
671
1073
  handle = _create_file(
672
1074
  path,
673
1075
  access=_FILE_READ_ATTRIBUTES,
@@ -677,10 +1079,11 @@ def _validate_existing_output(path: Path) -> None:
677
1079
  missing_ok=True,
678
1080
  )
679
1081
  if handle is None:
680
- return
1082
+ return False
681
1083
  with handle:
682
1084
  assert handle.value is not None
683
1085
  _verify_regular_file(handle.value, path)
1086
+ return True
684
1087
 
685
1088
 
686
1089
  def _existing_output_matches(path: Path, payload: bytes) -> bool:
@@ -723,64 +1126,189 @@ def _existing_output_matches(path: Path, payload: bytes) -> bool:
723
1126
  return False
724
1127
 
725
1128
 
1129
+ @contextlib.contextmanager
1130
+ def _written_temp(destination: Path, payload: bytes) -> Iterator[tuple[Path, _OwnedHandle]]:
1131
+ for _ in range(16):
1132
+ path = destination.with_name(f".{destination.name}.{secrets.token_hex(8)}.tmp")
1133
+ try:
1134
+ handle = _create_file(
1135
+ path,
1136
+ access=_GENERIC_WRITE | _DELETE | _FILE_READ_ATTRIBUTES,
1137
+ share=0,
1138
+ disposition=_CREATE_NEW,
1139
+ flags=_FILE_ATTRIBUTE_NORMAL,
1140
+ )
1141
+ except WindowsScanLocalFileError as exc:
1142
+ if exc.errno in _COLLISION_ERRORS:
1143
+ continue
1144
+ raise
1145
+ assert handle is not None and handle.value is not None
1146
+ with handle:
1147
+ try:
1148
+ _verify_regular_file(handle.value, path)
1149
+ _write_all(handle.value, payload)
1150
+ yield path, handle
1151
+ except BaseException:
1152
+ if handle.value is not None:
1153
+ with contextlib.suppress(OSError):
1154
+ _mark_handle_for_deletion(handle.value)
1155
+ raise
1156
+ return
1157
+ raise WindowsScanLocalFileError(errno.EEXIST, "could not allocate a unique temp file")
1158
+
1159
+
1160
+ def _stage_metadata(
1161
+ handle: _OwnedHandle, *, close_writer: bool = False
1162
+ ) -> tuple[os.stat_result, int]:
1163
+ # Windows can update LastWriteTime on last writer close. Observe the same
1164
+ # file across that close, independently of whatever is now at the name.
1165
+ assert handle.value is not None and _msvcrt is not None
1166
+ raw = _ReOpenFile(
1167
+ handle.value,
1168
+ _FILE_READ_ATTRIBUTES,
1169
+ _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
1170
+ 0,
1171
+ )
1172
+ if raw is None or raw == _INVALID_HANDLE_VALUE:
1173
+ _raise_last_error("ReOpenFile")
1174
+ with _OwnedHandle(raw) as observer:
1175
+ descriptor = _msvcrt.open_osfhandle(raw, os.O_RDONLY | os.O_BINARY)
1176
+ observer.detach()
1177
+ try:
1178
+ if close_writer:
1179
+ handle.close()
1180
+ try:
1181
+ return os.fstat(descriptor), file_change_time(descriptor)
1182
+ except BaseException:
1183
+ if close_writer:
1184
+ # The observer still identifies the staged file after the writer closed.
1185
+ cleanup = _ReOpenFile(
1186
+ raw, _DELETE, _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE, 0
1187
+ )
1188
+ if cleanup and cleanup != _INVALID_HANDLE_VALUE:
1189
+ with _OwnedHandle(cleanup), contextlib.suppress(OSError):
1190
+ _mark_handle_for_deletion(cleanup)
1191
+ raise
1192
+ finally:
1193
+ os.close(descriptor)
1194
+
1195
+
1196
+ @contextlib.contextmanager
1197
+ def stage_write(
1198
+ scan_dir: Path,
1199
+ relative_path: str,
1200
+ payload: bytes,
1201
+ *,
1202
+ expected_root_identity: tuple[int, int] | None = None,
1203
+ replace_existing: bool = False,
1204
+ ) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
1205
+ """Flush a patch and keep only a movable handle to its root across admission."""
1206
+ if expected_root_identity is None:
1207
+ root = scan_dir.lstat()
1208
+ expected_root_identity = (root.st_dev, root.st_ino)
1209
+ with _locked_parent(
1210
+ scan_dir, relative_path, create=True, expected_root_identity=expected_root_identity
1211
+ ) as (parent, leaf):
1212
+ destination = parent / leaf
1213
+ if _validate_existing_output(destination) and not replace_existing:
1214
+ raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination))
1215
+ root_handle = _open_directory(scan_dir, movable=True)
1216
+ assert root_handle is not None
1217
+ try:
1218
+ with _written_temp(destination, payload) as (temp, writer):
1219
+ staged, change_time = _stage_metadata(writer, close_writer=True)
1220
+ except BaseException:
1221
+ root_handle.close()
1222
+ raise
1223
+
1224
+ location = scan_dir
1225
+ published = False
1226
+
1227
+ @contextlib.contextmanager
1228
+ def open_stage() -> Iterator[tuple[_OwnedHandle, Path]]:
1229
+ with _locked_parent(
1230
+ location, relative_path, create=False, expected_root_identity=expected_root_identity
1231
+ ) as (parent, leaf):
1232
+ path = parent / temp.name
1233
+ handle = _create_file(
1234
+ path,
1235
+ access=_DELETE | _FILE_READ_ATTRIBUTES,
1236
+ share=0,
1237
+ disposition=_OPEN_EXISTING,
1238
+ flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
1239
+ )
1240
+ assert handle is not None and handle.value is not None
1241
+ with handle:
1242
+ _verify_regular_file(handle.value, path)
1243
+ current, changed = _stage_metadata(handle)
1244
+ if not (
1245
+ os.path.samestat(staged, current)
1246
+ and staged.st_size == current.st_size
1247
+ and staged.st_mtime_ns == current.st_mtime_ns
1248
+ and change_time == changed
1249
+ ):
1250
+ raise _invalid_path(path, "staged patch changed before publication")
1251
+ yield handle, parent / leaf
1252
+
1253
+ def publish(directory: Path | None = None) -> tuple[os.stat_result, int]:
1254
+ nonlocal location, published
1255
+ if directory is not None:
1256
+ location = directory
1257
+ with open_stage() as (handle, destination):
1258
+ assert handle.value is not None
1259
+ _rename_handle(handle.value, destination, replace_existing)
1260
+ published = True
1261
+ _verify_regular_file(handle.value, destination)
1262
+ return _stage_metadata(handle)
1263
+
1264
+ with root_handle:
1265
+ try:
1266
+ yield publish
1267
+ finally:
1268
+ if not published:
1269
+ # A different workbench database may own the archive move.
1270
+ assert root_handle.value is not None
1271
+ with contextlib.suppress(OSError):
1272
+ location = Path(_final_path(root_handle.value))
1273
+ while True:
1274
+ try:
1275
+ with open_stage() as (handle, _):
1276
+ assert handle.value is not None
1277
+ _mark_handle_for_deletion(handle.value)
1278
+ break
1279
+ except OSError:
1280
+ # A move can land between locating the root and fixing its parents.
1281
+ moved_to = Path(_final_path(root_handle.value))
1282
+ if moved_to == location:
1283
+ break
1284
+ location = moved_to
1285
+
1286
+
726
1287
  def atomic_write(
727
1288
  scan_dir: Path,
728
1289
  relative_path: str,
729
1290
  payload: bytes,
730
1291
  *,
731
1292
  expected_root_identity: tuple[int, int] | None = None,
1293
+ replace_existing: bool = True,
732
1294
  ) -> None:
733
- """Atomically replace a scan-local regular file with ``payload``."""
734
-
1295
+ """Atomically publish ``payload`` to a scan-local regular file."""
735
1296
  with _locked_parent(
736
- scan_dir,
737
- relative_path,
738
- create=True,
739
- expected_root_identity=expected_root_identity,
740
- ) as (parent_path, leaf_name):
741
- destination_path = parent_path / leaf_name
742
- _validate_existing_output(destination_path)
743
- if expected_root_identity is not None and _existing_output_matches(
744
- destination_path, payload
1297
+ scan_dir, relative_path, create=True, expected_root_identity=expected_root_identity
1298
+ ) as (parent, leaf):
1299
+ destination = parent / leaf
1300
+ if _validate_existing_output(destination) and not replace_existing:
1301
+ raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), str(destination))
1302
+ if (
1303
+ replace_existing
1304
+ and expected_root_identity is not None
1305
+ and _existing_output_matches(destination, payload)
745
1306
  ):
746
1307
  return
747
-
748
- temp_handle: _OwnedHandle | None = None
749
- temp_path: Path | None = None
750
- for _ in range(16):
751
- temp_path = parent_path / f".{leaf_name}.{secrets.token_hex(8)}.tmp"
752
- try:
753
- temp_handle = _create_file(
754
- temp_path,
755
- access=_GENERIC_WRITE | _DELETE | _FILE_READ_ATTRIBUTES,
756
- share=0,
757
- disposition=_CREATE_NEW,
758
- flags=_FILE_ATTRIBUTE_NORMAL,
759
- )
760
- except WindowsScanLocalFileError as exc:
761
- if exc.errno in _COLLISION_ERRORS:
762
- continue
763
- raise
764
- break
765
- if temp_handle is None or temp_path is None:
766
- raise WindowsScanLocalFileError(errno.EEXIST, "could not allocate a unique temp file")
767
-
768
- with temp_handle:
769
- assert temp_handle.value is not None
770
- try:
771
- _verify_regular_file(temp_handle.value, temp_path)
772
- _write_all(temp_handle.value, payload)
773
- _rename_handle(temp_handle.value, destination_path)
774
- _verify_regular_file(temp_handle.value, destination_path)
775
- except BaseException:
776
- # Deleting by handle removes the exact temp/output file and cannot
777
- # be redirected through a swapped path or reparse point.
778
- try:
779
- _mark_handle_for_deletion(temp_handle.value)
780
- except OSError:
781
- # Cleanup must not replace the original write or rename failure.
782
- pass
783
- raise
1308
+ with _written_temp(destination, payload) as (_, handle):
1309
+ assert handle.value is not None
1310
+ _rename_handle(handle.value, destination, replace_existing)
1311
+ _verify_regular_file(handle.value, destination)
784
1312
 
785
1313
 
786
1314
  def unlink_if_exists(scan_dir: Path, relative_path: str) -> None: