@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.
- package/LICENSE +201 -0
- package/README.md +306 -0
- package/_bundled_plugin/.app.json +20 -0
- package/_bundled_plugin/.codex-plugin/plugin.json +41 -0
- package/_bundled_plugin/.mcp.json +20 -0
- package/_bundled_plugin/assets/logo.png +0 -0
- package/_bundled_plugin/examples/completed-scan/coverage.json +22 -0
- package/_bundled_plugin/examples/completed-scan/findings.json +51 -0
- package/_bundled_plugin/examples/completed-scan/scan-manifest.json +43 -0
- package/_bundled_plugin/mcp/mcp-app.html.br +0 -0
- package/_bundled_plugin/mcp/server.mjs +24 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/preflight/capability-profiles.toml +179 -0
- package/_bundled_plugin/references/config-preflight.md +115 -0
- package/_bundled_plugin/references/final-report.md +205 -0
- package/_bundled_plugin/references/finding-detail-fields.md +162 -0
- package/_bundled_plugin/references/sarif-adapter.md +26 -0
- package/_bundled_plugin/references/scan-artifacts.md +116 -0
- package/_bundled_plugin/references/scan-contract.md +164 -0
- package/_bundled_plugin/references/security-guidance.md +15 -0
- package/_bundled_plugin/references/shared-hard-rules.md +15 -0
- package/_bundled_plugin/references/static-finding-assessment.md +75 -0
- package/_bundled_plugin/schemas/coverage.schema.json +228 -0
- package/_bundled_plugin/schemas/findings.schema.json +359 -0
- package/_bundled_plugin/schemas/scan-manifest.schema.json +332 -0
- package/_bundled_plugin/scripts/config_preflight.py +901 -0
- package/_bundled_plugin/scripts/deep_scan_config.py +108 -0
- package/_bundled_plugin/scripts/deep_scan_workbench.py +1547 -0
- package/_bundled_plugin/scripts/filesystem_identity.py +30 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +2208 -0
- package/_bundled_plugin/scripts/finding_preview.py +270 -0
- package/_bundled_plugin/scripts/generate_rank_input.py +1013 -0
- package/_bundled_plugin/scripts/normalize_candidates.py +320 -0
- package/_bundled_plugin/scripts/rank_preview.py +968 -0
- package/_bundled_plugin/scripts/report_projection.py +844 -0
- package/_bundled_plugin/scripts/resolve_security_md.py +158 -0
- package/_bundled_plugin/scripts/snapshot_sqlite.py +26 -0
- package/_bundled_plugin/scripts/validate_report_format.py +138 -0
- package/_bundled_plugin/scripts/validate_scan_contract.py +108 -0
- package/_bundled_plugin/scripts/validate_tracking_source.py +92 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +612 -0
- package/_bundled_plugin/scripts/workbench/__init__.py +1 -0
- package/_bundled_plugin/scripts/workbench/handoff.py +238 -0
- package/_bundled_plugin/scripts/workbench_cli.py +325 -0
- package/_bundled_plugin/scripts/workbench_constants.py +81 -0
- package/_bundled_plugin/scripts/workbench_db.py +3728 -0
- package/_bundled_plugin/scripts/workbench_native_indexes.py +242 -0
- package/_bundled_plugin/scripts/workbench_progress.py +226 -0
- package/_bundled_plugin/scripts/workbench_remediation.py +125 -0
- package/_bundled_plugin/scripts/workbench_scan_history.py +829 -0
- package/_bundled_plugin/scripts/workbench_scan_start.py +149 -0
- package/_bundled_plugin/scripts/workbench_schema.py +714 -0
- package/_bundled_plugin/scripts/workbench_source_excerpt.py +99 -0
- package/_bundled_plugin/scripts/workbench_target.py +469 -0
- package/_bundled_plugin/scripts/workbench_target_state.py +63 -0
- package/_bundled_plugin/scripts/workbench_validation.py +294 -0
- package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +117 -0
- package/_bundled_plugin/skills/attack-path-analysis/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +76 -0
- package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +153 -0
- package/_bundled_plugin/skills/deep-security-scan/SKILL.md +166 -0
- package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/define-security-policy/SKILL.md +93 -0
- package/_bundled_plugin/skills/define-security-policy/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/finding-discovery/SKILL.md +155 -0
- package/_bundled_plugin/skills/finding-discovery/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +112 -0
- package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +240 -0
- package/_bundled_plugin/skills/propose-security-hardening/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +424 -0
- package/_bundled_plugin/skills/security-diff-scan/SKILL.md +167 -0
- package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/security-scan/SKILL.md +42 -0
- package/_bundled_plugin/skills/security-scan/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/security-scan/references/repository-wide-scan.md +48 -0
- package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +85 -0
- package/_bundled_plugin/skills/threat-model/SKILL.md +59 -0
- package/_bundled_plugin/skills/threat-model/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/threat-model/references/threat-model-guidance.md +48 -0
- package/_bundled_plugin/skills/track-findings/SKILL.md +222 -0
- package/_bundled_plugin/skills/track-findings/agents/openai.yaml +6 -0
- package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +54 -0
- package/_bundled_plugin/skills/track-findings/references/jira.md +77 -0
- package/_bundled_plugin/skills/triage-finding/SKILL.md +342 -0
- package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +168 -0
- package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +62 -0
- package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +108 -0
- package/_bundled_plugin/skills/validation/SKILL.md +110 -0
- package/_bundled_plugin/skills/validation/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/validation/references/validation-guidance.md +122 -0
- package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +263 -0
- package/_bundled_plugin/skills/vulnerability-writeup/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +104 -0
- package/bin/codex-security.mjs +26 -0
- package/dist/api.d.ts +112 -0
- package/dist/api.d.ts.map +1 -0
- package/dist/api.js +1051 -0
- package/dist/api.js.map +1 -0
- package/dist/auth.d.ts +29 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +246 -0
- package/dist/auth.js.map +1 -0
- package/dist/bulk-scan-discovery.d.ts +35 -0
- package/dist/bulk-scan-discovery.d.ts.map +1 -0
- package/dist/bulk-scan-discovery.js +217 -0
- package/dist/bulk-scan-discovery.js.map +1 -0
- package/dist/cli.d.ts +67 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +2128 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +19 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +199 -0
- package/dist/config.js.map +1 -0
- package/dist/contract.d.ts +21 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +848 -0
- package/dist/contract.js.map +1 -0
- package/dist/cost.d.ts +30 -0
- package/dist/cost.d.ts.map +1 -0
- package/dist/cost.js +280 -0
- package/dist/cost.js.map +1 -0
- package/dist/errors.d.ts +38 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +52 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/knowledge-base.d.ts +7 -0
- package/dist/knowledge-base.d.ts.map +1 -0
- package/dist/knowledge-base.js +181 -0
- package/dist/knowledge-base.js.map +1 -0
- package/dist/models.d.ts +231 -0
- package/dist/models.d.ts.map +1 -0
- package/dist/models.js +3 -0
- package/dist/models.js.map +1 -0
- package/dist/multiscan.d.ts +30 -0
- package/dist/multiscan.d.ts.map +1 -0
- package/dist/multiscan.js +397 -0
- package/dist/multiscan.js.map +1 -0
- package/dist/result.d.ts +39 -0
- package/dist/result.d.ts.map +1 -0
- package/dist/result.js +71 -0
- package/dist/result.js.map +1 -0
- package/dist/runtime.d.ts +69 -0
- package/dist/runtime.d.ts.map +1 -0
- package/dist/runtime.js +997 -0
- package/dist/runtime.js.map +1 -0
- package/dist/scan-comparison.d.ts +42 -0
- package/dist/scan-comparison.d.ts.map +1 -0
- package/dist/scan-comparison.js +153 -0
- package/dist/scan-comparison.js.map +1 -0
- package/dist/scan-history-renderer.d.ts +13 -0
- package/dist/scan-history-renderer.d.ts.map +1 -0
- package/dist/scan-history-renderer.js +297 -0
- package/dist/scan-history-renderer.js.map +1 -0
- package/dist/targets.d.ts +39 -0
- package/dist/targets.d.ts.map +1 -0
- package/dist/targets.js +295 -0
- package/dist/targets.js.map +1 -0
- package/dist/trusted-executable.d.ts +6 -0
- package/dist/trusted-executable.d.ts.map +1 -0
- package/dist/trusted-executable.js +77 -0
- package/dist/trusted-executable.js.map +1 -0
- package/dist/version.d.ts +6 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +42 -0
- package/dist/version.js.map +1 -0
- package/dist/worker-progress.d.ts +13 -0
- package/dist/worker-progress.d.ts.map +1 -0
- package/dist/worker-progress.js +113 -0
- package/dist/worker-progress.js.map +1 -0
- 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."""
|