OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
import { nodeCommand } from "./support/shell.js";
import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import { join, resolve } from "node:path";
import { afterEach, describe, expect, test } from "bun:test";
import { parse } from "smol-toml";
import { scanRuntimeCodexConfig } from "../src/api.js";
import {
type JsonObject,
inlineToml,
quoteTomlString,
modelProviderConfigOverride,
resolveCodexProfile,
resolveCommandAuthConfig,
scanPricingContext,
scanModelConfiguration,
scanModelProvider,
} from "../src/config.js";
import {
ConfigurationError,
DEFAULT_CODEX_CONFIG,
mergedCodexConfig,
writeCodexConfig,
} from "../src/index.js";
import {
prepareCodexSecurityCredentialHome,
prepareOutputDir,
requireSecureCredentialHome,
resolveCodexCommand,
} from "../src/runtime.js";
import { PLUGIN_ROOT } from "./plugin-root.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures(
"codex-security-config-",
false,
);
let sandboxFixtureUsed = false;
afterEach(async () => {
if (sandboxFixtureUsed) {
await waitForWindowsSandboxSetup();
sandboxFixtureUsed = false;
}
await cleanup();
});
test("inline Codex overrides preserve literal keys and string values", () => {
const metadata = {
"literal.key": "value.with.dots",
'quote"slash\\雪': 'quote"slash\\雪',
"control\u007fkey": "control\u0000\b\t\n\f\r\u007fvalue",
};
expect(parse(`responses_api_metadata=${inlineToml(metadata)}`)).toEqual({
responses_api_metadata: metadata,
});
expect(
parse(
`permissions=${inlineToml({
review: { filesystem: { "path.with.dots/雪\u007f": "deny" } },
})}`,
),
).toEqual({
permissions: {
review: { filesystem: { "path.with.dots/雪\u007f": "deny" } },
},
});
for (const value of ["\ud800", "\udc00"]) {
expect(() => parse(`model=${quoteTomlString(value)}`)).toThrow();
expect(() =>
parse(`metadata=${inlineToml({ [value]: "literal" })}`),
).toThrow();
}
});
test.each([
["absent", undefined],
["null", null],
])(
"omits an optional %s profile selector before native configuration",
async (_name, profile) => {
const config = await mergedCodexConfig({
codexOverrides: {
...(profile === undefined ? {} : { profile }),
model: "synthetic-selected-model",
},
});
expect(resolveCodexProfile(config)).toMatchObject({
model: "synthetic-selected-model",
});
expect(resolveCodexProfile(config)).not.toHaveProperty("profile");
},
);
test("inline Codex overrides omit optional null fields like the file writer", async () => {
for (const value of [null, { args: ["fixture", null] }]) {
expect(() => inlineToml(value)).toThrow(ConfigurationError);
}
expect(modelProviderConfigOverride({ model_providers: null })).toEqual([]);
const provider = {
fixture: {
auth: { command: "synthetic-helper", args: null },
enabled: true,
},
};
const root = await temporaryDirectory();
const config = await mergedCodexConfig({
codexOverrides: { model_providers: provider },
});
const path = join(root, "config.toml");
await writeCodexConfig(path, config);
const written = parse(await readFile(path, "utf8"));
expect(
parse(`model_providers = ${inlineToml(provider)}`)["model_providers"],
).toEqual(written["model_providers"]);
expect(written["model_providers"]).toEqual({
fixture: { auth: { command: "synthetic-helper" }, enabled: true },
});
});
function runPinnedCodex(
codexHome: string,
arguments_: readonly string[],
overrides: NodeJS.ProcessEnv = {},
) {
const node = Bun.which("node");
if (node === null) {
throw new Error("The pinned Codex CLI requires Node.js.");
}
const environment: NodeJS.ProcessEnv = {
...process.env,
...overrides,
CODEX_HOME: codexHome,
};
delete environment["OPENAI_API_KEY"];
delete environment["CODEX_API_KEY"];
return Bun.spawnSync(
[
node,
join(
import.meta.dir,
"..",
"node_modules",
"@openai",
"codex",
"bin",
"codex.js",
),
...arguments_,
],
{
env: environment,
stdout: "pipe",
stderr: "pipe",
},
);
}
function macOsSandboxUnavailable(): boolean {
if (process.platform !== "darwin") return false;
// Check the host independently of the generated scan permission profile.
const result = Bun.spawnSync(
[
"/usr/bin/sandbox-exec",
"-p",
"(version 1) (allow default)",
"/usr/bin/true",
],
{ stdout: "pipe", stderr: "pipe" },
);
return (
result.exitCode !== 0 &&
new TextDecoder().decode(result.stderr).trim() ===
"sandbox-exec: sandbox_apply: Operation not permitted"
);
}
function shouldScheduleNativeSandboxTests(
platform: NodeJS.Platform,
environment: NodeJS.ProcessEnv,
): boolean {
if (platform !== "win32") return true;
const setting =
environment["CODEX_SECURITY_TEST_WINDOWS_SANDBOX"]?.toLowerCase();
if (setting === "1" || setting === "true") return true;
if (setting === "0" || setting === "false") return false;
return (
environment["GITHUB_ACTIONS"] === "true" &&
environment["RUNNER_ENVIRONMENT"] === "github-hosted"
);
}
const skipNativeSandboxTests =
!shouldScheduleNativeSandboxTests(process.platform, process.env) ||
macOsSandboxUnavailable();
describe("native sandbox test scheduling", () => {
const local = { CODEX_SECURITY_ALLOW_MACHINE_POLICY_TEST: "false" };
const hosted = {
...local,
GITHUB_ACTIONS: "true",
RUNNER_ENVIRONMENT: "github-hosted",
};
const setting = "CODEX_SECURITY_TEST_WINDOWS_SANDBOX";
const onWindows = (env: NodeJS.ProcessEnv) =>
shouldScheduleNativeSandboxTests("win32", env);
test("defaults Windows coverage to GitHub-hosted Actions runners", () => {
expect(onWindows(local)).toBe(false);
expect(onWindows(hosted)).toBe(true);
expect(onWindows({ ...hosted, [setting]: "" })).toBe(true);
expect(onWindows({ RUNNER_ENVIRONMENT: "github-hosted" })).toBe(false);
expect(onWindows({ ...hosted, RUNNER_ENVIRONMENT: "self-hosted" })).toBe(
false,
);
});
test.each(["1", "true", "True"])(
"opts into local Windows coverage with %s",
(value) => {
expect(onWindows({ ...local, [setting]: value })).toBe(true);
},
);
test.each(["0", "false"])(
"opts out of hosted Windows coverage with %s",
(value) => {
expect(onWindows({ ...hosted, [setting]: value })).toBe(false);
},
);
test.each(["darwin", "linux"] as const)(
"ignores the Windows setting on %s",
(platform) => {
expect(
shouldScheduleNativeSandboxTests(platform, { [setting]: "false" }),
).toBe(true);
},
);
});
async function sandboxFailureDetails(codexHome: string, details: string) {
if (process.platform !== "win32") return details;
const directory = join(codexHome, ".sandbox");
try {
for (const name of (await readdir(directory)).sort()) {
if (/^sandbox\.\d{4}-\d{2}-\d{2}\.log$/u.test(name)) {
details += `\n${name}:\n${await readFile(join(directory, name), "utf8")}`;
}
}
} catch (error) {
details += `\nCould not read native sandbox logs: ${String(error)}`;
}
return details;
}
async function waitForWindowsSandboxSetup() {
if (process.platform !== "win32") return;
// Codex applies read ACLs in a background worker shared across Codex homes.
// Finish that work before deleting its fixture or creating another workspace.
const result = Bun.spawnSync(
[
join(
process.env["SystemRoot"] ?? "C:\\Windows",
"System32",
"WindowsPowerShell",
"v1.0",
"powershell.exe",
),
"-NoLogo",
"-NoProfile",
"-NonInteractive",
"-Command",
`
$ErrorActionPreference = 'Stop'
try {
$mutex = [System.Threading.Mutex]::OpenExisting('Local\\CodexSandboxReadAcl')
} catch [System.Threading.WaitHandleCannotBeOpenedException] {
exit 0
}
try {
if (-not $mutex.WaitOne(30000)) {
throw 'Codex sandbox read ACL setup did not finish within 30 seconds'
}
$mutex.ReleaseMutex()
} finally {
$mutex.Dispose()
}`,
],
{ stdout: "pipe", stderr: "pipe" },
);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
}
async function scanSandboxFixture() {
await waitForWindowsSandboxSetup();
sandboxFixtureUsed = true;
const root = await temporaryDirectory();
const stateDirectory = join(root, "state");
const codexHome = await prepareCodexSecurityCredentialHome({
CODEX_SECURITY_STATE_DIR: stateDirectory,
});
const workspace = join(stateDirectory, "scans", "workspace");
const temporary = join(root, "temp");
await Promise.all([
prepareOutputDir(workspace, "sandbox-fixture"),
mkdir(temporary, { recursive: true }),
]);
await writeCodexConfig(
join(codexHome, "config.toml"),
scanRuntimeCodexConfig(await mergedCodexConfig({}), codexHome),
);
return {
root,
codexHome,
stateDirectory,
workspace,
// Native sandbox temp grants must not cover the credential-home ancestry.
environment: { TEMP: temporary, TMP: temporary, TMPDIR: temporary },
};
}
describe("Codex configuration", () => {
test("automatically reviews scan execution approvals by default", async () => {
expect(await mergedCodexConfig({})).toMatchObject({
approval_policy: "on-request",
approvals_reviewer: "auto_review",
});
});
test("lets Codex honor native and managed credential storage", async () => {
expect(DEFAULT_CODEX_CONFIG["cli_auth_credentials_store"]).toBe("auto");
expect((await mergedCodexConfig({}))["cli_auth_credentials_store"]).toBe(
"auto",
);
});
test("uses the sign-in settings from the user's Codex config below explicit overrides", async () => {
const home = await temporaryDirectory();
expect(
(await mergedCodexConfig({}, home))["cli_auth_credentials_store"],
).toBe("auto");
await writeFile(
join(home, "config.toml"),
[
'cli_auth_credentials_store = "file"',
'forced_login_method = "chatgpt"',
'model = "ambient-model"',
].join("\n"),
);
const config = await mergedCodexConfig({}, home);
expect(config).toMatchObject({
cli_auth_credentials_store: "file",
forced_login_method: "chatgpt",
});
expect(config["model"]).toBe(DEFAULT_CODEX_CONFIG["model"]);
expect(
(
await mergedCodexConfig(
{ codexOverrides: { cli_auth_credentials_store: "keyring" } },
home,
)
)["cli_auth_credentials_store"],
).toBe("keyring");
});
test("resolves selected profile model and effort before root settings", async () => {
const scenarios = [
{
overrides: {
profile: "review",
model: "gpt-5.6-sol",
model_reasoning_effort: "low",
profiles: {
review: {
model: "gpt-5.6-terra",
model_reasoning_effort: "high",
},
},
},
expected: { model: "gpt-5.6-terra", reasoningEffort: "high" },
},
{
overrides: {
profile: "review",
model_reasoning_effort: "low",
profiles: { review: { model: "gpt-5.6-terra" } },
},
expected: { model: "gpt-5.6-terra", reasoningEffort: "low" },
},
{
overrides: {
profile: "review",
model: "gpt-5.6-terra",
profiles: { review: { model_reasoning_effort: "medium" } },
},
expected: { model: "gpt-5.6-terra", reasoningEffort: "medium" },
},
] as const;
for (const scenario of scenarios) {
const config = await mergedCodexConfig({
codexOverrides: scenario.overrides,
});
expect(scanModelConfiguration(config)).toEqual(scenario.expected);
}
});
test("loads a native profile below explicit scan overrides", async () => {
const home = await temporaryDirectory();
await writeFile(
join(home, "review.config.toml"),
'model = "profile-model"\nmodel_reasoning_effort = "high"\nmodel_provider = "synthetic"\n',
);
const config = await mergedCodexConfig(
{
codexOverrides: {
profile: "review",
model: "explicit-model",
},
},
home,
);
expect(scanModelConfiguration(config)).toEqual({
model: "explicit-model",
reasoningEffort: "high",
});
expect(scanModelProvider(config)).toBe("synthetic");
expect(resolveCodexProfile(config)).not.toHaveProperty("profile");
});
test.each(
[
"model_instructions_file",
"experimental_compact_prompt_file",
"model_catalog_json",
"sqlite_home",
"log_dir",
].flatMap((key) =>
[undefined, "explicit.md"].map((explicit) => ({ key, explicit })),
),
)(
"resolves file-profile paths before explicit overrides: %j",
async ({ key, explicit }) => {
const home = await temporaryDirectory();
await writeFile(
join(home, "review.config.toml"),
`${key} = "instructions.md"\n`,
);
const overrides = {
profile: "review",
...(explicit === undefined ? {} : { [key]: explicit }),
};
const config = await mergedCodexConfig(
{ codexOverrides: overrides },
home,
);
expect(config[key]).toBe(explicit ?? join(home, "instructions.md"));
expect(overrides).toEqual({
profile: "review",
...(explicit === undefined ? {} : { [key]: explicit }),
});
},
);
test.each([undefined, "explicit.toml"])(
"resolves file-profile agent paths before explicit overrides: %j",
async (explicit) => {
const home = await temporaryDirectory();
await writeFile(
join(home, "review.config.toml"),
'[agents.reviewer]\ndescription = "Synthetic reviewer"\nconfig_file = "agents/reviewer.toml"\n',
);
const overrides = {
profile: "review",
...(explicit === undefined
? {}
: { agents: { reviewer: { config_file: explicit } } }),
};
const config = await mergedCodexConfig(
{ codexOverrides: overrides },
home,
);
expect(config["agents"]).toMatchObject({
reviewer: {
description: "Synthetic reviewer",
config_file: explicit ?? join(home, "agents/reviewer.toml"),
},
});
expect(overrides).toEqual({
profile: "review",
...(explicit === undefined
? {}
: { agents: { reviewer: { config_file: explicit } } }),
});
},
);
test.each([undefined, "explicit/SKILL.md", "~/native/SKILL.md"])(
"preserves native skill path origins before explicit overrides (%s)",
async (explicit) => {
const home = await temporaryDirectory("codex-security-skill-profile-");
await writeFile(
join(home, "review.config.toml"),
'[[skills.config]]\npath="skill/SKILL.md"\nenabled=false\n',
);
const config = await mergedCodexConfig(
{
codexOverrides: {
profile: "review",
...(explicit === undefined
? {}
: { skills: { config: [{ path: explicit, enabled: true }] } }),
},
},
home,
);
expect(config["skills"]).toEqual({
config: [
{
path: explicit ?? join(home, "skill/SKILL.md"),
enabled: explicit !== undefined,
},
],
});
},
);
test("validates effective native multi-agent settings after file overrides", async () => {
const home = await temporaryDirectory();
await writeFile(
join(home, "review.config.toml"),
"[features.multi_agent_v2]\nenabled = false\n",
);
await expect(
mergedCodexConfig({ codexOverrides: { profile: "review" } }, home),
).rejects.toThrow("cannot be disabled");
await expect(
mergedCodexConfig(
{
codexOverrides: {
profile: "review",
features: { multi_agent_v2: { enabled: true } },
},
},
home,
),
).resolves.toMatchObject({
features: { multi_agent_v2: { enabled: true } },
});
});
test.each(
["exporter", "trace_exporter", "metrics_exporter"].flatMap((exporter) =>
["otlp-http", "otlp-grpc"].flatMap((protocol) =>
[undefined, "explicit-client.key", "~/native/client.key"].map(
(explicit) => ({
exporter,
protocol,
explicit,
}),
),
),
),
)(
"preserves OTEL file origins before explicit TLS overrides: %j",
async ({ exporter, protocol, explicit }) => {
const home = await temporaryDirectory();
const paths = {
"ca-certificate": "tls/ca.pem",
"client-certificate": "tls/client.pem",
"client-private-key": "tls/client.key",
};
await writeFile(
join(home, "review.config.toml"),
`[otel.${exporter}.${protocol}.tls]\n` +
Object.entries(paths)
.map(([key, value]) => `${key}=${JSON.stringify(value)}\n`)
.join(""),
);
const overrides = {
profile: "review",
...(explicit === undefined
? {}
: {
otel: {
[exporter]: {
[protocol]: { tls: { "client-private-key": explicit } },
},
},
}),
};
const original = structuredClone(overrides);
const config = await mergedCodexConfig(
{ codexOverrides: overrides },
home,
);
expect(config["otel"]).toEqual({
[exporter]: {
[protocol]: {
tls: {
"ca-certificate": join(home, paths["ca-certificate"]),
"client-certificate": join(home, paths["client-certificate"]),
"client-private-key":
explicit ?? join(home, paths["client-private-key"]),
},
},
},
});
expect(overrides).toEqual(original);
},
);
test.each([undefined, "other helpers", "~/helpers"])(
"retains inherited command auth cwd unless the profile overrides it: %s",
async (cwd) => {
const home = await temporaryDirectory();
const config: JsonObject = {
profile: "review",
model_provider: "synthetic",
model_providers: {
synthetic: {
auth: {
command: "./token",
cwd: "helpers",
refresh_interval_ms: 1000,
},
},
},
profiles: {
review: {
model_providers: {
synthetic: {
auth: {
refresh_interval_ms: 2000,
...(cwd === undefined ? {} : { cwd }),
},
},
},
},
},
};
const saved = structuredClone(config);
expect(
resolveCodexProfile(resolveCommandAuthConfig(config, home)),
).toMatchObject({
model_providers: {
synthetic: {
auth: {
command: "./token",
cwd: cwd?.startsWith("~") ? cwd : join(home, cwd ?? "helpers"),
refresh_interval_ms: 2000,
},
},
},
});
expect(config).toEqual(saved);
},
);
test("rejects invalid native profile names and owned settings", async () => {
const home = await temporaryDirectory();
await writeFile(
join(home, "review.config.toml"),
"[features]\nplugins = false\n",
);
await expect(
mergedCodexConfig({ codexOverrides: { profile: "../review" } }, home),
).rejects.toThrow("plain name");
await expect(
mergedCodexConfig({ codexOverrides: { profile: "review" } }, home),
).rejects.toThrow("owns plugin loading configuration");
});
test("ignores model overrides from unselected Codex profiles", async () => {
const config = await mergedCodexConfig({
codexOverrides: {
profile: "missing",
model: "gpt-5.6-sol",
model_reasoning_effort: "low",
profiles: {
other: {
model: "gpt-5.6-terra",
model_reasoning_effort: "high",
},
},
},
});
expect(scanModelConfiguration(config)).toEqual({
model: "gpt-5.6-sol",
reasoningEffort: "low",
});
});
test("resolves the selected profile's provider before the root provider", async () => {
for (const [overrides, expected] of [
[
{
profile: "bedrock",
model_provider: "openai",
profiles: {
bedrock: { model_provider: "amazon-bedrock" },
},
},
"amazon-bedrock",
],
[
{
profile: "bedrock",
model_provider: "amazon-bedrock",
profiles: { bedrock: { model: "openai.gpt-5.6-luna" } },
},
"amazon-bedrock",
],
[
{
profile: "missing",
model_provider: "openai",
profiles: { bedrock: { model_provider: "amazon-bedrock" } },
},
"openai",
],
[{}, undefined],
] as const) {
const config = await mergedCodexConfig({ codexOverrides: overrides });
expect(scanModelProvider(config)).toBe(expected);
}
});
test.each(["amazon-bedrock", "amazon-bedrock-runtime"])(
"uses the selected %s provider's AWS region before the environment",
(provider) => {
const config = {
profile: "gov",
model_provider: "openai",
model_providers: { [provider]: { aws: { region: "us-east-2" } } },
profiles: {
gov: {
model_provider: provider,
model_providers: {
[provider]: { aws: { region: " us-gov-east-1 " } },
},
},
},
};
expect(scanPricingContext(config, { AWS_REGION: "us-west-1" })).toEqual({
provider: "amazon-bedrock",
region: "us-gov-east-1",
});
},
);
test("resolves Bedrock environment regions and preserves an unknown region", () => {
const config = { model_provider: "amazon-bedrock" };
const environment = {
AWS_REGION: "us-gov-west-1",
AWS_DEFAULT_REGION: "us-east-1",
};
expect(scanPricingContext(config, environment)).toEqual({
provider: "amazon-bedrock",
region: "us-gov-west-1",
});
expect(
scanPricingContext(config, { ...environment, AWS_REGION: " " }),
).toEqual({ provider: "amazon-bedrock", region: "us-east-1" });
expect(scanPricingContext(config, { AWS_PROFILE: "synthetic" })).toEqual({
provider: "amazon-bedrock",
region: null,
});
expect(
scanPricingContext({ model_provider: "openai" }, environment),
).toBeUndefined();
});
test.each([
["https://bedrock-mantle.us-gov-east-1.api.aws/openai/v1", "us-gov-east-1"],
[
"https://bedrock-runtime-fips.us-gov-west-1.amazonaws.com",
"us-gov-west-1",
],
["https://gateway.example.test", null],
])(
"uses the billing region from a Bedrock endpoint override %s",
(baseUrl, region) => {
const config = {
model_provider: "amazon-bedrock",
model_providers: {
"amazon-bedrock": { base_url: baseUrl, aws: { region: "us-east-1" } },
},
};
expect(scanPricingContext(config, { AWS_REGION: "us-west-2" })).toEqual({
provider: "amazon-bedrock",
region,
});
},
);
test("distinguishes managed Vertex APIs from dedicated endpoints and other gateways", () => {
const base =
"https://us-central1-aiplatform.googleapis.com/v1beta1/projects/example/locations/us-central1";
const fromUrl = (baseUrl: string) =>
scanPricingContext({ openai_base_url: baseUrl }, {});
expect(fromUrl(`${base}/endpoints/openapi`)).toEqual({
provider: "gcp",
managedEndpoint: true,
});
expect(fromUrl(`${base}/endpoints/1234`)).toEqual({
provider: "gcp",
managedEndpoint: false,
});
expect(
fromUrl("https://123.us-central1-example.prediction.vertexai.goog"),
).toEqual({ provider: "gcp", managedEndpoint: false });
expect(
fromUrl(
"https://aiplatform.mtls.googleapis.com./v1/projects/example/locations/global/endpoints/openapi",
),
).toEqual({ provider: "gcp", managedEndpoint: true });
expect(fromUrl("https://gateway.example.test")).toBeUndefined();
expect(
scanPricingContext(
{ model_providers: { openai: { base_url: base } } },
{ OPENAI_BASE_URL: base },
),
).toBeUndefined();
const config = {
profile: "review",
profiles: {
review: {
model_provider: "vertex",
model_providers: {
vertex: {
base_url:
"https://aiplatform.googleapis.com/v1/projects/example/locations/global/publishers/openai/v1/",
},
},
},
},
};
expect(scanPricingContext(config, {})).toEqual({
provider: "gcp",
managedEndpoint: true,
});
expect(
scanPricingContext(
{
model_provider: "gcp",
model_providers: {
gcp: { base_url: "https://gateway.example.test" },
},
},
{},
),
).toEqual({ provider: "gcp", managedEndpoint: false });
});
test("rejects invalid model settings from the selected Codex profile", async () => {
for (const [profile, message] of [
[{ model: " " }, "model must be a nonempty string"],
[{ model: 12 }, "model must be a nonempty string"],
[
{ model_reasoning_effort: " " },
"reasoning effort must be a nonempty string",
],
[
{ model_reasoning_effort: false },
"reasoning effort must be a nonempty string",
],
] as const) {
const config = await mergedCodexConfig({
codexOverrides: { profile: "review", profiles: { review: profile } },
});
expect(() => scanModelConfiguration(config)).toThrow(message);
}
});
test("still requires root model and effort when the profile omits them", async () => {
for (const field of ["model", "model_reasoning_effort"]) {
const config = await mergedCodexConfig({
codexOverrides: {
[field]: null,
profile: "review",
profiles: { review: { model: null, model_reasoning_effort: null } },
},
});
expect(() => scanModelConfiguration(config)).toThrow(ConfigurationError);
}
});
test("disables reasoning summaries by default for the selected Bedrock provider", async () => {
const scenarios: JsonObject[] = [
{ model_provider: "amazon-bedrock" },
{
model_provider: "openai",
profile: "cloud",
profiles: { cloud: { model_provider: "amazon-bedrock" } },
},
{
model_provider: "amazon-bedrock",
profile: "cloud",
profiles: { cloud: { model: "openai.gpt-5.6-luna" } },
},
];
for (const overrides of scenarios) {
const config = await mergedCodexConfig({ codexOverrides: overrides });
expect(resolveCodexProfile(config)).toMatchObject({
model_reasoning_summary: "none",
model_reasoning_effort: "xhigh",
});
}
});
test("keeps reasoning summaries when the selected provider is not Bedrock", async () => {
const scenarios: JsonObject[] = [
{
model_provider: "amazon-bedrock",
profile: "direct",
profiles: { direct: { model_provider: "openai" } },
},
{
model_provider: "openai",
profiles: { cloud: { model_provider: "amazon-bedrock" } },
},
];
for (const overrides of scenarios) {
const config = await mergedCodexConfig({ codexOverrides: overrides });
expect(resolveCodexProfile(config)["model_reasoning_summary"]).toBe(
"detailed",
);
}
});
test("preserves explicit Bedrock reasoning summary settings", async () => {
for (const [overrides, expected] of [
[
{ model_provider: "amazon-bedrock", model_reasoning_summary: "auto" },
"auto",
],
[
{
model_reasoning_summary: "concise",
profile: "cloud",
profiles: { cloud: { model_provider: "amazon-bedrock" } },
},
"concise",
],
[
{
model_provider: "amazon-bedrock",
model_reasoning_summary: "none",
profile: "cloud",
profiles: { cloud: { model_reasoning_summary: "detailed" } },
},
"detailed",
],
] as const) {
const config = await mergedCodexConfig({ codexOverrides: overrides });
expect(resolveCodexProfile(config)["model_reasoning_summary"]).toBe(
expected,
);
}
});
test("deep-merges native multi-agent v2 defaults", async () => {
const merged = await mergedCodexConfig({
codexOverrides: {
features: { multi_agent_v2: { max_concurrent_threads_per_session: 4 } },
model_reasoning_effort: "high",
model_reasoning_summary: "concise",
show_raw_agent_reasoning: false,
windows: { sandbox: "elevated" },
},
});
expect(merged["features"]).toEqual({
plugins: true,
goals: true,
multi_agent_v2: {
enabled: true,
max_concurrent_threads_per_session: 4,
},
});
expect(merged["agents"]).toBeUndefined();
expect(merged["model"]).toBe("gpt-5.6-sol");
expect(merged["model_reasoning_effort"]).toBe("high");
expect(merged["model_reasoning_summary"]).toBe("concise");
expect(merged["show_raw_agent_reasoning"]).toBe(false);
expect(merged["windows"]).toEqual({ sandbox: "elevated" });
});
test.each<{ name: string; overrides: JsonObject; expected: object }>([
{
name: "preserves legacy elevated Windows sandbox overrides",
overrides: {
features: { elevated_windows_sandbox: true },
},
expected: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "elevated" },
},
},
{
name: "projects legacy elevated Windows overrides into selected profiles",
overrides: {
profile: "elevated",
profiles: {
elevated: {
features: { elevated_windows_sandbox: true },
},
},
},
expected: {
windows: { sandbox: "elevated" },
profiles: {
elevated: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "elevated" },
},
},
},
},
{
name: "allows selected profiles to override root elevated sandbox defaults",
overrides: {
features: { elevated_windows_sandbox: true },
profile: "restricted",
profiles: {
restricted: {
features: { elevated_windows_sandbox: false },
},
},
},
expected: {
windows: { sandbox: "elevated" },
profiles: {
restricted: {
features: { elevated_windows_sandbox: false },
windows: { sandbox: "unelevated" },
},
},
},
},
{
name: "gives profile-local Windows sandbox overrides precedence",
overrides: {
profile: "restricted",
profiles: {
restricted: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "unelevated" },
},
},
},
expected: {
profiles: {
restricted: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "unelevated" },
},
},
},
},
{
name: "gives explicit Windows sandbox overrides precedence",
overrides: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "unelevated" },
},
expected: {
features: { elevated_windows_sandbox: true },
windows: { sandbox: "unelevated" },
},
},
])("$name", async ({ overrides, expected }) => {
const merged = await mergedCodexConfig({ codexOverrides: overrides });
expect(merged).toMatchObject(expected);
});
test("retains the Windows sandbox in the hardened scan profile", async () => {
const merged = await mergedCodexConfig({});
expect(scanRuntimeCodexConfig(merged)).toMatchObject({
windows: { sandbox: "elevated" },
default_permissions: "codex_security_scan",
permissions: {
codex_security_scan: {
filesystem: {
":root": "read",
":workspace_roots": "write",
},
},
},
});
});
test("writes scan permissions accepted by the pinned Codex CLI", async () => {
const { codexHome, workspace, environment } = await scanSandboxFixture();
const result = runPinnedCodex(
codexHome,
["--cd", workspace, "features", "list"],
environment,
);
expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
expect(result.stdout.length).toBeGreaterThan(0);
});
test.skipIf(skipNativeSandboxTests)(
"allows scan helpers to write workspace files without writable credential ancestry",
async () => {
const { root, codexHome, stateDirectory, workspace, environment } =
await scanSandboxFixture();
const node = Bun.which("node");
expect(node).not.toBeNull();
const attemptWrite = (path: string) =>
runPinnedCodex(
codexHome,
[
"sandbox",
"--config",
"permissions.codex_security_scan.network.enabled=true",
"--permission-profile",
"codex_security_scan",
"--cd",
workspace,
node!,
"-e",
"require('node:fs').writeFileSync(process.argv[1], 'probe')",
path,
],
environment,
);
const allowed = join(workspace, "inside.txt");
const permitted = attemptWrite(allowed);
const outside = join(root, "outside.txt");
expect(attemptWrite(outside).exitCode).not.toBe(0);
await expect(stat(outside)).rejects.toMatchObject({ code: "ENOENT" });
const stateFile = join(stateDirectory, "outside.txt");
expect(attemptWrite(stateFile).exitCode).not.toBe(0);
await expect(stat(stateFile)).rejects.toMatchObject({ code: "ENOENT" });
if (permitted.exitCode !== 0) {
const details = new TextDecoder().decode(permitted.stderr);
if (
process.platform === "linux" &&
/bwrap: (?:setting up uid map: Permission denied|loopback: Failed RTM_NEWADDR: Operation not permitted)/u.test(
details,
)
) {
expect(runPinnedCodex(codexHome, ["features", "list"]).exitCode).toBe(
0,
);
return;
}
throw new Error(
`The pinned Codex CLI rejected an allowed scan write: ${await sandboxFailureDetails(codexHome, details)}`,
);
}
expect(await readFile(allowed, "utf8")).toBe("probe");
const repository = join(root, "repository");
await mkdir(repository);
await writeFile(join(repository, "fixture.txt"), "synthetic source\n");
const inventory = join(workspace, "in-scope-files.txt");
const helper = runPinnedCodex(
codexHome,
[
"sandbox",
"--config",
"permissions.codex_security_scan.network.enabled=true",
"--permission-profile",
"codex_security_scan",
"--cd",
workspace,
nodeCommand().command,
join(PLUGIN_ROOT, "mcp", "helpers.mjs"),
"generate-in-scope-files",
"--repo",
repository,
"--scope",
".",
"--out",
inventory,
],
environment,
);
expect(helper.exitCode, new TextDecoder().decode(helper.stderr)).toBe(0);
const inventoryPaths = (await readFile(inventory, "utf8"))
.trim()
.split(/\r?\n/u)
.map((path) => resolve(repository, path));
expect(inventoryPaths).toEqual([join(repository, "fixture.txt")]);
await requireSecureCredentialHome(codexHome);
expect(
await prepareCodexSecurityCredentialHome({
CODEX_SECURITY_STATE_DIR: stateDirectory,
}),
).toBe(codexHome);
},
);
test.skipIf(skipNativeSandboxTests)(
"reads policy source without exposing credentials or changing host files",
async () => {
const { root, codexHome, workspace, stateDirectory, environment } =
await scanSandboxFixture();
if (process.platform === "win32") {
// Native read ACLs are applied in the background. Initialize with the
// scan profile, whose workspace grants are synchronous, then wait
// before checking the read-only profile in this private fixture.
const setup = runPinnedCodex(
codexHome,
[
"sandbox",
"--permission-profile",
"codex_security_scan",
"--cd",
workspace,
join(
process.env["SystemRoot"] ?? "C:\\Windows",
"System32",
"cmd.exe",
),
"/d",
"/c",
"exit",
"0",
],
environment,
);
expect(setup.exitCode, new TextDecoder().decode(setup.stderr)).toBe(0);
await waitForWindowsSandboxSetup();
}
const source = join(root, "repository", "component");
await mkdir(source, { recursive: true });
const sourceFile = join(source, "fixture.txt");
await writeFile(sourceFile, "source");
const gitMetadata = join(source, ".git");
await mkdir(gitMetadata);
const privateConfig = join(stateDirectory, "worker-config.json");
await writeFile(privateConfig, "SYNTHETIC_PRIVATE");
const ambientHome = join(root, "ambient [home]{set}");
await mkdir(ambientHome);
const ambientCredentials = [
join(ambientHome, "auth.json"),
join(ambientHome, "config.toml"),
join(ambientHome, "codex_security_synthetic.config.toml"),
join(ambientHome, ".synthetic.config.toml.tmp"),
];
const plugin = join(ambientHome, "plugins", "fixture");
await mkdir(plugin, { recursive: true });
const artifacts = join(ambientHome, "state", "policies");
await mkdir(artifacts, { recursive: true });
const guidance = join(plugin, "guidance.md");
await writeFile(guidance, "guidance");
const config = scanRuntimeCodexConfig(
await mergedCodexConfig({}),
codexHome,
);
const permissions = config["permissions"] as Record<
string,
{ filesystem: JsonObject }
>;
permissions["codex_security_policy"]!.filesystem[source] = {
".": "read",
};
permissions["codex_security_policy"]!.filesystem[plugin] = {
".": "read",
};
permissions["codex_security_policy"]!.filesystem[artifacts] = {
".": "read",
};
permissions["codex_security_policy"]!.filesystem[gitMetadata] = {
".": "deny",
};
permissions["codex_security_policy"]!.filesystem[privateConfig] = {
".": "deny",
};
if (process.platform === "win32") {
permissions["codex_security_policy"]!.filesystem[
join(
ambientHome.replace(/[*?[\]{}]/gu, "[$&]"),
"{auth.json,config.toml,*.config.toml,.*.config.toml.tmp}",
)
] = "deny";
}
// The debug sandbox re-execs Codex, which may live outside OS read roots.
permissions["codex_security_policy"]!.filesystem[
resolveCodexCommand({}).command
] = "read";
await writeCodexConfig(join(codexHome, "config.toml"), config);
const sandbox = (
operation: "read" | "write",
path: string,
permissionProfile = "codex_security_policy",
) =>
runPinnedCodex(
codexHome,
[
"sandbox",
"--permission-profile",
permissionProfile,
"--cd",
workspace,
...(process.platform === "win32"
? [
join(
process.env["SystemRoot"] ?? "C:\\Windows",
"System32",
"WindowsPowerShell",
"v1.0",
"powershell.exe",
),
"-NoLogo",
"-NoProfile",
"-NonInteractive",
"-Command",
operation === "read"
? "$ErrorActionPreference = 'Stop'; Write-Host -NoNewline (Get-Content -LiteralPath $env:POLICY_PROBE_PATH -Raw)"
: "$ErrorActionPreference = 'Stop'; Set-Content -LiteralPath $env:POLICY_PROBE_PATH -Value 'probe' -NoNewline",
]
: [
"/bin/sh",
"-c",
operation === "read"
? 'cat "$POLICY_PROBE_PATH"'
: 'printf probe > "$POLICY_PROBE_PATH"',
]),
],
{ ...environment, POLICY_PROBE_PATH: path },
);
const evidence = join(artifacts, "previous-SECURITY.md");
await writeFile(evidence, "original");
const read = sandbox("read", evidence);
if (read.exitCode !== 0) {
const details = new TextDecoder().decode(read.stderr);
if (
process.platform === "linux" &&
/bwrap: (?:setting up uid map: Permission denied|loopback: Failed RTM_NEWADDR: Operation not permitted)/u.test(
details,
)
) {
expect(runPinnedCodex(codexHome, ["features", "list"]).exitCode).toBe(
0,
);
return;
}
throw new Error(
`The pinned Codex CLI rejected an allowed policy read: ${await sandboxFailureDetails(codexHome, details)}`,
);
}
expect(new TextDecoder().decode(read.stdout)).toBe("original");
for (const path of ambientCredentials)
await expect(stat(path)).rejects.toMatchObject({ code: "ENOENT" });
const inspected = sandbox("read", sourceFile);
expect(
inspected.exitCode,
new TextDecoder().decode(inspected.stderr),
).toBe(0);
expect(new TextDecoder().decode(inspected.stdout)).toBe("source");
const pluginRead = sandbox("read", guidance);
expect(
pluginRead.exitCode,
new TextDecoder().decode(pluginRead.stderr),
).toBe(0);
expect(new TextDecoder().decode(pluginRead.stdout)).toBe("guidance");
const sibling = join(root, "repository", "sibling.txt");
await writeFile(sibling, "sibling");
const siblingRead = sandbox("read", sibling);
if (process.platform === "win32") {
expect(
siblingRead.exitCode,
new TextDecoder().decode(siblingRead.stderr),
).toBe(0);
expect(new TextDecoder().decode(siblingRead.stdout)).toBe("sibling");
} else {
expect(siblingRead.exitCode).not.toBe(0);
expect(new TextDecoder().decode(siblingRead.stdout)).not.toContain(
"sibling",
);
}
for (const path of [
join(codexHome, "private.txt"),
join(gitMetadata, "config"),
privateConfig,
...ambientCredentials,
]) {
await writeFile(path, "SYNTHETIC_PRIVATE");
const denied = sandbox("read", path);
expect(
denied.exitCode,
`${path}: ${new TextDecoder().decode(denied.stdout)} ${new TextDecoder().decode(denied.stderr)}`,
).not.toBe(0);
expect(new TextDecoder().decode(denied.stdout)).not.toContain(
"SYNTHETIC_PRIVATE",
);
}
for (const path of [
sourceFile,
join(workspace, "inside.txt"),
join(root, "outside.txt"),
join(stateDirectory, "policy.txt"),
join(codexHome, "policy.txt"),
evidence,
]) {
const denied = sandbox("write", path);
if (process.platform === "win32") {
expect(
denied.exitCode,
new TextDecoder().decode(denied.stderr),
).not.toBe(0);
}
if (path === sourceFile)
expect(await readFile(path, "utf8")).toBe("source");
else if (path === evidence)
expect(await readFile(path, "utf8")).toBe("original");
else await expect(stat(path)).rejects.toMatchObject({ code: "ENOENT" });
}
if (process.platform === "win32") {
// The same cmdlet must write when the scan profile permits it.
const allowed = join(workspace, "inside.txt");
const permitted = sandbox("write", allowed, "codex_security_scan");
expect(
permitted.exitCode,
new TextDecoder().decode(permitted.stderr),
).toBe(0);
expect(await readFile(allowed, "utf8")).toBe("probe");
}
await requireSecureCredentialHome(codexHome);
},
);
test("writes Windows sandbox settings accepted by the pinned Codex CLI", async () => {
const root = await temporaryDirectory();
const path = join(root, "config.toml");
await writeCodexConfig(path, await mergedCodexConfig({}));
expect(parse(await readFile(path, "utf8"))).toMatchObject({
windows: { sandbox: "elevated" },
});
const result = runPinnedCodex(root, ["features", "list"]);
expect(result.exitCode).toBe(0);
expect(result.stdout.length).toBeGreaterThan(0);
});
test("writes selected profile sandbox settings accepted by the pinned Codex CLI", async () => {
const root = await temporaryDirectory();
const path = join(root, "config.toml");
const config = await mergedCodexConfig({
codexOverrides: {
profile: "elevated",
profiles: {
elevated: {
features: { elevated_windows_sandbox: true },
},
},
},
});
await writeCodexConfig(path, resolveCodexProfile(config));
expect(parse(await readFile(path, "utf8"))).toMatchObject({
features: { elevated_windows_sandbox: true },
windows: { sandbox: "elevated" },
});
const result = runPinnedCodex(root, ["mcp", "list", "--json"]);
if (result.exitCode !== 0) {
throw new Error(
`The pinned Codex CLI rejected the selected Windows sandbox profile: ${new TextDecoder().decode(result.stderr)}`,
);
}
expect(result.exitCode).toBe(0);
expect(result.stdout.length).toBeGreaterThan(0);
});
test("rejects prototype-bearing override keys", async () => {
for (const key of ["__proto__", "constructor", "prototype"]) {
await expect(
mergedCodexConfig({
codexOverrides: JSON.parse(
`{"features":{"custom":[{"${key}":{"polluted":true}}]}}`,
),
}),
).rejects.toThrow(`Invalid Codex override key: ${key}`);
}
expect(({} as Record<string, unknown>)["polluted"]).toBeUndefined();
});
test("rejects non-object overrides with a configuration error", async () => {
for (const codexOverrides of [null, [], false, 1, "invalid"]) {
await expect(
mergedCodexConfig({ codexOverrides } as never),
).rejects.toThrow("codexOverrides must be an object");
}
});
test("keeps exported default configuration deeply immutable", async () => {
expect(Object.isFrozen(DEFAULT_CODEX_CONFIG)).toBe(true);
expect(Object.isFrozen(DEFAULT_CODEX_CONFIG["features"])).toBe(true);
expect(Object.isFrozen(DEFAULT_CODEX_CONFIG["windows"])).toBe(true);
expect(
Object.isFrozen(
(DEFAULT_CODEX_CONFIG["features"] as Record<string, unknown>)[
"multi_agent_v2"
],
),
).toBe(true);
expect(() => {
(DEFAULT_CODEX_CONFIG["features"] as Record<string, unknown>)["goals"] =
false;
}).toThrow();
expect((await mergedCodexConfig({}))["features"]).toMatchObject({
goals: true,
multi_agent_v2: {
enabled: true,
max_concurrent_threads_per_session: 9,
},
});
expect(await mergedCodexConfig({})).toMatchObject({
model: "gpt-5.6-sol",
model_reasoning_effort: "xhigh",
model_reasoning_summary: "detailed",
show_raw_agent_reasoning: true,
windows: {
sandbox: "elevated",
},
});
});
test("rejects owned plugin keys and incompatible v2 overrides", async () => {
await expect(
mergedCodexConfig({ codexOverrides: { features: false } }),
).rejects.toThrow("features must be a TOML table");
await expect(
mergedCodexConfig({ codexOverrides: { features: { plugins: false } } }),
).rejects.toThrow(ConfigurationError);
await expect(
mergedCodexConfig({ codexOverrides: { agents: { max_threads: 2 } } }),
).rejects.toThrow("legacy v1");
await expect(
mergedCodexConfig({
codexOverrides: { features: { multi_agent_v2: { enabled: false } } },
}),
).rejects.toThrow("cannot be disabled");
await expect(
mergedCodexConfig({
codexOverrides: {
profile: "disabled",
profiles: { disabled: { features: { plugins: false } } },
},
}),
).rejects.toThrow("owns plugin loading configuration");
for (const owned of ["plugins", "marketplaces"] as const) {
await expect(
mergedCodexConfig({
codexOverrides: {
profile: "disabled",
profiles: { disabled: { [owned]: {} } },
},
}),
).rejects.toThrow("owns plugin loading configuration");
}
await expect(
mergedCodexConfig({
codexOverrides: {
profile: "disabled",
profiles: {
disabled: {
features: { multi_agent_v2: { enabled: false } },
},
},
},
}),
).rejects.toThrow("cannot be disabled");
await expect(
mergedCodexConfig({
codexOverrides: {
profiles: { legacy: { agents: { max_threads: 2 } } },
},
}),
).rejects.toThrow("legacy v1");
await expect(
mergedCodexConfig({
codexOverrides: {
profiles: {
deep: {
features: {
multi_agent_v2: {
max_concurrent_threads_per_session: 5,
},
},
},
},
},
}),
).resolves.toBeDefined();
});
test("writes deterministic TOML atomically with restrictive permissions", async () => {
const root = await temporaryDirectory();
const path = join(root, "home", "config.toml");
await writeCodexConfig(path, {
features: { plugins: true, goals: true },
agents: { max_threads: 12 },
model_reasoning_effort: "high",
});
const text = await readFile(path, "utf8");
expect(parse(text)).toEqual({
features: { plugins: true, goals: true },
agents: { max_threads: 12 },
model_reasoning_effort: "high",
});
if (process.platform !== "win32") {
expect((await stat(path)).mode & 0o777).toBe(0o600);
}
});
test("serializes numeric TOML overrides", async () => {
const root = await temporaryDirectory();
const path = join(root, "config.toml");
await writeCodexConfig(path, {
max_safe: Number.MAX_SAFE_INTEGER,
fractional: 1.5,
exponent: 1e-7,
});
expect(parse(await readFile(path, "utf8"))).toEqual({
max_safe: Number.MAX_SAFE_INTEGER,
fractional: 1.5,
exponent: 1e-7,
});
});
test.skipIf(process.platform === "win32")(
"keeps atomic TOML output readable under a restrictive umask",
async () => {
const root = await temporaryDirectory();
const path = join(root, "config.toml");
const previous = process.umask(0o777);
try {
await writeCodexConfig(path, { model: "test" });
} finally {
process.umask(previous);
}
expect((await stat(path)).mode & 0o777).toBe(0o600);
expect(await readFile(path, "utf8")).toContain('model = "test"');
},
);
test("serializes nested inline tables in TOML arrays", async () => {
const root = await temporaryDirectory();
const path = join(root, "config.toml");
const hooks = {
SessionStart: [
{
matcher: "*",
hooks: [{ type: "command", command: "echo hi" }],
},
],
};
await writeCodexConfig(path, { hooks });
expect(parse(await readFile(path, "utf8"))).toEqual({ hooks });
});
});