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

feat(bulk-scan): enforce a cost limit for each repository (#379)

ianw-oaif7364ed245d2
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 347ba21cd..a8ca4894e 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -37,7 +37,7 @@ for argument do
fi
;;
--output-dir|--workers|--mode|--model|--effort|--provider|\
- --knowledge-base|--max-attempts|--plugin-path|--python|\
+ --knowledge-base|--max-attempts|--max-cost|--plugin-path|--python|\
--codex|--filter-output|--format|\
--scan-prompt-file|--post-scan-prompt-file|\
--token-limit|--token-offset)
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index b33eef9da..5c2cf0698 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -218,7 +218,7 @@ npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --su
npx @openai/codex-security install-hook
npx @openai/codex-security bulk-scan
npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
-npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3
+npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3 --max-cost 25
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
npx @openai/codex-security scans list /path/to/repository
@@ -498,6 +498,7 @@ it returns a sealed partial report with any completed findings and lists
unvalidated candidates as follow-up work. Requests already in progress can
finish above the limit; preparing the partial report makes no additional model
requests. Incomplete coverage retains its existing exit code.
+For `bulk-scan`, the limit applies separately to each repository attempt.
Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
for the complete CLI references.
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 7ab8ba5d0..7d5a77c60 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -1532,6 +1532,13 @@ export async function main(
.positive()
.default(1)
.describe("Maximum scan attempts per repository."),
+ maxCost: z
+ .number()
+ .positive()
+ .optional()
+ .describe(
+ "Stop each repository attempt if estimated USD cost exceeds AMOUNT.",
+ ),
pluginPath: z
.string()
.min(1)
@@ -1612,6 +1619,9 @@ export async function main(
workers: options.workers,
mode: options.mode,
maxAttempts: options.maxAttempts,
+ ...(options.maxCost === undefined
+ ? {}
+ : { maxCostUsd: options.maxCost }),
knowledgeBasePaths: options.knowledgeBase,
...prompts,
config: {
diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.ts
index e6cbeffb6..63f3a7909 100644
--- a/sdk/typescript/src/multiscan.ts
+++ b/sdk/typescript/src/multiscan.ts
@@ -20,7 +20,7 @@ import Papa from "papaparse";
import type { CodexSecurity } from "./api.js";
import type { CodexSecurityConfig } from "./config.js";
import type { ScanCost } from "./cost.js";
-import { safeErrorMessage } from "./errors.js";
+import { safeErrorMessage, ScanCostLimitExceededError } from "./errors.js";
import type { CoverageDocument } from "./models.js";
import { requireSecureOutputAncestry } from "./runtime.js";
import type { ScanMode } from "./targets.js";
@@ -63,6 +63,7 @@ export interface MultiscanOptions {
workers: number;
mode: ScanMode;
maxAttempts: number;
+ maxCostUsd?: number;
scanPrompt?: string;
postScanPrompt?: string;
config: CodexSecurityConfig;
@@ -219,6 +220,7 @@ async function runCampaign(
let warning: string | undefined;
let coverage: CoverageDocument["completeness"] | undefined;
let cost: Readonly<ScanCost> | null = null;
+ let exhaustedBudget = false;
try {
await ensureOutputDirectory(dirname(scanDir));
await rm(checkout, { recursive: true, force: true });
@@ -254,6 +256,9 @@ async function runCampaign(
...(options.postScanPrompt === undefined
? {}
: { postScanPrompt: options.postScanPrompt }),
+ ...(options.maxCostUsd === undefined
+ ? {}
+ : { maxCostUsd: options.maxCostUsd }),
onWarning: (warning) =>
notifyProgress(options, {
...progress,
@@ -274,6 +279,10 @@ async function runCampaign(
}
} catch (error) {
if (options.signal?.aborted === true) options.signal.throwIfAborted();
+ if (error instanceof ScanCostLimitExceededError) {
+ cost = error.cost;
+ exhaustedBudget = true;
+ }
failure = safeErrorMessage(error);
} finally {
await rm(checkout, { recursive: true, force: true });
@@ -308,6 +317,10 @@ async function runCampaign(
else incomplete += 1;
break;
}
+ if (exhaustedBudget) {
+ failed += 1;
+ break;
+ }
if (retry === options.maxAttempts - 1) failed += 1;
}
}
@@ -576,7 +589,10 @@ async function recoverLock(
async function ensureManifest(
path: string,
tasks: MultiscanTask[],
- options: Pick<MultiscanOptions, "scanPrompt" | "postScanPrompt">,
+ options: Pick<
+ MultiscanOptions,
+ "scanPrompt" | "postScanPrompt" | "maxCostUsd"
+ >,
): Promise<void> {
const expected = `${JSON.stringify(
{
@@ -588,6 +604,9 @@ async function ensureManifest(
...(options.postScanPrompt === undefined
? {}
: { postScanPrompt: options.postScanPrompt }),
+ ...(options.maxCostUsd === undefined
+ ? {}
+ : { maxCostUsd: options.maxCostUsd }),
},
null,
2,
diff --git a/sdk/typescript/tests-ts/container-entrypoint.test.ts b/sdk/typescript/tests-ts/container-entrypoint.test.ts
index 796678a09..ff25a177a 100644
--- a/sdk/typescript/tests-ts/container-entrypoint.test.ts
+++ b/sdk/typescript/tests-ts/container-entrypoint.test.ts
@@ -169,6 +169,7 @@ describe("customer container entrypoint", () => {
testPosix("accepts CSVs after global and bulk-scan options", async () => {
for (const arguments_ of [
["bulk-scan", "--workers", "2", "/input/repositories.csv"],
+ ["bulk-scan", "--max-cost", "12.50", "/input/repositories.csv"],
["bulk-scan", "bulk-scan", "--output-dir", "/output"],
[
"--format",
@@ -260,6 +261,7 @@ describe("customer container entrypoint", () => {
for (const arguments_ of [
["bulk-scan"],
["bulk-scan", "--workers", "8"],
+ ["bulk-scan", "--max-cost", "12.50"],
["bulk-scan", "--scan-prompt-file", "prompt.md"],
["bulk-scan", "--post-scan-prompt-file", "post-prompt.md"],
["--format", "json", "bulk-scan", "--mode", "deep"],
diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.ts
index 3f9e68ef5..33676192a 100644
--- a/sdk/typescript/tests-ts/multiscan.test.ts
+++ b/sdk/typescript/tests-ts/multiscan.test.ts
@@ -20,6 +20,7 @@ import { hostname, tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, spyOn, test } from "bun:test";
import { main } from "../src/cli.js";
+import { ScanCostLimitExceededError } from "../src/errors.js";
import type { ScanResult } from "../src/result.js";
import { buildGitHubCredentialArgs, runMultiscan } from "../src/multiscan.js";
import { resolveTrustedExecutable } from "../src/trusted-executable.js";
@@ -209,11 +210,13 @@ describe("multiscan", () => {
"Review boundaries.\n\nFocus on authentication, authorization.",
);
expect(scanOptions.postScanPrompt).toBe("Draft confirmed fixes.");
+ expect(scanOptions.maxCostUsd).toBe(12.5);
return await completedScan(scanOptions.outputDir!);
}),
{
scanPrompt: "Review boundaries.",
postScanPrompt: "Draft confirmed fixes.",
+ maxCostUsd: 12.5,
},
),
);
@@ -227,6 +230,7 @@ describe("multiscan", () => {
).toMatchObject({
scanPrompt: "Review boundaries.",
postScanPrompt: "Draft confirmed fixes.",
+ maxCostUsd: 12.5,
tasks: [
{ id: "payments", prompt: "Focus on authentication, authorization." },
],
@@ -264,6 +268,89 @@ describe("multiscan", () => {
]);
});
+ test("records an exhausted repository budget without retrying the scan", async () => {
+ const paths = await fixture();
+ const source = await repository(paths.root, "over-budget");
+ await writeFile(
+ paths.input,
+ `id,repository,revision\nover-budget,${source.path},${source.revision}\n`,
+ );
+ const cost = {
+ model: "gpt-5.6-sol",
+ inputTokens: 1_250,
+ cachedInputTokens: 200,
+ cacheWriteInputTokens: 0,
+ outputTokens: 30,
+ estimatedUsd: 25.25,
+ };
+ let attempts = 0;
+
+ const summary = await runMultiscan(
+ options(
+ paths,
+ client(async (_repository, scanOptions = {}) => {
+ attempts += 1;
+ throw new ScanCostLimitExceededError(
+ 25,
+ cost,
+ scanOptions.outputDir!,
+ );
+ }),
+ { maxAttempts: 3, maxCostUsd: 25 },
+ ),
+ );
+
+ expect(attempts).toBe(1);
+ expect(summary).toMatchObject({ completed: 0, failed: 1 });
+ expect(await results(summary.resultsPath)).toMatchObject([
+ { id: "over-budget", status: "failed", attempt: 1, cost },
+ ]);
+ });
+
+ test("forwards a bulk CLI cost limit and rejects zero", async () => {
+ const paths = await fixture();
+ const source = await repository(paths.root, "sample");
+ await writeFile(
+ paths.input,
+ `id,repository,revision\nsample,${source.path},${source.revision}\n`,
+ );
+ const stdout = capture();
+ const stderr = capture();
+ let scanOptions: unknown;
+
+ expect(
+ await main(
+ [
+ "bulk-scan",
+ "repositories.csv",
+ "--output-dir",
+ "results",
+ "--max-cost",
+ "12.5",
+ "--json",
+ ],
+ stdout.stream,
+ stderr.stream,
+ dependencies({
+ currentDirectory: paths.root,
+ onTurn: (_repository, options) => (scanOptions = options),
+ }),
+ ),
+ ).toBe(0);
+ expect(scanOptions).toMatchObject({ maxCostUsd: 12.5 });
+
+ const invalid = capture();
+ expect(
+ await main(
+ ["bulk-scan", "--max-cost=0"],
+ capture().stream,
+ invalid.stream,
+ dependencies({ currentDirectory: paths.root }),
+ ),
+ ).toBe(2);
+ expect(invalid.text()).toContain("expected number to be >0");
+ });
+
test("surfaces optional post-scan warnings without failing completed scans", async () => {
const paths = await fixture();
const source = await repository(paths.root, "follow-up-warning");
@@ -1428,6 +1515,7 @@ describe("multiscan", () => {
for (const prompts of [
{ scanPrompt: "Review different boundaries." },
{ postScanPrompt: "Draft confirmed fixes." },
+ { maxCostUsd: 12.5 },
]) {
await expect(
runMultiscan(options(paths, security, prompts)),