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
feat(bulk-scan): enforce a cost limit for each repository (#379)
ianw-oaif7364ed245d2
diff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex 347ba21cd..a8ca4894e 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -37,7 +37,7 @@ for argument dofi;;--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.mdindex 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 --sunpx @openai/codex-security install-hooknpx @openai/codex-security bulk-scannpx @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 25npx @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.pdfnpx @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.mdnpx @openai/codex-security scans list /path/to/repository@@ -498,6 +498,7 @@ it returns a sealed partial report with any completed findings and listsunvalidated candidates as follow-up work. Requests already in progress canfinish above the limit; preparing the partial report makes no additional modelrequests. 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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)),