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): explain why deep scans stop (#577)

ianw-oai2a132e82d34a
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index ab30d913a..e16136ea2 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -5497,6 +5497,16 @@ async function executeScan(
? result.toJSON()
: { ...result.toJSON(), warnings: targetWarnings };
const incomplete = result.coverage.completeness !== "complete";
+ let deepScanStop: DeepScanStop | undefined;
+ if (arguments_.mode === "deep") {
+ deepScanStop = (await readDeepScanStop(
+ result,
+ arguments_.maxCostUsd,
+ dependencies.runWorkbench,
+ ).catch(() => undefined)) ?? {
+ reason: "Stop reason unavailable. See the report for details.",
+ };
+ }
progress?.stage(`Scan complete · ${result.manifest.scan.id.slice(0, 8)}`);
printScanSummary(
result,
@@ -5505,6 +5515,7 @@ async function executeScan(
progress?.interactive === true &&
dependencies.environment["NO_COLOR"] === undefined &&
dependencies.environment["TERM"] !== "dumb",
+ deepScanStop,
);
const completedScan = (exitCode: number): ScanOutcome => {
diagnostic("scan.completed", {
@@ -5766,11 +5777,81 @@ function scanPhase(value: ScanWorkerPhase | ScanPhase): string {
}[value];
}
+interface DeepScanStop {
+ reason: string;
+ nextStep?: string;
+}
+
+async function readDeepScanStop(
+ result: ScanResult,
+ maxCostUsd: number | undefined,
+ runWorkbench: CliDependencies["runWorkbench"],
+): Promise<DeepScanStop | undefined> {
+ if (
+ maxCostUsd !== undefined &&
+ result.cost !== null &&
+ result.cost.estimatedUsd > maxCostUsd
+ ) {
+ return {
+ reason: `Reached the ${formatUsd(maxCostUsd)} cost limit. More issues may remain.`,
+ nextStep: "To scan further, rerun with a higher --max-cost.",
+ };
+ }
+ const response = await runWorkbench([
+ "get-deep-scan",
+ "--scan-id",
+ result.manifest.scan.id,
+ "--thread-id",
+ result.threadId,
+ ]);
+ const state = response["deepScan"] as
+ | {
+ terminalReason: string;
+ dispatchedCount: number;
+ completionSequence: number;
+ noNewStreak: number;
+ config: Required<DeepScanOptions>;
+ createdAt: string;
+ completedAt: string;
+ }
+ | undefined;
+ if (state?.terminalReason === "saturated") {
+ return {
+ reason: `The last ${state.noNewStreak} review rounds found no new issues. More issues may remain.`,
+ };
+ }
+ if (state?.terminalReason !== "capped") return undefined;
+ const { maxDiscoveryRuns, maxTimeHours } = state.config;
+ if (state.dispatchedCount >= maxDiscoveryRuns) {
+ const stillFindingIssues =
+ state.completionSequence > 0 && state.noNewStreak === 0;
+ return {
+ reason: `Reached the limit of ${maxDiscoveryRuns} review rounds. ${stillFindingIssues ? "The latest review still found new issues." : "More issues may remain."}`,
+ nextStep: `To scan further, rerun with --max-discovery-runs greater than ${maxDiscoveryRuns}.`,
+ };
+ }
+ const elapsedHours =
+ (Date.parse(state.completedAt) - Date.parse(state.createdAt)) / 3_600_000;
+ if (elapsedHours >= maxTimeHours) {
+ return {
+ reason: `Reached the ${maxTimeHours}-hour time limit. More issues may remain.`,
+ nextStep:
+ maxTimeHours < 96
+ ? "To scan further, rerun with a higher --max-time-hours."
+ : "To scan a smaller part of the repository, rerun with --path.",
+ };
+ }
+ return {
+ reason: "Stopped before the review finished. See the report for details.",
+ };
+}
+
function printScanSummary(
result: ScanResult,
progress: Progress | null,
errorOutput: Writable,
color: boolean,
+ deepScanStop?: DeepScanStop,
): void {
const paint = (value: string, code: number | string): string =>
color ? `\u001B[${code}m${value}\u001B[0m` : value;
@@ -5821,6 +5902,9 @@ function printScanSummary(
`\n ${paint("REPORT", "1;36")} ${paint(errorMessage(result.reportPath), 4)}\n\n` +
` ${paint("FINDINGS", 1)} ${paint(`${findingCount}${findingSummary === "" ? "" : ` (${findingSummary})`}`, findingColor)}\n` +
` ${paint("COVERAGE", 1)} ${result.coverage.completeness}\n` +
+ (deepScanStop === undefined
+ ? ""
+ : ` ${paint("STOPPED", 1)} ${deepScanStop.reason}\n`) +
` ${paint("ELAPSED", 1)} ${duration}\n`,
);
@@ -5836,6 +5920,9 @@ function printScanSummary(
errorOutput.write(
` ${paint("RESULTS", 1)} ${errorMessage(result.scanDir)}\n`,
);
+ if (deepScanStop?.nextStep !== undefined) {
+ errorOutput.write(`\n ${deepScanStop.nextStep}\n`);
+ }
}
function formatTokenUsage(usage: unknown): string | null {
diff --git a/sdk/typescript/tests-ts/cli-deep-scan-summary.test.ts b/sdk/typescript/tests-ts/cli-deep-scan-summary.test.ts
new file mode 100644
index 000000000..b4b358c69
--- /dev/null
+++ b/sdk/typescript/tests-ts/cli-deep-scan-summary.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import { main } from "../src/cli.js";
+import type { JsonObject } from "../src/config.js";
+import { capture, dependencies, fakeResult } from "./cli-fixtures.js";
+
+const cappedState: JsonObject = {
+ terminalReason: "capped",
+ dispatchedCount: 40,
+ completionSequence: 40,
+ noNewStreak: 0,
+ config: { maxDiscoveryRuns: 40, maxTimeHours: 96 },
+ createdAt: "2026-01-01T00:00:00Z",
+ completedAt: "2026-01-01T01:00:00Z",
+};
+
+async function summary(
+ options: Parameters<typeof dependencies>[0],
+ args = ["--mode", "deep"],
+) {
+ const stdout = capture();
+ const stderr = capture();
+ const result = options?.result ?? fakeResult(["high"], "partial");
+ expect(
+ await main(
+ ["scan", ...args, "--json"],
+ stdout.stream,
+ stderr.stream,
+ dependencies({ ...options, result }),
+ ),
+ ).toBe(result.coverage.completeness === "complete" ? 0 : 2);
+ expect(JSON.parse(stdout.text())).toEqual(result.toJSON());
+ return stderr.text();
+}
+
+describe("deep scan completion summary", () => {
+ test.each([
+ [
+ "review limit while finding issues",
+ {},
+ "40 review rounds. The latest review still found new issues",
+ "--max-discovery-runs greater than 40",
+ ],
+ [
+ "quiet round",
+ { noNewStreak: 1 },
+ "More issues may remain",
+ "--max-discovery-runs",
+ ],
+ [
+ "no recent new issues",
+ { terminalReason: "saturated", noNewStreak: 4 },
+ "last 4 review rounds found no new issues",
+ null,
+ ],
+ [
+ "time limit",
+ {
+ dispatchedCount: 3,
+ config: { maxDiscoveryRuns: 40, maxTimeHours: 0.5 },
+ },
+ "0.5-hour time limit",
+ "higher --max-time-hours",
+ ],
+ [
+ "maximum time limit",
+ { dispatchedCount: 3, completedAt: "2026-01-05T00:00:00Z" },
+ "96-hour time limit",
+ "rerun with --path",
+ ],
+ [
+ "another early stop",
+ { dispatchedCount: 3 },
+ "Stopped before the review finished",
+ null,
+ ],
+ ] as const)("explains %s", async (_name, overrides, reason, next) => {
+ const text = await summary({
+ onWorkbench: (args) => {
+ expect(args).toEqual([
+ "get-deep-scan",
+ "--scan-id",
+ "scan",
+ "--thread-id",
+ "thread-1",
+ ]);
+ return { deepScan: { ...cappedState, ...overrides } };
+ },
+ });
+ expect(text).toContain("STOPPED");
+ expect(text).toContain(reason);
+ if (next !== null) expect(text).toContain(next);
+ expect(text).not.toMatch(/saturat|merged|reducer/i);
+ });
+
+ test("uses the overall cost limit even if discovery stopped earlier", async () => {
+ const text = await summary(
+ {
+ result: fakeResult([], "partial", {
+ input_tokens: 1_250,
+ cached_input_tokens: 200,
+ output_tokens: 30,
+ }),
+ onWorkbench: () => {
+ throw new Error("The exceeded cost limit is already known");
+ },
+ },
+ ["--mode", "deep", "--max-cost", "0.005"],
+ );
+ expect(text).toContain("Reached the $0.005 cost limit");
+ expect(text).toContain("higher --max-cost");
+ expect(text).not.toContain("--max-discovery-runs");
+ });
+
+ test.each([false, true])(
+ "keeps the result when stop details are unavailable (read fails: %s)",
+ async (fails) => {
+ const text = await summary({
+ result: fakeResult(),
+ onWorkbench: () => {
+ if (fails) throw new Error("read failed");
+ return {};
+ },
+ });
+ expect(text).toContain("STOPPED Stop reason unavailable");
+ },
+ );
+
+ test("leaves standard scan summaries unchanged", async () => {
+ let reads = 0;
+ const text = await summary(
+ {
+ result: fakeResult(),
+ onWorkbench: () => {
+ reads++;
+ return {};
+ },
+ },
+ [],
+ );
+ expect(reads).toBe(0);
+ expect(text).not.toContain("STOPPED");
+ });
+});