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(sdk): forward component scan lifecycle and deep progress (#2317)
Michael D'Angeloc2c2803a8a9a
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 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 retainsdiff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 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 orfailed 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 anddiff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 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 === nulldiff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.tsindex 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.tsindex 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.#stagediff --git a/sdk/typescript/src/scan-progress.ts b/sdk/typescript/src/scan-progress.tsindex 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.tsindex 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.tsindex 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", []],