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(deep-scan): show direct coordinator events in verbose CLI scans (#2323)
Michael D'Angelo28a24c0c0545
diff --git a/plugins/codex-security/mcp-app/deep-scan-main.ts b/plugins/codex-security/mcp-app/deep-scan-main.tsindex a8a36e3b1..efd32e660 100644--- a/plugins/codex-security/mcp-app/deep-scan-main.ts+++ b/plugins/codex-security/mcp-app/deep-scan-main.ts@@ -35,6 +35,7 @@ export async function runCliDeepScan(): Promise<void> {model: string;reasoningEffort?: string;permissionProfile: unknown;+ diagnosticsVersion?: number;};scanId = input.scanId;const pluginRoot = PLUGIN_ROOT;@@ -67,6 +68,13 @@ export async function runCliDeepScan(): Promise<void> {runWorkbench,pluginRoot,pythonCommand: await resolvePythonCommand(),+ ...(input.diagnosticsVersion === 1 &&+ process.send && {+ log: (event) => {+ // A closing diagnostics channel must not interrupt durable cleanup.+ process.send?.(event, () => {});+ },+ }),parentSandbox,threadId: input.threadId,model: input.model,diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.tsindex 0ae45d953..b7871f8b0 100644--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts@@ -11,7 +11,9 @@ import { readOnlyParentSandboxState } from "./sandbox-state.ts";import { temporaryDirectory } from "./support/temporary-directories.ts";import assert from "node:assert/strict";import { parse as parseToml } from "smol-toml";-import { execFile } from "node:child_process";+import { execFile, fork } from "node:child_process";+import { once } from "node:events";+import { text } from "node:stream/consumers";import { createHash, randomUUID } from "node:crypto";import {chmod,@@ -1297,31 +1299,29 @@ async function testCliDeepScanEngine({]);return { scanId: registration.scanId as string, scanDir };};+ const request = (scanId: string) => ({+ scanId,+ threadId,+ model: "gpt-6.1-sol",+ reasoningEffort: "max",+ permissionProfile: (parentSandboxState as { permissionProfile: unknown })+ .permissionProfile,+ });+ const engineEnvironment = {+ ...environment,+ CODEX_SECURITY_KNOWLEDGE_BASE: knowledgeBase,+ };const launch = (scanId: string, overrides: NodeJS.ProcessEnv = {}) => {const execution = execFileAsync(process.execPath,[serverBundlePath, "--deep-scan-engine"],{- env: {- ...environment,- CODEX_SECURITY_KNOWLEDGE_BASE: knowledgeBase,- ...overrides,- },+ env: { ...engineEnvironment, ...overrides },encoding: "utf8",timeout: 30_000,},);- execution.child.stdin!.write(- JSON.stringify({- scanId,- threadId,- model: "gpt-6.1-sol",- reasoningEffort: "max",- permissionProfile: (- parentSandboxState as { permissionProfile: unknown }- ).permissionProfile,- }) + "\n",- );+ execution.child.stdin!.write(JSON.stringify(request(scanId)) + "\n");return execution;};const completed = await register("cli-engine-completed", true);@@ -1330,7 +1330,35 @@ async function testCliDeepScanEngine({const helperStartIndex = (await readLogLines(environment.FAKE_WORKBENCH_LAUNCH_LOG!)).length;- const result = await launch(completed.scanId);+ const verbose = fork(serverBundlePath, ["--deep-scan-engine"], {+ env: engineEnvironment,+ execArgv: [],+ timeout: 30_000,+ silent: true,+ });+ const diagnosticEvents: unknown[] = [];+ verbose.on("message", (event) => diagnosticEvents.push(event));+ const output = Promise.all([+ text(verbose.stdout!),+ text(verbose.stderr!),+ once(verbose, "close"),+ ]);+ verbose.stdin!.write(+ JSON.stringify({ ...request(completed.scanId), diagnosticsVersion: 1 }) ++ "\n",+ );+ const [stdout, stderr, [code]] = await output;+ assert.equal(code, 0, stderr);+ assert.ok(+ diagnosticEvents.some(+ (entry) => (entry as { event: string }).event === "discovery_accepted",+ ),+ );+ assert.ok(+ diagnosticEvents.some(+ (entry) => (entry as { event: string }).event === "coordinator_terminal",+ ),+ );const helperLaunches = (await readLogLines(environment.FAKE_WORKBENCH_LAUNCH_LOG!)).slice(helperStartIndex);@@ -1341,7 +1369,7 @@ async function testCliDeepScanEngine({assert.equal(launch.args.length, 7);assert.equal(launch.cwd, pluginRoot);}- assert.deepEqual(JSON.parse(result.stdout), {+ assert.deepEqual(JSON.parse(stdout), {scanId: completed.scanId,manifestPath: path.join(completed.scanDir, "scan-manifest.json"),});diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.mdindex 002526fe1..1a67ddd4c 100644--- a/sdk/typescript/docs/cli.md+++ b/sdk/typescript/docs/cli.md@@ -1055,7 +1055,8 @@ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage### TroubleshootingUse `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,-retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,+retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events+such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,saved failures, receipts, and patch-risk summaries. Review it for sensitiveinformation before sharing; upstream Codex output may already be redacted.diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 9f7efa97d..55e226bd4 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -117,6 +117,7 @@ import {deepScanParentToolOverrides,readDeepScanParentConfig,runDeepScan,+ type DeepScanDiagnostic,} from "./deep-scan.js";import {getDefaultSeverityRubric,@@ -696,6 +697,7 @@ export interface CodexSecurityMetadata {export type CodexSecuritySurface = "cli" | "sdk";interface CodexSecurityRuntimeOptions {+ onDeepScanDiagnostic?: (event: DeepScanDiagnostic) => void;surface: CodexSecuritySurface;}@@ -759,6 +761,7 @@ export class CodexSecurity {readonly #dependencies: ClientDependencies;readonly #surface: CodexSecuritySurface;+ readonly #onDeepScanDiagnostic: CodexSecurityRuntimeOptions["onDeepScanDiagnostic"];readonly #loginHandles = new Set<CodexLoginHandle>();readonly #abortController = new AbortController();#activeOperation: Promise<unknown> | null = null;@@ -782,6 +785,7 @@ export class CodexSecurity {this.config = structuredClone(config);this.#dependencies = dependencies;this.#surface = runtimeOptions.surface;+ this.#onDeepScanDiagnostic = runtimeOptions.onDeepScanDiagnostic;}public async run(@@ -3265,6 +3269,7 @@ export class CodexSecurity {tracker.beginParentTurn(resumeThreadId !== undefined);const events = directDeepScan? (this.#dependencies.runDeepScan ?? runDeepScan)({+ onDiagnostic: this.#onDeepScanDiagnostic,codexOptions,preflightCommand:await this.#providerPreflightCommand(effectiveConfig),diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex e8f6974ff..f7be8d886 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -107,6 +107,7 @@ import {readCodexHomeConfig,} from "./auth.js";import { loadContract, sha256Text } from "./contract.js";+import type { DeepScanDiagnostic } from "./deep-scan.js";import {formatDeepScanReviews,type DeepScanProgress,@@ -1292,6 +1293,7 @@ interface PatchRiskAssessment extends PatchRiskReport {interface CliDependencies {createSecurity(config: CodexSecurityConfig,+ onDeepScanDiagnostic?: (event: DeepScanDiagnostic) => void,): Pick<CodexSecurity, "run" | "preflight" | "validate" | "close">;createPolicySecurity?: (config: CodexSecurityConfig) => PolicySecurity;policyPrompt?: PolicyPrompt;@@ -1401,8 +1403,11 @@ export const runRepositoryCommand: CliDependencies["runRepositoryCommand"] =};const DEFAULT_DEPENDENCIES: CliDependencies = {- createSecurity: (config) =>- new CodexSecurity(config, undefined, { surface: "cli" }),+ createSecurity: (config, onDeepScanDiagnostic) =>+ new CodexSecurity(config, undefined, {+ surface: "cli",+ onDeepScanDiagnostic,+ }),environment: process.env,checkForUpdate: (signal) =>checkForUpdate({ environment: process.env, signal }),@@ -10189,7 +10194,12 @@ async function executeScan(progress.startTimer("Preparing scan");}}- security = dependencies.createSecurity(config);+ security = dependencies.createSecurity(+ config,+ verbose && arguments_.mode === "deep"+ ? (fields) => diagnostic("deep_scan.coordinator", fields)+ : undefined,+ );if (arguments_.mock) {errorOutput.write("codex-security: Mock scan: generating synthetic findings; no security analysis or LLM calls.\n",diff --git a/sdk/typescript/src/deep-scan.ts b/sdk/typescript/src/deep-scan.tsindex 840be4b86..9c5dc7bec 100644--- a/sdk/typescript/src/deep-scan.ts+++ b/sdk/typescript/src/deep-scan.ts@@ -1,4 +1,4 @@-import { spawn } from "node:child_process";+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";import { realpathSync } from "node:fs";import { join, resolve } from "node:path";import { pathToFileURL } from "node:url";@@ -29,7 +29,10 @@ import {withCodexPreflightLock,} from "./provider-profile.js";+export type DeepScanDiagnostic = Readonly<Record<string, string | number>>;+export interface DirectDeepScanOptions {+ onDiagnostic?: (event: DeepScanDiagnostic) => void;codexOptions: CodexOptions & { nativeProfile?: string };preflightCommand: CodexCommand;pluginRoot: string;@@ -407,8 +410,13 @@ export async function* runDeepScan(node?.executable ?? process.execPath,[join(options.pluginRoot, "mcp", "server.mjs"), "--deep-scan-engine"],node?.environment ?? environment,- JSON.stringify({ scanId: options.scanId, ...session }),+ JSON.stringify({+ scanId: options.scanId,+ ...session,+ ...(options.onDiagnostic && { diagnosticsVersion: 1 }),+ }),options.signal,+ options.onDiagnostic,);const completed = JSON.parse(output);if (@@ -433,12 +441,33 @@ function runEngine(env: NodeJS.ProcessEnv,request: string,signal: AbortSignal,+ onDiagnostic: DirectDeepScanOptions["onDiagnostic"],): Promise<string> {signal.throwIfAborted();const child = spawn(executablePathForSpawn(command), args, {env,windowsHide: true,- });+ serialization: "json",+ stdio: onDiagnostic ? ["pipe", "pipe", "pipe", "ipc"] : "pipe",+ }) as ChildProcessWithoutNullStreams;+ if (onDiagnostic) {+ child.on("message", (message) => {+ if (!isRecord(message) || typeof message["event"] !== "string") return;+ const fields: Record<string, string | number> = {};+ for (const [name, value] of Object.entries(message)) {+ if (+ /^[a-zA-Z][a-zA-Z0-9]*$/u.test(name) &&+ (typeof value === "number" || typeof value === "string")+ )+ fields[name] = value;+ }+ try {+ void Promise.resolve(onDiagnostic(fields)).catch(() => {});+ } catch {+ // The optional diagnostic sink cannot stop the scan.+ }+ });+ }// EOF requests graceful coordinator/worker cleanup on Windows as well as Unix.// Keep the control pipe open until completion or explicit cancellation.const cancel = () => child.stdin.end();diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 3e0c59df1..5b83ed11e 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -3907,6 +3907,44 @@ describe("CLI", () => {expect(stderr.text()).not.toContain("SYNTHETIC_VERBOSE_SECRET");});+ test.each([true, false])(+ "routes direct Deep Scan coordinator diagnostics in verbose mode (%p)",+ async (verbose) => {+ const { stdout, stderr, runCli } = createCliTest(main);+ const deps = dependencies();+ deps.createSecurity = (_config, observe) =>+ fakeSecurity(async () => {+ expect(typeof observe).toBe(verbose ? "function" : "undefined");+ observe?.({+ event: "finding_comparison_failed",+ reason: "first\nsecond",+ });+ return fakeResult();+ });+ expect(+ await runCli(+ [+ "scan",+ ".",+ "--mode",+ "deep",+ "--json",+ ...(verbose ? ["--verbose"] : []),+ ],+ deps,+ ),+ ).toBe(0);+ expect(JSON.parse(stdout.text())).toEqual(fakeResult().toJSON());+ const diagnostics = stderr+ .text()+ .split("\n")+ .filter((line) => line.includes("deep_scan.coordinator"));+ expect(diagnostics).toHaveLength(verbose ? 1 : 0);+ if (verbose)+ expect(diagnostics[0]).toContain('event="finding_comparison_failed"');+ },+ );+test("reports the effective default model and reasoning effort in verbose scan diagnostics", async () => {const { stdout, stderr, runCli } = createCliTest(main);diff --git a/sdk/typescript/tests-ts/direct-deep-scan.test.ts b/sdk/typescript/tests-ts/direct-deep-scan.test.tsindex 7385fc61e..670b3996c 100644--- a/sdk/typescript/tests-ts/direct-deep-scan.test.ts+++ b/sdk/typescript/tests-ts/direct-deep-scan.test.ts@@ -59,12 +59,20 @@ import { createInterface } from 'node:readline';const lines = createInterface({input: process.stdin});const request = JSON.parse((await lines[Symbol.asyncIterator]().next()).value);writeFileSync(process.env.SYNTHETIC_RECEIPT, JSON.stringify({- request, argv: process.argv.slice(2), key: process.env.CODEX_API_KEY,+ request, ipc: !!process.send, argv: process.argv.slice(2), key: process.env.CODEX_API_KEY,execPath: process.execPath, bun: process.versions.bun,awsProfile: process.env.AWS_PROFILE, snapshot: process.env.CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH,externalImports: process.env.CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS,}));-if (process.env.SYNTHETIC_WAIT === '1') {+if (request.diagnosticsVersion === 1 && process.env.SYNTHETIC_OLD_ENGINE !== '1') {+ process.send({ event: 'discovery_worker_replaced', scanId: request.scanId, reason: 'tool error' });+}+if (process.env.SYNTHETIC_FAIL === '1') {+ process.stderr.write('first detail\\nlast detail');+ process.exitCode = 1;+ lines.close();+ process.stdin.destroy();+} else if (process.env.SYNTHETIC_WAIT === '1') {lines.once('close', () => { writeFileSync(process.env.SYNTHETIC_RECEIPT + '.stopped', 'stopped'); process.exit(0); });setInterval(() => {}, 1000);} else {@@ -151,6 +159,8 @@ test("isolates direct engine credentials and runtime snapshots across concurrent},});assert.deepEqual(saved.argv, ["--deep-scan-engine"]);+ assert.equal(saved.ipc, false);+ assert.equal(saved.request.diagnosticsVersion, undefined);assert.deepEqual(saved.request.permissionProfile, {commandArgs: ["--config", `model_provider="provider_${name}"`],configOverrides: [@@ -181,6 +191,49 @@ test("isolates direct engine credentials and runtime snapshots across concurrentassert.equal(DIRECT_DEEP_SCAN_CONTROL_USAGE.input_tokens, 0);});+test("keeps direct coordinator events separate from results and child errors across helper versions", async () => {+ const { root, pluginRoot } = await fixture();+ for (const [old, failed] of [+ [false, false],+ [true, false],+ [false, true],+ [true, true],+ ]) {+ const observed: string[] = [];+ const events = runDeepScan({+ preflightCommand: { command: "/synthetic/codex" },+ repository: root,+ pluginRoot,+ scanDir: root,+ scanId: "fixture",+ prompt: "Review fixture",+ signal: new AbortController().signal,+ async onDiagnostic(fields) {+ observed.push(String(fields["event"]));+ throw new Error("unavailable sink");+ },+ codexOptions: {+ env: {+ PATH: process.versions["bun"] ? process.env["PATH"]! : "",+ CODEX_HOME: join(root, "codex-home"),+ CODEX_SECURITY_SCAN_DIR: root,+ SYNTHETIC_RECEIPT: join(root, "receipt"),+ SYNTHETIC_THREAD_ID: "parent",+ SYNTHETIC_OLD_ENGINE: old ? "1" : "0",+ SYNTHETIC_FAIL: failed ? "1" : "0",+ },+ },+ });+ assert.equal((await events.next()).value?.type, "thread.started");+ if (failed)+ await assert.rejects(events.next(), {+ message: "first detail\nlast detail",+ });+ else assert.equal((await events.next()).value?.type, "turn.completed");+ assert.deepEqual(observed, old ? [] : ["discovery_worker_replaced"]);+ }+});+test("preserves complete worker usage and cost after direct engine completion", async () => {const { root, pluginRoot } = await fixture();const codexHome = join(root, "codex-home");@@ -307,6 +360,9 @@ test("waits for the direct engine to stop when the scan is canceled", async () =repository: root,scanDir: root,scanId: "canceled-scan",+ onDiagnostic() {+ throw new Error("closed presentation");+ },prompt: "Synthetic audit.",signal: controller.signal,codexOptions: {