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

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.mjs
index 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.py
index 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.py
index 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.py
index 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.md
index 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 or
using 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.mjs
index 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.ts
index 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 temporary
diff --git a/sdk/typescript/src/deep-progress.ts b/sdk/typescript/src/deep-progress.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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(