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(sdk): allow parallel ChatGPT scans (#440)

soyeon-oai59f5a63da3c8
diff --git a/sdk/typescript/_bundled_plugin/.mcp.json b/sdk/typescript/_bundled_plugin/.mcp.json
index ef0dc3a21..9a4fc836e 100644
--- a/sdk/typescript/_bundled_plugin/.mcp.json
+++ b/sdk/typescript/_bundled_plugin/.mcp.json
@@ -29,6 +29,7 @@
"AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
"PYTHON",
"CODEX_SECURITY_KNOWLEDGE_BASE",
+ "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
"CODEX_SECURITY_SCAN_ROOT",
"CODEX_SECURITY_STATE_DIR",
"CODEX_SECURITY_SURFACE",
diff --git a/sdk/typescript/_bundled_plugin/scripts/deep_scan_config.py b/sdk/typescript/_bundled_plugin/scripts/deep_scan_config.py
index 87857f55a..36130417d 100644
--- a/sdk/typescript/_bundled_plugin/scripts/deep_scan_config.py
+++ b/sdk/typescript/_bundled_plugin/scripts/deep_scan_config.py
@@ -35,6 +35,9 @@ def codex_home() -> Path:
def config_path() -> Path:
+ configured = os.environ.get("CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH", "").strip()
+ if configured:
+ return Path(configured).expanduser()
return codex_home() / "codex-security" / "config.toml"
diff --git a/sdk/typescript/scripts/run-windows-ci-tests.mjs b/sdk/typescript/scripts/run-windows-ci-tests.mjs
index b65b1d373..534f9fac4 100644
--- a/sdk/typescript/scripts/run-windows-ci-tests.mjs
+++ b/sdk/typescript/scripts/run-windows-ci-tests.mjs
@@ -10,7 +10,7 @@ const tests = (await readdir(testsDirectory))
const slowApiTestNames = [
"keeps a private preflight snapshot isolated from persistent credentials",
"reuses keyring-compatible credentials across separate scan clients",
- "serializes parallel scans sharing a managed credential home",
+ "runs parallel ChatGPT scans with isolated mutable configuration",
"reuses the managed runtime when scan authentication changes",
"does not reimport ambient credentials after an explicit logout",
];
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 9f04dca44..3fde8e860 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -145,12 +145,16 @@ interface PreparedRuntime {
persistentCredentialHome?: boolean;
bootstrapWorkspace?: string;
configPath?: string;
+ deepScanConfigPath?: string;
plugin: PluginInstall;
environment: Record<string, string>;
credentialsAvailable: boolean;
effectiveConfig?: JsonObject;
}
+const DEEP_SCAN_CONFIG_PATH_ENVIRONMENT =
+ "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH";
+
export interface DeepScanOptions {
workers?: number;
subagents?: number;
@@ -537,9 +541,19 @@ export class CodexSecurity {
}
const runtimeHome = await realpath(runtime.codexHome);
requireOutputOutsideRepository(protectedRoot, runtimeHome, "runtime");
- if (mode === "deep") {
+ const sessionConfig = scanRuntimeCodexConfig(
+ effectiveConfig,
+ stateDirectory,
+ runtimeHome,
+ );
+ const deepScanConfigPath =
+ mode === "deep"
+ ? runtime.deepScanConfigPath ??
+ join(runtimeHome, "codex-security", "config.toml")
+ : undefined;
+ if (deepScanConfigPath !== undefined) {
await prepareDeepScanConfig(
- runtimeHome,
+ deepScanConfigPath,
this.#dependencies.environment,
options,
signal,
@@ -569,6 +583,10 @@ export class CodexSecurity {
? "stored_credentials"
: null;
}
+ if (mode !== "deep" || runtime.deepScanConfigPath !== undefined) {
+ await releaseCredentialHome?.();
+ releaseCredentialHome = null;
+ }
if (externalProvider === null && apiKey !== null) {
this.#runtimeCredentialSource = "api_key";
}
@@ -603,10 +621,6 @@ export class CodexSecurity {
options.auth,
modelProvider,
);
- if (authentication.method !== "stored_credentials") {
- await releaseCredentialHome?.();
- releaseCredentialHome = null;
- }
notifyObserver(
"onAuthentication",
options.onAuthentication,
@@ -983,6 +997,11 @@ export class CodexSecurity {
...(runtime.configPath === undefined
? {}
: { CODEX_SECURITY_CONFIG_PATH: runtime.configPath }),
+ ...(mode !== "deep" || runtime.deepScanConfigPath === undefined
+ ? {}
+ : {
+ [DEEP_SCAN_CONFIG_PATH_ENVIRONMENT]: runtime.deepScanConfigPath,
+ }),
...(targetPathsFile === null
? {}
: { CODEX_SECURITY_TARGET_PATHS_FILE: targetPathsFile }),
@@ -1004,8 +1023,13 @@ export class CodexSecurity {
CODEX_HOME: runtime.codexHome,
...runtimePaths,
};
- const sdkCodexConfig = { ...preflightConfig };
+ const sdkCodexConfig = { ...sessionConfig };
delete sdkCodexConfig["projects"];
+ const configuredResponsesMetadata = isRecord(
+ sdkCodexConfig["responses_api_metadata"],
+ )
+ ? sdkCodexConfig["responses_api_metadata"]
+ : {};
const codexPathOverride =
environmentValue(this.#dependencies.environment, "CODEX_CLI_PATH") ===
undefined
@@ -1022,6 +1046,7 @@ export class CodexSecurity {
default_permissions: SCAN_PERMISSION_PROFILE,
allow_login_shell: false,
responses_api_metadata: {
+ ...configuredResponsesMetadata,
codex_security_surface: this.#surface,
},
},
@@ -1417,7 +1442,7 @@ export class CodexSecurity {
// outcome the try and catch blocks already produced, so these failures are reported
// as warnings: a scan that failed has to say why it failed, not why its temporary
// files outlived it. The whole step is guarded so that a cleanup which rejects, or
- // throws synchronously, still cannot skip the credential lock release below.
+ // throws synchronously, still cannot skip a pending startup-lock release below.
try {
for (const cleanup of await Promise.allSettled([
knowledgeBase?.cleanup(),
@@ -1430,14 +1455,15 @@ export class CodexSecurity {
} catch (error) {
warnCleanupFailed(options, error);
} finally {
- // Releasing the credential home lock is not best effort, so it keeps its own
- // finally and runs even if reporting the failures above went wrong. The release
- // only marks itself done once the lock directory is gone, so a failure leaves an
- // owner.json naming this still-running process; recoverStaleCredentialHomeLock
- // then refuses to reclaim it because that pid is alive, and later scans in this
- // process wait on a lock nothing frees. Reporting success while leaving the client
- // in that state is worse than failing, so the failure is only downgraded to a
- // warning when the scan already failed and that error is the one worth keeping.
+ // The startup lock is normally released before workbench registration and Codex
+ // execution. This fallback covers failures during runtime preparation or
+ // authentication. The release only marks itself done once the lock directory is
+ // gone, so a failure leaves an owner.json naming this still-running process;
+ // recoverStaleCredentialHomeLock then refuses to reclaim it because that pid is
+ // alive, and later scans in this process wait on a lock nothing frees. Reporting
+ // success while leaving the client in that state is worse than failing, so the
+ // failure is only downgraded to a warning when the scan already failed and that
+ // error is the one worth keeping.
try {
await releaseCredentialHome?.();
} catch (error) {
@@ -1693,7 +1719,7 @@ export class CodexSecurity {
throwIfAborted(signal);
const config = await preserveCodexSecurityPluginRegistration(
runtime.codexHome,
- scanRuntimeCodexConfig(
+ sharedCredentialCodexConfig(
mergedConfig,
codexSecurityStateDirectory(environment),
runtime.codexHome,
@@ -1709,6 +1735,11 @@ export class CodexSecurity {
signal,
},
);
+ runtime.deepScanConfigPath =
+ runtime.bootstrapWorkspace !== undefined &&
+ (await pluginSupportsIsolatedDeepScanConfig(runtime.plugin.pluginRoot))
+ ? join(runtime.bootstrapWorkspace, "deep-scan-config.toml")
+ : undefined;
runtime.effectiveConfig = mergedConfig;
}
@@ -1820,7 +1851,7 @@ export class CodexSecurity {
requestedConfig ?? (await mergedCodexConfig(this.config));
const codexConfig = await preserveCodexSecurityPluginRegistration(
codexHome,
- scanRuntimeCodexConfig(
+ sharedCredentialCodexConfig(
mergedConfig,
codexSecurityStateDirectory(processEnvironment),
codexHome,
@@ -1834,6 +1865,11 @@ export class CodexSecurity {
environment: withoutCodexHome(processEnvironment),
signal,
});
+ const deepScanConfigPath = (await pluginSupportsIsolatedDeepScanConfig(
+ plugin.pluginRoot,
+ ))
+ ? join(bootstrapWorkspace, "deep-scan-config.toml")
+ : undefined;
const credentialsAvailable =
isExternalModelProvider(modelProvider) ||
modelProvider === "amazon-bedrock"
@@ -1848,6 +1884,7 @@ export class CodexSecurity {
persistentCredentialHome: true,
bootstrapWorkspace,
configPath,
+ deepScanConfigPath,
plugin,
environment: {
...withoutCodexHome(processEnvironment),
@@ -1927,7 +1964,7 @@ function deepScanOptions(options: ScanOptions): DeepScanOptions {
}
async function prepareDeepScanConfig(
- codexHome: string,
+ destination: string,
environment: ProcessEnvironment,
options: DeepScanOptions,
signal: AbortSignal,
@@ -1959,7 +1996,6 @@ async function prepareDeepScanConfig(
const value = options[name];
if (value !== undefined) overrides[key] = value;
}
- const destination = join(codexHome, "codex-security", "config.toml");
const hasOverrides = Object.keys(overrides).length > 0;
if (existing === undefined && !hasOverrides) {
if (destination !== source) {
@@ -2823,6 +2859,34 @@ export function scanRuntimeCodexConfig(
};
}
+function sharedCredentialCodexConfig(
+ config: JsonObject,
+ stateDirectory: string,
+ credentialHome: string,
+): JsonObject {
+ const shared: JsonObject = {
+ features: { plugins: true },
+ };
+ for (const key of [
+ "cli_auth_credentials_store",
+ "forced_login_method",
+ "forced_chatgpt_workspace_id",
+ ]) {
+ if (Object.hasOwn(config, key)) shared[key] = structuredClone(config[key]!);
+ }
+ const modelProvider = scanModelProvider(config);
+ if (typeof modelProvider === "string" && modelProvider.length > 0) {
+ shared["model_provider"] = modelProvider;
+ const providers = config["model_providers"];
+ if (isRecord(providers) && Object.hasOwn(providers, modelProvider)) {
+ shared["model_providers"] = {
+ [modelProvider]: structuredClone(providers[modelProvider]!),
+ };
+ }
+ }
+ return scanRuntimeCodexConfig(shared, stateDirectory, credentialHome);
+}
+
export function scanPreflightCodexConfig(config: JsonObject): JsonObject {
const safeString = (value: unknown): value is string =>
typeof value === "string" &&
@@ -2946,6 +3010,29 @@ export function scanPreflightCodexConfig(config: JsonObject): JsonObject {
return result;
}
+async function pluginSupportsIsolatedDeepScanConfig(
+ pluginRoot: string,
+): Promise<boolean> {
+ let configuration: unknown;
+ try {
+ configuration = JSON.parse(
+ await readFile(join(pluginRoot, ".mcp.json"), "utf8"),
+ );
+ } catch {
+ return false;
+ }
+ if (!isRecord(configuration)) return false;
+ const servers = configuration["mcpServers"];
+ if (!isRecord(servers)) return false;
+ const server = servers["codex-security"];
+ if (!isRecord(server)) return false;
+ const environment = server["env_vars"];
+ return (
+ Array.isArray(environment) &&
+ environment.includes(DEEP_SCAN_CONFIG_PATH_ENVIRONMENT)
+ );
+}
+
function requireOutputOutsideRepository(
repository: string,
outputDirectory: string,
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 17514bf89..a4e0fcdea 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -4048,6 +4048,9 @@ describe("CodexSecurity orchestration", () => {
shell_environment_policy: {
set: { PRIVATE_TOKEN: "RUNTIME_SHELL_SECRET" },
},
+ responses_api_metadata: {
+ request_trace: "preserve-configured-metadata",
+ },
},
},
{
@@ -4094,10 +4097,26 @@ describe("CodexSecurity orchestration", () => {
"utf8",
);
expect(options.env?.["CODEX_SECURITY_SURFACE"]).toBe("sdk");
- expect(codexConfig).toContain(
- 'model_reasoning_summary = "detailed"',
- );
- expect(codexConfig).toContain("show_raw_agent_reasoning = true");
+ expect(codexConfig).not.toContain("model_reasoning_summary");
+ expect(codexConfig).not.toContain("show_raw_agent_reasoning");
+ expect(options.config).toMatchObject({
+ model_reasoning_summary: "detailed",
+ show_raw_agent_reasoning: true,
+ windows: { sandbox: "unelevated" },
+ mcp_servers: {
+ private: {
+ command: "echo",
+ env: { PRIVATE_TOKEN: "RUNTIME_MCP_SECRET" },
+ },
+ },
+ shell_environment_policy: {
+ set: { PRIVATE_TOKEN: "RUNTIME_SHELL_SECRET" },
+ },
+ responses_api_metadata: {
+ request_trace: "preserve-configured-metadata",
+ codex_security_surface: "sdk",
+ },
+ });
if (process.platform !== "win32") {
expect((await stat(configPath!)).mode & 0o777).toBe(0o600);
}
@@ -4316,9 +4335,19 @@ describe("CodexSecurity orchestration", () => {
),
).toBe(true);
expect(existsSync(join(codexHome, "auth.json"))).toBe(false);
- expect(
- await readFile(join(codexHome, "config.toml"), "utf8"),
- ).not.toContain("synthetic-transient-key");
+ const persistentConfigText = await readFile(
+ join(codexHome, "config.toml"),
+ "utf8",
+ );
+ expect(persistentConfigText).not.toContain("synthetic-transient-key");
+ const persistentConfig = parseToml(persistentConfigText);
+ expect(persistentConfig["model"]).toBeUndefined();
+ if (provider !== undefined) {
+ expect(persistentConfig).toMatchObject({
+ model_provider: provider,
+ model_providers: { [provider]: providerConfig },
+ });
+ }
},
);
@@ -4411,7 +4440,7 @@ describe("CodexSecurity orchestration", () => {
}
});
- test("serializes parallel scans sharing a managed credential home", async () => {
+ test("runs parallel ChatGPT scans with isolated mutable configuration", async () => {
const root = await temporaryDirectory();
const repository = join(root, "repository");
const ambientHome = join(root, "ambient-codex-home");
@@ -4422,6 +4451,11 @@ describe("CodexSecurity orchestration", () => {
await writeFile(join(ambientHome, "auth.json"), "{}\n");
let activeScans = 0;
let maximumActiveScans = 0;
+ const deepScanConfigPaths = new Set<string>();
+ let releaseScans!: () => void;
+ const concurrentScans = new Promise<void>((resolve) => {
+ releaseScans = resolve;
+ });
const clients = await Promise.all(
[0, 1].map(async (index) => {
@@ -4444,33 +4478,52 @@ describe("CodexSecurity orchestration", () => {
repositoryRevision: async () => "deadbeef",
createCodex: (options: CodexOptions) => {
expect(options.env?.["CODEX_HOME"]).toBe(credentialHome);
+ const expectedModel =
+ index === 0 ? "gpt-5.6-sol" : "gpt-5.6-terra";
+ expect(options.config?.["model"]).toBe(expectedModel);
+ const deepScanConfigPath =
+ options.env?.["CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH"];
+ expect(typeof deepScanConfigPath).toBe("string");
+ deepScanConfigPaths.add(deepScanConfigPath!);
return {
startThread: () => ({
id: null,
async runStreamed() {
+ expect(
+ existsSync(
+ join(credentialHome, ".codex-security-scan.lock"),
+ ),
+ ).toBe(false);
activeScans += 1;
maximumActiveScans = Math.max(
maximumActiveScans,
activeScans,
);
+ if (activeScans === 2) releaseScans();
try {
- const expectedModel =
- index === 0 ? "gpt-5.6-sol" : "gpt-5.6-terra";
- const before = parseToml(
+ const credentialConfig = parseToml(
await readFile(
join(credentialHome, "config.toml"),
"utf8",
),
);
- expect(before["model"]).toBe(expectedModel);
- await new Promise((resolve) => setTimeout(resolve, 40));
+ expect(credentialConfig["model"]).toBeUndefined();
+ const before = parseToml(
+ await readFile(deepScanConfigPath!, "utf8"),
+ );
+ expect(before["deep_scan"]).toMatchObject({
+ workers: index + 2,
+ });
+ await Promise.race([
+ concurrentScans,
+ new Promise((resolve) => setTimeout(resolve, 5_000)),
+ ]);
const after = parseToml(
- await readFile(
- join(credentialHome, "config.toml"),
- "utf8",
- ),
+ await readFile(deepScanConfigPath!, "utf8"),
);
- expect(after["model"]).toBe(expectedModel);
+ expect(after["deep_scan"]).toMatchObject({
+ workers: index + 2,
+ });
throw new Error("parallel managed scan reached");
} finally {
activeScans -= 1;
@@ -4485,21 +4538,102 @@ describe("CodexSecurity orchestration", () => {
);
try {
- await Promise.all(
- clients.map(
- async (client) =>
- await expect(client.run(repository)).rejects.toThrow(
- "parallel managed scan reached",
- ),
+ const results = await Promise.allSettled(
+ clients.map((client, index) =>
+ client.run(repository, { mode: "deep", workers: index + 2 }),
),
);
+ for (const result of results) {
+ expect(result).toMatchObject({
+ status: "rejected",
+ reason: expect.objectContaining({
+ message: "parallel managed scan reached",
+ }),
+ });
+ }
expect(existsSync(credentialHome)).toBe(true);
- expect(maximumActiveScans).toBe(1);
+ expect(maximumActiveScans).toBe(2);
+ expect(deepScanConfigPaths.size).toBe(2);
+ const pluginConfiguration = JSON.parse(
+ await readFile(join(PLUGIN_ROOT, ".mcp.json"), "utf8"),
+ ) as { mcpServers: Record<string, { env_vars: string[] }> };
+ expect(
+ pluginConfiguration.mcpServers["codex-security"]?.env_vars.includes(
+ "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
+ ),
+ ).toBe(true);
} finally {
await Promise.all(clients.map(async (client) => await client.close()));
}
});
+ test("keeps legacy custom-plugin Deep Scan settings under the credential lock", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const ambientHome = join(root, "ambient-codex-home");
+ const stateDirectory = join(root, "state");
+ const credentialHome = join(stateDirectory, "codex-home");
+ const legacyPlugin = join(root, "legacy-plugin");
+ const scanDir = join(root, "scan");
+ await mkdir(repository);
+ await mkdir(ambientHome);
+ await mkdir(scanDir, { mode: 0o700 });
+ await writeFile(join(ambientHome, "auth.json"), "{}\n");
+ await cp(PLUGIN_ROOT, legacyPlugin, { recursive: true });
+ const mcpPath = join(legacyPlugin, ".mcp.json");
+ const mcpConfiguration = JSON.parse(await readFile(mcpPath, "utf8")) as {
+ mcpServers: Record<string, { env_vars: string[] }>;
+ };
+ const server = mcpConfiguration.mcpServers["codex-security"]!;
+ server.env_vars = server.env_vars.filter(
+ (name) => name !== "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
+ );
+ await writeFile(mcpPath, `${JSON.stringify(mcpConfiguration, null, 2)}\n`);
+
+ const client = new TestClient(
+ { pluginPath: legacyPlugin },
+ {
+ environment: {
+ CODEX_HOME: ambientHome,
+ CODEX_SECURITY_STATE_DIR: stateDirectory,
+ },
+ resolvePluginPython: async () => "/managed/python",
+ prepareOutputDir: async () => scanDir,
+ repositoryRevision: async () => "deadbeef",
+ createCodex: (options: CodexOptions) => ({
+ startThread: () => ({
+ id: null,
+ async runStreamed() {
+ expect(
+ options.env?.["CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH"],
+ ).toBeUndefined();
+ expect(
+ existsSync(join(credentialHome, ".codex-security-scan.lock")),
+ ).toBe(true);
+ expect(
+ parseToml(
+ await readFile(
+ join(credentialHome, "codex-security", "config.toml"),
+ "utf8",
+ ),
+ )["deep_scan"],
+ ).toMatchObject({ workers: 7 });
+ throw new Error("legacy custom plugin scan reached");
+ },
+ }),
+ }),
+ },
+ );
+
+ try {
+ await expect(
+ client.run(repository, { mode: "deep", workers: 7 }),
+ ).rejects.toThrow("legacy custom plugin scan reached");
+ } finally {
+ await client.close();
+ }
+ });
+
test("rejects a shell-visible plugin root inside CODEX_HOME", async () => {
const root = await temporaryDirectory();
const repository = join(root, "repository");
diff --git a/sdk/typescript/tests-ts/deep-scan-workbench.test.ts b/sdk/typescript/tests-ts/deep-scan-workbench.test.ts
index a4902f028..b4a0469c8 100644
--- a/sdk/typescript/tests-ts/deep-scan-workbench.test.ts
+++ b/sdk/typescript/tests-ts/deep-scan-workbench.test.ts
@@ -7,7 +7,7 @@ import {
writeFile,
} from "node:fs/promises";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
import { afterEach, describe, expect, test } from "bun:test";
import { PLUGIN_ROOT } from "./plugin-root.js";
@@ -194,6 +194,46 @@ describe("deep scan workbench ownership", () => {
},
);
+ test("loads an explicitly isolated Deep Scan configuration", async () => {
+ const root = await realpath(
+ await mkdtemp(join(tmpdir(), "codex-security-deep-isolated-config-")),
+ );
+ temporaryDirectories.push(root);
+ const codexHome = join(root, "codex-home");
+ const sharedConfig = join(codexHome, "codex-security", "config.toml");
+ const isolatedConfig = join(root, "isolated-deep-scan.toml");
+ await mkdir(dirname(sharedConfig), { recursive: true });
+ await writeFile(sharedConfig, "[deep_scan]\nworkers = 2\n");
+ await writeFile(isolatedConfig, "[deep_scan]\nworkers = 7\n");
+ const python = Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+
+ const result = Bun.spawnSync(
+ [
+ python!,
+ "-I",
+ "-B",
+ join(PLUGIN_ROOT, "scripts", "deep_scan_config.py"),
+ "--available-parallelism",
+ "8",
+ ],
+ {
+ env: {
+ ...process.env,
+ CODEX_HOME: codexHome,
+ CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH: isolatedConfig,
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ },
+ );
+
+ expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
+ expect(JSON.parse(new TextDecoder().decode(result.stdout))).toMatchObject({
+ workers: 7,
+ });
+ });
+
test("rejects invalid discovery deadlines before returning scan configuration", async () => {
const root = await realpath(
await mkdtemp(join(tmpdir(), "codex-security-deep-invalid-deadline-")),