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: preserve local scan startup diagnostics (#2115)

andy-tang-oaicf22bcd7af75
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 3ed321e07..f6e7793b7 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -986,6 +986,15 @@ Finish older-version operations before upgrading. Never remove
`.codex-security-scan.sqlite3` during an operation. Stop all operations using the
credential home before manually removing an old `.codex-security-scan.lock`.
+If credential-home preparation fails, the error includes the underlying
+filesystem diagnostic. For permission or read-only filesystem errors, check
+the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
+directory outside the repository. A new state directory has separate history
+and does not migrate existing credentials or reports.
+
+Sandbox startup errors include the native diagnostic followed by a command to
+reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
+
On Windows, credential-home checks require trusted ownership and permissions
through every ancestor, including the volume root. Codex Security can repair
the credential home and its descendants; it does not change ancestor ownership
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index cfb35d7cd..5e13b2f98 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -216,6 +216,7 @@ import {
OutputDirectoryError,
OutputInsideProtectedRootError,
PluginPythonUnavailableError,
+ SandboxUnavailableError,
errorMessage,
ScanCostLimitExceededError,
ScanInterruptedError,
@@ -10448,7 +10449,8 @@ function isLocalScanFailure(error: unknown): boolean {
error instanceof OutputDirectoryError ||
error instanceof ConfigurationError ||
error instanceof LocalPluginBootstrapError ||
- error instanceof PluginPythonUnavailableError
+ error instanceof PluginPythonUnavailableError ||
+ error instanceof SandboxUnavailableError
) {
return true;
}
diff --git a/sdk/typescript/src/runtime.ts b/sdk/typescript/src/runtime.ts
index c49ca468f..1a8cf648d 100644
--- a/sdk/typescript/src/runtime.ts
+++ b/sdk/typescript/src/runtime.ts
@@ -290,8 +290,13 @@ export async function prepareCodexSecurityCredentialHome(
return canonical;
} catch (error) {
if (error instanceof OutputDirectoryError) throw error;
+ const code = nodeErrorCode(error);
+ const recovery =
+ code === "EACCES" || code === "EPERM" || code === "EROFS"
+ ? "\nCheck permissions or set CODEX_SECURITY_STATE_DIR to a private, writable directory outside the repository."
+ : "";
throw new OutputDirectoryError(
- `Unable to prepare the Codex Security credential home: ${path}`,
+ `Unable to prepare the Codex Security credential home: ${path}\n${errorMessage(error)}${recovery}`,
{ cause: error },
);
}
@@ -3338,8 +3343,12 @@ export async function probeCodexSandbox(
signal?.throwIfAborted();
detail = processErrorDetail(error);
}
+ const guidance =
+ process.platform === "linux"
+ ? "\nOn Linux this usually means unprivileged user namespaces are restricted (kernel.apparmor_restrict_unprivileged_userns=1 on Ubuntu 24.04 and later), which Bubblewrap needs; inside the container image, use the AppArmor profile and Compose override from the SDK README."
+ : "";
throw new SandboxUnavailableError(
- `Codex could not run a command in its sandbox; reproduce with '${command.command} ${args.join(" ")}'. On Linux this usually means unprivileged user namespaces are restricted (kernel.apparmor_restrict_unprivileged_userns=1 on Ubuntu 24.04 and later), which Bubblewrap needs; inside the container image, use the AppArmor profile and Compose override from the SDK README. Codex reported: ${detail}`,
+ `Codex could not run a command in its sandbox: ${detail}\nTo reproduce, run '${command.command} ${args.join(" ")}'.${guidance}`,
);
}
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index fa534b2c2..877f9409f 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -30,9 +30,11 @@ import {
PluginBootstrapError,
DiffTarget,
InvalidTargetError,
+ IncompleteScanError,
OutputDirectoryError,
OutputInsideProtectedRootError,
PluginPythonUnavailableError,
+ SandboxUnavailableError,
ScanCostLimitExceededError,
ScanInterruptedError,
ScanResult,
@@ -4584,6 +4586,23 @@ describe("CLI", () => {
"The configured plugin Python interpreter is unavailable or unusable: /usr/bin/python3",
),
],
+ [
+ "sandbox startup denied",
+ new SandboxUnavailableError(
+ "bwrap: setting up uid map: Permission denied",
+ ),
+ ],
+ [
+ "incomplete scan caused by sandbox startup denial",
+ new IncompleteScanError(
+ "Scan did not complete: bwrap: setting up uid map: Permission denied",
+ {
+ cause: new SandboxUnavailableError(
+ "bwrap: setting up uid map: Permission denied",
+ ),
+ },
+ ),
+ ],
];
for (const [, failure] of failures) {
diff --git a/sdk/typescript/tests-ts/config.test.ts b/sdk/typescript/tests-ts/config.test.ts
index 0bdbd0d29..56b3d4900 100644
--- a/sdk/typescript/tests-ts/config.test.ts
+++ b/sdk/typescript/tests-ts/config.test.ts
@@ -699,6 +699,33 @@ describe("Codex configuration", () => {
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");
diff --git a/sdk/typescript/tests-ts/runtime.test.ts b/sdk/typescript/tests-ts/runtime.test.ts
index f227d99d9..9dbe88188 100644
--- a/sdk/typescript/tests-ts/runtime.test.ts
+++ b/sdk/typescript/tests-ts/runtime.test.ts
@@ -2948,6 +2948,43 @@ for await (const line of createInterface({ input: process.stdin })) {
});
describe("runtime directories and plugin Python boundary", () => {
+ test.each([
+ ["EACCES", "permission denied", true],
+ ["EPERM", "operation not permitted", true],
+ ["EROFS", "read-only file system", true],
+ ["ENOSPC", "no space left on device", false],
+ ] as const)(
+ "preserves %s credential-home failures with relevant recovery advice",
+ async (code, detail, permissionFailure) => {
+ const root = await temporaryDirectory();
+ const environment = { CODEX_SECURITY_STATE_DIR: join(root, "state") };
+ const home = codexSecurityCredentialHome(environment);
+ const cause = Object.assign(
+ new Error(`${code}: ${detail}, mkdir '${home}'`),
+ { code },
+ );
+ const createDirectory = spyOn(fsPromises, "mkdir").mockRejectedValue(
+ cause,
+ );
+ try {
+ const failure = await prepareCodexSecurityCredentialHome(
+ environment,
+ ).then(
+ () => null,
+ (error: Error) => error,
+ );
+ expect(failure?.name).toBe("OutputDirectoryError");
+ expect(failure?.message).toContain(cause.message);
+ expect(failure?.cause).toBe(cause);
+ expect(failure?.message.includes("CODEX_SECURITY_STATE_DIR")).toBe(
+ permissionFailure,
+ );
+ } finally {
+ createDirectory.mockRestore();
+ }
+ },
+ );
+
test("prepares one private, reusable managed-credential home", async () => {
const root = await temporaryDirectory();
const environment = { CODEX_SECURITY_STATE_DIR: join(root, "state") };
diff --git a/sdk/typescript/tests-ts/sandbox-probe.test.ts b/sdk/typescript/tests-ts/sandbox-probe.test.ts
index 9f639722e..357378dfe 100644
--- a/sdk/typescript/tests-ts/sandbox-probe.test.ts
+++ b/sdk/typescript/tests-ts/sandbox-probe.test.ts
@@ -7,7 +7,9 @@ import { TestClient } from "./support/api-client.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
const SANDBOX_DENIAL =
- "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted";
+ process.platform === "darwin"
+ ? "sandbox-exec: sandbox_apply: Operation not permitted"
+ : "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted";
const { temporaryDirectory, cleanup } = createApiTestFixtures(
"codex-security-sandbox-",
@@ -58,6 +60,15 @@ describe("Codex sandbox probe", () => {
expect(failure?.message).toContain(
`${command} sandbox -- ${command} --version`,
);
+ expect(failure?.message.indexOf(SANDBOX_DENIAL)).toBeLessThan(
+ failure?.message.indexOf("reproduce") ?? -1,
+ );
+ expect(failure?.message.includes("AppArmor")).toBe(
+ process.platform === "linux",
+ );
+ expect(failure?.message.includes("user namespaces")).toBe(
+ process.platform === "linux",
+ );
},
);