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(scans): warn when repository HEAD changes during a scan (#360)

hari75633fb5fd09
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index a09a38418..7646a8382 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -177,6 +177,7 @@ const distModules = [
"server/errors",
"server/sqlite-store",
"server/storage",
+ "target-drift",
"targets",
"terminal-columns",
"terminal-stream",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 955a18ea6..baffd734f 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -309,6 +309,7 @@ import {
validateCommittedDiffCheckout,
validateMode,
} from "./targets.js";
+import { startHeadDriftMonitor } from "./target-drift.js";
import {
inspectTrustedExecutable,
isWithin,
@@ -2217,6 +2218,7 @@ export class CodexSecurity {
id: string;
options: WorkbenchCommandOptions;
} | null = null;
+ let stopHeadDriftMonitor: (() => void) | undefined;
const prepareArtifactRestorer =
this.#dependencies.prepareScanArtifactRestorer ??
prepareScanArtifactRestorer;
@@ -2534,11 +2536,11 @@ export class CodexSecurity {
);
}
checkOpen();
+ const readRepositoryRevision =
+ this.#dependencies.repositoryRevision ?? repositoryRevision;
const expectation: ScanExpectation = {
repository: repo,
- repositoryRevision: await (
- this.#dependencies.repositoryRevision ?? repositoryRevision
- )(repo, signal),
+ repositoryRevision: await readRepositoryRevision(repo, signal),
target: normalized,
mode,
pluginVersion: runtime.plugin.version,
@@ -3165,6 +3167,27 @@ export class CodexSecurity {
notifyObserver(options, "onOutputDirReady")(scanDir);
}
throwIfAborted(signal, scanDir);
+ if (
+ options.onWarning !== undefined &&
+ targetRevision !== null &&
+ (targetKind === "git_revision" ||
+ targetKind === "git_worktree" ||
+ (targetKind === "git_diff" && normalized.kind === "working_tree"))
+ ) {
+ stopHeadDriftMonitor = startHeadDriftMonitor({
+ expectedRevision: registeredRevision,
+ readRevision: (revisionSignal) =>
+ readRepositoryRevision(repo, revisionSignal),
+ signal,
+ onDrift: () =>
+ notifyObserver(
+ options,
+ "onWarning",
+ )(
+ `Repository HEAD changed while the scan was running. This scan remains bound to ${registeredRevision}. To scan the new revision, stop this scan and restart it.`,
+ ),
+ });
+ }
if (
this.#dependencies.hostedScan === undefined &&
((mode !== "deep" && options.onProgress !== undefined) ||
@@ -3712,6 +3735,7 @@ export class CodexSecurity {
? []
: ["--cost-json", JSON.stringify(completionCost)]),
]);
+ stopHeadDriftMonitor?.();
activeScan = null;
const completedScan = completion["scan"];
notifyScanLifecycle(options, completedScan);
@@ -4130,6 +4154,7 @@ export class CodexSecurity {
activeScan = null;
} catch {}
}
+ stopHeadDriftMonitor?.();
if (runPostScan !== null && !signal.aborted) {
scanProgressTracker?.stop();
try {
@@ -4157,6 +4182,7 @@ export class CodexSecurity {
}
throw failure;
} finally {
+ stopHeadDriftMonitor?.();
budgetAbortController.abort();
scanProgressTracker?.stop();
// Temporary-input cleanup must not replace the scan's outcome.
diff --git a/sdk/typescript/src/target-drift.ts b/sdk/typescript/src/target-drift.ts
new file mode 100644
index 000000000..a431a2705
--- /dev/null
+++ b/sdk/typescript/src/target-drift.ts
@@ -0,0 +1,36 @@
+interface HeadDriftMonitorOptions {
+ expectedRevision: string;
+ readRevision: (signal: AbortSignal) => Promise<string | null>;
+ signal: AbortSignal;
+ onDrift: () => void;
+}
+
+export function startHeadDriftMonitor(
+ options: HeadDriftMonitorOptions,
+): () => void {
+ const controller = new AbortController();
+ const signal = AbortSignal.any([options.signal, controller.signal]);
+ let timer: NodeJS.Timeout | undefined;
+ signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+
+ async function check(): Promise<void> {
+ if (signal.aborted) return;
+ try {
+ const revision = await options.readRevision(signal);
+ if (
+ !signal.aborted &&
+ revision !== null &&
+ revision !== options.expectedRevision
+ ) {
+ controller.abort();
+ options.onDrift();
+ }
+ } catch {
+ // Failed reads and warning observers must not interrupt the scan.
+ }
+ if (!signal.aborted) timer = setTimeout(check, 1_000).unref();
+ }
+
+ void check();
+ return () => controller.abort();
+}
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index f4e661e0d..050b9e3d5 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -3126,6 +3126,201 @@ if __name__ == "__main__":
await client.close();
});
+ test.each([false, true])(
+ "warns before completion when repository HEAD drifts (observer fails: %s)",
+ async (observerFails) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ let revision = "deadbeef";
+ let completed = false;
+ const details: unknown[] = [];
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ repositoryRevision: async () => revision,
+ runWorkbench: async (_options, args, input) => {
+ const result = mockWorkbench(args, input);
+ if (args[0] === "register-cli-scan") revision = "changed";
+ return result;
+ },
+ createCodex: () => ({
+ startThread: () => ({
+ id: null,
+ async runStreamed() {
+ expect(details).toEqual([undefined]);
+ expect(completed).toBe(false);
+ await copyCompletedScan(root);
+ return { events: completedEvents() };
+ },
+ }),
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onWarning: (message, detail) => {
+ if (!message.startsWith("Repository HEAD changed")) return;
+ expect(completed).toBe(false);
+ details.push(detail);
+ if (observerFails) throw new Error("Synthetic observer failure");
+ },
+ onObserverError: () => {
+ throw new Error("Synthetic observer error handler failure");
+ },
+ });
+ completed = true;
+ expect(details).toEqual([undefined]);
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
+ test.each(["success", "failure"] as const)(
+ "stops HEAD monitoring before post-scan instructions after %s",
+ async (outcome) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const releaseRead = Promise.withResolvers<void>();
+ let revision = "deadbeef";
+ let reads = 0;
+ let monitorSignal: AbortSignal | undefined;
+ let turns = 0;
+ let finalization: string | undefined;
+ let finalizationAtFollowup: string | undefined;
+ let monitorAbortedAtFollowup: boolean | undefined;
+ const warnings: string[] = [];
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ resolvePluginPython: async () => pythonExecutable()!,
+ repositoryRevision: async (_repository, signal) => {
+ if (++reads > 1) {
+ monitorSignal = signal;
+ await releaseRead.promise;
+ }
+ return revision;
+ },
+ runWorkbench: async (_options, args, input) => {
+ if (args[0] === "complete-scan" || args[0] === "fail-scan") {
+ finalization = args[0];
+ return { scan: { warnings: [] }, targetWarnings: [] };
+ }
+ return mockWorkbench(args, input);
+ },
+ createCodex: codexFactory(async () => {
+ if (++turns === 1) {
+ if (outcome === "failure")
+ return {
+ events: (async function* () {
+ yield {
+ type: "turn.failed" as const,
+ error: { message: "SYNTHETIC_MAIN_SCAN_FAILURE" },
+ };
+ })(),
+ };
+ await copyCompletedScan(root);
+ return { events: completedEvents() };
+ }
+ finalizationAtFollowup = finalization;
+ monitorAbortedAtFollowup = monitorSignal?.aborted;
+ revision = "temporary-follow-up-revision";
+ releaseRead.resolve();
+ // Let the pending read and warning observer settle without a polling delay.
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ revision = "deadbeef";
+ return { events: completedEvents() };
+ }, "thread-1"),
+ });
+ try {
+ const result = client.run(repository, {
+ postScanPrompt:
+ "Inspect another local revision and restore the checkout.",
+ onWarning: (message) => {
+ if (message.startsWith("Repository HEAD changed"))
+ warnings.push(message);
+ },
+ });
+ if (outcome === "success")
+ expect((await result).manifest.scan.status).toBe("completed");
+ else
+ await expect(result).rejects.toThrow("SYNTHETIC_MAIN_SCAN_FAILURE");
+ expect(turns).toBe(2);
+ expect(finalizationAtFollowup).toBe(
+ outcome === "success" ? "complete-scan" : "fail-scan",
+ );
+ expect(monitorAbortedAtFollowup).toBe(true);
+ expect(revision).toBe("deadbeef");
+ expect(warnings).toEqual([]);
+ } finally {
+ releaseRead.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ ["repository", true, 2],
+ ["repository", false, 1],
+ ["worktree", true, 2],
+ ["working_tree", true, 2],
+ ["refs", true, 1],
+ ["unversioned", true, 1],
+ ] as const)(
+ "monitors HEAD only for mutable %s targets with a warning observer (observed: %s)",
+ async (kind, observed, expectedReads) => {
+ const { repository, codexHome, scanDir } = await scanDirectories();
+ if (kind === "refs" || kind === "working_tree") {
+ gitText(["init", "-q"], { cwd: repository });
+ gitText(
+ [
+ "-c",
+ "user.name=Synthetic Test",
+ "-c",
+ "commit",
+ "--allow-empty",
+ "-qm",
+ "Synthetic revision",
+ ],
+ { cwd: repository },
+ );
+ }
+ const readRevision = mock(async () =>
+ kind === "unversioned" ? null : "deadbeef",
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ repositoryRevision: readRevision,
+ runWorkbench: async (_options, args, input) => {
+ const result = mockWorkbench(args, input);
+ if (args[0] === "register-cli-scan" && kind === "worktree")
+ result["contract"] = {
+ target: {
+ allowedKinds: ["git_worktree"],
+ requiredSnapshotDigest: TEST_SNAPSHOT_DIGEST,
+ },
+ };
+ return result;
+ },
+ createCodex: () => {
+ throw new Error("Synthetic scan boundary");
+ },
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ onWarning: observed ? mock() : undefined,
+ target:
+ kind === "refs"
+ ? DiffTarget.refs({ base: "HEAD", head: "HEAD" })
+ : kind === "working_tree"
+ ? DiffTarget.workingTree({ base: "HEAD" })
+ : "repository",
+ }),
+ ).rejects.toThrow("Synthetic scan boundary");
+ expect(readRevision).toHaveBeenCalledTimes(expectedReads);
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
test("passes the workbench snapshot contract to dirty Git scans", async () => {
const { repository, codexHome, scanDir } = await scanDirectories();
const createCodex = mock((_options: CodexOptions) => {
diff --git a/sdk/typescript/tests-ts/cli-patch.test.ts b/sdk/typescript/tests-ts/cli-patch.test.ts
index e48cf48e6..2f6e0b06c 100644
--- a/sdk/typescript/tests-ts/cli-patch.test.ts
+++ b/sdk/typescript/tests-ts/cli-patch.test.ts
@@ -26,6 +26,12 @@ import {
} from "./support/temporary-directories.js";
import { throwing } from "./support/errors.js";
import { createCliTest } from "./support/cli-run.js";
+import { TestClient, mockWorkbench } from "./support/api-client.js";
+import {
+ completedEvents,
+ scanRuntimeDependencies,
+} from "./support/api-events.js";
+import { copyCompletedScan } from "./plugin-root.js";
const CURRENT_REPOSITORY = resolve("/current/repository");
const SAVED_REPOSITORY = resolve("/saved/repository");
@@ -211,6 +217,109 @@ async function runWorkflow(
}
describe("scan and patch workflow", () => {
+ test.each([true, false])(
+ "uses completion validation after an early HEAD drift warning (restored: %s)",
+ async (restored) => {
+ const root = await temporaryDirectory("scan-head-warning-");
+ const repository = join(root, "repository");
+ const codexHome = join(root, "home");
+ const scanDir = join(root, "scan");
+ for (const directory of [repository, codexHome, scanDir])
+ await mkdir(directory, { mode: 0o700 });
+ let revision = "deadbeef";
+ const completionWarning =
+ "Repository HEAD changed while the scan was running; results were saved for the original revision.";
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ repositoryRevision: async () => revision,
+ runWorkbench: async (_options, args, input) => {
+ if (args[0] === "prepare-scan-completion")
+ return {
+ targetWarnings:
+ revision === "deadbeef" ? [] : [completionWarning],
+ };
+ if (args[0] === "complete-scan")
+ return {
+ scan: {
+ warnings: revision === "deadbeef" ? [] : [completionWarning],
+ },
+ };
+ const result = mockWorkbench(args, input);
+ if (args[0] === "register-cli-scan") revision = "changed";
+ return result;
+ },
+ createCodex: () => ({
+ startThread: () => ({
+ id: null,
+ async runStreamed() {
+ expect(earlyDetails).toEqual([undefined]);
+ if (restored) revision = "deadbeef";
+ await copyCompletedScan(root);
+ return { events: completedEvents() };
+ },
+ }),
+ }),
+ });
+ const result = resultWithFindings(["high"]);
+ let patchCalls = 0;
+ const earlyDetails: unknown[] = [];
+ try {
+ const outcome = await runWorkflow(
+ ["scan", repository, "--patch", "--json"],
+ {
+ currentDirectory: repository,
+ result,
+ onCodex: (args, output) => {
+ patchCalls++;
+ completePatches(args, output);
+ return 0;
+ },
+ },
+ {
+ configure: (current) => {
+ current.createSecurity = () => ({
+ preflight: client.preflight.bind(client),
+ validate: client.validate.bind(client),
+ close: client.close.bind(client),
+ run: async (path, options) => {
+ await client.run(path, {
+ ...options,
+ onWarning: (message, details) => {
+ options?.onWarning?.(message, details);
+ if (
+ message.startsWith("Repository HEAD changed") &&
+ message !== completionWarning
+ ) {
+ earlyDetails.push(details);
+ }
+ },
+ });
+ return result;
+ },
+ });
+ },
+ },
+ );
+ expect(outcome.exitCode, outcome.stderr).toBe(restored ? 0 : 2);
+ expect(patchCalls).toBe(restored ? 1 : 0);
+ expect(earlyDetails).toEqual([undefined]);
+ const payload = JSON.parse(outcome.stdout);
+ expect(payload.warnings).toEqual(
+ restored ? undefined : [completionWarning],
+ );
+ expect(outcome.stderr).toContain(
+ "This scan remains bound to deadbeef.",
+ );
+ expect(outcome.stderr).toContain("stop this scan and restart it");
+ if (restored)
+ expect(payload.patches).toMatchObject([{ status: "verified" }]);
+ } finally {
+ await client.close();
+ await rm(root, { recursive: true, force: true });
+ }
+ },
+ );
+
test.each([false, true])(
"shows progress during baseline preparation and cleans up on failure: %p",
async (failSnapshot) => {
diff --git a/sdk/typescript/tests-ts/target-drift.test.ts b/sdk/typescript/tests-ts/target-drift.test.ts
new file mode 100644
index 000000000..1478ccdf8
--- /dev/null
+++ b/sdk/typescript/tests-ts/target-drift.test.ts
@@ -0,0 +1,126 @@
+import { afterEach, describe, expect, jest, test } from "bun:test";
+import { startHeadDriftMonitor } from "../src/target-drift.js";
+import { repositoryRevision } from "../src/targets.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { gitText } from "./support/shell.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures("target-drift-");
+afterEach(cleanup);
+
+describe("head drift monitor", () => {
+ test.each(["stop", "abort"] as const)(
+ "%s cancels an in-flight revision read",
+ async (operation) => {
+ const parent = new AbortController();
+ const started = Promise.withResolvers<AbortSignal>();
+ const cancelled = Promise.withResolvers<unknown>();
+ let warnings = 0;
+ const stop = startHeadDriftMonitor({
+ expectedRevision: "before",
+ signal: parent.signal,
+ readRevision: (signal) => {
+ started.resolve(signal);
+ return new Promise((_resolve, reject) => {
+ signal.addEventListener(
+ "abort",
+ () => {
+ cancelled.resolve(signal.reason);
+ reject(signal.reason);
+ },
+ { once: true },
+ );
+ });
+ },
+ onDrift: () => {
+ warnings++;
+ },
+ });
+ try {
+ const signal = await started.promise;
+ const reason = new Error("Synthetic scan cancellation");
+ if (operation === "stop") stop();
+ else parent.abort(reason);
+ const actualReason = await cancelled.promise;
+ expect(signal.aborted).toBe(true);
+ if (operation === "abort") expect(actualReason).toBe(reason);
+ else expect(parent.signal.aborted).toBe(false);
+ expect(warnings).toBe(0);
+ } finally {
+ stop();
+ }
+ },
+ );
+
+ test("retries failed reads without overlapping them and ignores observer failure", async () => {
+ const parent = new AbortController();
+ jest.useFakeTimers();
+ const first = Promise.withResolvers<string | null>();
+ const revisions = [first.promise, null, "before", "after"];
+ let reads = 0;
+ let warnings = 0;
+ const stop = startHeadDriftMonitor({
+ expectedRevision: "before",
+ signal: parent.signal,
+ readRevision: () => Promise.resolve(revisions[reads++]!),
+ onDrift: () => {
+ warnings++;
+ throw new Error("Synthetic observer failure");
+ },
+ });
+ try {
+ jest.advanceTimersByTime(5_000);
+ expect(reads).toBe(1);
+ first.reject(new Error("Synthetic transient Git failure"));
+ await Promise.resolve();
+ const nextPoll = async () => {
+ jest.advanceTimersByTime(1_000);
+ await Promise.resolve();
+ };
+ await nextPoll(); // Missing revision.
+ await nextPoll(); // Unchanged revision.
+ expect(warnings).toBe(0);
+ await nextPoll(); // Changed revision.
+ jest.advanceTimersByTime(5_000);
+ expect(reads).toBe(4);
+ expect(warnings).toBe(1);
+ } finally {
+ stop();
+ jest.useRealTimers();
+ }
+ });
+
+ test("warns after a real Git HEAD change", async () => {
+ const repository = await temporaryDirectory();
+ gitText(["init", "-q"], { cwd: repository });
+ const commit = () =>
+ gitText(
+ [
+ "-c",
+ "user.name=Synthetic Test",
+ "-c",
+ "commit",
+ "--allow-empty",
+ "-qm",
+ "Synthetic revision",
+ ],
+ { cwd: repository },
+ );
+ commit();
+ const expectedRevision = await repositoryRevision(repository);
+ expect(expectedRevision).not.toBeNull();
+ const warned = Promise.withResolvers<void>();
+ const stop = startHeadDriftMonitor({
+ expectedRevision: expectedRevision!,
+ readRevision: (signal) => repositoryRevision(repository, signal),
+ signal: new AbortController().signal,
+ onDrift: () => warned.resolve(),
+ });
+ try {
+ commit();
+ await warned.promise;
+ } finally {
+ stop();
+ }
+ });
+});