Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix: reject Windows-ambiguous portable paths (#495)

faizan-oaif38594587dd0
diff --git a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py
index 198a101e1..dbb5eedc1 100644
--- a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py
+++ b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py
@@ -73,6 +73,10 @@ EXPORT_PATHS = {
"json": "exports/findings.json",
"sarif": "exports/results.sarif",
}
+WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
+ r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
+ re.IGNORECASE,
+)
class ContractError(ValueError):
@@ -225,10 +229,12 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
path = PurePosixPath(value)
normalized = path.as_posix()
if (
- not value
+ not value.strip()
or (normalized == "." and not allow_dot)
+ or (len(value) >= 2 and value[0].isalpha() and value[1] == ":")
or "\\" in value
or "\0" in value
+ or any(ord(character) < 32 for character in value)
or path.is_absolute()
or ".." in path.parts
):
@@ -236,6 +242,21 @@ def _require_safe_relative_path(value: str, context: str, *, allow_dot: bool = F
return normalized
+def _require_portable_relative_path(
+ value: str, context: str, *, allow_dot: bool = False
+) -> str:
+ normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
+ if any(_windows_unsafe_path_component(part) for part in value.split("/")):
+ raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
+ return normalized
+
+
+def _windows_unsafe_path_component(value: str) -> bool:
+ if not value or value == ".":
+ return False
+ return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None
+
+
def _require_scan_directory(scan_dir: Path) -> Path:
scan_dir = scan_dir.absolute()
try:
@@ -347,7 +368,7 @@ def _open_scan_local_directory(root_fd: int, parts: tuple[str, ...], *, create:
def open_scan_local_file_descriptor(scan_dir: Path, relative_path: str, context: str) -> int:
scan_dir = _require_scan_directory(scan_dir)
- relative_path = _require_safe_relative_path(relative_path, context)
+ relative_path = _require_portable_relative_path(relative_path, context)
if not _descriptor_relative_reads_available():
if not _is_windows():
raise ContractError("scan-local input requires descriptor-relative file operations")
@@ -478,7 +499,7 @@ def write_scan_local_bytes(
if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
raise ContractError("external output path: expected a safe file name")
else:
- relative_path = _require_safe_relative_path(relative_path, "scan-local output path")
+ relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
path = scan_dir / relative_path
if not _descriptor_relative_writes_available():
if not _is_windows():
@@ -529,7 +550,7 @@ def write_scan_local_bytes(
def _remove_scan_local_file_if_exists(scan_dir: Path, relative_path: str) -> None:
scan_dir = _require_scan_directory(scan_dir)
- relative_path = _require_safe_relative_path(relative_path, "scan-local cleanup path")
+ relative_path = _require_portable_relative_path(relative_path, "scan-local cleanup path")
if not _descriptor_relative_writes_available():
if not _is_windows():
raise ContractError("scan-local cleanup requires descriptor-relative file operations")
@@ -936,7 +957,7 @@ def _recover_unsealed_coverage(
try:
if not isinstance(ref, str):
raise ContractError(f"{ref_context}: expected a string")
- normalized_ref = _require_safe_relative_path(ref, ref_context)
+ normalized_ref = _require_portable_relative_path(ref, ref_context)
if not normalized_ref.startswith("artifacts/"):
raise ContractError(
f"{ref_context}: expected a file under artifacts/"
@@ -1322,7 +1343,9 @@ def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_
for ref_index, ref in enumerate(receipt_refs):
if not isinstance(ref, str):
raise ContractError(f"{context}.receiptRefs[{ref_index}]: expected a string")
- normalized_ref = _require_safe_relative_path(ref, f"{context}.receiptRefs[{ref_index}]")
+ normalized_ref = _require_portable_relative_path(
+ ref, f"{context}.receiptRefs[{ref_index}]"
+ )
if not normalized_ref.startswith("artifacts/"):
raise ContractError(
f"{context}.receiptRefs[{ref_index}]: expected a file under artifacts/"
@@ -1367,16 +1390,19 @@ def _validate_manifest(manifest: dict[str, Any]) -> None:
if not artifacts:
raise ContractError("manifest.scan.artifacts: expected generated artifact records")
artifact_paths: set[str] = set()
+ artifact_collision_keys: set[str] = set()
for index, artifact in enumerate(artifacts):
context = f"manifest.scan.artifacts[{index}]"
if not isinstance(artifact, dict):
raise ContractError(f"{context}: expected an object")
- path = _require_safe_relative_path(
+ path = _require_portable_relative_path(
_require_str(artifact, "path", context), f"{context}.path"
)
- if path in artifact_paths:
+ collision_key = path.lower()
+ if collision_key in artifact_collision_keys:
raise ContractError(f"{context}.path: duplicate artifact path")
artifact_paths.add(path)
+ artifact_collision_keys.add(collision_key)
_require_str(artifact, "sha256", context)
_require_str(artifact, "mediaType", context)
for required_path in ("findings.json", "coverage.json"):
@@ -2146,7 +2172,7 @@ def _validate_sarif(sarif: dict[str, Any]) -> None:
def _artifact_record(
scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
) -> dict[str, str]:
- relative_path = _require_safe_relative_path(relative_path, "artifact path")
+ relative_path = _require_portable_relative_path(relative_path, "artifact path")
if contents is not None:
_require_scan_local_file(scan_dir, relative_path, relative_path)
return {
@@ -2167,7 +2193,7 @@ def _coverage_receipt_refs(coverage: dict[str, Any]) -> list[str]:
def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
artifact_paths = {
- _require_safe_relative_path(artifact["path"], "sealed artifact path")
+ _require_portable_relative_path(artifact["path"], "sealed artifact path")
for artifact in scan["artifacts"]
}
for ref in _coverage_receipt_refs(coverage):
@@ -2190,16 +2216,19 @@ def _validate_existing_seal(
if not isinstance(artifacts, list) or not artifacts:
raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
artifact_paths: set[str] = set()
+ artifact_collision_keys: set[str] = set()
for index, artifact in enumerate(artifacts):
context = f"manifest.scan.artifacts[{index}]"
if not isinstance(artifact, dict):
raise ContractError(f"{context}: expected an object")
- path = _require_safe_relative_path(
+ path = _require_portable_relative_path(
_require_str(artifact, "path", context), f"{context}.path"
)
- if path in artifact_paths:
+ collision_key = path.lower()
+ if collision_key in artifact_collision_keys:
raise ContractError(f"{context}.path: duplicate artifact path")
artifact_paths.add(path)
+ artifact_collision_keys.add(collision_key)
expected_sha256 = _require_str(artifact, "sha256", context)
contents = (artifact_contents or {}).get(path)
actual_sha256 = (
@@ -2424,7 +2453,7 @@ def write_export_output(scan_dir: Path, output: Path, export_format: str, conten
scan = _require_dict(manifest, "scan", "manifest")
artifacts = _require_list(scan, "artifacts", "manifest.scan")
artifact_paths = [
- _require_safe_relative_path(
+ _require_portable_relative_path(
_require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
f"manifest.scan.artifacts[{index}].path",
)
diff --git a/sdk/typescript/_bundled_plugin/scripts/generate_in_scope_files.py b/sdk/typescript/_bundled_plugin/scripts/generate_in_scope_files.py
index 6449bf747..42bb48dc6 100644
--- a/sdk/typescript/_bundled_plugin/scripts/generate_in_scope_files.py
+++ b/sdk/typescript/_bundled_plugin/scripts/generate_in_scope_files.py
@@ -15,6 +15,21 @@ class InventoryError(ValueError):
"""Raised when the repository, scope, or inventory cannot be used safely."""
+def windows_stream_component(path: Path) -> str | None:
+ """Return the first NTFS alternate-data-stream component."""
+
+ if os.name != "nt":
+ return None
+ return next(
+ (
+ component
+ for component in path.parts
+ if component != path.anchor and ":" in component
+ ),
+ None,
+ )
+
+
def resolve_repository(value: str) -> Path:
"""Resolve the repository once so every scope is bound to its real root."""
try:
@@ -32,6 +47,11 @@ def resolve_scope(repository: Path, value: str) -> str:
raise InventoryError("--scope: expected a non-empty file or directory")
requested = Path(value).expanduser()
+ stream = windows_stream_component(requested)
+ if stream is not None:
+ raise InventoryError(
+ f"--scope: NTFS alternate data streams are not supported: {stream}"
+ )
scope = requested if requested.is_absolute() else repository / requested
try:
resolved = scope.resolve(strict=True)
diff --git a/sdk/typescript/_bundled_plugin/scripts/generate_rank_input.py b/sdk/typescript/_bundled_plugin/scripts/generate_rank_input.py
index 92018d74b..0f8e6f87d 100644
--- a/sdk/typescript/_bundled_plugin/scripts/generate_rank_input.py
+++ b/sdk/typescript/_bundled_plugin/scripts/generate_rank_input.py
@@ -293,6 +293,21 @@ def path_is_excluded(path: Path) -> bool:
return path.name.endswith((".min.js", ".map"))
+def windows_stream_component(path: Path) -> str | None:
+ """Return the first NTFS alternate-data-stream component."""
+
+ if os.name != "nt":
+ return None
+ return next(
+ (
+ component
+ for component in path.parts
+ if component != path.anchor and ":" in component
+ ),
+ None,
+ )
+
+
def resolve_scope(
repo: Path,
scope: str,
@@ -301,6 +316,9 @@ def resolve_scope(
reject_symlinks: bool = False,
) -> Path:
scope_path = Path(scope).expanduser() if expand_user else Path(scope)
+ stream = windows_stream_component(scope_path)
+ if stream is not None:
+ raise SystemExit(f"Scope must not use an NTFS alternate data stream: {stream}")
if not scope_path.is_absolute():
scope_path = repo / scope_path
if reject_symlinks:
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index b508766ba..3126df4f9 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -189,6 +189,7 @@ const distFiles = new Set(
"targets",
"trusted-executable",
"version",
+ "windows-path",
"worker-progress",
].flatMap((module) =>
["js", "js.map", "d.ts", "d.ts.map"].map(
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index e16136ea2..6c59c2691 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -101,6 +101,7 @@ import {
import type { ScanResult } from "./result.js";
import {
bundledPluginRoot,
+ canonicalizeModelSafePath,
codexSecurityCredentialHome,
codexSecurityStateDirectory,
expandHome,
@@ -1585,7 +1586,11 @@ export async function main(
const scanRoot =
options.scanRoot === undefined
? undefined
- : resolveCliPath(directory, options.scanRoot);
+ : process.platform === "win32"
+ ? await canonicalizeModelSafePath(
+ resolveCliPath(directory, options.scanRoot),
+ )
+ : resolveCliPath(directory, options.scanRoot);
const repository =
scanRoot !== undefined && args.repository === undefined
? undefined
diff --git a/sdk/typescript/src/contract.ts b/sdk/typescript/src/contract.ts
index 7e80a8fa4..c8c4b8548 100644
--- a/sdk/typescript/src/contract.ts
+++ b/sdk/typescript/src/contract.ts
@@ -20,6 +20,7 @@ import {
requireSecureOutputAncestry,
} from "./runtime.js";
import type { NormalizedTarget, ScanMode } from "./targets.js";
+import { isWindowsUnsafePathComponent } from "./windows-path.js";
const DOCUMENTS = {
"scan-manifest.json": "scan-manifest.schema.json",
@@ -518,7 +519,7 @@ async function requireCheckedScanFile(
const checkedRoot = await requireScanRoot(scanDirectory, signal);
const scanDir = checkedRoot.path;
throwIfAborted(signal);
- const safePath = safeRelativePath(relativePath, context);
+ const safePath = portableRelativePath(relativePath, context);
const parts = safePath.split("/");
let current = scanDir;
try {
@@ -593,16 +594,19 @@ async function validateSeal(
}
const artifactPaths = new Set<string>();
+ const artifactCollisionKeys = new Set<string>();
for (const [index, artifact] of scan.artifacts.entries()) {
throwIfAborted(signal);
const context = `manifest.scan.artifacts[${index}]`;
- const normalized = safeRelativePath(artifact.path, `${context}.path`);
- if (artifactPaths.has(normalized)) {
+ const normalized = portableRelativePath(artifact.path, `${context}.path`);
+ const collisionKey = normalized.toLowerCase();
+ if (artifactCollisionKeys.has(collisionKey)) {
throw new ContractValidationError(
`${context}.path: duplicate artifact path.`,
);
}
artifactPaths.add(normalized);
+ artifactCollisionKeys.add(collisionKey);
const digest =
documentDigests.get(normalized) ??
(await sha256ScanFile(
@@ -622,7 +626,7 @@ async function validateSeal(
for (const surface of coverage.surfaces) {
for (const receipt of surface.receiptRefs) {
throwIfAborted(signal);
- const normalized = safeRelativePath(receipt, "coverage receipt");
+ const normalized = portableRelativePath(receipt, "coverage receipt");
if (!normalized.startsWith("artifacts/")) {
throw new ContractValidationError(
`Coverage receipt must be under artifacts/: ${receipt}`,
@@ -826,15 +830,14 @@ async function verifyScanRoot(
function safeRelativePath(value: string, context: string): string {
const parts = value.split("/");
if (
- value.length === 0 ||
+ value.trim().length === 0 ||
!isWellFormedUnicode(value) ||
value === "." ||
value.startsWith("/") ||
/^[A-Za-z]:/.test(value) ||
parts.includes("..") ||
value.includes("\\") ||
- value.includes("\0") ||
- parts.some((part) => part.includes(":"))
+ /[\u0000-\u001f]/u.test(value)
) {
throw new ContractValidationError(
`${context}: expected a safe scan-relative POSIX path.`,
@@ -853,6 +856,16 @@ function safeRelativePath(value: string, context: string): string {
return normalized;
}
+function portableRelativePath(value: string, context: string): string {
+ const normalized = safeRelativePath(value, context);
+ if (value.split("/").some(isWindowsUnsafePathComponent)) {
+ throw new ContractValidationError(
+ `${context}: expected a safe scan-relative POSIX path.`,
+ );
+ }
+ return normalized;
+}
+
function safeScopePath(value: string): string {
return value === "."
? value
diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.ts
index 6cd7ae37d..07d37cec1 100644
--- a/sdk/typescript/src/multiscan.ts
+++ b/sdk/typescript/src/multiscan.ts
@@ -35,6 +35,8 @@ const REQUIRED_ARTIFACTS = [
];
const LOCK_LEASE_MS = 30_000;
const LOCK_HEARTBEAT_MS = 5_000;
+const WINDOWS_DEVICE_PATH_NAME =
+ /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
interface MultiscanTask {
id: string;
@@ -721,7 +723,7 @@ function parseInventory(
if (
!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(id) ||
id.endsWith(".") ||
- /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(id)
+ WINDOWS_DEVICE_PATH_NAME.test(id)
) {
throw new Error("Multiscan task IDs must be safe, unique path names.");
}
@@ -743,6 +745,7 @@ function parseInventory(
(isAbsolute(scope) ||
scope.includes("\\") ||
scope.split("/").includes("..") ||
+ (process.platform === "win32" && scope.includes(":")) ||
scope.includes("\0"))
) {
throw new Error("Multiscan scope must stay inside its repository.");
diff --git a/sdk/typescript/src/runtime.ts b/sdk/typescript/src/runtime.ts
index 6d3304f23..758949782 100644
--- a/sdk/typescript/src/runtime.ts
+++ b/sdk/typescript/src/runtime.ts
@@ -57,6 +57,10 @@ import {
} from "./errors.js";
import type { JsonObject } from "./config.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
+import {
+ isWindowsUnsafePathComponent,
+ windowsUnsafePathComponent,
+} from "./windows-path.js";
const execFile = promisify(execFileCallback);
@@ -130,17 +134,21 @@ export function codexSecurityStateDirectory(
environment: ProcessEnvironment = process.env,
): string {
const configured = environmentValue(environment, "CODEX_SECURITY_STATE_DIR");
- if (configured !== undefined) {
- return resolve(expandHome(configured, environment));
- }
- const codexHome =
- environmentValue(environment, "CODEX_HOME") ?? join(homedir(), ".codex");
- return resolve(
- expandHome(codexHome, environment),
- "state",
- "plugins",
- "codex-security",
- );
+ const path =
+ configured !== undefined
+ ? resolve(expandHome(configured, environment))
+ : resolve(
+ expandHome(
+ environmentValue(environment, "CODEX_HOME") ??
+ join(homedir(), ".codex"),
+ environment,
+ ),
+ "state",
+ "plugins",
+ "codex-security",
+ );
+ requireModelSafeOutputDir(path);
+ return path;
}
export function codexSecurityCredentialHome(
@@ -851,7 +859,7 @@ async function secureWindowsCredentialHome(path: string): Promise<void> {
"$path = $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
"while ($true) { $parent = Microsoft.PowerShell.Management\\Split-Path -Path $path -Parent; if (-not $parent -or $parent -eq $path) { break }; Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $parent | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl; $path = $parent }",
"Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl",
- "Microsoft.PowerShell.Management\\Get-ChildItem -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH -Recurse -Force | Microsoft.PowerShell.Security\\Get-Acl | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl",
+ "Microsoft.PowerShell.Management\\Get-ChildItem -LiteralPath $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH -Recurse -Force | Microsoft.PowerShell.Core\\ForEach-Object { try { Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $_.FullName | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl } catch { if ($_.FullyQualifiedErrorId -notlike 'GetAcl_PathNotFound,*') { throw } } }",
].join("; ");
const resolvePrincipalScript = [
"$ErrorActionPreference = 'Stop'",
@@ -1334,6 +1342,7 @@ export async function preparePersistentOutputRoot(
category: "scans" | "policies",
repositoryName: string,
): Promise<string> {
+ requireModelSafeOutputDir(stateDirectory);
await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
let root = await realpath(stateDirectory);
for (const directory of [category, safePrefix(repositoryName)]) {
@@ -1523,6 +1532,31 @@ export function requireModelSafeOutputDir(path: string): void {
"Scan output directory must not contain control or line-separator characters.",
);
}
+ const ambiguous =
+ process.platform === "win32" ? windowsUnsafePathComponent(path) : undefined;
+ if (ambiguous !== undefined) {
+ throw new OutputDirectoryError(
+ `Codex Security paths must not contain Windows-ambiguous components: ${ambiguous}`,
+ );
+ }
+}
+
+export async function canonicalizeModelSafePath(
+ input: string,
+): Promise<string> {
+ const path = resolve(expandHome(input));
+ requireModelSafeOutputDir(path);
+ for (let ancestor = path; ; ancestor = dirname(ancestor)) {
+ try {
+ const canonicalAncestor = resolve(ancestor, await realpath(ancestor));
+ const canonical = resolve(canonicalAncestor, relative(ancestor, path));
+ requireModelSafeOutputDir(canonical);
+ return canonical;
+ } catch (error) {
+ if (nodeErrorCode(error) !== "ENOENT") throw error;
+ if (dirname(ancestor) === ancestor) throw error;
+ }
+ }
}
export async function prepareOutputDir(
@@ -2462,7 +2496,7 @@ function safeArchivePath(value: string): string {
parts.includes("..") ||
value.includes("\\") ||
value.includes("\0") ||
- parts.some((part) => part.includes(":")) ||
+ parts.some(isWindowsUnsafePathComponent) ||
normalized.length === 0
) {
throw new PluginBootstrapError(
diff --git a/sdk/typescript/src/targets.ts b/sdk/typescript/src/targets.ts
index 3b4577d38..975e43e5f 100644
--- a/sdk/typescript/src/targets.ts
+++ b/sdk/typescript/src/targets.ts
@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { promisify } from "node:util";
import { InvalidTargetError } from "./errors.js";
import { resolveTrustedExecutable } from "./trusted-executable.js";
+import { windowsUnsafePathComponent } from "./windows-path.js";
const execFile = promisify(execFileCallback);
const UNSUPPORTED_GIT_ENVIRONMENT = new Set([
@@ -111,6 +112,7 @@ export async function normalizeRepository(
signal?: AbortSignal,
): Promise<string> {
const candidate = resolveRepositoryPath(repository);
+ requirePortableWindowsRepositoryPath(candidate);
let canonical: string;
try {
canonical = await abortable(() => realpath(candidate), signal);
@@ -126,6 +128,7 @@ export async function normalizeRepository(
},
);
}
+ requirePortableWindowsRepositoryPath(canonical);
return canonical;
}
@@ -133,6 +136,16 @@ export function resolveRepositoryPath(repository: string): string {
return resolve(expandHome(repository));
}
+function requirePortableWindowsRepositoryPath(path: string): void {
+ if (process.platform !== "win32") return;
+ const ambiguous = windowsUnsafePathComponent(path);
+ if (ambiguous !== undefined) {
+ throw new InvalidTargetError(
+ `Repository paths must not contain Windows-ambiguous components: ${ambiguous}`,
+ );
+ }
+}
+
export async function enclosingGitWorktreeRoot(
repository: string,
signal?: AbortSignal,
@@ -276,6 +289,14 @@ export async function normalizeTarget(
`Path target is outside the repository: ${value}`,
);
}
+ if (
+ process.platform === "win32" &&
+ relativePath.split(sep).some((part) => part.includes(":"))
+ ) {
+ throw new InvalidTargetError(
+ `Path target contains an unsupported colon component: ${value}`,
+ );
+ }
const normalized = relativePath.split(sep).join("/") || ".";
if (!paths.includes(normalized)) {
paths.push(normalized);
diff --git a/sdk/typescript/src/windows-path.ts b/sdk/typescript/src/windows-path.ts
new file mode 100644
index 000000000..05b3911fb
--- /dev/null
+++ b/sdk/typescript/src/windows-path.ts
@@ -0,0 +1,21 @@
+import { parse } from "node:path";
+
+const UNSAFE_COMPONENT = /[<>:"|?*\u0000-\u001f]|[ .]$/u;
+const RESERVED_COMPONENT =
+ /^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$/iu;
+
+export function isWindowsUnsafePathComponent(value: string): boolean {
+ return (
+ value !== "" &&
+ value !== "." &&
+ (UNSAFE_COMPONENT.test(value) || RESERVED_COMPONENT.test(value))
+ );
+}
+
+export function windowsUnsafePathComponent(path: string): string | undefined {
+ const root = parse(path).root;
+ return path
+ .slice(root.length)
+ .split(/[\\/]/u)
+ .find(isWindowsUnsafePathComponent);
+}
diff --git a/sdk/typescript/tests-ts/cli-history-paths.test.ts b/sdk/typescript/tests-ts/cli-history-paths.test.ts
new file mode 100644
index 000000000..8a8c9372c
--- /dev/null
+++ b/sdk/typescript/tests-ts/cli-history-paths.test.ts
@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "bun:test";
+import { main } from "../src/cli.js";
+import { capture, dependencies } from "./cli-fixtures.js";
+
+test.skipIf(process.platform !== "win32")(
+ "rejects an aliased Windows scan root before querying history",
+ async () => {
+ const root = await realpath(
+ await mkdtemp(join(tmpdir(), "codex-security-history-root-alias-")),
+ );
+ try {
+ const scanRoot = join(root, "history");
+ const ambiguous = join(root, "history.");
+ await Promise.all([mkdir(scanRoot), mkdir(ambiguous)]);
+ expect(await realpath(scanRoot)).not.toBe(await realpath(ambiguous));
+ let workbenchCalls = 0;
+ const stderr = capture();
+
+ expect(
+ await main(
+ ["scans", "list", "--scan-root", ambiguous],
+ capture().stream,
+ stderr.stream,
+ dependencies({
+ currentDirectory: root,
+ onWorkbench: () => {
+ workbenchCalls += 1;
+ return { scans: [] };
+ },
+ }),
+ ),
+ ).toBe(2);
+ expect(workbenchCalls).toBe(0);
+ expect(stderr.text()).toContain("Windows-ambiguous components");
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+ },
+);
diff --git a/sdk/typescript/tests-ts/contract.test.ts b/sdk/typescript/tests-ts/contract.test.ts
index 4bcecb9e2..eb48deb2e 100644
--- a/sdk/typescript/tests-ts/contract.test.ts
+++ b/sdk/typescript/tests-ts/contract.test.ts
@@ -7,6 +7,7 @@ import {
mkdir,
mkdtemp,
readFile,
+ realpath,
rm,
symlink,
type FileHandle,
@@ -560,7 +561,12 @@ describe("canonical scan contract", () => {
});
test("rejects unsafe Windows and traversal artifact paths", async () => {
- for (const unsafe of ["D:/escape", "../escape", "artifacts\\escape"]) {
+ for (const unsafe of [
+ "D:/escape",
+ "../escape",
+ "artifacts\\escape",
+ "artifacts/report?.json",
+ ]) {
const scanDir = await copyExample();
const path = join(scanDir, "scan-manifest.json");
const manifest = await readJson(path);
@@ -574,6 +580,135 @@ describe("canonical scan contract", () => {
loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
).rejects.toThrow(ContractValidationError);
}
+
+ for (const unsafe of [
+ "artifacts/report.json.",
+ "artifacts/report.json ",
+ "artifacts/CON.txt",
+ ]) {
+ const scanDir = await copyExample();
+ const path = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(path);
+ manifest["scan"]["artifacts"].push({
+ path: unsafe,
+ sha256: "0".repeat(64),
+ mediaType: "text/plain",
+ });
+ await writeJson(path, manifest);
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).rejects.toThrow("safe scan-relative POSIX path");
+ }
+ });
+
+ test("keeps bundled finalizer paths portable to Windows", () => {
+ const python =
+ process.env["PYTHON"] ?? Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ if (python === null) return;
+ const program = [
+ "import json, sys",
+ "sys.path.insert(0, sys.argv[1])",
+ "import finalize_scan_contract as finalizer",
+ "def accepted(value):",
+ " try:",
+ " finalizer._require_portable_relative_path(value, 'artifact path')",
+ " except finalizer.ContractError:",
+ " return False",
+ " return True",
+ "print(json.dumps([accepted(value) for value in ['artifacts/report.json.', 'artifacts/report.json ', 'artifacts/CON.txt', 'artifacts/report?.json', 'artifacts/report:stream']]))",
+ ].join("\n");
+ const result = Bun.spawnSync(
+ [python, "-I", "-B", "-c", program, join(PLUGIN_ROOT, "scripts")],
+ { stdout: "pipe", stderr: "pipe" },
+ );
+
+ expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
+ expect(JSON.parse(new TextDecoder().decode(result.stdout))).toEqual([
+ false,
+ false,
+ false,
+ false,
+ false,
+ ]);
+ });
+
+ test("accepts Unix-valid source and scope path components", async () => {
+ const scanDir = await copyExample();
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const findingsPath = join(scanDir, "findings.json");
+ const coveragePath = join(scanDir, "coverage.json");
+ const manifest = await readJson(manifestPath);
+ const findings = await readJson(findingsPath);
+ const coverage = await readJson(coveragePath);
+ findings["findings"][0]["locations"][0]["path"] = "src/app.ts:fixture";
+ manifest["scan"]["scope"]["includePaths"] = ["src/CON.py"];
+ coverage["includePaths"] = ["src/CON.py"];
+ await writeJson(findingsPath, findings);
+ await writeJson(coveragePath, coverage);
+ await writeJson(manifestPath, manifest);
+ await reseal(scanDir);
+
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).resolves.toBeDefined();
+ });
+
+ test("rejects trailing-dot aliases for sealed artifacts", async () => {
+ const scanDir = await copyExample();
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ await writeFile(
+ join(scanDir, "findings.json."),
+ await readFile(join(scanDir, "findings.json")),
+ );
+ manifest["scan"]["artifacts"].push({
+ ...manifest["scan"]["artifacts"][0],
+ path: "findings.json.",
+ });
+ await writeJson(manifestPath, manifest);
+
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).rejects.toThrow("safe scan-relative POSIX path");
+ });
+
+ test("rejects case-insensitive aliases for sealed artifacts", async () => {
+ const scanDir = await copyExample();
+ const manifestPath = join(scanDir, "scan-manifest.json");
+ const manifest = await readJson(manifestPath);
+ await writeFile(
+ join(scanDir, "FINDINGS.json"),
+ await readFile(join(scanDir, "findings.json")),
+ );
+ manifest["scan"]["artifacts"].push({
+ ...manifest["scan"]["artifacts"][0],
+ path: "FINDINGS.json",
+ });
+ await writeJson(manifestPath, manifest);
+
+ await expect(
+ loadContract(scanDir, { pluginRoot: PLUGIN_ROOT }),
+ ).rejects.toThrow("duplicate artifact path");
+
+ const python =
+ process.env["PYTHON"] ?? Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ if (python === null) return;
+ const result = Bun.spawnSync(
+ [
+ python,
+ "-I",
+ "-B",
+ join(PLUGIN_ROOT, "scripts", "finalize_scan_contract.py"),
+ "--scan-dir",
+ await realpath(scanDir),
+ ],
+ { stdout: "pipe", stderr: "pipe" },
+ );
+ const stderr = new TextDecoder().decode(result.stderr);
+ expect(result.exitCode, stderr).not.toBe(0);
+ expect(stderr).toContain("duplicate artifact path");
});
test("rejects calendar-invalid RFC 3339 timestamps", async () => {
diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.ts
index 328f2359d..873b5cb47 100644
--- a/sdk/typescript/tests-ts/multiscan.test.ts
+++ b/sdk/typescript/tests-ts/multiscan.test.ts
@@ -835,6 +835,31 @@ describe("multiscan", () => {
expect(scans).toBe(0);
});
+ test("rejects task IDs that collide with Windows path names", async () => {
+ const paths = await fixture();
+ let scans = 0;
+ for (const id of ["task.", "CON", "nul.txt", "COM1", "LPT9.log"]) {
+ await writeFile(
+ paths.input,
+ `id,repository,revision\n${id},./repository,${"0".repeat(40)}\n`,
+ );
+
+ await expect(
+ runMultiscan(
+ options(
+ paths,
+ client(async (_repository, scanOptions = {}) => {
+ scans += 1;
+ return await completedScan(scanOptions.outputDir!);
+ }),
+ ),
+ ),
+ ).rejects.toThrow("safe, unique path names");
+ }
+
+ expect(scans).toBe(0);
+ });
+
test("materializes the pinned commit, applies row options, and removes its checkout", async () => {
const paths = await fixture();
const source = await repository(paths.root, "payments");
@@ -2071,6 +2096,14 @@ describe("multiscan", () => {
name: "scope",
row: `safe,${source.path},${source.revision},../outside`,
},
+ ...(process.platform === "win32"
+ ? [
+ {
+ name: "windows-qualified-scope",
+ row: `safe,${source.path},${source.revision},src:stream`,
+ },
+ ]
+ : []),
{
name: "revision",
row: `safe,${source.path},HEAD,.`,
diff --git a/sdk/typescript/tests-ts/runtime.test.ts b/sdk/typescript/tests-ts/runtime.test.ts
index 7990f1d06..423039d73 100644
--- a/sdk/typescript/tests-ts/runtime.test.ts
+++ b/sdk/typescript/tests-ts/runtime.test.ts
@@ -51,6 +51,7 @@ import {
import {
acquireCodexSecurityCredentialHomeLock,
bundledPluginCandidates,
+ canonicalizeModelSafePath,
codexSecurityCredentialAllowsAmbientImport,
codexSecurityCredentialHome,
codexSecurityHasStoredFileCredentials,
@@ -450,6 +451,63 @@ describe("plugin runtime preparation", () => {
}
});
+ test.skipIf(process.platform !== "win32")(
+ "rejects alternate data streams in bundled scan scopes",
+ async () => {
+ const root = await temporaryDirectory("codex-security-scope-ads-");
+ const repository = join(root, "repository");
+ await mkdir(repository);
+ await writeFile(
+ join(repository, "source.ts"),
+ "export const safe = true;\n",
+ );
+ await writeFile(
+ join(repository, "source.ts:synthetic-stream"),
+ "export const hidden = true;\n",
+ );
+ const python =
+ process.env["PYTHON"] ?? Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+
+ const inventory = spawnSync(
+ python!,
+ [
+ "-I",
+ "-B",
+ join(PLUGIN_ROOT, "scripts", "generate_in_scope_files.py"),
+ "--repo",
+ repository,
+ "--scope",
+ "source.ts:synthetic-stream",
+ "--out",
+ join(root, "inventory.txt"),
+ ],
+ { encoding: "utf8" },
+ );
+ expect(inventory.status).toBe(2);
+ expect(inventory.stderr).toContain("NTFS alternate data streams");
+
+ const rankInput = spawnSync(
+ python!,
+ [
+ "-I",
+ "-B",
+ join(PLUGIN_ROOT, "scripts", "generate_rank_input.py"),
+ "make-repo-rank-input",
+ "--repo",
+ repository,
+ "--scope",
+ "source.ts:synthetic-stream",
+ "--out",
+ join(root, "rank-input.jsonl"),
+ ],
+ { encoding: "utf8" },
+ );
+ expect(rankInput.status).toBe(1);
+ expect(rankInput.stderr).toContain("NTFS alternate data stream");
+ },
+ );
+
test("preserves remediation when the filesystem device changes", async () => {
const python = Bun.which("python3") ?? Bun.which("python");
expect(python).not.toBeNull();
@@ -800,8 +858,9 @@ describe("plugin runtime preparation", () => {
inScope: true,
contractValid:
item.path.trim().length > 0 &&
+ !/^[A-Za-z]:/.test(item.path) &&
!item.path.includes("\\") &&
- !item.path.includes(":"),
+ !/[\u0000-\u001f]/u.test(item.path),
})),
);
},
@@ -1204,7 +1263,7 @@ describe("plugin runtime preparation", () => {
).toBe(false);
});
- test("rejects traversal, Windows-qualified, duplicate, and symlink ZIP paths", async () => {
+ test("rejects unsafe, Windows-ambiguous, duplicate, and symlink ZIP paths", async () => {
const unsafeArchives: Array<[string, Uint8Array]> = [
["traversal", zipSync({ "../escape": strToU8("bad") })],
["drive", zipSync({ "D:/escape": strToU8("bad") })],
@@ -1223,6 +1282,53 @@ describe("plugin runtime preparation", () => {
"release/scripts/file.py": strToU8("overwrite"),
}),
],
+ [
+ "trailing-dot-collision",
+ zipSync({
+ "release/.codex-plugin/plugin.json": strToU8(
+ JSON.stringify({ name: "codex-security", version: "1.2.3" }),
+ ),
+ "release/helper.py": strToU8("same"),
+ "release/helper.py.": strToU8("same"),
+ }),
+ ],
+ [
+ "trailing-space-collision",
+ zipSync({
+ "release/.codex-plugin/plugin.json": strToU8(
+ JSON.stringify({ name: "codex-security", version: "1.2.3" }),
+ ),
+ "release/helper.py": strToU8("same"),
+ "release/helper.py ": strToU8("same"),
+ }),
+ ],
+ [
+ "reserved-device-name",
+ zipSync({
+ "release/.codex-plugin/plugin.json": strToU8(
+ JSON.stringify({ name: "codex-security", version: "1.2.3" }),
+ ),
+ "release/CON.txt": strToU8("bad"),
+ }),
+ ],
+ [
+ "reserved-console-device-name",
+ zipSync({
+ "release/.codex-plugin/plugin.json": strToU8(
+ JSON.stringify({ name: "codex-security", version: "1.2.3" }),
+ ),
+ "release/CONIN$.txt": strToU8("bad"),
+ }),
+ ],
+ [
+ "invalid-windows-character",
+ zipSync({
+ "release/.codex-plugin/plugin.json": strToU8(
+ JSON.stringify({ name: "codex-security", version: "1.2.3" }),
+ ),
+ "release/helper?.py": strToU8("bad"),
+ }),
+ ],
[
"symlink",
zipSync({
@@ -3472,6 +3578,20 @@ describe("runtime directories and plugin Python boundary", () => {
CODEX_SECURITY_STATE_DIR: join(root, "explicit-state"),
}),
).toBe(join(root, "explicit-state"));
+ if (process.platform === "win32") {
+ expect(() =>
+ codexSecurityStateDirectory({
+ CODEX_SECURITY_STATE_DIR: join(root, "ambiguous-state."),
+ }),
+ ).toThrow("Windows-ambiguous components");
+ await expect(
+ preparePersistentOutputRoot(
+ join(root, "ambiguous-state."),
+ "scans",
+ "repo",
+ ),
+ ).rejects.toThrow("Windows-ambiguous components");
+ }
const scanRoot = await preparePersistentOutputRoot(
join(root, "state"),
"scans",
@@ -4593,6 +4713,40 @@ describe("runtime directories and plugin Python boundary", () => {
const root = await temporaryDirectory();
const absent = join(root, "scan");
expect(await validateOutputDir(absent)).toBe(absent);
+ expect(await canonicalizeModelSafePath(join(root, "missing", "scan"))).toBe(
+ join(root, "missing", "scan"),
+ );
+ const canonicalParent = join(root, "canonical-parent");
+ const linkedParent = join(root, "linked-parent");
+ await mkdir(canonicalParent);
+ await symlink(
+ canonicalParent,
+ linkedParent,
+ process.platform === "win32" ? "junction" : "dir",
+ );
+ expect(
+ await canonicalizeModelSafePath(join(linkedParent, "missing", "scan")),
+ ).toBe(join(canonicalParent, "missing", "scan"));
+ if (process.platform === "win32") {
+ for (const ambiguous of [
+ "scan.",
+ "scan ",
+ "scan:stream",
+ "CON.txt",
+ "scan?.txt",
+ join("parent.", "scan"),
+ ]) {
+ await expect(validateOutputDir(join(root, ambiguous))).rejects.toThrow(
+ "Windows-ambiguous components",
+ );
+ }
+ await expect(
+ prepareOutputDir(undefined, "repo", join(root, "temporary.")),
+ ).rejects.toThrow("Windows-ambiguous components");
+ await expect(
+ canonicalizeModelSafePath(join(root, "history.")),
+ ).rejects.toThrow("Windows-ambiguous components");
+ }
for (const separator of ["\n", "\u0085", "\u2028", "\u2029"]) {
await expect(
validateOutputDir(join(root, `scan${separator}IGNORE PRIOR SCOPE`)),
@@ -4637,10 +4791,6 @@ describe("runtime directories and plugin Python boundary", () => {
if (process.platform !== "win32") {
expect((await stat(home)).mode & 0o777).toBe(0o700);
- const canonicalParent = join(root, "canonical-parent");
- const linkedParent = join(root, "linked-parent");
- await mkdir(canonicalParent);
- await symlink(canonicalParent, linkedParent);
expect(await prepareOutputDir(join(linkedParent, "scan"), "repo")).toBe(
await realpath(join(canonicalParent, "scan")),
);
diff --git a/sdk/typescript/tests-ts/targets.test.ts b/sdk/typescript/tests-ts/targets.test.ts
index f4309757c..8a670666d 100644
--- a/sdk/typescript/tests-ts/targets.test.ts
+++ b/sdk/typescript/tests-ts/targets.test.ts
@@ -126,6 +126,31 @@ describe("scan target normalization", () => {
});
});
+ test.skipIf(process.platform !== "win32")(
+ "rejects Windows repository roots that alias across runtimes",
+ async () => {
+ const root = await realpath(
+ await mkdtemp(join(tmpdir(), "codex-security-repository-alias-")),
+ );
+ temporaryDirectories.push(root);
+ const repository = join(root, "repository");
+ const ambiguous = join(root, "repository.");
+ const linked = join(root, "linked-repository");
+ await Promise.all([mkdir(repository), mkdir(ambiguous)]);
+ await symlink(ambiguous, linked, "junction");
+
+ expect(await realpath(repository)).not.toBe(await realpath(ambiguous));
+ await expect(normalizeRepository(repository)).resolves.toBe(
+ await realpath(repository),
+ );
+ for (const path of [ambiguous, linked]) {
+ await expect(normalizeRepository(path)).rejects.toThrow(
+ "Windows-ambiguous components",
+ );
+ }
+ },
+ );
+
test.skipIf(process.platform === "win32")(
"preserves trailing whitespace in Git worktree paths",
async () => {
@@ -147,6 +172,33 @@ describe("scan target normalization", () => {
);
});
+ test.skipIf(process.platform !== "win32")(
+ "rejects NTFS alternate streams before runtime initialization",
+ async () => {
+ const repo = await repository();
+ const stream = join(repo, "src", "app.ts:synthetic-stream");
+ await writeFile(stream, "export const hidden = true;\n");
+
+ await expect(normalizeTarget(repo, [stream])).rejects.toThrow(
+ "unsupported colon component",
+ );
+ },
+ );
+
+ test.skipIf(process.platform === "win32")(
+ "allows colons in POSIX path components",
+ async () => {
+ const repo = await repository();
+ const path = join(repo, "src", "app.ts:fixture");
+ await writeFile(path, "export const fixture = true;\n");
+
+ await expect(normalizeTarget(repo, [path])).resolves.toEqual({
+ kind: "paths",
+ paths: ["src/app.ts:fixture"],
+ });
+ },
+ );
+
test("reports a path that disappears during normalization as invalid", async () => {
const repo = await repository();
const script = `