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
fix(cli): explain why deep scans stop (#577)
ianw-oai2a132e82d34a
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 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.tsnew file mode 100644index 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");+ });+});