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(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.ts
index 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.ts
index 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.md
index 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
### Troubleshooting
Use `--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 sensitive
information before sharing; upstream Codex output may already be redacted.
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 concurrent
assert.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: {