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(sdk): expose deep scan progress (#710)
akosiakov-oai0bc42c69d336
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.mjs b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.mjsindex 2ad79adef..0dd9ff270 100644--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.mjs+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.mjs@@ -478,6 +478,7 @@ async function testDeepScanStdioLifecycle() {assert.deepEqual(paused.scan.progress.independentReviews, {completed: 1,active: 0,+ maximum: 2,consolidating: false});assert.deepEqual(diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.pyindex a9de0bffe..80f679524 100644--- a/plugins/codex-security/scripts/deep_scan_workbench.py+++ b/plugins/codex-security/scripts/deep_scan_workbench.py@@ -496,7 +496,11 @@ def independent_review_progress(connection: sqlite3.Connection, scan_id: str) -> dict[str, int | str] | None:run = connection.execute(- "SELECT completion_sequence, phase, updated_at FROM deep_scan_runs WHERE scan_id = ?",+ """+ SELECT completion_sequence, phase, updated_at, max_discovery_runs+ FROM deep_scan_runs+ WHERE scan_id = ?+ """,(scan_id,),).fetchone()if run is None:@@ -514,6 +518,7 @@ def independent_review_progress(return {"active": int(active),"completed": int(run["completion_sequence"]),+ "maximum": int(run["max_discovery_runs"]),"consolidating": run["phase"] == "reducing","updatedAt": str(run["updated_at"]),}diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.pyindex 69e58b0d5..219efcb6b 100644--- a/plugins/codex-security/scripts/workbench_db.py+++ b/plugins/codex-security/scripts/workbench_db.py@@ -3293,6 +3293,7 @@ def scan_result(progress_result["independentReviews"] = {"active": independent_reviews["active"],"completed": independent_reviews["completed"],+ "maximum": independent_reviews["maximum"],"consolidating": independent_reviews["consolidating"],}return {diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.pyindex 2e39cd074..545e9b575 100644--- a/plugins/codex-security/tests/test_workbench_deep_scan.py+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py@@ -435,6 +435,7 @@ def test_paused_discovery_resumes_after_restart_with_original_handoff_claim(assert paused["progress"]["independentReviews"] == {"completed": 1,"active": 0,+ "maximum": 2,"consolidating": False,}assert (paused["reportAvailable"], paused["findingCount"], paused["artifacts"]) == (@@ -1109,7 +1110,12 @@ def test_scan_progress_projects_active_and_completed_independent_reviews(context = run_workbench(state_dir, "get-scan", "--scan-id", scan_id)return context["scan"]["progress"]["independentReviews"]- assert independent_reviews() == {"active": 0, "completed": 0, "consolidating": False}+ assert independent_reviews() == {+ "active": 0,+ "completed": 0,+ "maximum": 40,+ "consolidating": False,+ }first_prompt, first_artifacts, first_result = worker_paths(scan_dir, "discovery-1")second_prompt, second_artifacts, _ = worker_paths(scan_dir, "discovery-2")@@ -1137,7 +1143,12 @@ def test_scan_progress_projects_active_and_completed_independent_reviews(artifact_dir=second_artifacts,attempt=1,)- assert independent_reviews() == {"active": 2, "completed": 0, "consolidating": False}+ assert independent_reviews() == {+ "active": 2,+ "completed": 0,+ "maximum": 40,+ "consolidating": False,+ }first_result.write_text("{}\n")upsert_worker(@@ -1152,7 +1163,12 @@ def test_scan_progress_projects_active_and_completed_independent_reviews(result_path=first_result,attempt=1,)- assert independent_reviews() == {"active": 1, "completed": 1, "consolidating": False}+ assert independent_reviews() == {+ "active": 1,+ "completed": 1,+ "maximum": 40,+ "consolidating": False,+ }upsert_worker(state_dir,@@ -1165,7 +1181,12 @@ def test_scan_progress_projects_active_and_completed_independent_reviews(artifact_dir=second_artifacts,attempt=1,)- assert independent_reviews() == {"active": 0, "completed": 1, "consolidating": False}+ assert independent_reviews() == {+ "active": 0,+ "completed": 1,+ "maximum": 40,+ "consolidating": False,+ }def test_reducer_claim_updates_review_pass_once_and_projects_consolidation(@@ -1217,6 +1238,7 @@ def test_reducer_claim_updates_review_pass_once_and_projects_consolidation(assert progress["independentReviews"] == {"active": 0,"completed": 2,+ "maximum": 40,"consolidating": True,}diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 7b71e940d..aef85bd58 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -152,7 +152,10 @@ Options for `security.run(repository, options)` and| `signal` | `AbortSignal` to cancel a scan. |Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives-saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.+saved events with thread IDs and worker numbers. Deep scans can additionally use+`onDeepProgress` for durable independent-review counts: `completed`, `active`,+and `maximum`. The maximum is a configured cap, not a percentage denominator.+`ScanOptions` lists all callbacks.`preflight` and CLI `--dry-run` check local inputs without starting Codex orusing the network. They don't authenticate, verify model access, resolve Python,diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjsindex 06bddf458..313f99fec 100644--- a/sdk/typescript/scripts/check-package.mjs+++ b/sdk/typescript/scripts/check-package.mjs@@ -179,6 +179,7 @@ const distFiles = new Set("custom-validation","custom-validation-prompt","custom-publish",+ "deep-progress","errors","github","index",diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 854bf67f0..ca308aadf 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -62,6 +62,10 @@ import {type ScanCost,type ScanSessionEvent,} from "./cost.js";+import {+ DeepScanProgressTracker,+ type DeepScanProgress,+} from "./deep-progress.js";import {loadContract,readScanFile,@@ -251,6 +255,7 @@ export interface ScanOptions extends DeepScanOptions {onActivity?: (activity: ScanActivity) => void;onSessionEvent?: (event: ScanSessionEvent) => void;onProgress?: (progress: ScanProgress) => void;+ onDeepProgress?: (progress: DeepScanProgress) => void;onWorkerStatus?: (status: ScanWorkerStatus) => void;onWarning?: (warning: string, details?: ScanWarningDetails) => void;onObserverError?: (observer: ScanObserverName, error: unknown) => void;@@ -338,6 +343,7 @@ type ScanObserverName =| "onActivity"| "onSessionEvent"| "onProgress"+ | "onDeepProgress"| "onWorkerStatus"| "onWarning";@@ -746,6 +752,7 @@ export class CodexSecurity {let targetPathsFile: string | null = null;let knowledgeBase: PreparedKnowledgeBase | null = null;let costTracker: ScanCostTracker | null = null;+ let deepProgressTracker: DeepScanProgressTracker | null = null;let releaseCredentialHome: (() => Promise<void>) | null = null;let scanFailure = false;let customValidationComplete = false;@@ -1142,6 +1149,37 @@ export class CodexSecurity {);}activeScan = { id: scanId, options: workbenchOptions };+ if (mode === "deep" && options.onDeepProgress !== undefined) {+ let progressWarningReported = false;+ deepProgressTracker = new DeepScanProgressTracker({+ read: (progressSignal) =>+ workbench(+ {+ ...workbenchOptions,+ signal: AbortSignal.any([signal, progressSignal]),+ },+ ["get-scan", "--scan-id", scanId],+ ),+ onProgress: (progress) =>+ notifyObserver(+ "onDeepProgress",+ options.onDeepProgress,+ options.onObserverError,+ progress,+ ),+ onError: (error) => {+ if (progressWarningReported) return;+ progressWarningReported = true;+ notifyObserver(+ "onWarning",+ options.onWarning,+ options.onObserverError,+ `Could not track Deep Scan progress: ${errorMessage(error)}`,+ );+ },+ });+ deepProgressTracker.start();+ }if (options.validationPrompt !== undefined) {await writeCustomValidationStatus(scanDir,@@ -1721,6 +1759,7 @@ export class CodexSecurity {}throw failure;} finally {+ deepProgressTracker?.stop();// Removing the temporary scan inputs is best effort. A throw here would replace the// outcome the try and catch blocks already produced, so these failures are reported// as warnings: a scan that failed has to say why it failed, not why its temporarydiff --git a/sdk/typescript/src/deep-progress.ts b/sdk/typescript/src/deep-progress.tsnew file mode 100644index 000000000..08487c415--- /dev/null+++ b/sdk/typescript/src/deep-progress.ts@@ -0,0 +1,137 @@+export interface DeepScanProgress {+ completed: number;+ active: number;+ maximum: number;+}++interface DeepScanProgressTrackerOptions {+ read: (signal: AbortSignal) => Promise<unknown>;+ onProgress: (progress: DeepScanProgress) => void;+ onError?: (error: unknown) => void;+ pollIntervalMs?: number;+}++const DEEP_PROGRESS_POLL_INTERVAL_MS = 5_000;++export class DeepScanProgressTracker {+ readonly #options: DeepScanProgressTrackerOptions;+ #timer: NodeJS.Timeout | null = null;+ #pending: Promise<void> | null = null;+ #abortController: AbortController | null = null;+ #lastProgress: DeepScanProgress | null = null;+ #stopped = false;++ public constructor(options: DeepScanProgressTrackerOptions) {+ this.#options = options;+ }++ public start(): void {+ if (this.#timer !== null || this.#stopped) return;+ const poll = () => {+ void this.refresh().catch((error: unknown) => {+ this.#options.onError?.(error);+ });+ };+ this.#timer = setInterval(+ poll,+ this.#options.pollIntervalMs ?? DEEP_PROGRESS_POLL_INTERVAL_MS,+ );+ this.#timer.unref();+ poll();+ }++ public async refresh(): Promise<void> {+ if (this.#stopped) return;+ if (this.#pending !== null) return await this.#pending;+ const abortController = new AbortController();+ this.#abortController = abortController;+ let update: Promise<void> | null = null;+ update = (async () => {+ try {+ const progress = deepScanProgressFromWorkbench(+ await this.#options.read(abortController.signal),+ );+ if (+ this.#stopped ||+ abortController.signal.aborted ||+ progress === null ||+ sameProgress(progress, this.#lastProgress)+ ) {+ return;+ }+ this.#lastProgress = progress;+ this.#options.onProgress(progress);+ } catch (error) {+ if (this.#stopped || abortController.signal.aborted) return;+ throw error;+ } finally {+ if (this.#pending === update) this.#pending = null;+ if (this.#abortController === abortController) {+ this.#abortController = null;+ }+ }+ })();+ this.#pending = update;+ await update;+ }++ public stop(): void {+ if (this.#stopped) return;+ this.#stopped = true;+ if (this.#timer !== null) {+ clearInterval(this.#timer);+ this.#timer = null;+ }+ this.#abortController?.abort();+ this.#abortController = null;+ }+}++export function deepScanProgressFromWorkbench(+ result: unknown,+): DeepScanProgress | null {+ if (!isRecord(result) || !isRecord(result["scan"])) return null;+ const progress = result["scan"]["progress"];+ if (!isRecord(progress)) return null;+ const independentReviews = progress["independentReviews"];+ if (independentReviews === undefined) return null;+ if (+ !isRecord(independentReviews) ||+ !isCount(independentReviews["completed"]) ||+ !isCount(independentReviews["active"]) ||+ !isPositiveCount(independentReviews["maximum"])+ ) {+ throw new Error(+ "Codex Security workbench returned invalid Deep Scan progress.",+ );+ }+ return {+ completed: independentReviews["completed"],+ active: independentReviews["active"],+ maximum: independentReviews["maximum"],+ };+}++function sameProgress(+ left: DeepScanProgress,+ right: DeepScanProgress | null,+): boolean {+ return (+ right !== null &&+ left.completed === right.completed &&+ left.active === right.active &&+ left.maximum === right.maximum+ );+}++function isCount(value: unknown): value is number {+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;+}++function isPositiveCount(value: unknown): value is number {+ return isCount(value) && value > 0;+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === "object" && !Array.isArray(value);+}diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex eeca8727d..29de039dd 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -14,6 +14,7 @@ export type {} from "./component-plan.js";export { estimateScanCost } from "./cost.js";export type { ScanCost, ScanSessionEvent } from "./cost.js";+export type { DeepScanProgress } from "./deep-progress.js";export type { CustomValidationResult } from "./custom-validation.js";export type { ScanActivity, ScanActivityStatus } from "./scan-activity.js";export type {diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex 3c8f6249a..e258155f5 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -34,6 +34,7 @@ import {OutputInsideProtectedRootError,type ScanAuthentication,ScanCostLimitExceededError,+ type DeepScanProgress,type ScanOptions,type ScanProgress,type ScanSessionEvent,@@ -2643,6 +2644,71 @@ describe("CodexSecurity orchestration", () => {await client.close();});+ test("forwards durable Deep Scan independent-review progress", async () => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ await mkdir(repository);+ await mkdir(codexHome);+ await mkdir(scanDir, { mode: 0o700 });+ const updates: DeepScanProgress[] = [];+ const environment = { CODEX_CLI_PATH: process.execPath };+ const client = new TestClient(+ {},+ {+ environment,+ prepareRuntime: async () => ({+ ...preparedRuntime(codexHome),+ environment,+ }),+ resolvePluginPython: async () => "/managed/python",+ prepareOutputDir: async () => scanDir,+ repositoryRevision: async () => "deadbeef",+ resolveCodexCommand: () => ({ command: process.execPath }),+ runWorkbench: async (+ _options: unknown,+ args: readonly string[],+ input?: string,+ ): Promise<JsonObject> => {+ if (args[0] === "get-scan") {+ return {+ scan: {+ progress: {+ independentReviews: {+ completed: 3,+ active: 2,+ maximum: 40,+ },+ },+ },+ };+ }+ return mockWorkbench(args, input);+ },+ createCodex: () => ({+ startThread: () => ({+ id: null,+ async runStreamed() {+ await Bun.sleep(0);+ throw new Error("deep progress captured");+ },+ }),+ }),+ },+ );++ await expect(+ client.run(repository, {+ mode: "deep",+ onDeepProgress: (progress) => updates.push(progress),+ }),+ ).rejects.toThrow("deep progress captured");+ await Bun.sleep(0);+ expect(updates).toEqual([{ completed: 3, active: 2, maximum: 40 }]);+ await client.close();+ });+test.skipIf(process.platform !== "win32")("loads deep scan settings from a backslash home-relative CODEX_HOME",async () => {diff --git a/sdk/typescript/tests-ts/deep-progress.test.ts b/sdk/typescript/tests-ts/deep-progress.test.tsnew file mode 100644index 000000000..d1b08377f--- /dev/null+++ b/sdk/typescript/tests-ts/deep-progress.test.ts@@ -0,0 +1,112 @@+import { describe, expect, test } from "bun:test";+import {+ DeepScanProgressTracker,+ deepScanProgressFromWorkbench,+ type DeepScanProgress,+} from "../src/deep-progress.js";++function workbenchResult(+ independentReviews?: Record<string, unknown>,+): Record<string, unknown> {+ return {+ scan: {+ progress: {+ ...(independentReviews === undefined ? {} : { independentReviews }),+ },+ },+ };+}++describe("Deep Scan progress", () => {+ test("reads durable independent-review counts from the workbench projection", () => {+ expect(+ deepScanProgressFromWorkbench(+ workbenchResult({+ completed: 34,+ active: 2,+ maximum: 40,+ consolidating: false,+ }),+ ),+ ).toEqual({ completed: 34, active: 2, maximum: 40 });+ });++ test("waits for the Deep Scan coordinator to create independent-review state", () => {+ expect(deepScanProgressFromWorkbench(workbenchResult())).toBeNull();+ });++ test.each([+ { completed: -1, active: 0, maximum: 40 },+ { completed: 0, active: 0, maximum: 0 },+ { completed: 0, active: "two", maximum: 40 },+ ])("rejects invalid workbench progress %#", (independentReviews) => {+ expect(() =>+ deepScanProgressFromWorkbench(workbenchResult(independentReviews)),+ ).toThrow("invalid Deep Scan progress");+ });++ test("reports only changed progress and ignores refresh after stop", async () => {+ const reads = [+ workbenchResult(),+ workbenchResult({ completed: 0, active: 2, maximum: 40 }),+ workbenchResult({ completed: 0, active: 2, maximum: 40 }),+ workbenchResult({ completed: 1, active: 1, maximum: 40 }),+ ];+ const progress: DeepScanProgress[] = [];+ let readCount = 0;+ const tracker = new DeepScanProgressTracker({+ read: async () => {+ readCount += 1;+ return reads.shift() ?? workbenchResult();+ },+ onProgress: (update) => progress.push(update),+ });++ await tracker.refresh();+ await tracker.refresh();+ await tracker.refresh();+ await tracker.refresh();+ await tracker.stop();+ await tracker.refresh();++ expect(progress).toEqual([+ { completed: 0, active: 2, maximum: 40 },+ { completed: 1, active: 1, maximum: 40 },+ ]);+ expect(readCount).toBe(4);+ });++ test("does not queue or await stalled polls during stop", async () => {+ const progress: DeepScanProgress[] = [];+ let readCount = 0;+ let aborted = false;+ const tracker = new DeepScanProgressTracker({+ read: async (signal) => {+ readCount += 1;+ return await new Promise((resolve) => {+ signal.addEventListener(+ "abort",+ () => {+ aborted = true;+ resolve(+ workbenchResult({ completed: 1, active: 0, maximum: 40 }),+ );+ },+ { once: true },+ );+ });+ },+ onProgress: (update) => progress.push(update),+ });++ const first = tracker.refresh();+ await Bun.sleep(0);+ const second = tracker.refresh();+ tracker.stop();+ await Promise.all([first, second]);++ expect(readCount).toBe(1);+ expect(aborted).toBe(true);+ expect(progress).toEqual([]);+ });+});diff --git a/sdk/typescript/tests-ts/deep-scan-workbench.test.ts b/sdk/typescript/tests-ts/deep-scan-workbench.test.tsindex 02c66b8d6..1df7f704a 100644--- a/sdk/typescript/tests-ts/deep-scan-workbench.test.ts+++ b/sdk/typescript/tests-ts/deep-scan-workbench.test.ts@@ -258,6 +258,16 @@ test.each(["deep-scan-mcp/v1",]);const deepScan = begun["deepScan"] as Record<string, unknown>;+ const running = await command(["get-scan", "--scan-id", scanId]);+ expect(running["scan"]).toMatchObject({+ progress: {+ independentReviews: {+ active: 0,+ completed: 0,+ maximum: 40,+ },+ },+ });const templates =/\/\/ templates\/deep-scan\/discovery\.md\n([\s\S]*?)\/\/ src\/deep-scan\/worker-runner\.ts/u.exec(