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): identify the state directory in protected-root errors (#1537)

ilaigolde82b2cf43ded
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index fb53c1376..82eadf250 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1125,6 +1125,12 @@ 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 a scan reports that its state directory overlaps a protected root, choose a
+private directory in a separate tree, such as a sibling of the protected root.
+Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
+scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
+can match `"state"` for this case.
+
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
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index aa8bcf0dc..955a18ea6 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -5504,7 +5504,11 @@ export class CodexSecurity {
this.#dependencies.environment,
);
const canonicalStateDirectory = await canonicalConfigPath(stateDirectory);
- requireOutputOutsideRepositories(protectedRoots, canonicalStateDirectory);
+ requireOutputOutsideRepositories(
+ protectedRoots,
+ canonicalStateDirectory,
+ "state",
+ );
return {
repository: repo,
target: normalized,
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index d1066954e..d9e0e8cb7 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -12032,6 +12032,7 @@ function componentScanEventLine(
function protectedRootErrorMessage(
error: OutputInsideProtectedRootError,
): string {
+ if (error.pathKind === "state") return error.message;
const description =
error.pathKind === "output"
? "Scan output directory"
diff --git a/sdk/typescript/src/errors.ts b/sdk/typescript/src/errors.ts
index ca0e86230..35939ccaf 100644
--- a/sdk/typescript/src/errors.ts
+++ b/sdk/typescript/src/errors.ts
@@ -63,7 +63,8 @@ export class OutputDirectoryNotEmptyError extends OutputDirectoryError {
);
}
}
-export type ProtectedScanPathKind = "output" | "temporary" | "runtime";
+export type ProtectedScanPathKind =
+ "output" | "state" | "temporary" | "runtime";
export class OutputInsideProtectedRootError extends OutputDirectoryError {
public constructor(
@@ -72,7 +73,14 @@ export class OutputInsideProtectedRootError extends OutputDirectoryError {
public readonly pathKind: ProtectedScanPathKind = "output",
) {
super(
- `Scan ${pathKind} directory must be outside the protected scan root: ${outputDirectory}`,
+ pathKind === "state"
+ ? [
+ "Codex Security state directory must be outside the protected scan root and cannot contain it.",
+ ` Resolved path: ${outputDirectory}`,
+ ` Protected root: ${protectedRoot}`,
+ "Set CODEX_SECURITY_STATE_DIR to a private directory that does not overlap the protected root. For hosted scans, set stateDirectory on the request.",
+ ].join("\n")
+ : `Scan ${pathKind} directory must be outside the protected scan root: ${outputDirectory}`,
);
}
}
diff --git a/sdk/typescript/src/runtime.ts b/sdk/typescript/src/runtime.ts
index b3157d114..37a814796 100644
--- a/sdk/typescript/src/runtime.ts
+++ b/sdk/typescript/src/runtime.ts
@@ -1744,7 +1744,8 @@ export function requireOutputOutsideRepository(
): void {
if (
isWithin(repository, outputDirectory) ||
- (pathKind === "output" && isWithin(outputDirectory, repository))
+ ((pathKind === "output" || pathKind === "state") &&
+ isWithin(outputDirectory, repository))
) {
throw new OutputInsideProtectedRootError(
outputDirectory,
diff --git a/sdk/typescript/tests-ts/api-policy.test.ts b/sdk/typescript/tests-ts/api-policy.test.ts
index ef4bc4282..04ee1263a 100644
--- a/sdk/typescript/tests-ts/api-policy.test.ts
+++ b/sdk/typescript/tests-ts/api-policy.test.ts
@@ -789,9 +789,9 @@ describe("CodexSecurity policy API", () => {
{},
{ environment: { CODEX_SECURITY_STATE_DIR: outputDir } },
);
- await expect(state.preflightPolicy(repository)).rejects.toThrow(
- "outside the protected scan root",
- );
+ await expect(state.preflightPolicy(repository)).rejects.toMatchObject({
+ pathKind: "state",
+ });
if (kind === "linked" && metadata === gitDirectory) {
await expect(state.generatePolicy(repository)).rejects.toThrow(
"outside the protected scan root",
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 4d86cad7f..f4e661e0d 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -16011,7 +16011,11 @@ if __name__ == "__main__":
for (const operation of ["preflight", "run"] as const) {
await expect(
client[operation](repository, { outputDir: join(root, "output") }),
- ).rejects.toBeInstanceOf(OutputInsideProtectedRootError);
+ ).rejects.toMatchObject({
+ name: OutputInsideProtectedRootError.name,
+ pathKind: "state",
+ message: expect.stringContaining("stateDirectory"),
+ });
}
if (stateDirectory !== root && stateDirectory !== linkedState)
expect(existsSync(stateDirectory)).toBe(false);
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index a409efa5d..5f2f31284 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -6173,6 +6173,28 @@ describe("CLI", () => {
}
});
+ test("explains how to fix an overlapping state directory", async () => {
+ const { stdout, stderr, runCli } = createCliTest(main);
+ const failing = scanDependencies(async () => {
+ throw new OutputInsideProtectedRootError(
+ "/state",
+ "/state/repo",
+ "state",
+ );
+ });
+
+ expect(await runCli(["scan", ".", "--json"], failing)).toBe(2);
+ const { message } = JSON.parse(stdout.text());
+ expect(message).toContain(
+ "Codex Security state directory must be outside the protected scan root and cannot contain it.",
+ );
+ expect(message).toContain("Resolved path: /state");
+ expect(message).toContain("Protected root: /state/repo");
+ expect(message).toContain("Set CODEX_SECURITY_STATE_DIR");
+ expect(message).not.toContain("--output-dir");
+ expect(stderr.text()).toContain(message);
+ });
+
test("identifies the output directory for a late protected-root failure", async () => {
const { stdout, stderr, runCli } = createCliTest(main);