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(cli): honor scan budgets across batch attempts and follow-ups (#2592)

Michael D'Angelo6b0d0a7ce12d
diff --git a/docs/project-configuration.md b/docs/project-configuration.md
index edc61464b..c04333d9c 100644
--- a/docs/project-configuration.md
+++ b/docs/project-configuration.md
@@ -335,7 +335,8 @@ aliases there are errors, while equivalent durations are accepted.
`max_cost_usd_per_scan` has the same meaning as `--max-cost`: an estimated limit for one
scan attempt. In-flight work may exceed it. It is not a total budget for a batch or
follow-up actions. `fail_on_severity` changes the exit status without filtering the
-retained findings.
+retained findings. A bounded scan cannot run `--patch` or `--validate`. Select a
+finding from the saved scan to patch or validate separately.
## Batch and component scans
@@ -351,6 +352,12 @@ context, prompts, per-attempt cost and investigation limits, and severity policy
as `scan`. The investigation allowance applies independently to each scan, not
planning, result matching, or total campaign time.
+Use `--max-total-cost USD` for a whole invocation. It divides the estimate among
+explicit components or pending repository attempts, including retries. A tighter
+configured per-scan limit still applies. The total limit skips model-based matching
+and owner suggestions, including when `scan.owner_suggestions` is enabled. See the [component scan](../sdk/typescript/docs/cli.md#scan-project-components)
+and [bulk scan](../sdk/typescript/docs/cli.md#bulk-scans) guides for planning and recovery behavior.
+
A bulk CSV row's mode and scope override the file's defaults for that repository.
Bulk checkouts are clean, shallow snapshots, so bulk scans accept repository or
path scopes. A configured diff or working-tree scope is rejected before work
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index d63838715..427a7c8f5 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -881,9 +881,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry with
The retry report covers only those components. Each registered component keeps its
scan ID in the summary, including when the scan fails.
-`--max-cost` applies per component, excluding planning and matching. `--model`
-and `--effort` also apply to matching; `--auth` applies throughout. Planning and
-matching reject ambient command providers that conflict with explicit ChatGPT
+`--max-cost` applies per component, excluding planning and matching.
+Use `--max-total-cost USD` with explicit components to split one estimated
+budget among them. The smaller of each component's share and its per-scan
+limit applies. Findings stay separate because model-based matching is skipped.
+The total limit also skips owner suggestions, including when enabled in project configuration.
+Automatic planning and post-scan prompts must run separately.
+
+`--model` and `--effort` also apply to matching. `--auth` applies throughout.
+Planning and matching reject ambient command providers that conflict with explicit ChatGPT
or API-key auth. SDK-selected command providers retain their authentication.
From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
@@ -1373,6 +1379,15 @@ codex-security bulk-scan repositories.csv \
--output-dir /path/outside/repositories/results --workers 4
```
+`--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
+estimated limit among the pending repositories and their possible attempts for
+this invocation, including recovery. For example, a $12 limit with three pending
+repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
+overrun reduces the remaining budget for queued attempts. In-flight work can
+exceed a limit. The total limit skips model-based matching and owner suggestions,
+including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
+limit and includes prior recorded usage in its cost estimate.
+
Bulk scans use clean shallow checkouts and support repository/path scopes.
CSV scopes are literal paths relative to each checkout, including names such
as `~/src`.
@@ -2674,7 +2689,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
task. The container must provide it. There is no automatic fallback; optional
patch-risk assessment still uses its read-only sandbox.
-`scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
+`scan --patch` runs after a complete scan without a cost limit. A cost-limited
+scan saves the findings and skips the interactive patch offer. Use
+`codex-security patch --scan SCAN_ID` to patch separately.
+`--patch-severity` defaults to `low`;
`high` selects high and critical findings. Interactive users can select findings
and add instructions. The interactive finding browser lists critical, high,
medium, then low findings, preserving scan order within each severity.
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 6dc154a36..0575ade4f 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -1,5 +1,6 @@
const distModules = [
"api",
+ "batch-cost",
"scan-executor",
"host-protocol",
"hosted-remediation",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 03023c252..fe9007ce5 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -394,6 +394,8 @@ const scanLifecycleSchema = z.object({
export type ScanLifecycle = Readonly<z.infer<typeof scanLifecycleSchema>>;
export interface ScanOptions extends ScanSettings {
+ /** @internal A bounded batch omits unmetered model calls after the scan. */
+ skipFindingMatching?: boolean;
/** Explicit policy for the initial scan and its workers. */
severityRubric?: SeverityRubricSnapshot;
/** Markdown policy file to capture when starting a new scan. */
@@ -4041,11 +4043,9 @@ export class CodexSecurity {
try {
const runWorkbench = (args: readonly string[], input?: string) =>
workbench(workbenchOptions, args, input);
- const previousFindings = await listRepositoryFindings(
- runWorkbench,
- targetId,
- "all",
- );
+ const previousFindings = options.skipFindingMatching
+ ? undefined
+ : await listRepositoryFindings(runWorkbench, targetId, "all");
if (previousFindings !== undefined) {
await matchCompletedScan({
scanId,
@@ -4068,6 +4068,8 @@ export class CodexSecurity {
),
...inferenceOptions,
});
+ }
+ if (previousFindings !== undefined || options.skipFindingMatching) {
result.repositoryFindings = (await listRepositoryFindings(
runWorkbench,
targetId,
diff --git a/sdk/typescript/src/batch-cost.ts b/sdk/typescript/src/batch-cost.ts
new file mode 100644
index 000000000..767c9e843
--- /dev/null
+++ b/sdk/typescript/src/batch-cost.ts
@@ -0,0 +1,63 @@
+import { ConfigurationError } from "./errors.js";
+import type { ScanCost } from "./cost.js";
+import type { ScanSettings } from "./scan-settings.js";
+
+export function batchScanBudget(
+ share: number | undefined,
+ settings: Pick<
+ ScanSettings,
+ "maxCostUsd" | "postScanPrompt" | "postScanPromptFile"
+ >,
+): {
+ maxCostUsd?: number;
+ skipFindingMatching?: true;
+ ownerSuggestions?: false;
+} {
+ if (share === undefined) return { maxCostUsd: settings.maxCostUsd };
+ if (
+ settings.postScanPrompt !== undefined ||
+ settings.postScanPromptFile !== undefined
+ )
+ throw new ConfigurationError(
+ "--max-total-cost cannot cover a post-scan prompt. Remove the post-scan prompt and run it separately.",
+ );
+ return {
+ maxCostUsd: Math.min(share, settings.maxCostUsd ?? share),
+ skipFindingMatching: true,
+ ownerSuggestions: false,
+ };
+}
+
+/** Reserve before dispatch, including in-flight attempts. Charge observed overruns to the remaining pool. */
+export class BatchCostPool {
+ #remaining: number;
+ readonly share: number;
+
+ constructor(totalUsd: number, slots: number) {
+ this.#remaining = totalUsd;
+ this.share = totalUsd / slots;
+ if (!Number.isFinite(this.share) || this.share <= 0)
+ throw new ConfigurationError(
+ "The total cost limit must allow a positive USD amount per scan attempt.",
+ );
+ }
+
+ reserve(share = this.share) {
+ const maxCostUsd = Math.min(share, this.#remaining);
+ if (maxCostUsd <= 0)
+ throw new ConfigurationError(
+ "The invocation cost limit is exhausted. No further scan attempts can start.",
+ );
+ this.#remaining -= maxCostUsd;
+ let charged = maxCostUsd;
+ return {
+ maxCostUsd,
+ record: (cost: Readonly<ScanCost> | null | undefined) => {
+ if (cost && cost.estimatedUsd > charged) {
+ this.#remaining -= cost.estimatedUsd - charged;
+ charged = cost.estimatedUsd;
+ }
+ },
+ };
+ }
+}
diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.ts
index d09ebffb2..e161c5bd3 100644
--- a/sdk/typescript/src/cli-help.ts
+++ b/sdk/typescript/src/cli-help.ts
@@ -82,6 +82,7 @@ const VALUE_LABELS: Record<string, string> = {
python: "path",
codex: "key=value",
"max-cost": "usd",
+ "max-total-cost": "usd",
"max-time": "minutes",
"max-time-hours": "hours",
"fail-on-severity": "level",
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 17919e6dd..71d8aaab2 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -228,6 +228,7 @@ import {
type JsonValue,
} from "./config.js";
import { formatUsd, type ScanCost } from "./cost.js";
+import { batchScanBudget } from "./batch-cost.js";
import {
formatScanCost,
formatScanCostTokens,
@@ -5497,7 +5498,9 @@ export async function main(
patch: z
.boolean()
.default(false)
- .describe("Patch and verify confirmed findings after the scan."),
+ .describe(
+ "Patch and verify findings after a scan without a cost limit.",
+ ),
validate: z
.boolean()
.default(false)
@@ -6321,6 +6324,9 @@ export async function main(
maxCost: ScanSettingsSchema.shape.maxCostUsd.describe(
"Stop each component scan if estimated USD cost exceeds AMOUNT.",
),
+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe(
+ "Divide estimated USD among explicit components for this invocation. Skips model-based finding matching and owner suggestions.",
+ ),
showCost: SHOW_COST_OPTION,
...RUNTIME_OPTION_SCHEMAS,
})
@@ -6417,6 +6423,7 @@ export async function main(
),
mode: settings.mode,
maxCostUsd: settings.maxCostUsd,
+ maxTotalCostUsd: options.maxTotalCost,
showCost: options.showCost,
clock: dependencies,
color: dependencies.environment["NO_COLOR"] === undefined,
@@ -6437,6 +6444,7 @@ export async function main(
outputDir: settings.outputDir,
...(options.auto ? { auto: true } : { components }),
planOnly: options.planOnly,
+ maxTotalCostUsd: options.maxTotalCost,
workers: options.workers,
config,
scanOptions: {
@@ -6447,6 +6455,10 @@ export async function main(
planComponents: dependencies.planComponents,
matchFindings: dependencies.matchFindings,
onPlan: (components) => {
+ if (dashboard === null && options.maxTotalCost !== undefined)
+ errorOutput.write(
+ `codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`,
+ );
for (const component of components)
componentNames.set(component.id, component.name);
dashboard?.setComponents(components);
@@ -6461,7 +6473,9 @@ export async function main(
const line = componentScanEventLine(
componentName,
event,
- options.showCost || settings.maxCostUsd !== undefined,
+ options.showCost ||
+ settings.maxCostUsd !== undefined ||
+ options.maxTotalCost !== undefined,
settings.auth,
);
if (line !== null) errorOutput.write(line);
@@ -6480,16 +6494,22 @@ export async function main(
signal: controller.signal,
onProgress: (component) => {
if (dashboard !== null) dashboard.updateComponent(component);
- else
+ else {
+ const budget =
+ component.status === "started" &&
+ component.maxCostUsd !== undefined
+ ? ` (${formatUsd(component.maxCostUsd)} per component)`
+ : "";
errorOutput.write(
- `codex-security: ${diagnosticValue(component.name)} ${component.status}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`,
+ `codex-security: ${diagnosticValue(component.name)} ${component.status}${budget}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`,
);
+ }
},
onComplete: (result) => {
dashboard?.finishComponents(result);
stopDashboard();
errorOutput.write(
- `Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`,
+ `Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : result.deduplication?.status === "skipped" ? " (matching skipped under total cost limit)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`,
);
if (result.retryPlanPath !== undefined)
errorOutput.write(
@@ -6578,6 +6598,9 @@ export async function main(
maxCost: ScanSettingsSchema.shape.maxCostUsd.describe(
"Stop each repository attempt if estimated USD cost exceeds AMOUNT.",
),
+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe(
+ "Divide estimated USD among pending repository attempts, including retries, for this invocation. Skips model-based finding matching and owner suggestions.",
+ ),
...runtimeOptions(() => z.string().min(1)),
}),
usage: [
@@ -6668,6 +6691,10 @@ export async function main(
).options,
]),
);
+ if (options.maxTotalCost !== undefined)
+ errorOutput.write(
+ `codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`,
+ );
const result = await runMultiscan({
inputPath,
outputDir,
@@ -6675,6 +6702,7 @@ export async function main(
workers: options.workers,
mode: settings.mode,
maxAttempts: options.maxAttempts,
+ maxTotalCostUsd: options.maxTotalCost,
...(settings.maxCostUsd === undefined
? {}
: { maxCostUsd: settings.maxCostUsd }),
@@ -6716,6 +6744,7 @@ export async function main(
signal: controller.signal,
});
return {
+ alreadyCompleted: true,
manifest: contract.manifest,
findings: contract.findings,
cost:
@@ -6769,6 +6798,10 @@ export async function main(
try {
return await security.run(recipe.repository!, {
...pickScanSettings(recipe),
+ ...batchScanBudget(
+ prompts.maxTotalCostShareUsd,
+ recipe,
+ ),
knowledgeBaseSnapshot: prompts.knowledgeBaseSnapshot,
telemetryContext: prompts.telemetryContext,
onTelemetry: prompts.onTelemetry,
@@ -6787,10 +6820,21 @@ export async function main(
}
: {}),
signal: controller.signal,
- onProgress: ({ repository, status, attempt, error, warning }) => {
+ onProgress: ({
+ repository,
+ status,
+ attempt,
+ maxCostUsd,
+ error,
+ warning,
+ }) => {
const detail = error ?? warning;
+ const budget =
+ maxCostUsd === undefined
+ ? ""
+ : `, ${formatUsd(maxCostUsd)} per repository attempt`;
errorOutput.write(
- `codex-security: ${repository} ${status} (attempt ${attempt})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`,
+ `codex-security: ${repository} ${status} (attempt ${attempt}${budget})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`,
);
},
});
@@ -11109,6 +11153,10 @@ async function executeScan(
let usageFreshness: string | null = null;
let accountLimits: string | null = null;
let maxCostUsd = arguments_.maxCostUsd;
+ if (maxCostUsd !== undefined && arguments_.patch)
+ throw new CodexSecurityError(
+ "--patch cannot be combined with a scan cost limit. Run the bounded scan first, then use `codex-security patch --scan SCAN_ID` separately.",
+ );
const showCost = arguments_.showCost === true || maxCostUsd !== undefined;
let phase: string | null = null;
const targetWarnings: string[] = [];
@@ -12217,6 +12265,7 @@ async function executeScan(
try {
if (
!arguments_.mock &&
+ maxCostUsd === undefined &&
actionableFindings.length > 0 &&
arguments_.patchSeverity === undefined &&
progress?.interactive === true &&
diff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.ts
index ede16e84c..3dc042d23 100644
--- a/sdk/typescript/src/component-scan.ts
+++ b/sdk/typescript/src/component-scan.ts
@@ -35,12 +35,13 @@ import type {
} from "./cost.js";
import type { ScanTokenUsage } from "./cost-model.js";
import { readThreatModelPath } from "./artifact-export.js";
-import { errorMessage } from "./errors.js";
+import { errorMessage, ScanCostLimitExceededError } from "./errors.js";
import type { Finding } from "./models.js";
import type { ScanResult } from "./result.js";
import type { ScanActivity } from "./scan-activity.js";
import type { DeepScanProgress } from "./scan-progress.js";
import type { ScanSettings } from "./scan-settings.js";
+import { BatchCostPool, batchScanBudget } from "./batch-cost.js";
import type { ScanProgress, ScanWorkerStatus } from "./worker-progress.js";
import {
matchScanFindingsInternal,
@@ -58,6 +59,7 @@ export interface ComponentScanOptions {
auto?: boolean;
planOnly?: boolean;
workers?: number;
+ maxTotalCostUsd?: number;
config?: CodexSecurityConfig;
scanOptions?: Omit<ScanSettings, "target" | "outputDir"> &
Pick<ScanOptions, "onMeasurement">;
@@ -83,6 +85,7 @@ export interface ComponentReceipt {
id: string;
name: string;
paths: string[];
+ maxCostUsd?: number;
status: "pending" | "started" | "completed" | "failed";
outputDir: string;
scanId?: string;
@@ -124,7 +127,7 @@ interface CombinedFinding {
}
export interface ComponentDeduplicationSummary {
- status: "completed" | "failed";
+ status: "completed" | "failed" | "skipped";
confirmedGroups: number;
uncertainPairs: number;
error?: string;
@@ -153,6 +156,18 @@ export async function runComponentScans(
throw new Error("Component workers must be a positive integer.");
if (Boolean(options.auto) === (options.components !== undefined))
throw new Error("Choose exactly one of components or automatic planning.");
+ if (options.auto && options.maxTotalCostUsd !== undefined)
+ throw new Error(
+ "--max-total-cost requires --component or --components-file because automatic planning calls an unmetered model.",
+ );
+ const pool =
+ options.planOnly || options.maxTotalCostUsd === undefined
+ ? undefined
+ : new BatchCostPool(
+ options.maxTotalCostUsd,
+ options.components?.length ?? 1,
+ );
+ const budget = batchScanBudget(pool?.share, options.scanOptions ?? {});
const auth = options.scanOptions?.auth;
let environment = options.environment;
if (auth !== undefined && auth !== "auto") {
@@ -215,11 +230,13 @@ export async function runComponentScans(
};
if (options.planOnly) return base;
+ const { maxCostUsd } = budget;
const receipts: ComponentReceipt[] = plan.components.map(
(component, index) => ({
...component,
id: `component-${index + 1}`,
operationId: randomUUID(),
+ ...(maxCostUsd === undefined ? {} : { maxCostUsd }),
status: "pending",
outputDir: join(output, `component-${index + 1}`),
}),
@@ -246,8 +263,6 @@ export async function runComponentScans(
while (!options.signal?.aborted) {
const receipt = receipts[next++];
if (receipt === undefined) return;
- receipt.status = "started";
- notify(() => options.onProgress?.(copyReceipt(receipt)));
const emit = (event: ComponentScanUpdate): void =>
notify(() =>
options.onScanEvent?.({ ...event, componentId: receipt.id }),
@@ -271,9 +286,17 @@ export async function runComponentScans(
onWorkerStatus: (value) => emit({ type: "workers", value }),
onWarning: (value) => emit({ type: "warning", value }),
};
+ let reservation: ReturnType<BatchCostPool["reserve"]> | undefined;
try {
+ reservation = pool?.reserve(maxCostUsd);
+ if (reservation !== undefined)
+ receipt.maxCostUsd = reservation.maxCostUsd;
+ receipt.status = "started";
+ notify(() => options.onProgress?.(copyReceipt(receipt)));
const result = await security.run(repository, {
...options.scanOptions,
+ ...budget,
+ maxCostUsd: receipt.maxCostUsd,
...observers,
onScanRegistered: ({ scanId }) => {
receipt.scanId = scanId;
@@ -287,6 +310,7 @@ export async function runComponentScans(
parentAttemptId,
},
onMeasurement: (measurement) => {
+ reservation?.record(measurement.cost);
receipt.measurement = measurement;
if (measurement.cost !== null) receipt.cost = measurement.cost;
else delete receipt.cost;
@@ -294,6 +318,7 @@ export async function runComponentScans(
emit({ type: "measurement", value: measurement });
},
});
+ reservation?.record(result.cost);
if (result.manifest.scan.status !== "completed")
throw new Error(`Component scan ${result.manifest.scan.status}.`);
results.set(receipt.id, result);
@@ -305,6 +330,8 @@ export async function runComponentScans(
if (result.threatModelPath !== null)
receipt.threatModelPath = result.threatModelPath;
} catch (error) {
+ if (error instanceof ScanCostLimitExceededError)
+ reservation?.record(error.cost);
receipt.status = "failed";
receipt.outcome = options.signal?.aborted ? "canceled" : "failed";
receipt.error = errorMessage(error);
@@ -335,10 +362,10 @@ export async function runComponentScans(
notify(() => options.onProgress?.(copyReceipt(receipt)));
}
}
- const { findings, matches, uncertain, related, error } =
+ const { findings, matches, uncertain, related, error, skipped } =
await deduplicateFindings(receipts, results, { ...options, environment });
const deduplication: ComponentDeduplicationSummary = {
- status: error === undefined ? "completed" : "failed",
+ status: skipped ? "skipped" : error === undefined ? "completed" : "failed",
confirmedGroups: matches.length,
uncertainPairs: uncertain.length,
...(error === undefined ? {} : { error }),
@@ -403,7 +430,11 @@ async function deduplicateFindings(
results: Map<string, ScanResult>,
options: ComponentScanOptions,
): Promise<
- ScanComparisonResult & { findings: CombinedFinding[]; error?: string }
+ ScanComparisonResult & {
+ findings: CombinedFinding[];
+ error?: string;
+ skipped?: boolean;
+ }
> {
const scans = receipts.flatMap((receipt) => {
const findings = results.get(receipt.id)?.findings.findings ?? [];
@@ -424,6 +455,8 @@ async function deduplicateFindings(
);
const matching: ScanComparisonResult = { matches: [], uncertain: [] };
const [first, ...remaining] = scans;
+ if (remaining.length && options.maxTotalCostUsd !== undefined)
+ return { ...matching, findings, skipped: true };
const componentFindings = ({
receipt,
findings,
@@ -525,6 +558,12 @@ function renderReport(
"# Component scan report",
"",
`${summary.completed} complete, ${summary.failed} failed. ${findings.length} finding groups.`,
+ ...(summary.deduplication?.status === "skipped"
+ ? [
+ "",
+ "Cross-component matching skipped under the total cost limit. Findings are listed separately.",
+ ]
+ : []),
...(summary.deduplication?.status === "failed"
? ["", `Cross-component matching failed: ${summary.deduplication.error}`]
: []),
diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.ts
index 86128bd1a..e46d745a2 100644
--- a/sdk/typescript/src/multiscan.ts
+++ b/sdk/typescript/src/multiscan.ts
@@ -33,6 +33,7 @@ import type { CodexSecurity, ScanOptions } from "./api.js";
import type { CodexSecurityConfig, JsonObject } from "./config.js";
import { ContractSchemaError, loadContract, readScanFile } from "./contract.js";
import type { ScanCost, ScanUsageMeasurement } from "./cost.js";
+import { BatchCostPool, batchScanBudget } from "./batch-cost.js";
import { deepScanOptions } from "./deep-config.js";
import { readThreatModelPath } from "./artifact-export.js";
import {
@@ -123,6 +124,7 @@ export interface MultiscanOptions extends ScanPromptSettings {
scanDir: string,
prompts: ScanPromptSettings &
Pick<ScanOptions, "onMeasurement" | "onTelemetry"> & {
+ maxTotalCostShareUsd?: number;
knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;
/** @internal Preserve correlation when the resumed SDK has no saved binding. */
telemetryContext?: { operationId: string; parentAttemptId?: string };
@@ -130,10 +132,12 @@ export interface MultiscanOptions extends ScanPromptSettings {
): Promise<
| (Pick<ScanResult, "manifest" | "cost" | "findings"> & {
usage?: JsonObject;
+ alreadyCompleted?: boolean;
})
| undefined
>;
maxCostUsd?: number;
+ maxTotalCostUsd?: number;
// Prompts are shared across modes and prepared from the top-level options.
scanOptionsByMode?: Partial<
Record<ScanMode, Omit<ScanSettings, keyof ScanPromptSettings>>
@@ -147,6 +151,7 @@ export interface MultiscanOptions extends ScanPromptSettings {
repository: string;
status: "started" | "completed" | "failed";
attempt: number;
+ maxCostUsd?: number;
error?: string;
warning?: string;
}): void;
@@ -432,6 +437,13 @@ async function runCampaign(
});
if (pending.length === 0) return summarize();
+ const pool =
+ options.maxTotalCostUsd === undefined
+ ? undefined
+ : new BatchCostPool(
+ options.maxTotalCostUsd,
+ pending.length * options.maxAttempts,
+ );
let next = 0;
let receiptTail = Promise.resolve();
const worker = async (
@@ -442,6 +454,11 @@ async function runCampaign(
const task = pending[next++];
if (task === undefined) return;
const knowledge = knowledgeByMode[task.mode];
+ const scanSettings = options.scanOptionsByMode?.[task.mode];
+ const budget = batchScanBudget(pool?.share, {
+ ...options,
+ maxCostUsd: options.maxCostUsd ?? scanSettings?.maxCostUsd,
+ });
const history = receipts.get(task.id.toLowerCase());
let operationId = history?.scan?.operationId;
let maxAttempt = history?.maxAttempt ?? 0;
@@ -479,9 +496,11 @@ async function runCampaign(
let attemptPolicyFailed: boolean | undefined;
let cost: Readonly<ScanCost> | null = null;
let measurement: Readonly<ScanUsageMeasurement> | null = null;
+ let reservation: ReturnType<BatchCostPool["reserve"]> | undefined;
let savedUsage: JsonObject | undefined;
const observers: Pick<ScanOptions, "onMeasurement" | "onTelemetry"> = {
onMeasurement: (value) => {
+ reservation?.record(value.cost);
measurement = value;
cost = value.cost;
},
@@ -495,11 +514,14 @@ async function runCampaign(
let knowledgeBaseFailure = false;
let checkoutOccupied = false;
try {
+ reservation = pool?.reserve(budget.maxCostUsd);
+ const maxCostUsd = reservation?.maxCostUsd ?? budget.maxCostUsd;
await ensureOutputDirectory(artifactRoot);
let result:
| (Pick<ScanResult, "manifest" | "cost" | "findings"> &
Partial<Pick<ScanResult, "threatModelPath">> & {
usage?: JsonObject;
+ alreadyCompleted?: boolean;
})
| undefined;
if (
@@ -529,6 +551,7 @@ async function runCampaign(
repository: task.id,
attempt,
status: "started",
+ maxCostUsd,
});
if (knowledge?.failure !== undefined) {
knowledgeBaseFailure = true;
@@ -536,6 +559,9 @@ async function runCampaign(
}
result = await options.recoverScan(scanDir, {
...options,
+ ...(options.maxTotalCostUsd === undefined
+ ? {}
+ : { maxTotalCostShareUsd: maxCostUsd }),
knowledgeBaseSnapshot: knowledge?.snapshot,
...observers,
...(operationId === undefined
@@ -545,7 +571,6 @@ async function runCampaign(
attemptedResume = result !== undefined;
}
}
- const scanSettings = options.scanOptionsByMode?.[task.mode];
if (result === undefined) {
if (options.recoverScan !== undefined) attempt = nextAttempt();
scanDir = join(artifactRoot, `attempt-${attempt}`);
@@ -553,6 +578,7 @@ async function runCampaign(
repository: task.id,
attempt,
status: "started",
+ maxCostUsd,
});
if (options.recoverScan === undefined)
await validateOutputDir(scanDir);
@@ -633,9 +659,8 @@ async function runCampaign(
...(options.postScanPrompt === undefined
? {}
: { postScanPrompt: options.postScanPrompt }),
- ...(options.maxCostUsd === undefined
- ? {}
- : { maxCostUsd: options.maxCostUsd }),
+ ...budget,
+ maxCostUsd,
...observers,
onWarning: (warning) => {
runWarnings.push(warning);
@@ -653,6 +678,7 @@ async function runCampaign(
}
threatModelPath = result.threatModelPath;
cost = result.cost;
+ if (!result.alreadyCompleted) reservation?.record(cost);
savedUsage = result.usage;
const failureSeverity = scanSettings?.failureSeverity;
if (failureSeverity !== undefined) {
@@ -667,8 +693,10 @@ async function runCampaign(
// Recovery retains its resumable attempt and checkout; SDK telemetry records cancellation.
if (options.signal?.aborted && options.recoverScan !== undefined)
options.signal.throwIfAborted();
+ if (pool && !reservation) exhaustedBudget = true;
if (error instanceof ScanCostLimitExceededError) {
cost = error.cost;
+ reservation?.record(cost);
exhaustedBudget = true;
}
requiresRecovery = error instanceof OutputDirectoryNotEmptyError;
diff --git a/sdk/typescript/src/scan-dashboard.ts b/sdk/typescript/src/scan-dashboard.ts
index ecddac4df..41742c2de 100644
--- a/sdk/typescript/src/scan-dashboard.ts
+++ b/sdk/typescript/src/scan-dashboard.ts
@@ -96,6 +96,7 @@ interface ScanDashboardOptions {
model?: ScanModelConfiguration;
pricingContext?: ScanPricingContext;
maxCostUsd?: number;
+ maxTotalCostUsd?: number;
showCost?: boolean;
clock: DashboardClock;
color?: boolean;
@@ -470,6 +471,7 @@ export class ScanDashboard {
...this.#options,
presentation: "scan",
componentName: receipt.name,
+ maxCostUsd: receipt.maxCostUsd ?? this.#options.maxCostUsd,
});
dashboard.setStage(COMPONENT_STATUS.pending);
dashboard.note(`Scope: ${receipt.paths.join(", ")}`);
@@ -486,6 +488,8 @@ export class ScanDashboard {
const { dashboard } = component;
if (receipt.status !== component.receipt.status) {
if (receipt.status === "started") {
+ if (receipt.maxCostUsd !== undefined)
+ dashboard.#options.maxCostUsd = receipt.maxCostUsd;
dashboard.#startedAt = this.#options.clock.now();
dashboard.setStage("Preparing scan");
} else if (receipt.status !== "pending") {
@@ -1057,7 +1061,9 @@ export class ScanDashboard {
get #showCost(): boolean {
return (
- this.#options.showCost === true || this.#options.maxCostUsd !== undefined
+ this.#options.showCost === true ||
+ this.#options.maxCostUsd !== undefined ||
+ this.#options.maxTotalCostUsd !== undefined
);
}
@@ -1072,11 +1078,20 @@ export class ScanDashboard {
const costs = this.#components.flatMap(({ dashboard }) =>
dashboard.#cost === null ? [] : [dashboard.#cost],
);
- return wrapActivity(
- " COST ",
- `${costs.length === 0 ? "waiting for usage" : formatScanCosts(costs)}${this.#components.some(({ dashboard }) => dashboard.#usageCoverage !== "complete") ? " (partial)" : ""} · component scans only`,
- this.#width(),
+ const partial = this.#components.some(
+ ({ dashboard }) => dashboard.#usageCoverage !== "complete",
);
+ const lines = [
+ (costs.length ? formatScanCosts(costs) : "waiting for usage") +
+ (partial ? " (partial)" : ""),
+ "component scans only",
+ ];
+ if (this.#options.maxTotalCostUsd !== undefined)
+ lines.push(`${formatUsd(this.#options.maxTotalCostUsd)} total limit`);
+ const perComponent = this.#components[0]?.receipt.maxCostUsd;
+ if (perComponent !== undefined)
+ lines.push(`up to ${formatUsd(perComponent)} per component`);
+ return wrapActivity(" COST ", lines.join(" · "), this.#width());
}
#width(): number {
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index bbd042ce3..dde633bd4 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -14331,6 +14331,7 @@ if __name__ == "__main__":
["semantic matching fails", "matcher", "matcher unavailable"],
["the repository index fails", "index", "index unavailable"],
["the repository projection is unavailable", "projection", undefined],
+ ["a batch cost limit skips unmetered matching", "batch-budget", undefined],
["a cost limit still allows false-positive matching", "budget", undefined],
[
"cost-limited matching needs additional context",
@@ -14370,7 +14371,9 @@ if __name__ == "__main__":
[nativeHeader]: " synthetic-required-header ",
}
: {};
- const limited = failure === "budget" || failure === "budget-context";
+ const boundedBatch = failure === "batch-budget";
+ const limited =
+ boundedBatch || failure === "budget" || failure === "budget-context";
const { root, repository, codexHome, scanDir } = await scanDirectories();
const current = {
findingId: "csf_852f90d6e1177502ff113d4a",
@@ -14544,7 +14547,10 @@ if __name__ == "__main__":
},
{
...scanRuntimeDependencies(codexHome, scanDir),
- environment: gatewayEnvironment,
+ environment: {
+ ...gatewayEnvironment,
+ CODEX_SECURITY_STATE_DIR: join(root, "state"),
+ },
prepareRuntime: runtimePreparer(codexHome, () => ({
environment: {
SYNTHETIC_MATCH_HEADER: "synthetic-comparison-header",
@@ -14791,6 +14797,7 @@ if __name__ == "__main__":
try {
const result = await client.run(repository, {
ownerSuggestions: ownerSpy !== undefined,
+ skipFindingMatching: boundedBatch,
...(limited ? { maxCostUsd: 1 } : {}),
cyberAccessProgram: "daybreak_blue",
onProgress() {},
@@ -14803,7 +14810,7 @@ if __name__ == "__main__":
expect(
result.repositoryFindings?.map(({ findingId }) => findingId),
).toEqual(
- failure === "budget"
+ failure === "budget" || boundedBatch
? ["another-open-finding"]
: failure === "dismissed" ||
failure === "managed" ||
@@ -14811,17 +14818,12 @@ if __name__ == "__main__":
? []
: undefined,
);
- expect(modelCalled).toBe(
- failure !== "index" && failure !== "projection",
- );
- expect(observedSingleTurn).toBe(
- failure === "index" || failure === "projection" ? undefined : limited,
- );
+ const expectsModel =
+ !boundedBatch && failure !== "index" && failure !== "projection";
+ expect(modelCalled).toBe(expectsModel);
+ expect(observedSingleTurn).toBe(expectsModel ? limited : undefined);
expect(matchingTurns).toBe(
- failure === "index" ||
- failure === "projection" ||
- failure === "matcher" ||
- failure === "managed"
+ !expectsModel || failure === "matcher" || failure === "managed"
? 0
: 1,
);
diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.ts
index 31c16f2d5..20206562a 100644
--- a/sdk/typescript/tests-ts/cli-help.test.ts
+++ b/sdk/typescript/tests-ts/cli-help.test.ts
@@ -96,6 +96,14 @@ describe("CLI help", () => {
expect(text).toContain("<command> --help");
});
+ test.each(["bulk-scan", "scan-components"])(
+ "labels %s cost limits in USD",
+ async (command) => {
+ const text = await help([command, "--help"]);
+ expect(option(text, "--max-total-cost")).toContain("<usd>");
+ },
+ );
+
test("shows semantic values, repeatable inputs, choices, and scan defaults", async () => {
const text = await help(["scan", "--help"]);
expect(text).toContain("Usage: codex-security scan [repository]");
diff --git a/sdk/typescript/tests-ts/cli-patch.test.ts b/sdk/typescript/tests-ts/cli-patch.test.ts
index 65f1b35e7..5225df6af 100644
--- a/sdk/typescript/tests-ts/cli-patch.test.ts
+++ b/sdk/typescript/tests-ts/cli-patch.test.ts
@@ -2361,6 +2361,24 @@ describe("scan and patch workflow", () => {
}
});
+ test("shows findings without offering interactive patches on a budgeted scan", async () => {
+ const confirmPatchReview = mock(resolving(true));
+ const patchEditor = mock(resolving(null));
+ const outcome = await runWorkflow(
+ ["scan", "--max-cost", "1"],
+ { result: resultWithFindings(["high"]) },
+ {
+ interactive: true,
+ configure: (value) =>
+ Object.assign(value, { confirmPatchReview, patchEditor }),
+ },
+ );
+ expect(outcome.exitCode).toBe(0);
+ expect(outcome.stderr).toContain("FINDINGS");
+ expect(confirmPatchReview).not.toHaveBeenCalled();
+ expect(patchEditor).not.toHaveBeenCalled();
+ });
+
test("shows normal scan findings before optionally opening patch review", async () => {
for (const review of [true, false]) {
let opened = false;
diff --git a/sdk/typescript/tests-ts/cli-project-config.test.ts b/sdk/typescript/tests-ts/cli-project-config.test.ts
index b1bd29d05..943aabba4 100644
--- a/sdk/typescript/tests-ts/cli-project-config.test.ts
+++ b/sdk/typescript/tests-ts/cli-project-config.test.ts
@@ -392,6 +392,29 @@ test("rerun rejects a blank replacement when scan instructions are required", as
expect(onConfig).not.toHaveBeenCalled();
});
+test.each(["project", "flag"])(
+ "rejects patching before starting a scan with a %s budget",
+ async (source) => {
+ const input = await fixture({ limits: { max_cost_usd_per_scan: 1 } });
+ const onRun = mock(throwing("unexpected scan"));
+ const onCodex = mock(throwing("unexpected patch"));
+ const stderr = captureCli(main, "stderr");
+ const budget =
+ source === "project" ? ["-c", input.config] : ["--max-cost", "1"];
+ expect(
+ await stderr.run(
+ ["scan", input.repository, "--patch", ...budget, "--json"],
+ dependencies({ onRun, onCodex }),
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toContain(
+ "--patch cannot be combined with a scan cost limit",
+ );
+ expect(onRun).not.toHaveBeenCalled();
+ expect(onCodex).not.toHaveBeenCalled();
+ },
+);
+
test.each(["instructions_file", "validation_file"] as const)(
"bulk %s retains directory-link protection for local CSV repositories",
async (file) => {
diff --git a/sdk/typescript/tests-ts/component-scan.test.ts b/sdk/typescript/tests-ts/component-scan.test.ts
index 2293cb03c..f191d082f 100644
--- a/sdk/typescript/tests-ts/component-scan.test.ts
+++ b/sdk/typescript/tests-ts/component-scan.test.ts
@@ -484,6 +484,69 @@ test("omits a failed component's stale model link while retaining its model", as
);
});
+test.each([
+ [9, 2],
+ [3, 1],
+])(
+ "divides a $%i budget across concurrent components",
+ async (total, expected) => {
+ const paths = await fixture();
+ const config = join(paths.root, "settings.yaml");
+ await writeFile(config, "scan:\n owner_suggestions: true\n");
+ const matchFindings = mock(rejecting("unexpected unmetered model call"));
+ const { code, stderr, stdout } = await cli(
+ paths,
+ [
+ ...components.flatMap(({ paths }) => ["--component", paths[0]!]),
+ "--config",
+ config,
+ "--workers",
+ "3",
+ "--max-cost",
+ "2",
+ "--max-total-cost",
+ String(total),
+ ],
+ {
+ createSecurity: client(async (repository, options) => {
+ expect(options.maxCostUsd).toBe(expected);
+ expect(options.skipFindingMatching).toBe(true);
+ expect(options.ownerSuggestions).toBe(false);
+ return completed(repository, options);
+ }),
+ matchFindings,
+ },
+ );
+ expect(code).toBe(0);
+ expect(JSON.parse(stdout)).toMatchObject({
+ completed: 3,
+ findingCount: 3,
+ deduplication: { status: "skipped" },
+ });
+ expect(stderr).toContain(`$${expected}.00 per component`);
+ expect(matchFindings).not.toHaveBeenCalled();
+ },
+);
+
+test("rejects unmetered planning and post-scan prompts under a total limit", async () => {
+ const paths = await fixture();
+ const planComponents = mock(rejecting("unexpected planner call"));
+ const result = await cli(
+ paths,
+ ["--auto", "--plan-only", "--max-total-cost", "2"],
+ { planComponents },
+ );
+ expect(result.code).toBe(2);
+ expect(result.stderr).toContain("--component or --components-file");
+ expect(planComponents).not.toHaveBeenCalled();
+ await expect(
+ scan(paths, {
+ maxTotalCostUsd: 2,
+ scanOptions: { postScanPrompt: "Extra turn" },
+ }),
+ ).rejects.toThrow("post-scan prompt");
+});
+
test("bounds standard scans, continues after failure, and preserves partial results", async () => {
const paths = await fixture();
let active = 0,
@@ -496,6 +559,7 @@ test("bounds standard scans, continues after failure, and preserves partial resu
scanOptions: {
auth: "chatgpt",
scanPrompt: "Check access controls",
+ ownerSuggestions: true,
maxCostUsd: 3,
},
onProgress: throwing("optional observer"),
@@ -510,6 +574,7 @@ test("bounds standard scans, continues after failure, and preserves partial resu
mode: "standard",
auth: "chatgpt",
scanPrompt: "Check access controls",
+ ownerSuggestions: true,
maxCostUsd: 3,
});
if (scope(repository, options) === "apps/api")
diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.ts
index 5e42caba6..f290c4dce 100644
--- a/sdk/typescript/tests-ts/multiscan.test.ts
+++ b/sdk/typescript/tests-ts/multiscan.test.ts
@@ -44,6 +44,85 @@ afterEach(cleanup);
const testPosix = test.skipIf(process.platform === "win32");
describe("multiscan", () => {
+ test("divides an invocation budget across pending repositories and retries", async () => {
+ const paths = await fixture();
+ const source = await repository(paths.root, "source");
+ await writeFile(
+ paths.input,
+ `id,repository,revision
+first,${source.path},${source.revision}
+second,${source.path},${source.revision}
+`,
+ );
+ const limits: number[] = [];
+ const bothStarted = Promise.withResolvers<void>();
+ const summary = await runMultiscan(
+ options(
+ paths,
+ client(async (_checkout, scan = {}) => {
+ limits.push(scan.maxCostUsd!);
+ expect(scan.skipFindingMatching).toBe(true);
+ expect(scan.ownerSuggestions).toBe(false);
+ if (scan.outputDir!.endsWith("attempt-1")) {
+ if (limits.length === 2) bothStarted.resolve();
+ await bothStarted.promise;
+ throw new Error("Retry this repository");
+ }
+ return completedScan(scan.outputDir!);
+ }),
+ {
+ maxCostUsd: 12,
+ maxTotalCostUsd: 8,
+ workers: 2,
+ maxAttempts: 2,
+ scanOptionsByMode: { standard: { ownerSuggestions: true } },
+ },
+ ),
+ );
+ expect(summary).toMatchObject({ completed: 2, failed: 0 });
+ expect(limits).toEqual([2, 2, 2, 2]);
+ });
+
+ test("charges observed overruns before dispatching queued repository attempts", async () => {
+ const paths = await fixture();
+ const source = await repository(paths.root, "source");
+ const rows = ["first", "second", "third"].map(
+ (id) => `${id},${source.path},${source.revision}`,
+ );
+ await writeFile(
+ paths.input,
+ ["id,repository,revision", ...rows].join("\n"),
+ );
+ const limits: number[] = [];
+ const summary = await runMultiscan(
+ options(
+ paths,
+ client(async (_repo, scan = {}) => {
+ limits.push(scan.maxCostUsd!);
+ const estimatedUsd = limits.length === 1 ? 5 : 2;
+ throw new ScanCostLimitExceededError(
+ scan.maxCostUsd!,
+ {
+ model: "gpt-5.6-sol",
+ inputTokens: 10,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: 10,
+ estimatedUsd,
+ },
+ scan.outputDir!,
+ );
+ }),
+ { workers: 1, maxAttempts: 1, maxTotalCostUsd: 6 },
+ ),
+ );
+ expect(limits).toEqual([2, 1]);
+ expect(summary).toMatchObject({ failed: 3 });
+ expect((await results(summary.resultsPath)).at(-1)?.["error"]).toContain(
+ "invocation cost limit is exhausted",
+ );
+ });
+
test("prepares shared prompt files once while missing sources remain row failures", async () => {
const paths = await fixture();
const source = await repository(paths.root, "prompt-source");
diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.ts
index 7291a05bb..0c4992384 100644
--- a/sdk/typescript/tests-ts/scan-resume.test.ts
+++ b/sdk/typescript/tests-ts/scan-resume.test.ts
@@ -58,6 +58,8 @@ async function interruptedScan(
settings: Pick<
ScanOptions,
| "safetyIdentifier"
+ | "maxCostUsd"
+ | "ownerSuggestions"
| "postScanPrompt"
| "auth"
| "knowledgeBasePaths"
@@ -772,6 +774,50 @@ test.each([false, true])(
},
);
+test.each([
+ [undefined, 2],
+ [1, 1],
+])(
+ "applies the invocation share when recovering a scan with saved limit %p",
+ async (savedLimit, expected) => {
+ const f = await interruptedScan("deep", true, {
+ maxCostUsd: savedLimit,
+ ownerSuggestions: true,
+ });
+ const seen: ScanOptions[] = [];
+ const deps = dependencies({
+ environment: f.environment,
+ currentDirectory: f.root,
+ onTurn: (_repo, options) => seen.push(options),
+ });
+ deps.runWorkbench = f.command;
+ const { runCli } = createCliTest(main);
+ await runCli(
+ [
+ "bulk-scan",
+ f.input,
+ "--output-dir",
+ f.root,
+ "--recover",
+ "--max-attempts",
+ "2",
+ "--max-total-cost",
+ "4",
+ "--json",
+ ],
+ deps,
+ );
+ expect(seen).toMatchObject([
+ {
+ resumeScanId: f.scanId,
+ maxCostUsd: expected,
+ skipFindingMatching: true,
+ ownerSuggestions: false,
+ },
+ ]);
+ },
+);
+
test("resuming reports a committed cancellation once without another launch", async () => {
const f = await interruptedScan();
const { stderr, runCli } = createCliTest(main);