@openai/codex-security 0.1.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 (178) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +306 -0
  3. package/_bundled_plugin/.app.json +20 -0
  4. package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
  5. package/_bundled_plugin/.mcp.json +20 -0
  6. package/_bundled_plugin/assets/logo.png +0 -0
  7. package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
  8. package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
  9. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
  11. package/_bundled_plugin/mcp/server.mjs +24 -0
  12. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  14. package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
  15. package/_bundled_plugin/references/config-preflight.md +115 -0
  16. package/_bundled_plugin/references/final-report.md +205 -0
  17. package/_bundled_plugin/references/finding-detail-fields.md +162 -0
  18. package/_bundled_plugin/references/sarif-adapter.md +26 -0
  19. package/_bundled_plugin/references/scan-artifacts.md +116 -0
  20. package/_bundled_plugin/references/scan-contract.md +164 -0
  21. package/_bundled_plugin/references/security-guidance.md +15 -0
  22. package/_bundled_plugin/references/shared-hard-rules.md +15 -0
  23. package/_bundled_plugin/references/static-finding-assessment.md +75 -0
  24. package/_bundled_plugin/schemas/coverage.schema.json +228 -0
  25. package/_bundled_plugin/schemas/findings.schema.json +359 -0
  26. package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
  27. package/_bundled_plugin/scripts/config_preflight.py +901 -0
  28. package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
  29. package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
  30. package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
  31. package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
  32. package/_bundled_plugin/scripts/finding_preview.py +270 -0
  33. package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
  34. package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
  35. package/_bundled_plugin/scripts/rank_preview.py +968 -0
  36. package/_bundled_plugin/scripts/report_projection.py +844 -0
  37. package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
  38. package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
  39. package/_bundled_plugin/scripts/validate_report_format.py +138 -0
  40. package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
  41. package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
  43. package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
  44. package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
  45. package/_bundled_plugin/scripts/workbench_cli.py +325 -0
  46. package/_bundled_plugin/scripts/workbench_constants.py +81 -0
  47. package/_bundled_plugin/scripts/workbench_db.py +3728 -0
  48. package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
  49. package/_bundled_plugin/scripts/workbench_progress.py +226 -0
  50. package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
  51. package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
  52. package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
  53. package/_bundled_plugin/scripts/workbench_schema.py +714 -0
  54. package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
  55. package/_bundled_plugin/scripts/workbench_target.py +469 -0
  56. package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
  57. package/_bundled_plugin/scripts/workbench_validation.py +294 -0
  58. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
  59. package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
  60. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
  61. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
  62. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
  63. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
  64. package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
  65. package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
  66. package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
  67. package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
  68. package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
  69. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
  70. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
  71. package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
  72. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
  73. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
  74. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
  75. package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
  76. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
  77. package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
  78. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
  79. package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
  80. package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
  81. package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
  82. package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
  83. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
  84. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
  85. package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
  86. package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
  87. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
  88. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
  90. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
  91. package/_bundled_plugin/skills/validation/SKILL.md +110 -0
  92. package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
  94. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
  95. package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
  96. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
  97. package/bin/codex-security.mjs +26 -0
  98. package/dist/api.d.ts +112 -0
  99. package/dist/api.d.ts.map +1 -0
  100. package/dist/api.js +1051 -0
  101. package/dist/api.js.map +1 -0
  102. package/dist/auth.d.ts +29 -0
  103. package/dist/auth.d.ts.map +1 -0
  104. package/dist/auth.js +246 -0
  105. package/dist/auth.js.map +1 -0
  106. package/dist/bulk-scan-discovery.d.ts +35 -0
  107. package/dist/bulk-scan-discovery.d.ts.map +1 -0
  108. package/dist/bulk-scan-discovery.js +217 -0
  109. package/dist/bulk-scan-discovery.js.map +1 -0
  110. package/dist/cli.d.ts +67 -0
  111. package/dist/cli.d.ts.map +1 -0
  112. package/dist/cli.js +2128 -0
  113. package/dist/cli.js.map +1 -0
  114. package/dist/config.d.ts +19 -0
  115. package/dist/config.d.ts.map +1 -0
  116. package/dist/config.js +199 -0
  117. package/dist/config.js.map +1 -0
  118. package/dist/contract.d.ts +21 -0
  119. package/dist/contract.d.ts.map +1 -0
  120. package/dist/contract.js +848 -0
  121. package/dist/contract.js.map +1 -0
  122. package/dist/cost.d.ts +30 -0
  123. package/dist/cost.d.ts.map +1 -0
  124. package/dist/cost.js +280 -0
  125. package/dist/cost.js.map +1 -0
  126. package/dist/errors.d.ts +38 -0
  127. package/dist/errors.d.ts.map +1 -0
  128. package/dist/errors.js +52 -0
  129. package/dist/errors.js.map +1 -0
  130. package/dist/index.d.ts +22 -0
  131. package/dist/index.d.ts.map +1 -0
  132. package/dist/index.js +11 -0
  133. package/dist/index.js.map +1 -0
  134. package/dist/knowledge-base.d.ts +7 -0
  135. package/dist/knowledge-base.d.ts.map +1 -0
  136. package/dist/knowledge-base.js +181 -0
  137. package/dist/knowledge-base.js.map +1 -0
  138. package/dist/models.d.ts +231 -0
  139. package/dist/models.d.ts.map +1 -0
  140. package/dist/models.js +3 -0
  141. package/dist/models.js.map +1 -0
  142. package/dist/multiscan.d.ts +30 -0
  143. package/dist/multiscan.d.ts.map +1 -0
  144. package/dist/multiscan.js +397 -0
  145. package/dist/multiscan.js.map +1 -0
  146. package/dist/result.d.ts +39 -0
  147. package/dist/result.d.ts.map +1 -0
  148. package/dist/result.js +71 -0
  149. package/dist/result.js.map +1 -0
  150. package/dist/runtime.d.ts +69 -0
  151. package/dist/runtime.d.ts.map +1 -0
  152. package/dist/runtime.js +997 -0
  153. package/dist/runtime.js.map +1 -0
  154. package/dist/scan-comparison.d.ts +42 -0
  155. package/dist/scan-comparison.d.ts.map +1 -0
  156. package/dist/scan-comparison.js +153 -0
  157. package/dist/scan-comparison.js.map +1 -0
  158. package/dist/scan-history-renderer.d.ts +13 -0
  159. package/dist/scan-history-renderer.d.ts.map +1 -0
  160. package/dist/scan-history-renderer.js +297 -0
  161. package/dist/scan-history-renderer.js.map +1 -0
  162. package/dist/targets.d.ts +39 -0
  163. package/dist/targets.d.ts.map +1 -0
  164. package/dist/targets.js +295 -0
  165. package/dist/targets.js.map +1 -0
  166. package/dist/trusted-executable.d.ts +6 -0
  167. package/dist/trusted-executable.d.ts.map +1 -0
  168. package/dist/trusted-executable.js +77 -0
  169. package/dist/trusted-executable.js.map +1 -0
  170. package/dist/version.d.ts +6 -0
  171. package/dist/version.d.ts.map +1 -0
  172. package/dist/version.js +42 -0
  173. package/dist/version.js.map +1 -0
  174. package/dist/worker-progress.d.ts +13 -0
  175. package/dist/worker-progress.d.ts.map +1 -0
  176. package/dist/worker-progress.js +113 -0
  177. package/dist/worker-progress.js.map +1 -0
  178. package/package.json +74 -0
