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): avoid worker dispatch for empty targets (#2054)

Muzzy51508bede3b1915d
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
index 73a5421ab..86bb54017 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
@@ -80,6 +80,10 @@ export interface CoordinatorOptions {
run: DeepScanRunState,
signal: AbortSignal,
) => Promise<DeepScanRunState>;
+ checkFreshTarget?: (
+ run: DeepScanRunState,
+ signal: AbortSignal,
+ ) => Promise<void>;
onComplete?: (
draft: ScanDraftInput,
signal: AbortSignal,
@@ -347,6 +351,14 @@ export class DeepScanCoordinator {
await ensureDeepScanDirectories(this.artifacts);
if (this.canceled || this.externallyFailed) return;
+ if (this.options.checkFreshTarget && isFreshRun(this.state)) {
+ await this.options.checkFreshTarget(
+ this.state,
+ this.discoveryAbortController.signal,
+ );
+ }
+ if (this.canceled || this.externallyFailed) return;
+
this.setupComplete = true;
const loopResult = await this.runIterations();
if (this.canceled || this.externallyFailed) return;
@@ -1072,6 +1084,15 @@ function cloneState(state: DeepScanRunState): DeepScanRunState {
return { ...state, config: { ...state.config } };
}
+function isFreshRun(state: DeepScanRunState): boolean {
+ return (
+ !state.discoveryStarted &&
+ state.dispatchedCount === 0 &&
+ !state.persistedWorkers?.some((worker) => worker.kind !== "setup") &&
+ (state.persistedDedupInputs?.length ?? 0) === 0
+ );
+}
+
function discoverySequence(artifactDir: string): bigint {
return workerLabelSequence(basename(dirname(artifactDir)), "discovery");
}
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/engine.ts b/plugins/codex-security/mcp-app/src/deep-scan/engine.ts
index 0548510c9..26e287b0b 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/engine.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/engine.ts
@@ -1,5 +1,7 @@
+import { join } from "node:path";
import { createScanArtifactContext } from "../artifact-context.js";
import { recordCodexSecurityScanDraftViaWorkbench } from "../artifact-scan-draft.js";
+import { runPythonWithInput } from "../python_command.js";
import { workbenchArgs } from "../workbench-arguments.js";
import { CodexSdkWorkerExecutor } from "./executor.js";
import type { DeepWorkerParentSandbox } from "./parent-sandbox.js";
@@ -58,6 +60,8 @@ export function startDeepScanEngine(options: {
onStart: options.onStart,
handoffClaimToken,
threadId,
+ checkFreshTarget: (state, signal) =>
+ checkFreshTarget(state, signal, options.pythonCommand, pluginRoot),
onComplete: async (draft, signal, publication) => {
const context = await createScanArtifactContext(
run.scanId,
@@ -93,3 +97,33 @@ export function startDeepScanEngine(options: {
},
});
}
+
+export async function checkFreshTarget(
+ run: DeepScanRunState,
+ signal: AbortSignal,
+ pythonCommand: string,
+ pluginRoot: string,
+): Promise<void> {
+ if (signal.aborted) return;
+ try {
+ await runPythonWithInput(
+ pythonCommand,
+ [
+ "-I",
+ "-X",
+ "utf8",
+ join(pluginRoot, "scripts", "check_deep_scan_target.py"),
+ ],
+ JSON.stringify({
+ targetPath: run.targetPath,
+ includePaths: run.includePaths ?? [run.scope],
+ filePaths: run.filePaths ?? [],
+ }),
+ "Deep Scan target check",
+ signal,
+ );
+ } catch (error) {
+ // Cancellation and elapsed discovery budgets are finalized by the coordinator.
+ if (!signal.aborted) throw error;
+ }
+}
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/response.ts b/plugins/codex-security/mcp-app/src/deep-scan/response.ts
index f795f70b2..72291e074 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/response.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/response.ts
@@ -79,6 +79,7 @@ export const runSchema = z
sdkOwnsCompletion: z.boolean().optional(),
serviceTier: optionalString,
coordinatorGeneration: optionalValue(positiveInteger),
+ discoveryStarted: z.boolean().optional(),
createdAt: optionalString,
updatedAt: optionalString,
targetPath: requiredString,
diff --git a/plugins/codex-security/mcp-app/src/python_command.ts b/plugins/codex-security/mcp-app/src/python_command.ts
index 6919de2c6..9e1d2e689 100644
--- a/plugins/codex-security/mcp-app/src/python_command.ts
+++ b/plugins/codex-security/mcp-app/src/python_command.ts
@@ -113,9 +113,12 @@ export function runPythonWithInput(
args: string[],
input: string | Buffer,
label: string,
+ signal?: AbortSignal,
): Promise<string> {
return new Promise((resolve, reject) => {
const child = spawn(python, ["-B", ...args], {
+ signal,
+ killSignal: "SIGKILL",
stdio: ["pipe", "pipe", "pipe"],
windowsHide: true,
});
@@ -128,7 +131,16 @@ export function runPythonWithInput(
.setEncoding("utf8")
.on("data", (chunk: string) => errors.push(chunk));
let inputError: Error | undefined;
- child.on("error", reject);
+ child.on("error", (error) => {
+ if (signal?.aborted) {
+ // A killed helper can remain in a kernel filesystem call until its mount responds.
+ child.stdin.destroy();
+ child.stdout.destroy();
+ child.stderr.destroy();
+ child.unref();
+ }
+ reject(error);
+ });
child.stdin.on("error", (error: Error) => {
inputError = error;
});
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_empty_target.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_empty_target.ts
new file mode 100644
index 000000000..b80583cd3
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_empty_target.ts
@@ -0,0 +1,296 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { chmod, mkdir, rm, symlink, watch, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { after, test } from "node:test";
+import type { DeepScanRunState } from "../src/deep-scan/types.js";
+import {
+ createCoordinator,
+ eventually,
+ FakeExecutor,
+ FakeStore,
+ fixtureRun,
+ runCoordinator,
+ temporaryDirectories,
+} from "./deep_scan_coordinator_fixture.ts";
+import { importSource } from "./import-module.ts";
+
+const python = process.env.PYTHON?.trim() || "python3";
+const pluginRoot = resolve(import.meta.dirname, "../..");
+const { checkFreshTarget } = await importSource("src/deep-scan/engine.ts", {
+ loader: { ".md": "text" },
+});
+
+function inspect(run: DeepScanRunState) {
+ return checkFreshTarget(
+ run,
+ new AbortController().signal,
+ python,
+ pluginRoot,
+ );
+}
+
+after(() => temporaryDirectories.cleanup());
+
+test("only registered paths determine whether the target is empty", async () => {
+ const { run } = await fixtureRun();
+ run.includePaths = ["left", "right"];
+ const left = join(run.targetPath, "left");
+ const right = join(run.targetPath, "right");
+ await mkdir(left, { recursive: true });
+ await mkdir(right);
+ await writeFile(join(run.targetPath, "outside.py"), "");
+ const git = (...args: string[]) =>
+ execFileSync("git", ["-C", run.targetPath, ...args], { stdio: "pipe" });
+ git("init", "-q");
+ git("add", "outside.py");
+ git(
+ "-c",
+ "user.name=Fixture",
+ "-c",
+ "-c",
+ "commit.gpgsign=false",
+ "commit",
+ "-qm",
+ "outside selection",
+ );
+ await assert.rejects(
+ inspect({ ...run, targetPath: left, includePaths: undefined }),
+ /target is empty.*no security audit/iu,
+ );
+ await assert.rejects(inspect(run), /target is empty.*no security audit/iu);
+
+ // Any entry counts, even if normal source inventory would ignore it.
+ await writeFile(join(right, ".gitignore"), "*");
+ await inspect(run);
+ run.includePaths.reverse();
+ await inspect(run);
+
+ await rm(left, { recursive: true });
+ await writeFile(left, "");
+ run.includePaths = ["left"];
+ run.filePaths = ["left"];
+ await inspect(run);
+});
+
+test("a usable selection cannot mask a replaced file or an unsafe sibling", async () => {
+ const { run } = await fixtureRun();
+ await mkdir(run.targetPath);
+ await writeFile(join(run.targetPath, "first"), "");
+ const external = join(dirname(run.targetPath), "external");
+ await mkdir(external);
+ await writeFile(join(external, "source.py"), "");
+ await symlink(
+ external,
+ join(run.targetPath, "link"),
+ process.platform === "win32" ? "junction" : "dir",
+ );
+ await mkdir(join(run.targetPath, "was-file"));
+ for (const [sibling, error] of [
+ ["missing", /no such file|not found|cannot find/iu],
+ ["link", /symbolic link|outside|reparse|symlink/iu],
+ ["../external", /inside|outside|relative|escapes/iu],
+ ["was-file", /regular file/iu],
+ ] as const) {
+ run.includePaths = ["first", sibling];
+ run.filePaths = sibling === "was-file" ? ["first", sibling] : ["first"];
+ await assert.rejects(inspect(run), error);
+ }
+});
+
+test(
+ "an unreadable directory preserves its diagnostic unless a sibling can be scanned",
+ { skip: process.platform === "win32" || process.getuid?.() === 0 },
+ async () => {
+ const { run } = await fixtureRun();
+ const denied = join(run.targetPath, "denied");
+ await mkdir(denied, { recursive: true });
+ await writeFile(join(run.targetPath, "ok"), "");
+ await chmod(denied, 0);
+ try {
+ run.includePaths = ["denied"];
+ await assert.rejects(inspect(run), /permission denied|EACCES/iu);
+ run.includePaths.push("ok");
+ await inspect(run);
+ } finally {
+ await chmod(denied, 0o700);
+ }
+ },
+);
+
+test(
+ "a POSIX directory and entry retain their original filesystem bytes",
+ { skip: process.platform === "win32" },
+ async () => {
+ const { run } = await fixtureRun();
+ const { decodePosixBytes } = await importSource(
+ "src/helpers/posix-path.ts",
+ );
+ const name =
+ process.platform === "darwin" ? Buffer.from("雪") : Buffer.from([0xff]);
+ const directory = Buffer.concat([Buffer.from(run.targetPath + "/"), name]);
+ await mkdir(directory, { recursive: true });
+ await writeFile(Buffer.concat([directory, Buffer.from("/"), name]), "");
+ run.includePaths = [decodePosixBytes(name)];
+ await inspect(run);
+ },
+);
+
+test(
+ "Windows distinguishes a lone surrogate from its replacement character",
+ { skip: process.platform !== "win32" },
+ async () => {
+ const { run } = await fixtureRun();
+ await mkdir(run.targetPath);
+ run.includePaths = ["selected-\ud800"];
+ const selected = join(run.targetPath, run.includePaths[0]!);
+ // Create the unpaired UTF-16 name through Python; Node string paths replace it.
+ const changeDirectory = (operation: "mkdir" | "rmdir") =>
+ execFileSync(python, [
+ "-I",
+ "-c",
+ `import os, sys; os.${operation}(bytes.fromhex(sys.argv[1]).decode('utf-16-le','surrogatepass'))`,
+ Buffer.from(selected, "utf16le").toString("hex"),
+ ]);
+ changeDirectory("mkdir");
+ const replacement = join(run.targetPath, "selected-\ufffd");
+ await mkdir(replacement);
+ await writeFile(join(replacement, "source.py"), "");
+ try {
+ await assert.rejects(inspect(run), /target is empty/iu);
+ } finally {
+ changeDirectory("rmdir");
+ }
+ },
+);
+
+for (const stop of ["cancellation", "deadline"]) {
+ test(
+ `a blocked directory read cannot delay ${stop}`,
+ { timeout: 15_000 },
+ async (t) => {
+ const fixture = await fixtureRun();
+ const { run } = fixture;
+ await mkdir(run.targetPath);
+ const scripts = join(fixture.pluginRoot, "scripts");
+ await mkdir(scripts, { recursive: true });
+ const markerDir = join(dirname(run.targetPath), "ready");
+ await mkdir(markerDir);
+ const scriptName = "check_deep_scan_target.py";
+ // Stop the real helper inside enumeration. The marker arms the interruption
+ // only once the child owns the request, even on slow hosts.
+ await writeFile(
+ join(scripts, scriptName),
+ `
+import os, runpy, sys, time
+from pathlib import Path
+real_scan = os.scandir
+def blocked(path):
+ if os.fsdecode(path) == ${JSON.stringify(run.targetPath)}:
+ Path(${JSON.stringify(markerDir)}, str(os.getpid())).touch()
+ time.sleep(30)
+ return real_scan(path)
+os.scandir = blocked
+sys.path.insert(0, ${JSON.stringify(join(pluginRoot, "scripts"))})
+runpy.run_path(${JSON.stringify(join(pluginRoot, "scripts", scriptName))}, run_name="__main__")
+`,
+ );
+ const executor = new FakeExecutor();
+ const coordinator = createCoordinator(
+ fixture,
+ new FakeStore(run),
+ executor,
+ {
+ discoveryTimeoutMs: 60_000,
+ checkFreshTarget: (state, signal) =>
+ checkFreshTarget(state, signal, python, fixture.pluginRoot),
+ },
+ );
+ const watcher = watch(markerDir, { signal: t.signal });
+ const ready = watcher.next();
+ if (stop === "deadline") t.mock.timers.enable({ apis: ["setTimeout"] });
+ coordinator.start();
+ try {
+ const marker = await Promise.race([
+ ready,
+ coordinator
+ .settled()
+ .then((result: DeepScanRunState) =>
+ assert.fail(
+ result.error ?? "coordinator settled before enumeration",
+ ),
+ ),
+ ]);
+ assert.ok(!marker.done && marker.value.filename);
+ const pid = Number(marker.value.filename);
+ assert.ok(Number.isSafeInteger(pid) && pid > 0);
+ if (stop === "deadline") {
+ t.mock.timers.tick(60_000);
+ t.mock.timers.reset();
+ } else coordinator.cancel("fixture cancellation");
+ const result = await coordinator.wait(undefined, 5_000);
+ assert.equal(
+ result?.status,
+ stop === "deadline" ? "succeeded" : "canceled",
+ result?.error,
+ );
+ assert.equal(
+ result.terminalReason,
+ stop === "deadline" ? "capped" : undefined,
+ );
+ assert.equal(executor.discoveryCalls, 0);
+ await eventually(() => {
+ try {
+ process.kill(pid, 0);
+ return false;
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === "ESRCH";
+ }
+ });
+ } finally {
+ t.mock.timers.reset();
+ coordinator.cancel("fixture cleanup");
+ await watcher.return?.();
+ }
+ },
+ );
+}
+
+test("legacy setup workers still require admission before the first discovery", async () => {
+ const fixture = await fixtureRun();
+ const { run } = fixture;
+ await mkdir(run.targetPath);
+ run.persistedWorkers = [
+ {
+ id: "setup-1",
+ kind: "setup",
+ status: "succeeded",
+ mergeState: "none",
+ attempt: 0,
+ promptPath: join(run.scanDir, "setup.md"),
+ artifactDir: join(run.scanDir, "setup"),
+ },
+ ];
+ const executor = new FakeExecutor();
+ const result = await runCoordinator(fixture, new FakeStore(run), executor, {
+ checkFreshTarget: inspect,
+ });
+ assert.equal(result?.status, "failed");
+ assert.match(result.error, /target is empty/iu);
+ assert.equal(executor.discoveryCalls, 0);
+});
+
+test("prior dispatch history bypasses fresh admission", async () => {
+ const fixture = await fixtureRun({ maxDiscoveryRuns: 2 });
+ fixture.run.dispatchedCount = 1;
+ const store = new FakeStore(fixture.run);
+ const executor = new FakeExecutor();
+ const result = await runCoordinator(fixture, store, executor, {
+ checkFreshTarget: async () => {
+ assert.fail("re-entered admission after prior dispatch");
+ },
+ });
+ assert.equal(result?.status, "succeeded", result?.error);
+ assert.equal(executor.discoveryCalls, 1);
+});
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_finite_publication.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_finite_publication.ts
index eac133482..5183f10c8 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_finite_publication.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_finite_publication.ts
@@ -35,7 +35,7 @@ test("Deep engine preserves stopped results for an option-shaped thread ID", asy
const executor = new FakeExecutor({ blockDiscoveryAfterCalls: 0 });
const start = registry.start.bind(registry);
registry.start = (options: CoordinatorOptions) =>
- start({ ...options, executor });
+ start({ ...options, executor, checkFreshTarget: async () => {} });
const calls: string[][] = [];
const { coordinator } = await startDeepScanEngine({
run: store.run,
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 96504302c..0ae45d953 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
@@ -1,4 +1,5 @@
import { jsonLineInputSource } from "./support/json-line-input-source.ts";
+import { readFixtureCoverage } from "./deep_scan_coverage_fixture.ts";
import type { PersistedDeepScanWorker } from "../src/deep-scan/types.js";
import { readJson, readJsonLines } from "./support/json.ts";
import {
@@ -33,7 +34,9 @@ import { startRpcServer } from "./support/rpc-server.ts";
const execFileAsync = promisify(execFile);
-const pluginRoot = path.resolve(mcpAppRoot, "..");
+const pluginRoot = await realpath(
+ path.resolve(mcpAppRoot, "../../../sdk/typescript/_bundled_plugin"),
+);
const workbenchPath = path.join(pluginRoot, "scripts", "workbench_db.py");
let parentSandboxState: unknown = readOnlyParentSandboxState(pluginRoot);
@@ -49,11 +52,13 @@ async function testDeepScanStdioLifecycle() {
const fixtureRoot = await temporaryDirectory("codex-security-deep-stdio-");
const targetPath = path.join(fixtureRoot, "target");
const failedTargetPath = path.join(fixtureRoot, "failed-target");
+ const expiredTargetPath = path.join(fixtureRoot, "expired-target");
const stateDir = path.join(fixtureRoot, "state");
const codexHome = path.join(fixtureRoot, "codex [home]");
const installedPluginRoot = path.join(codexHome, "plugins", "installed");
const runtimeConfigPath = path.join(fixtureRoot, "active-config.toml");
const projectConfigPath = path.join(fixtureRoot, "selected.yaml");
+ const expiredProjectConfigPath = path.join(fixtureRoot, "expired.yaml");
const startLogPath = path.join(fixtureRoot, "fake-codex-started.jsonl");
const exitLogPath = path.join(fixtureRoot, "fake-codex-exited.jsonl");
const restartControlPath = path.join(
@@ -88,11 +93,14 @@ async function testDeepScanStdioLifecycle() {
await mkdir(targetPath, { recursive: true });
await mkdir(failedTargetPath, { recursive: true });
+ await mkdir(expiredTargetPath, { recursive: true });
await mkdir(path.join(codexHome, "codex-security"), { recursive: true });
for (const directory of [
"scripts",
"references",
"schemas",
+ "shared",
+ "mcp/native",
".codex-plugin",
]) {
await cp(
@@ -153,6 +161,10 @@ max_discovery_runs = 2
);
await writeFakeCodex(fakeCodexPath);
await writeFile(projectConfigPath, "scan: {max_time_minutes: 30}\n");
+ await writeFile(
+ expiredProjectConfigPath,
+ "scan: {mode: deep, max_time_minutes: 0.000001}\n",
+ );
await writeFile(
runtimeConfigPath,
`model_reasoning_summary = "detailed"
@@ -256,6 +268,35 @@ service_tier = "ultrafast"
[],
);
+ const expired = await server.request(
+ 5,
+ "tools/call",
+ toolCall(
+ "start_codex_security_deep_scan",
+ {
+ targetPath: expiredTargetPath,
+ projectConfigPath: expiredProjectConfigPath,
+ },
+ threadId,
+ ),
+ );
+ assertNoError(expired);
+ const expiredScanId = expired.result.structuredContent.scanId;
+ const expiredState = await getDeepScan({
+ environment,
+ scanId: expiredScanId,
+ threadId,
+ });
+ assert.equal(expiredState.terminalReason, "capped");
+ assert.equal(expiredState.dispatchedCount, 0);
+ assert.equal(
+ expired.result.structuredContent.completion.scan.reportAvailable,
+ true,
+ );
+ const coverage = await readFixtureCoverage(expiredState.scanDir, stateDir);
+ assert.match(coverage.deferred[0].reason, /discovery time limit elapsed/);
+ assert.deepEqual(await readLogLines(startLogPath), []);
+
const targetRequest = {
targetPath,
scope: ".",
@@ -276,7 +317,10 @@ service_tier = "ultrafast"
}),
);
- const scanId = await waitForScanId({ server });
+ const scanId = await waitForScanId({
+ server,
+ excludedScanIds: [expiredScanId],
+ });
await waitForDeepScanWorker({ environment, scanId, threadId });
const [startedWorker] = await waitForJsonLines(startLogPath, 1);
assert.equal(startedWorker.hasExpectedApiKey, true);
@@ -534,7 +578,7 @@ service_tier = "ultrafast"
const failedScanId = await waitForScanId({
server,
requestId: 20,
- excludedScanIds: [scanId],
+ excludedScanIds: [expiredScanId, scanId],
});
await waitForDeepScanWorker({
environment,
@@ -1601,6 +1645,7 @@ async function getDeepScan({
async function waitForDeepScanWorker(input: Parameters<typeof getDeepScan>[0]) {
await waitFor(async () => {
const deepScan = await getDeepScan(input);
+ if (deepScan.status === "failed") throw new Error(deepScan.error);
const worker = deepScan.workers.find(
(candidate: PersistedDeepScanWorker) =>
candidate.kind === "discovery" && candidate.status === "running",
@@ -1704,8 +1749,10 @@ import { appendFileSync, existsSync, unlinkSync } from "node:fs";
import { spawnSync } from "node:child_process";
const args = process.argv.slice(2);
const input = Buffer.concat(await process.stdin.toArray());
-const workbenchArgs = JSON.parse(input.subarray(0, input.indexOf(10)).toString('utf8'));
-appendFileSync(process.env.FAKE_WORKBENCH_LAUNCH_LOG, JSON.stringify({ args, workbenchArgs, cwd: process.cwd() }) + '\\n');
+const workbenchArgs = args.at(-1).endsWith('workbench_db.py')
+ ? JSON.parse(input.subarray(0, input.indexOf(10)).toString('utf8'))
+ : [];
+if (workbenchArgs.length) appendFileSync(process.env.FAKE_WORKBENCH_LAUNCH_LOG, JSON.stringify({ args, workbenchArgs, cwd: process.cwd() }) + '\\n');
const control = process.env.FAKE_WORKBENCH_CANCEL_FAILURE_CONTROL;
if (workbenchArgs[0] === 'cancel-scan') {
appendFileSync(process.env.FAKE_WORKBENCH_CANCEL_LOG, JSON.stringify(workbenchArgs) + '\\n');
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_store.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_store.ts
index 785375a01..0da10144d 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_store.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_store.ts
@@ -55,6 +55,7 @@ async function testBeginProtocolAndParsing() {
scanRoot: "/fixture/scans",
});
assert.equal(result.scanId, scanId);
+ assert.equal(result.discoveryStarted, false);
assert.equal(result.serviceTier, "default");
assert.deepEqual(result.config, {
workers: 6,
@@ -1061,6 +1062,7 @@ function stateResult(
deepScan: {
scanId,
status: "running",
+ discoveryStarted: false,
targetPath: "/fixture/repository",
scope: ".",
userContext: null,
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
index aa524720d..3e491a909 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_store_integration.ts
@@ -22,8 +22,10 @@ import type {
DeepScanPublication,
ScanDraftInput,
} from "../src/artifact-scan-draft.js";
+import type { CoordinatorOptions } from "../src/deep-scan/coordinator.js";
import {
DeepScanCoordinator,
+ DeepScanCoordinatorRegistry,
FakeExecutor,
} from "./deep_scan_coordinator_fixture.ts";
@@ -33,19 +35,24 @@ const pluginRoot = path.resolve(mcpAppRoot, "..");
const workbenchPath = path.join(pluginRoot, "scripts", "workbench_db.py");
const {
WorkbenchDeepScanStore,
+ startDeepScanEngine,
createScanArtifactContext,
recordCodexSecurityScanDraftViaWorkbench,
saveScanDraftCheckpoint,
} = await importModule({
stdin: {
contents: `export { WorkbenchDeepScanStore } from "./src/deep-scan/store.ts";
+export { startDeepScanEngine } from "./src/deep-scan/engine.ts";
export { createScanArtifactContext } from "./src/artifact-context.ts";
export { recordCodexSecurityScanDraftViaWorkbench, saveScanDraftCheckpoint } from "./src/artifact-scan-draft.ts";`,
resolveDir: mcpAppRoot,
},
+ loader: { ".md": "text" },
});
await testCanonicalParentCheckpointsSurviveSuccessiveWrites();
+await testJoiningCallerAdmission(false);
+await testJoiningCallerAdmission(true);
await testFreeformFailureMessagesAgainstRealWorkbench();
await testWorkerRetryThreadsRemainInScanUsage();
await testReducerCommitAndFinishAgainstRealWorkbench();
@@ -67,6 +74,99 @@ await testCoordinatorCommitResponseRecovery();
await testCoordinatorCommitResponseRecovery("record-deep-scan-iteration");
await testCoordinatorCommitResponseRecovery("finish-deep-scan");
+async function testJoiningCallerAdmission(afterDiscoveryProgress: boolean) {
+ const { fixtureRoot, targetPath, environment } = await createWorkbenchFixture(
+ "deep-scan-joining-caller-",
+ );
+ const runWorkbench = createWorkbenchRunner(environment);
+ const owner = new WorkbenchDeepScanStore(runWorkbench);
+ const joiner = new WorkbenchDeepScanStore(runWorkbench);
+ const threadId = "admission-thread";
+ const scanRoot = path.join(fixtureRoot, "scans");
+ const executor = new FakeExecutor({ blockDiscoveryAfterCalls: 0 });
+ const registry = new DeepScanCoordinatorRegistry();
+ const start = registry.start.bind(registry);
+ registry.start = (options: CoordinatorOptions) =>
+ start({ ...options, executor });
+ try {
+ const created = await owner.begin({ targetPath, threadId, scanRoot });
+ const lease = { scanId: created.scanId, threadId };
+ // The joining caller sees the run before its owner starts discovery.
+ // Admission must use the state returned by the later claim.
+ const joined = await joiner.begin({ ...lease, scanRoot });
+ assert.equal(joined.discoveryStarted, false);
+ if (afterDiscoveryProgress) {
+ const claimed = await owner.claimCoordinator(lease);
+ assert.equal(claimed.acquired, true);
+ await owner.updateProgress({
+ scanId: created.scanId,
+ phase: "discovery",
+ });
+ const observer = await joiner.claimCoordinator(lease);
+ assert.equal(observer.acquired, false);
+ assert.equal(observer.run.discoveryStarted, true);
+ assert.equal(observer.run.dispatchedCount, 0);
+ await expireLease(environment, created.scanId);
+ }
+ await rm(path.join(targetPath, "fixture.py"));
+ const { coordinator } = await startDeepScanEngine({
+ run: joined,
+ store: joiner,
+ registry,
+ runWorkbench,
+ pluginRoot,
+ pythonCommand: process.env.PYTHON?.trim() || "python3",
+ parentSandbox: { filesystemDenies: [] },
+ threadId,
+ });
+ try {
+ if (afterDiscoveryProgress) {
+ await Promise.race([
+ executor.discoveryStarted.promise,
+ coordinator
+ .wait(undefined, 30_000)
+ .then((run: { error?: string } | undefined) =>
+ assert.fail(
+ run?.error ?? "Adopted coordinator did not dispatch a worker",
+ ),
+ ),
+ ]);
+ const recovered = await joiner.get(created.scanId, threadId);
+ assert.equal(recovered.coordinatorGeneration, 3);
+ assert.ok(recovered.dispatchedCount > 0);
+ await assert.rejects(
+ owner.updateProgress({ scanId: created.scanId, phase: "discovery" }),
+ /newer generation/,
+ );
+ } else {
+ const terminal = await coordinator.wait(undefined, 30_000);
+ assert.equal(terminal?.status, "failed");
+ assert.match(terminal.error, /target is empty.*no security audit/iu);
+ assert.equal(executor.discoveryCalls, 0);
+ const persisted = await owner.get(created.scanId, threadId);
+ assert.equal(persisted.status, "failed");
+ assert.deepEqual(persisted.persistedWorkers, []);
+ }
+ } finally {
+ coordinator.cancel("fixture cleanup");
+ await coordinator.wait(undefined, 30_000);
+ }
+ } finally {
+ await rm(fixtureRoot, { recursive: true, force: true });
+ }
+}
+
+async function expireLease(environment: NodeJS.ProcessEnv, scanId: string) {
+ await execFileAsync(process.env.PYTHON?.trim() || "python3", [
+ "-c",
+ `import sqlite3, sys
+with sqlite3.connect(sys.argv[1]) as connection:
+ connection.execute("UPDATE deep_scan_runs SET updated_at = '2000-01-01T00:00:00Z' WHERE scan_id = ?", (sys.argv[2],))`,
+ path.join(environment.CODEX_SECURITY_STATE_DIR!, "workbench.sqlite3"),
+ scanId,
+ ]);
+}
+
async function testCoordinatorCommitResponseRecovery(
exhaustOperation?: "record-deep-scan-iteration" | "finish-deep-scan",
) {
@@ -1944,15 +2044,7 @@ async function testReplacementFailureDuringCancellation() {
assert.equal((await store.get(run.scanId, threadId)).status, "running");
// Expire only the lease clock; claim and failure use the real workbench.
- await execFileAsync(process.env.PYTHON?.trim() || "python3", [
- "-c",
- `import sqlite3, sys
-connection = sqlite3.connect(sys.argv[1])
-connection.execute("UPDATE deep_scan_runs SET updated_at = ? WHERE scan_id = ?", ("2000-01-01T00:00:00Z", sys.argv[2]))
-connection.commit()`,
- path.join(environment.CODEX_SECURITY_STATE_DIR, "workbench.sqlite3"),
- run.scanId,
- ]);
+ await expireLease(environment, run.scanId);
await rm(
path.join(
run.scanDir,
diff --git a/plugins/codex-security/plugin-files.json b/plugins/codex-security/plugin-files.json
index 9edf8e3c5..90687ea92 100644
--- a/plugins/codex-security/plugin-files.json
+++ b/plugins/codex-security/plugin-files.json
@@ -60,6 +60,7 @@
"schemas/tools/discovery-candidates.schema.json",
"schemas/tools/review-items.schema.json",
"schemas/tools/scan-draft.schema.json",
+ "scripts/check_deep_scan_target.py",
"scripts/codex_profile.mjs",
"scripts/codex_session.mjs",
"scripts/deep_scan_config.py",
diff --git a/plugins/codex-security/scripts/check_deep_scan_target.py b/plugins/codex-security/scripts/check_deep_scan_target.py
new file mode 100644
index 000000000..ba4b58457
--- /dev/null
+++ b/plugins/codex-security/scripts/check_deep_scan_target.py
@@ -0,0 +1,75 @@
+"""Check the physical contents of the targets registered for a fresh Deep Scan."""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+
+def check_selected_targets(root: Path, selections: list[str], file_paths: list[str]) -> None:
+ files = set(file_paths)
+
+ def check_path(selection: str) -> tuple[Path, bool]:
+ relative = Path(selection)
+ if (
+ not selection
+ or relative.anchor
+ or ".." in relative.parts
+ or (os.name == "nt" and ":" in selection)
+ ):
+ raise ValueError(f"Scope must be inside repo: {selection}")
+ mode = root.lstat().st_mode
+ if not stat.S_ISDIR(mode):
+ raise ValueError(f"Deep Scan repository is no longer a directory: {root}")
+ target = root
+ for part in relative.parts:
+ target /= part
+ info = target.lstat()
+ mode = info.st_mode
+ if stat.S_ISLNK(mode) or getattr(info, "st_reparse_tag", 0) & 0x20000000:
+ raise ValueError(f"Requested scope must not contain symbolic links: {target}")
+ if not target.resolve(strict=True).is_relative_to(root):
+ raise ValueError(f"Scope must be inside repo: {target}")
+ regular = stat.S_ISREG(mode)
+ if selection in files and not regular:
+ raise ValueError(f"Selected file is no longer a regular file: {selection}")
+ if not regular and not stat.S_ISDIR(mode):
+ raise OSError(errno.ENOTDIR, "Expected a regular file or directory", str(target))
+ return target, regular
+
+ # Every selection must be valid, even when another file or directory is usable.
+ for selection in selections:
+ check_path(selection)
+
+ failure = None
+ for selection in selections:
+ try:
+ # A previously validated directory may have changed during another probe.
+ target, regular = check_path(selection)
+ if regular:
+ return
+ with os.scandir(target) as entries:
+ if next(entries, None) is not None:
+ return
+ except OSError as exc:
+ if selection in files:
+ raise
+ if failure is None:
+ failure = exc
+ if failure is not None:
+ raise failure
+ raise ValueError("Deep Scan target is empty; no security audit was performed.")
+
+
+if __name__ == "__main__":
+ request = json.load(sys.stdin)
+ try:
+ check_selected_targets(
+ Path(request["targetPath"]), request["includePaths"], request["filePaths"]
+ )
+ except (OSError, ValueError) as exc:
+ sys.exit(str(exc))
diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.py
index 5b197d82e..1d42e4fcf 100644
--- a/plugins/codex-security/scripts/deep_scan_workbench.py
+++ b/plugins/codex-security/scripts/deep_scan_workbench.py
@@ -17,6 +17,7 @@ import workbench_saved_results as saved_results
from deep_scan_config import resolve_deep_scan_setup
from workbench.handoff import require_current_continuation
from workbench.storage import create_private_directory
+from workbench_constants import PHASES
from workbench_source_scopes import capture_source_scopes
from workbench_target import directory_snapshot_regular_file_count
from workbench_validation import optional_text, require_uuid, user_context_argument
@@ -338,6 +339,11 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
"coordinatorGeneration": run["coordinator_generation"],
"status": run["status"],
"phase": run["phase"],
+ # Older coordinators could persist discovery on the parent before dispatching.
+ "discoveryStarted": (
+ PHASES.index(scan["phase"]) >= PHASES.index("discovery")
+ or run["phase"] in {"discovery", "reducing"}
+ ),
"config": {
"workers": run["workers"],
"subagents": run["subagents"],
diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.py
index 8512643ab..20bb05510 100644
--- a/plugins/codex-security/tests/test_workbench_deep_scan.py
+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py
@@ -3,9 +3,11 @@ from __future__ import annotations
import hashlib
import json
import os
+import runpy
import sqlite3
import uuid
from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from pathlib import Path
@@ -93,6 +95,33 @@ def start_empty_target_scan(tmp_path: Path, *, config: str | None = None) -> Dee
return DeepScan(state_dir, codex_home, str(run["scanId"]), Path(str(run["scanDir"])))
+def test_target_admission_reads_one_entry_without_looking_up_its_type(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ script = Path(__file__).resolve().parents[1] / "scripts" / "check_deep_scan_target.py"
+ check_selected_targets = runpy.run_path(str(script))["check_selected_targets"]
+ events = []
+
+ def entries():
+ events.append("read")
+ # A filesystem can report DT_UNKNOWN. Any entry-type lookup here fails.
+ yield object()
+ pytest.fail("admission read a second directory entry")
+
+ @contextmanager
+ def scandir(path):
+ assert Path(path) == tmp_path
+ try:
+ yield entries()
+ finally:
+ events.append("closed")
+
+ monkeypatch.setattr(os, "scandir", scandir)
+ check_selected_targets(tmp_path, ["."], [])
+ assert events == ["read", "closed"]
+
+
def restore_v53_schema(state_dir: Path) -> None:
with sqlite3.connect(state_dir / "workbench.sqlite3") as connection:
connection.execute("DROP TRIGGER classify_legacy_scan_recipe")
@@ -431,6 +460,7 @@ def test_legacy_generation_with_active_worker_observes_grace_then_adopts(tmp_pat
assert adopted["deepScan"]["coordinatorGeneration"] == 2
assert adopted["deepScan"]["workers"][0]["status"] == "canceled"
assert adopted["deepScan"]["dispatchedCount"] == 0
+ assert adopted["deepScan"]["discoveryStarted"] is True
def test_expired_coordinator_preserves_incomplete_setup(tmp_path: Path) -> None:
@@ -450,6 +480,35 @@ def test_expired_coordinator_preserves_incomplete_setup(tmp_path: Path) -> None:
assert not inventory.exists()
+def test_observer_and_successor_see_discovery_progress_before_first_dispatch(
+ tmp_path: Path,
+) -> None:
+ deep = start_empty_target_scan(tmp_path)
+ owner = claim_deep_scan_coordinator(deep.state_dir, deep.codex_home, deep.id)["deepScan"]
+ assert owner["discoveryStarted"] is False
+
+ deep.command(
+ "update-progress",
+ "--phase",
+ "discovery",
+ "--coordinator-generation",
+ str(owner["coordinatorGeneration"]),
+ )
+ before = deep.read("thread-deep-scan")
+ observed = claim_deep_scan_coordinator(deep.state_dir, deep.codex_home, deep.id)
+ assert observed["coordinatorDisposition"] == "observing"
+ assert observed["deepScan"]["updatedAt"] == before["updatedAt"]
+
+ expire_deep_scan_coordinator(deep.state_dir, deep.id)
+ adopted = claim_deep_scan_coordinator(deep.state_dir, deep.codex_home, deep.id)
+ assert adopted["coordinatorDisposition"] == "adopted"
+ for run in (before, observed["deepScan"], adopted["deepScan"]):
+ assert run["phase"] == "setup"
+ assert run["discoveryStarted"] is True
+ assert run["dispatchedCount"] == 0
+ assert run["workers"] == []
+
+
@pytest.mark.cross_platform
def test_paused_discovery_resumes_after_restart_with_original_handoff_claim(
tmp_path: Path,