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(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.mjsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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",+ "[email protected]",+ "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.tsindex 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.tsnew file mode 100644index 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",+ "[email protected]",+ "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();+ }+ });+});