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(sdk): forward component scan lifecycle and deep progress (#2317)

Michael D'Angeloc2c2803a8a9a
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 6dd52146b..9208ec4a1 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -412,6 +412,10 @@ await security.run(repository, {
});
```
+For `runComponentScans()`, subscribe to `onScanEvent` and select events with
+`type === "lifecycle"` to correlate each snapshot with its `componentId`. Deep
+component scans also emit `deep-progress` events with independent review counts.
+
Group observations by `scanId`. A completed scan with
`hasReportableFindings: false` finished with zero reportable findings.
The field is `null` until that outcome is known. Saved scan history retains
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 325f226e0..14f6589a6 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -784,7 +784,8 @@ individual scan folder.
Failures do not stop other components. Failed scans or
failed matching return `2`; severity-policy violations return `1`. Retry with
`--components-file retry-components.json` and a new empty output directory.
-The retry report covers only those components.
+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
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index ea35b594c..a4976798f 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -107,7 +107,10 @@ import {
readCodexHomeConfig,
} from "./auth.js";
import { loadContract, sha256Text } from "./contract.js";
-import type { DeepScanProgress } from "./scan-progress.js";
+import {
+ formatDeepScanReviews,
+ type DeepScanProgress,
+} from "./scan-progress.js";
import { isRecord as isJsonObject } from "./record.js";
import { suggestOwnersInternal } from "./suggest-owners.js";
import { parseImportedFindings } from "./findings-import.js";
@@ -10152,9 +10155,7 @@ async function executeScan(
);
}
if (deepProgress !== null) {
- details.push(
- `Reviews: ${deepProgress.completed} completed, ${deepProgress.active} active, cap ${deepProgress.maximum}`,
- );
+ details.push(formatDeepScanReviews(deepProgress));
} else if (fileProgress !== null) {
details.push(formatScanProgressCount(fileProgress, "status"));
}
@@ -10465,7 +10466,7 @@ async function executeScan(
update.consolidating === true ||
(deepConsolidating && update.active === 0);
phase = deepConsolidating ? "consolidating results" : "discovery";
- const message = `Scan phase: ${phase} | Reviews: ${update.completed} completed, ${update.active} active, cap ${update.maximum}`;
+ const message = `Scan phase: ${phase} | ${formatDeepScanReviews(update)}`;
if (dashboard !== null) {
dashboard.setStage(phase);
dashboard.note(message);
@@ -11501,6 +11502,12 @@ function componentScanEventLine(
const count = formatScanProgressCount(progress, "status");
return `codex-security: ${componentName} ${scanPhase(progress.phase)} | ${count}\n`;
}
+ if (event.type === "deep-progress") {
+ const phase = event.value.consolidating
+ ? "consolidating results"
+ : "discovery";
+ return `codex-security: ${componentName} ${phase} | ${formatDeepScanReviews(event.value)}\n`;
+ }
if (event.type === "usage") {
const tokens = formatTokenUsage(event.value);
return tokens === null
diff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.ts
index df7c6ea9e..e51b675af 100644
--- a/sdk/typescript/src/component-scan.ts
+++ b/sdk/typescript/src/component-scan.ts
@@ -10,6 +10,7 @@ import {
selectedScanEnvironment,
type CodexSecuritySurface,
type ScanAuthentication,
+ type ScanLifecycle,
type ScanOptions,
} from "./api.js";
import {
@@ -36,6 +37,7 @@ import { errorMessage } 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 type { ScanProgress, ScanWorkerStatus } from "./worker-progress.js";
import {
@@ -89,7 +91,9 @@ export interface ComponentReceipt {
type ComponentScanUpdate =
| { type: "authentication"; value: ScanAuthentication }
+ | { type: "lifecycle"; value: ScanLifecycle }
| { type: "progress"; value: ScanProgress }
+ | { type: "deep-progress"; value: DeepScanProgress }
| { type: "activity"; value: ScanActivity }
| { type: "session"; value: ScanSessionEvent }
| { type: "cost"; value: Readonly<ScanCost> }
@@ -244,7 +248,10 @@ export async function runComponentScans(
: {
onAuthentication: (value) =>
emit({ type: "authentication", value }),
+ onLifecycle: (value) => emit({ type: "lifecycle", value }),
onProgress: (value) => emit({ type: "progress", value }),
+ onDeepProgress: (value) =>
+ emit({ type: "deep-progress", value }),
onActivity: (value) => emit({ type: "activity", value }),
onSessionEvent: (value) => emit({ type: "session", value }),
onCost: (value) => emit({ type: "cost", value }),
@@ -258,6 +265,9 @@ export async function runComponentScans(
const result = await security.run(repository, {
...options.scanOptions,
...observers,
+ onScanRegistered: ({ scanId }) => {
+ receipt.scanId = scanId;
+ },
mode: options.scanOptions?.mode ?? "standard",
target: receipt.paths.map((path) => resolve(repository, path)),
outputDir: receipt.outputDir,
diff --git a/sdk/typescript/src/scan-dashboard.ts b/sdk/typescript/src/scan-dashboard.ts
index 8eaee43cf..9fa80bc27 100644
--- a/sdk/typescript/src/scan-dashboard.ts
+++ b/sdk/typescript/src/scan-dashboard.ts
@@ -27,6 +27,7 @@ import {
formatTokenUsage,
type ScanTokenUsage,
} from "./cost-model.js";
+import { formatDeepScanReviews } from "./scan-progress.js";
import type { ScanActivity } from "./scan-activity.js";
import {
ACCOUNT_LIMITS_UNAVAILABLE,
@@ -168,6 +169,7 @@ export class ScanDashboard {
} | null = null;
#stage = "Preparing scan";
#files: ScanProgress | null = null;
+ #componentReviews: string | null = null;
#publicationProgress: { completed: number; total: number } | null = null;
#cost: Readonly<ScanCost> | null = null;
#tokens: string | null = null;
@@ -479,7 +481,6 @@ export class ScanDashboard {
const dashboard = new ScanDashboard(this.#stream, {
...this.#options,
presentation: "scan",
- mode: "standard",
componentName: receipt.name,
});
dashboard.setStage(COMPONENT_STATUS.pending);
@@ -501,6 +502,7 @@ export class ScanDashboard {
dashboard.setStage("Preparing scan");
} else if (receipt.status !== "pending") {
const status = COMPONENT_STATUS[receipt.status];
+ dashboard.#componentReviews = null;
dashboard.#finishedAt = this.#options.clock.now();
dashboard.setStage(status);
dashboard.note(
@@ -527,6 +529,13 @@ export class ScanDashboard {
dashboard.setFiles(event.value);
dashboard.setStage(scanPhaseLabel(event.value.phase));
break;
+ case "deep-progress":
+ dashboard.#componentReviews = `${event.value.completed} done, ${event.value.active} active`;
+ dashboard.setStage(
+ event.value.consolidating ? "consolidating results" : "discovery",
+ );
+ dashboard.note(formatDeepScanReviews(event.value));
+ break;
case "activity":
dashboard.record(event.value);
break;
@@ -939,9 +948,10 @@ export class ScanDashboard {
? null
: scanProgressCount(dashboard.#files);
const progress =
- count === null
+ dashboard.#componentReviews ??
+ (count === null
? "—"
- : `${formatCount(count.completed)}/${formatCount(count.total)} ${count.label}`;
+ : `${formatCount(count.completed)}/${formatCount(count.total)} ${count.label}`);
const status =
receipt.status === "started"
? dashboard.#stage
diff --git a/sdk/typescript/src/scan-progress.ts b/sdk/typescript/src/scan-progress.ts
index 0e3438220..b629e179f 100644
--- a/sdk/typescript/src/scan-progress.ts
+++ b/sdk/typescript/src/scan-progress.ts
@@ -19,6 +19,10 @@ export interface DeepScanProgress extends z.output<typeof deepProgressSchema> {
consolidating?: boolean;
}
+export function formatDeepScanReviews(progress: DeepScanProgress): string {
+ return `Reviews: ${progress.completed} completed, ${progress.active} active, cap ${progress.maximum}`;
+}
+
interface ScanProgressTrackerOptions {
read: (signal: AbortSignal) => Promise<unknown>;
onProgress?: (progress: SavedScanProgress) => void;
diff --git a/sdk/typescript/tests-ts/cli-verify-fix.test.ts b/sdk/typescript/tests-ts/cli-verify-fix.test.ts
index 36952ac7c..83fb218a5 100644
--- a/sdk/typescript/tests-ts/cli-verify-fix.test.ts
+++ b/sdk/typescript/tests-ts/cli-verify-fix.test.ts
@@ -575,9 +575,9 @@ describe("read-only finding verification", () => {
seen.length === 1 &&
(scenario === "SIGINT" || scenario === "SIGTERM")
)
- setImmediate(() => signals.emit(scenario));
+ queueMicrotask(() => signals.emit(scenario));
if (seen.length === 1 && scenario === "repeated signal")
- setImmediate(() => {
+ queueMicrotask(() => {
signals.emit("SIGINT");
signals.emit("SIGTERM");
});
diff --git a/sdk/typescript/tests-ts/component-scan.test.ts b/sdk/typescript/tests-ts/component-scan.test.ts
index 81773289e..7504387be 100644
--- a/sdk/typescript/tests-ts/component-scan.test.ts
+++ b/sdk/typescript/tests-ts/component-scan.test.ts
@@ -56,7 +56,7 @@ import { createApiTestFixtures } from "./support/temporary-directories.js";
import { readJson } from "./support/json.js";
import { runTestInSubprocess } from "./support/test-subprocess.js";
import { rejecting, throwing } from "./support/errors.js";
-import { mockWorkbench } from "./support/api-client.js";
+import { mockWorkbench, TestClient } from "./support/api-client.js";
import { preparedRuntime } from "./support/api-events.js";
const { temporaryDirectory, cleanup } =
@@ -472,6 +472,49 @@ test("bounds standard scans, continues after failure, and preserves partial resu
);
});
+test.each([true, false])(
+ "saves the registered scan ID for failed components (lifecycle observer: %p)",
+ async (observe) => {
+ const paths = await fixture();
+ const controller = new AbortController();
+ const stateDir = join(paths.root, "state");
+ const client = TestClient.withDependencies({
+ runWorkbench: runtime.runWorkbench,
+ environment: {
+ PATH: process.env["PATH"],
+ SystemRoot: process.env["SystemRoot"],
+ CODEX_SECURITY_STATE_DIR: stateDir,
+ },
+ });
+ const events: ComponentScanEvent[] = [];
+ const summary = await scan(paths, {
+ components: [components[0]!],
+ createSecurity: () => ({
+ close: () => client.close(),
+ run: (repository, options) =>
+ client.run(repository, {
+ ...options,
+ mock: true,
+ signal: controller.signal,
+ onScanStarted: () => controller.abort(),
+ }),
+ }),
+ onScanEvent: observe ? (event) => events.push(event) : undefined,
+ });
+ const [receipt] = (await json(summary.summaryPath!)).components;
+ expect(receipt.status).toBe("failed");
+ expect(typeof receipt.scanId).toBe("string");
+ expect(events.filter((event) => event.type === "lifecycle")).toMatchObject(
+ observe
+ ? ["running", "failed"].map((status) => ({
+ componentId: receipt.id,
+ value: { status, scanId: receipt.scanId },
+ }))
+ : [],
+ );
+ },
+);
+
test("forwards scan events with their component identity without letting observers stop scans", async () => {
const paths = await fixture();
const events: ComponentScanEvent[] = [];
@@ -580,6 +623,54 @@ test("forwards scan events with their component identity without letting observe
}
});
+test.each([true, false])(
+ "CLI displays Deep component review counts (headless: %p)",
+ async (headless) => {
+ const paths = await fixture();
+ const config = join(paths.root, "settings.yaml");
+ await writeFile(config, "scan:\n mode: deep\n");
+ const { stderr, runCli } = createCliTest(main, { stderr: true });
+ const code = await runCli(
+ [
+ "scan-components",
+ paths.repository,
+ "--config",
+ config,
+ "--component",
+ "apps/api",
+ "--output-dir",
+ paths.outputDir,
+ ...(headless ? ["--headless"] : []),
+ ],
+ {
+ ...dependencies({
+ currentDirectory: paths.root,
+ environment: { NO_COLOR: "1" },
+ }),
+ createSecurity: client(async (repository, options) => {
+ expect(options.mode).toBe("deep");
+ options.onDeepProgress?.({ completed: 3, active: 2, maximum: 40 });
+ await Promise.resolve();
+ options.onDeepProgress?.({
+ completed: 5,
+ active: 0,
+ maximum: 40,
+ consolidating: true,
+ });
+ return completed(repository, options);
+ }),
+ },
+ );
+ expect(code).toBe(0);
+ expect(stderr.text()).toContain(
+ headless
+ ? "apps/api discovery | Reviews: 3 completed, 2 active, cap 40"
+ : "3 done, 2 active",
+ );
+ expect(stderr.text()).toContain("consolidating results");
+ },
+);
+
test.each([
["dashboard", []],
["headless", []],