@@ -0,0 +1,612 @@
1
+ """Secure scan-local file operations for Windows.
2
+
3
+ Windows does not implement Python's descriptor-relative ``dir_fd`` APIs or
4
+ ``O_NOFOLLOW``. This module provides the three operations needed by the scan
5
+ finalizer without falling back to check-then-use path validation.
6
+
7
+ The implementation opens every directory with ``FILE_FLAG_OPEN_REPARSE_POINT``
8
+ and rejects all reparse points, including junctions. Directory handles remain
9
+ open without ``FILE_SHARE_DELETE`` for the full operation, which prevents an
10
+ already-validated ancestor from being renamed or replaced during a read,
11
+ write, or delete. Writes rename the exact temporary-file handle into place so
12
+ an attacker cannot substitute another file at the temporary name.
13
+
14
+ Importing this module is safe on non-Windows hosts. Its public operations
15
+ raise ``WindowsScanLocalFileError`` when called anywhere other than Windows.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import argparse
21
+ import contextlib
22
+ import ctypes
23
+ import errno
24
+ import importlib
25
+ import ntpath
26
+ import os
27
+ import secrets
28
+ from collections.abc import Iterator
29
+ from ctypes import wintypes
30
+ from pathlib import Path, PurePosixPath
31
+
32
+ _msvcrt = importlib.import_module("msvcrt") if os.name == "nt" else None
33
+
34
+
35
+ class WindowsScanLocalFileError(OSError):
36
+ """Raised when a scan-local operation cannot be completed securely."""
37
+
38
+
39
+ # CreateFile access and sharing flags.
40
+ _DELETE = 0x00010000
41
+ _FILE_READ_ATTRIBUTES = 0x00000080
42
+ _GENERIC_READ = 0x80000000
43
+ _GENERIC_WRITE = 0x40000000
44
+ _FILE_SHARE_READ = 0x00000001
45
+ _FILE_SHARE_WRITE = 0x00000002
46
+ _FILE_SHARE_DELETE = 0x00000004
47
+
48
+ # CreateFile dispositions, attributes, and flags.
49
+ _CREATE_NEW = 1
50
+ _OPEN_EXISTING = 3
51
+ _FILE_ATTRIBUTE_DIRECTORY = 0x00000010
52
+ _FILE_ATTRIBUTE_NORMAL = 0x00000080
53
+ _FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400
54
+ _FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
55
+ _FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
56
+
57
+ # GetFileInformationByHandleEx / SetFileInformationByHandle classes.
58
+ _FILE_RENAME_INFO_CLASS = 3
59
+ _FILE_DISPOSITION_INFO_CLASS = 4
60
+ _FILE_ATTRIBUTE_TAG_INFO_CLASS = 9
61
+
62
+ _FILE_TYPE_DISK = 0x0001
63
+ _FILE_NAME_OPENED = 0x00000008
64
+ _ERROR_FILE_NOT_FOUND = 2
65
+ _ERROR_PATH_NOT_FOUND = 3
66
+ _ERROR_FILE_EXISTS = 80
67
+ _ERROR_ALREADY_EXISTS = 183
68
+ _MISSING_ERRORS = {_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND}
69
+ _COLLISION_ERRORS = {_ERROR_FILE_EXISTS, _ERROR_ALREADY_EXISTS}
70
+ _INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
71
+ _MAX_WRITE_CHUNK = 1024 * 1024
72
+
73
+ _INVALID_COMPONENT_CHARACTERS = frozenset('<>:"|?*')
74
+ _RESERVED_DEVICE_NAMES = {
75
+ "AUX",
76
+ "CON",
77
+ "CONIN$",
78
+ "CONOUT$",
79
+ "NUL",
80
+ "PRN",
81
+ *(f"COM{number}" for number in range(1, 10)),
82
+ *(f"LPT{number}" for number in range(1, 10)),
83
+ *(f"COM{number}" for number in "¹²³"),
84
+ *(f"LPT{number}" for number in "¹²³"),
85
+ }
86
+
87
+
88
+ class _FileAttributeTagInfo(ctypes.Structure):
89
+ _fields_ = [
90
+ ("FileAttributes", wintypes.DWORD),
91
+ ("ReparseTag", wintypes.DWORD),
92
+ ]
93
+
94
+
95
+ class _FileDispositionInfo(ctypes.Structure):
96
+ _fields_ = [("DeleteFile", wintypes.BOOLEAN)]
97
+
98
+
99
+ class _FileRenameInfo(ctypes.Structure):
100
+ # The first field is a union. FileRenameInfo interprets its low byte as
101
+ # ReplaceIfExists; representing the union as DWORD also provides the
102
+ # correct alignment for RootDirectory on 32-bit and 64-bit Windows.
103
+ _fields_ = [
104
+ ("FlagsOrReplaceIfExists", wintypes.DWORD),
105
+ ("RootDirectory", wintypes.HANDLE),
106
+ ("FileNameLength", wintypes.DWORD),
107
+ ("FileName", wintypes.WCHAR * 1),
108
+ ]
109
+
110
+
111
+ class _OwnedHandle:
112
+ """Own a Win32 HANDLE and close it exactly once."""
113
+
114
+ def __init__(self, value: int) -> None:
115
+ self.value: int | None = value
116
+
117
+ def close(self) -> None:
118
+ if self.value is not None:
119
+ _close_handle(self.value)
120
+ self.value = None
121
+
122
+ def detach(self) -> int:
123
+ if self.value is None:
124
+ raise RuntimeError("handle is already closed")
125
+ value = self.value
126
+ self.value = None
127
+ return value
128
+
129
+ def __enter__(self) -> _OwnedHandle:
130
+ return self
131
+
132
+ def __exit__(self, *_: object) -> None:
133
+ self.close()
134
+
135
+
136
+ if os.name == "nt":
137
+ _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
138
+
139
+ _CreateFileW = _kernel32.CreateFileW
140
+ _CreateFileW.argtypes = [
141
+ wintypes.LPCWSTR,
142
+ wintypes.DWORD,
143
+ wintypes.DWORD,
144
+ wintypes.LPVOID,
145
+ wintypes.DWORD,
146
+ wintypes.DWORD,
147
+ wintypes.HANDLE,
148
+ ]
149
+ _CreateFileW.restype = wintypes.HANDLE
150
+
151
+ _CreateDirectoryW = _kernel32.CreateDirectoryW
152
+ _CreateDirectoryW.argtypes = [wintypes.LPCWSTR, wintypes.LPVOID]
153
+ _CreateDirectoryW.restype = wintypes.BOOL
154
+
155
+ _CloseHandle = _kernel32.CloseHandle
156
+ _CloseHandle.argtypes = [wintypes.HANDLE]
157
+ _CloseHandle.restype = wintypes.BOOL
158
+
159
+ _GetFileInformationByHandleEx = _kernel32.GetFileInformationByHandleEx
160
+ _GetFileInformationByHandleEx.argtypes = [
161
+ wintypes.HANDLE,
162
+ ctypes.c_int,
163
+ wintypes.LPVOID,
164
+ wintypes.DWORD,
165
+ ]
166
+ _GetFileInformationByHandleEx.restype = wintypes.BOOL
167
+
168
+ _GetFileType = _kernel32.GetFileType
169
+ _GetFileType.argtypes = [wintypes.HANDLE]
170
+ _GetFileType.restype = wintypes.DWORD
171
+
172
+ _GetFinalPathNameByHandleW = _kernel32.GetFinalPathNameByHandleW
173
+ _GetFinalPathNameByHandleW.argtypes = [
174
+ wintypes.HANDLE,
175
+ wintypes.LPWSTR,
176
+ wintypes.DWORD,
177
+ wintypes.DWORD,
178
+ ]
179
+ _GetFinalPathNameByHandleW.restype = wintypes.DWORD
180
+
181
+ _SetFileInformationByHandle = _kernel32.SetFileInformationByHandle
182
+ _SetFileInformationByHandle.argtypes = [
183
+ wintypes.HANDLE,
184
+ ctypes.c_int,
185
+ wintypes.LPVOID,
186
+ wintypes.DWORD,
187
+ ]
188
+ _SetFileInformationByHandle.restype = wintypes.BOOL
189
+
190
+ _WriteFile = _kernel32.WriteFile
191
+ _WriteFile.argtypes = [
192
+ wintypes.HANDLE,
193
+ wintypes.LPCVOID,
194
+ wintypes.DWORD,
195
+ ctypes.POINTER(wintypes.DWORD),
196
+ wintypes.LPVOID,
197
+ ]
198
+ _WriteFile.restype = wintypes.BOOL
199
+
200
+ _FlushFileBuffers = _kernel32.FlushFileBuffers
201
+ _FlushFileBuffers.argtypes = [wintypes.HANDLE]
202
+ _FlushFileBuffers.restype = wintypes.BOOL
203
+ else:
204
+ _kernel32 = None
205
+
206
+
207
+ def _require_windows() -> None:
208
+ if _kernel32 is None:
209
+ raise WindowsScanLocalFileError(
210
+ errno.ENOSYS,
211
+ "secure Windows scan-local file operations require Windows",
212
+ )
213
+
214
+
215
+ def _raise_last_error(operation: str, path: Path | None = None) -> None:
216
+ error = ctypes.get_last_error()
217
+ detail = ctypes.FormatError(error).strip()
218
+ target = f" for {path}" if path is not None else ""
219
+ raise WindowsScanLocalFileError(error, f"{operation}{target}: {detail}", str(path or ""))
220
+
221
+
222
+ def _invalid_path(path: Path | str, reason: str) -> WindowsScanLocalFileError:
223
+ return WindowsScanLocalFileError(errno.EINVAL, reason, str(path))
224
+
225
+
226
+ def _validated_parts(relative_path: str) -> tuple[str, ...]:
227
+ """Validate a POSIX contract path against Windows filesystem aliases."""
228
+
229
+ path = PurePosixPath(relative_path)
230
+ normalized = path.as_posix()
231
+ if (
232
+ not relative_path
233
+ or normalized == "."
234
+ or path.is_absolute()
235
+ or ".." in path.parts
236
+ or "\\" in relative_path
237
+ or "\0" in relative_path
238
+ ):
239
+ raise _invalid_path(relative_path, "expected a safe scan-relative POSIX path")
240
+
241
+ for component in path.parts:
242
+ if (
243
+ any(character in _INVALID_COMPONENT_CHARACTERS for character in component)
244
+ or any(ord(character) < 32 for character in component)
245
+ or component.endswith((" ", "."))
246
+ ):
247
+ raise _invalid_path(relative_path, "path contains a Windows-unsafe component")
248
+ device_name = component.split(".", 1)[0].upper()
249
+ if device_name in _RESERVED_DEVICE_NAMES:
250
+ raise _invalid_path(relative_path, "path contains a reserved Windows device name")
251
+ return path.parts
252
+
253
+
254
+ def _extended_path(path: Path) -> str:
255
+ """Return a Win32 extended-length path so long scan paths remain usable."""
256
+
257
+ value = str(path)
258
+ if value.startswith("\\\\?\\"):
259
+ return value
260
+ if value.startswith("\\\\"):
261
+ return "\\\\?\\UNC\\" + value[2:]
262
+ return "\\\\?\\" + value
263
+
264
+
265
+ def _normalized_windows_path(path: Path | str) -> str:
266
+ value = str(path)
267
+ if value.startswith("\\\\?\\UNC\\"):
268
+ value = "\\\\" + value[8:]
269
+ elif value.startswith("\\\\?\\"):
270
+ value = value[4:]
271
+ return ntpath.normcase(ntpath.normpath(value))
272
+
273
+
274
+ def _close_handle(handle: int) -> None:
275
+ _require_windows()
276
+ if not _CloseHandle(handle):
277
+ _raise_last_error("CloseHandle")
278
+
279
+
280
+ def _create_file(
281
+ path: Path,
282
+ *,
283
+ access: int,
284
+ share: int,
285
+ disposition: int,
286
+ flags: int,
287
+ missing_ok: bool = False,
288
+ ) -> _OwnedHandle | None:
289
+ _require_windows()
290
+ handle = _CreateFileW(
291
+ _extended_path(path),
292
+ access,
293
+ share,
294
+ None,
295
+ disposition,
296
+ flags,
297
+ None,
298
+ )
299
+ if handle == _INVALID_HANDLE_VALUE:
300
+ error = ctypes.get_last_error()
301
+ if missing_ok and error in _MISSING_ERRORS:
302
+ return None
303
+ _raise_last_error("CreateFileW", path)
304
+ return _OwnedHandle(int(handle))
305
+
306
+
307
+ def _attributes(handle: int) -> _FileAttributeTagInfo:
308
+ info = _FileAttributeTagInfo()
309
+ if not _GetFileInformationByHandleEx(
310
+ handle,
311
+ _FILE_ATTRIBUTE_TAG_INFO_CLASS,
312
+ ctypes.byref(info),
313
+ ctypes.sizeof(info),
314
+ ):
315
+ _raise_last_error("GetFileInformationByHandleEx")
316
+ return info
317
+
318
+
319
+ def _final_path(handle: int, *, opened_name: bool = False) -> str:
320
+ flags = _FILE_NAME_OPENED if opened_name else 0
321
+ size = _GetFinalPathNameByHandleW(handle, None, 0, flags)
322
+ if size == 0:
323
+ _raise_last_error("GetFinalPathNameByHandleW")
324
+ buffer = ctypes.create_unicode_buffer(size + 1)
325
+ written = _GetFinalPathNameByHandleW(handle, buffer, len(buffer), flags)
326
+ if written == 0 or written >= len(buffer):
327
+ _raise_last_error("GetFinalPathNameByHandleW")
328
+ return buffer.value
329
+
330
+
331
+ def _verify_handle_path(handle: int, expected_path: Path, *, opened_name: bool = False) -> None:
332
+ actual = _normalized_windows_path(_final_path(handle, opened_name=opened_name))
333
+ expected = _normalized_windows_path(expected_path)
334
+ if actual != expected:
335
+ raise _invalid_path(expected_path, "opened file resolved outside its verified scan path")
336
+
337
+
338
+ def _verify_directory(handle: int, expected_path: Path) -> None:
339
+ info = _attributes(handle)
340
+ if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
341
+ raise _invalid_path(expected_path, "scan-local directories must not be reparse points")
342
+ if not info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY:
343
+ raise _invalid_path(expected_path, "expected a scan-local directory")
344
+ _verify_handle_path(handle, expected_path)
345
+
346
+
347
+ def _verify_regular_file(handle: int, expected_path: Path) -> None:
348
+ info = _attributes(handle)
349
+ if info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
350
+ raise _invalid_path(expected_path, "scan-local files must not be reparse points")
351
+ if info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY or _GetFileType(handle) != _FILE_TYPE_DISK:
352
+ raise _invalid_path(expected_path, "expected a regular scan-local file")
353
+ _verify_handle_path(handle, expected_path)
354
+
355
+
356
+ def _canonical_scan_directory(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
357
+ absolute = Path(scan_dir).absolute()
358
+ try:
359
+ expected = absolute.lstat()
360
+ canonical = absolute.resolve(strict=True)
361
+ except OSError as exc:
362
+ raise _invalid_path(scan_dir, "expected an existing scan directory") from exc
363
+ if _normalized_windows_path(absolute) != _normalized_windows_path(canonical):
364
+ raise _invalid_path(scan_dir, "scan directory must be canonical and non-reparse")
365
+ return canonical, (expected.st_dev, expected.st_ino)
366
+
367
+
368
+ def _open_directory(path: Path, *, missing_ok: bool = False) -> _OwnedHandle | None:
369
+ handle = _create_file(
370
+ path,
371
+ access=_FILE_READ_ATTRIBUTES,
372
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
373
+ disposition=_OPEN_EXISTING,
374
+ flags=_FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT,
375
+ missing_ok=missing_ok,
376
+ )
377
+ if handle is not None:
378
+ try:
379
+ assert handle.value is not None
380
+ _verify_directory(handle.value, path)
381
+ except BaseException:
382
+ handle.close()
383
+ raise
384
+ return handle
385
+
386
+
387
+ def _create_directory(path: Path) -> None:
388
+ if _CreateDirectoryW(_extended_path(path), None):
389
+ return
390
+ error = ctypes.get_last_error()
391
+ if error not in _COLLISION_ERRORS:
392
+ _raise_last_error("CreateDirectoryW", path)
393
+
394
+
395
+ @contextlib.contextmanager
396
+ def _locked_parent(
397
+ scan_dir: Path,
398
+ relative_path: str,
399
+ *,
400
+ create: bool,
401
+ ) -> Iterator[tuple[Path, str]]:
402
+ """Hold non-deletable handles for every directory in the absolute target path."""
403
+
404
+ _require_windows()
405
+ parts = _validated_parts(relative_path)
406
+ root_path, expected_root_identity = _canonical_scan_directory(scan_dir)
407
+ handles: list[_OwnedHandle] = []
408
+ try:
409
+ # Absolute-path Win32 calls remain safe only while every ancestor is
410
+ # fixed in place. Otherwise an attacker could rename an ancestor of the
411
+ # scan root and substitute a different tree at the stored path.
412
+ for directory_path in (*reversed(root_path.parents), root_path):
413
+ directory_handle = _open_directory(directory_path)
414
+ assert directory_handle is not None
415
+ handles.append(directory_handle)
416
+ current_root = root_path.lstat()
417
+ if (current_root.st_dev, current_root.st_ino) != expected_root_identity:
418
+ raise _invalid_path(scan_dir, "scan directory changed while it was being opened")
419
+ current_path = root_path
420
+ for component in parts[:-1]:
421
+ current_path /= component
422
+ child_handle = _open_directory(current_path, missing_ok=create)
423
+ if child_handle is None:
424
+ _create_directory(current_path)
425
+ child_handle = _open_directory(current_path)
426
+ assert child_handle is not None
427
+ handles.append(child_handle)
428
+ yield current_path, parts[-1]
429
+ finally:
430
+ for handle in reversed(handles):
431
+ handle.close()
432
+
433
+
434
+ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
435
+ """Open a verified regular file and return an owned binary read descriptor."""
436
+
437
+ try:
438
+ with _locked_parent(scan_dir, relative_path, create=False) as (parent_path, leaf_name):
439
+ path = parent_path / leaf_name
440
+ handle = _create_file(
441
+ path,
442
+ access=_GENERIC_READ | _FILE_READ_ATTRIBUTES,
443
+ # Denying write/delete sharing keeps the opened contents stable.
444
+ share=_FILE_SHARE_READ,
445
+ disposition=_OPEN_EXISTING,
446
+ flags=_FILE_FLAG_OPEN_REPARSE_POINT,
447
+ )
448
+ assert handle is not None and handle.value is not None
449
+ try:
450
+ _verify_regular_file(handle.value, path)
451
+ raw_handle = handle.detach()
452
+ try:
453
+ assert _msvcrt is not None
454
+ return _msvcrt.open_osfhandle(raw_handle, os.O_RDONLY | os.O_BINARY)
455
+ except BaseException:
456
+ _close_handle(raw_handle)
457
+ raise
458
+ finally:
459
+ handle.close()
460
+ except WindowsScanLocalFileError as exc:
461
+ raise WindowsScanLocalFileError(
462
+ exc.errno,
463
+ f"{context}: {exc.strerror}",
464
+ exc.filename,
465
+ ) from exc
466
+
467
+
468
+ def _write_all(handle: int, payload: bytes) -> None:
469
+ view = memoryview(payload)
470
+ offset = 0
471
+ while offset < len(view):
472
+ chunk = bytes(view[offset : offset + _MAX_WRITE_CHUNK])
473
+ buffer = ctypes.create_string_buffer(chunk, len(chunk))
474
+ written = wintypes.DWORD()
475
+ if not _WriteFile(handle, buffer, len(chunk), ctypes.byref(written), None):
476
+ _raise_last_error("WriteFile")
477
+ if written.value == 0:
478
+ raise WindowsScanLocalFileError(errno.EIO, "WriteFile made no progress")
479
+ offset += written.value
480
+ if not _FlushFileBuffers(handle):
481
+ _raise_last_error("FlushFileBuffers")
482
+
483
+
484
+ def _rename_handle(handle: int, destination_path: Path) -> None:
485
+ encoded_name = _extended_path(destination_path).encode("utf-16-le")
486
+ file_name_offset = _FileRenameInfo.FileName.offset
487
+ buffer_size = max(
488
+ ctypes.sizeof(_FileRenameInfo),
489
+ file_name_offset + len(encoded_name) + ctypes.sizeof(wintypes.WCHAR),
490
+ )
491
+ buffer = ctypes.create_string_buffer(buffer_size)
492
+ info = ctypes.cast(buffer, ctypes.POINTER(_FileRenameInfo)).contents
493
+ info.FlagsOrReplaceIfExists = 1
494
+ # The fully qualified destination uses a null RootDirectory. Verified
495
+ # directory handles remain open to prevent ancestor replacement.
496
+ info.RootDirectory = None
497
+ info.FileNameLength = len(encoded_name)
498
+ ctypes.memmove(ctypes.addressof(buffer) + file_name_offset, encoded_name, len(encoded_name))
499
+ if not _SetFileInformationByHandle(
500
+ handle,
501
+ _FILE_RENAME_INFO_CLASS,
502
+ buffer,
503
+ buffer_size,
504
+ ):
505
+ _raise_last_error("SetFileInformationByHandle(FileRenameInfo)")
506
+
507
+
508
+ def _mark_handle_for_deletion(handle: int) -> None:
509
+ info = _FileDispositionInfo(True)
510
+ if not _SetFileInformationByHandle(
511
+ handle,
512
+ _FILE_DISPOSITION_INFO_CLASS,
513
+ ctypes.byref(info),
514
+ ctypes.sizeof(info),
515
+ ):
516
+ _raise_last_error("SetFileInformationByHandle(FileDispositionInfo)")
517
+
518
+
519
+ def _validate_existing_output(path: Path) -> None:
520
+ handle = _create_file(
521
+ path,
522
+ access=_FILE_READ_ATTRIBUTES,
523
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
524
+ disposition=_OPEN_EXISTING,
525
+ flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
526
+ missing_ok=True,
527
+ )
528
+ if handle is None:
529
+ return
530
+ with handle:
531
+ assert handle.value is not None
532
+ _verify_regular_file(handle.value, path)
533
+
534
+
535
+ def atomic_write(scan_dir: Path, relative_path: str, payload: bytes) -> None:
536
+ """Atomically replace a scan-local regular file with ``payload``."""
537
+
538
+ with _locked_parent(scan_dir, relative_path, create=True) as (parent_path, leaf_name):
539
+ destination_path = parent_path / leaf_name
540
+ _validate_existing_output(destination_path)
541
+
542
+ temp_handle: _OwnedHandle | None = None
543
+ temp_path: Path | None = None
544
+ for _ in range(16):
545
+ temp_path = parent_path / f".{leaf_name}.{secrets.token_hex(8)}.tmp"
546
+ try:
547
+ temp_handle = _create_file(
548
+ temp_path,
549
+ access=_GENERIC_WRITE | _DELETE | _FILE_READ_ATTRIBUTES,
550
+ share=0,
551
+ disposition=_CREATE_NEW,
552
+ flags=_FILE_ATTRIBUTE_NORMAL,
553
+ )
554
+ except WindowsScanLocalFileError as exc:
555
+ if exc.errno in _COLLISION_ERRORS:
556
+ continue
557
+ raise
558
+ break
559
+ if temp_handle is None or temp_path is None:
560
+ raise WindowsScanLocalFileError(errno.EEXIST, "could not allocate a unique temp file")
561
+
562
+ with temp_handle:
563
+ assert temp_handle.value is not None
564
+ try:
565
+ _verify_regular_file(temp_handle.value, temp_path)
566
+ _write_all(temp_handle.value, payload)
567
+ _rename_handle(temp_handle.value, destination_path)
568
+ _verify_regular_file(temp_handle.value, destination_path)
569
+ except BaseException:
570
+ # Deleting by handle removes the exact temp/output file and cannot
571
+ # be redirected through a swapped path or reparse point.
572
+ try:
573
+ _mark_handle_for_deletion(temp_handle.value)
574
+ except OSError:
575
+ pass
576
+ raise
577
+
578
+
579
+ def unlink_if_exists(scan_dir: Path, relative_path: str) -> None:
580
+ """Delete a scan-local regular file or reparse-point leaf without following it."""
581
+
582
+ with _locked_parent(scan_dir, relative_path, create=False) as (parent_path, leaf_name):
583
+ path = parent_path / leaf_name
584
+ handle = _create_file(
585
+ path,
586
+ access=_DELETE | _FILE_READ_ATTRIBUTES,
587
+ # Deny delete sharing so an existing delete-capable handle makes
588
+ # cleanup fail instead of moving the verified object before delete.
589
+ share=_FILE_SHARE_READ | _FILE_SHARE_WRITE,
590
+ disposition=_OPEN_EXISTING,
591
+ flags=_FILE_FLAG_OPEN_REPARSE_POINT | _FILE_FLAG_BACKUP_SEMANTICS,
592
+ missing_ok=True,
593
+ )
594
+ if handle is None:
595
+ return
596
+ with handle:
597
+ assert handle.value is not None
598
+ info = _attributes(handle.value)
599
+ is_reparse_point = bool(info.FileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT)
600
+ is_directory = bool(info.FileAttributes & _FILE_ATTRIBUTE_DIRECTORY)
601
+ if is_directory and not is_reparse_point:
602
+ raise _invalid_path(path, "scan-local cleanup target must not be a directory")
603
+ _verify_handle_path(handle.value, path, opened_name=is_reparse_point)
604
+ _mark_handle_for_deletion(handle.value)
605
+
606
+
607
+ def main() -> None:
608
+ argparse.ArgumentParser(description=__doc__).parse_args()
609
+
610
+
611
+ if __name__ == "__main__":
612
+ main()
@@ -0,0 +1 @@
1
+ """Focused Codex Security workbench operation modules."""