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
chore(codex-security): sync public projection
mldangelo-oai8d753f13666b
diff --git a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.pyindex 0a8f1f141..f3226a321 100644--- a/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py+++ b/sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py@@ -1962,9 +1962,12 @@ def _write_sarif_projection_if_possible() -> None:try:write_sarif_projection(scan_dir, source_root, schema_dir)- except (ContractError, OSError):- # SARIF is a downstream projection. Call the strict writer directly when it is required.- pass+ except (ContractError, OSError) as error:+ print(+ f"codex-security: warning: automatic SARIF export failed: {error}. "+ "Run `codex-security export <scan-dir> --export-format sarif` to retry.",+ file=sys.stderr,+ )PreparedScanFinalization = tuple[diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 46db830ea..0b20d8af6 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -37,6 +37,7 @@ import {workerStatusFromEvent,type ScanWorkerStatus,} from "./worker-progress.js";+import { CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION } from "./version.js";import {bootstrapPlugin,cleanupSdkDirectory,@@ -107,9 +108,17 @@ export interface ScanOptions {onScanStarted?: () => void;onReconnect?: (attempt: number, maxAttempts: number) => void;onWorkerStatus?: (status: ScanWorkerStatus) => void;+ onObserverError?: (observer: ScanObserverName, error: unknown) => void;signal?: AbortSignal;}+type ScanObserverName =+ | "onOutputArchived"+ | "onOutputDirReady"+ | "onScanStarted"+ | "onReconnect"+ | "onWorkerStatus";+export interface ScanPreflight {repository: string;target: NormalizedTarget;@@ -124,9 +133,9 @@ interface LocalScanInputs extends ScanPreflight {export interface CodexSecurityMetadata {sdk: "@openai/codex-sdk";- sdkVersion: "0.144.6";+ sdkVersion: string;executable: "@openai/codex";- executableVersion: "0.144.6";+ executableVersion: string;}interface ClientDependencies {@@ -153,9 +162,9 @@ export class CodexSecurity {public readonly config: Readonly<CodexSecurityConfig>;public readonly metadata: CodexSecurityMetadata = {sdk: "@openai/codex-sdk",- sdkVersion: "0.144.6",+ sdkVersion: CODEX_SDK_VERSION,executable: "@openai/codex",- executableVersion: "0.144.6",+ executableVersion: CODEX_EXECUTABLE_VERSION,};readonly #dependencies: ClientDependencies;@@ -294,11 +303,22 @@ export class CodexSecurity {temporaryRoot,(path) => requireOutputOutsideRepository(protectedRoot, path),options.archiveExisting,- options.onOutputArchived,+ (archiveDir) =>+ notifyObserver(+ "onOutputArchived",+ options.onOutputArchived,+ options.onObserverError,+ archiveDir,+ ),);requireOutputOutsideRepository(protectedRoot, scanDir);requireModelSafeOutputDir(scanDir);- options.onOutputDirReady?.(scanDir);+ notifyObserver(+ "onOutputDirReady",+ options.onOutputDirReady,+ options.onObserverError,+ scanDir,+ );checkOpen();const shellPluginRoot = runtime.plugin.pluginRoot;@@ -334,7 +354,6 @@ export class CodexSecurity {pluginVersion: runtime.plugin.version,};checkOpen();-targetPathsFile =normalized.kind === "paths"? join(@@ -434,6 +453,7 @@ export class CodexSecurity {onScanStarted: options.onScanStarted,onReconnect: options.onReconnect,onWorkerStatus: options.onWorkerStatus,+ onObserverError: options.onObserverError,});} catch (error) {if (this.#closed) this.#requireOpen();@@ -787,6 +807,7 @@ interface ScanEventRunOptions {onScanStarted?: () => void;onReconnect?: (attempt: number, maxAttempts: number) => void;onWorkerStatus?: (status: ScanWorkerStatus) => void;+ onObserverError?: (observer: ScanObserverName, error: unknown) => void;}export async function runScanEvents(@@ -801,13 +822,24 @@ export async function runScanEvents(try {for await (const event of options.events) {const workerStatus = workerStatusFromEvent(event);- if (workerStatus !== null) options.onWorkerStatus?.(workerStatus);+ if (workerStatus !== null) {+ notifyObserver(+ "onWorkerStatus",+ options.onWorkerStatus,+ options.onObserverError,+ workerStatus,+ );+ }if (event.type === "thread.started") {const startedThreadId = event["thread_id"];if (typeof startedThreadId === "string") threadId = startedThreadId;if (!scanStarted) {scanStarted = true;- options.onScanStarted?.();+ notifyObserver(+ "onScanStarted",+ options.onScanStarted,+ options.onObserverError,+ );}} else if (event.type === "item.completed" &&@@ -833,7 +865,12 @@ export async function runScanEvents(const reconnect = reconnectAttempt(message);if (reconnect === null) throw new CodexSecurityError(message);lastStreamError = message;- options.onReconnect?.(...reconnect);+ notifyObserver(+ "onReconnect",+ options.onReconnect,+ options.onObserverError,+ ...reconnect,+ );}}if (options.signal.aborted) {@@ -989,6 +1026,20 @@ async function collectResult(});}+function notifyObserver<Arguments extends unknown[]>(+ observerName: ScanObserverName,+ observer: ((...args: Arguments) => void) | undefined,+ onObserverError:+ | ((observer: ScanObserverName, error: unknown) => void)+ | undefined,+ ...args: Arguments+): void {+ void Promise.resolve()+ .then(() => observer?.(...args))+ .catch((error: unknown) => onObserverError?.(observerName, error))+ .catch(() => {});+}+function environmentApiKey(environment: ProcessEnvironment): string | null {for (const requested of ["OPENAI_API_KEY", "CODEX_API_KEY"]) {const canonical = environment[requested]?.trim();diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 791aa874f..82ef24633 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -248,33 +248,7 @@ const DEFAULT_DEPENDENCIES: CliDependencies = {});const forwarded =arguments_.output === "-" && output !== undefined- ? pipeline(- invocation.stdout,- output instanceof NodeWritable- ? output- : new NodeWritable({- write(chunk, _encoding, callback) {- try {- if (output.write(chunk)) {- callback();- } else {- callback(- new CodexSecurityError(- "The export stdout stream cannot report backpressure safely.",- ),- );- }- } catch (error) {- callback(- error instanceof Error- ? error- : new Error(String(error)),- );- }- },- }),- { end: false },- )+ ? writeCliOutput(output, invocation.stdout): Promise.resolve(invocation.stdout.resume());let status: number;try {@@ -303,6 +277,47 @@ const DEFAULT_DEPENDENCIES: CliDependencies = {},};+async function writeCliOutput(+ output: Writable,+ value: string | Uint8Array | AsyncIterable<Uint8Array>,+): Promise<void> {+ const destination = new NodeWritable({+ write(chunk, _encoding, callback) {+ try {+ if (output instanceof NodeWritable) {+ output.write(chunk, callback);+ } else if (output.write(chunk)) {+ callback();+ } else {+ callback(+ new CodexSecurityError(+ "The export stdout stream cannot report backpressure safely.",+ ),+ );+ }+ } catch (error) {+ callback(error instanceof Error ? error : new Error(String(error)));+ }+ },+ });+ const forwardError = (error: Error): void => {+ destination.destroy(error);+ };+ if (output instanceof NodeWritable) output.once("error", forwardError);+ try {+ await pipeline(+ typeof value === "string" || value instanceof Uint8Array+ ? [value]+ : value,+ destination,+ );+ } finally {+ if (output instanceof NodeWritable) {+ output.removeListener("error", forwardError);+ }+ }+}+export function exportEnvironment(environment: NodeJS.ProcessEnv = process.env,): NodeJS.ProcessEnv {@@ -730,8 +745,14 @@ export async function main();return 2;}- output.write(frameworkOutput);- return exitCode;+ if (frameworkOutput.length === 0) return exitCode;+ try {+ await writeCliOutput(output, frameworkOutput);+ return exitCode;+ } catch (error) {+ errorOutput.write(`codex-security: ${cliErrorMessage(error)}\n`);+ return 2;+ }}function validateCliArguments(@@ -899,7 +920,16 @@ async function runExport(: !isOutsidePath(scanRelativeOutput)? join(canonicalScan, scanRelativeOutput): join(- await realpath(dirname(arguments_.output)),+ await realpath(dirname(arguments_.output)).catch(+ (error: NodeJS.ErrnoException) => {+ if (error.code === "ENOENT") {+ throw new CodexSecurityError(+ `Export output directory does not exist: ${dirname(arguments_.output)}. Create the directory and retry.`,+ );+ }+ throw error;+ },+ ),basename(arguments_.output),);if (arguments_.output !== "-") {@@ -924,7 +954,9 @@ async function runExport(output,);if (arguments_.output === "-") {- if (contents !== undefined) output.write(Buffer.from(contents));+ if (contents !== undefined) {+ await writeCliOutput(output, Buffer.from(contents));+ }} else {errorOutput.write(`${arguments_.format.toUpperCase()}: ${arguments_.output}\n`,@@ -1035,6 +1067,11 @@ async function runScan(progress.stage(message);progress.startTimer("Running scan");},+ onObserverError: (observer, error) => {+ errorOutput.write(+ `codex-security: warning: ${observer} observer failed: ${cliErrorMessage(error)}\n`,+ );+ },};if (arguments_.dryRun) {preflight = await security.preflight(repository, options);diff --git a/sdk/typescript/src/version.ts b/sdk/typescript/src/version.tsindex 52afeb02a..c71a6db34 100644--- a/sdk/typescript/src/version.ts+++ b/sdk/typescript/src/version.ts@@ -1,13 +1,20 @@import { readFileSync } from "node:fs";-/** npm-compatible successor to the Python package version 0.1.0b3. */-export const VERSION = manifestVersion(+const PACKAGE_VERSIONS = packageVersions(new URL("../package.json", import.meta.url),- "package",);++/** npm-compatible successor to the Python package version 0.1.0b3. */+export const VERSION = PACKAGE_VERSIONS.package;+export const CODEX_SDK_VERSION = PACKAGE_VERSIONS.sdk;+export const CODEX_EXECUTABLE_VERSION = PACKAGE_VERSIONS.executable;export const BUNDLED_PLUGIN_VERSION = "0.1.14" as const;-function manifestVersion(url: URL, label: string): string {+function packageVersions(url: URL): {+ package: string;+ sdk: string;+ executable: string;+} {try {const manifest: unknown = JSON.parse(readFileSync(url, "utf8"));if (@@ -19,9 +26,30 @@ function manifestVersion(url: URL, label: string): string {) {throw new Error("version must be a non-empty string");}- return manifest.version;+ const dependencies =+ "dependencies" in manifest ? manifest.dependencies : undefined;+ if (typeof dependencies !== "object" || dependencies === null) {+ throw new Error("dependencies must be an object");+ }+ const sdk =+ "@openai/codex-sdk" in dependencies+ ? dependencies["@openai/codex-sdk"]+ : undefined;+ const executable =+ "@openai/codex" in dependencies+ ? dependencies["@openai/codex"]+ : undefined;+ if (+ typeof sdk !== "string" ||+ sdk.length === 0 ||+ typeof executable !== "string" ||+ executable.length === 0+ ) {+ throw new Error("Codex dependencies must have non-empty versions");+ }+ return { package: manifest.version, sdk, executable };} catch (error) {- throw new Error(`Unable to read Codex Security ${label} version.`, {+ throw new Error("Unable to read Codex Security package versions.", {cause: error,});}diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex ba835e9f2..e64b6885f 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -27,6 +27,7 @@ import {InvalidTargetError,OutputDirectoryError,OutputInsideProtectedRootError,+ type ScanOptions,ScanInterruptedError,type ScanWorkerStatus,} from "../src/index.js";@@ -41,6 +42,10 @@ import { writeCodexConfig } from "../src/config.js";import { normalizeTarget } from "../src/targets.js";import { INTEGRATION_TARGET, PLUGIN_ROOT } from "./plugin-root.js";+type ScanObserverName = Parameters<+ NonNullable<ScanOptions["onObserverError"]>+>[0];+const REPOSITORY_ROOT = fileURLToPath(new URL("../../..", import.meta.url));const EXAMPLE = join(PLUGIN_ROOT, "examples", "completed-scan");const temporaryDirectories: string[] = [];@@ -97,6 +102,7 @@ function runEvents(onReconnect?: (attempt: number, maxAttempts: number) => void,onWorkerStatus?: (status: ScanWorkerStatus) => void,onScanStarted?: () => void,+ onObserverError?: (observer: ScanObserverName, error: unknown) => void,): ReturnType<typeof runScanEvents> {return runScanEvents({thread: {@@ -112,6 +118,7 @@ function runEvents(onScanStarted,onReconnect,onWorkerStatus,+ onObserverError,expectation: {repository: "/repository",repositoryRevision: "deadbeef",@@ -198,6 +205,7 @@ describe("one-shot scan events", () => {test("reports a scan as started only once if thread events are replayed", async () => {const scanDir = await copyCompletedScan(await temporaryDirectory());let starts = 0;+ const observerErrors: Array<[ScanObserverName, string]> = [];async function* replayedEvents(): AsyncGenerator<ThreadEvent> {yield { type: "thread.started", thread_id: "thread-1" };@@ -212,10 +220,17 @@ describe("one-shot scan events", () => {undefined,() => {starts += 1;+ throw new Error("start observer exploded");+ },+ (observer, error) => {+ observerErrors.push([observer, (error as Error).message]);},);expect(starts).toBe(1);+ expect(observerErrors).toEqual([+ ["onScanStarted", "start observer exploded"],+ ]);});test("retains partial output and reports interruption", async () => {@@ -258,6 +273,46 @@ describe("one-shot scan events", () => {await expect(stat(scanDir)).resolves.toBeDefined();});+ test("isolates synchronous and asynchronous progress-observer failures", async () => {+ for (const asynchronous of [false, true]) {+ const scanDir = await copyCompletedScan(await temporaryDirectory());+ const observerErrors: Array<[ScanObserverName, string]> = [];+ async function* reconnectingEvents(): AsyncGenerator<ThreadEvent> {+ yield { type: "thread.started", thread_id: "thread-1" };+ yield { type: "error", message: "Reconnecting... 2/5" };+ yield {+ type: "turn.completed",+ usage: {+ input_tokens: 1,+ cached_input_tokens: 0,+ output_tokens: 1,+ reasoning_output_tokens: 0,+ },+ };+ }++ await expect(+ runEvents(+ scanDir,+ reconnectingEvents(),+ new AbortController(),+ () => {+ const error = new Error("observer exploded");+ if (asynchronous) return Promise.reject(error);+ throw error;+ },+ undefined,+ undefined,+ (observer, error) => {+ observerErrors.push([observer, (error as Error).message]);+ if (asynchronous) return Promise.reject(new Error("report failed"));+ },+ ),+ ).resolves.toBeDefined();+ expect(observerErrors).toEqual([["onReconnect", "observer exploded"]]);+ }+ });+test("keeps the Codex stream alive through reconnect notifications", async () => {const scanDir = await copyCompletedScan(await temporaryDirectory());const reconnects: Array<[number, number]> = [];@@ -827,6 +882,7 @@ describe("CodexSecurity orchestration", () => {await mkdir(output, { mode: 0o700 });await writeFile(join(output, "previous.txt"), "previous scan\n");let archived: string | undefined;+ const observerErrors: Array<[ScanObserverName, string]> = [];const client = new TestClient({},{@@ -851,9 +907,16 @@ describe("CodexSecurity orchestration", () => {archiveExisting: true,onOutputArchived: (archiveDir) => {archived = archiveDir;+ throw new Error("archive observer exploded");+ },+ onObserverError: (observer, error) => {+ observerErrors.push([observer, (error as Error).message]);},}),).rejects.toThrow("scan did not start");+ expect(observerErrors).toEqual([+ ["onOutputArchived", "archive observer exploded"],+ ]);expect(archived?.startsWith(`${output}.previous-`)).toBe(true);expect(await readFile(join(archived!, "previous.txt"), "utf8")).toBe("previous scan\n",diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.tsindex 3028091da..209f98df8 100644--- a/sdk/typescript/tests-ts/cli.test.ts+++ b/sdk/typescript/tests-ts/cli.test.ts@@ -872,6 +872,33 @@ describe("CLI", () => {}});+ test("waits for delayed stdout writes without closing the destination", async () => {+ let contents = "";+ const stdout = new Writable({+ write(chunk, _encoding, callback) {+ setTimeout(() => {+ contents += chunk.toString();+ callback();+ }, 20);+ },+ });++ try {+ expect(+ await main(+ ["export", "scan", "--export-format", "json", "--output", "-"],+ stdout,+ capture().stream,+ dependencies(),+ ),+ ).toBe(0);+ expect(contents).toBe('{"documentType":"codex-security.findings"}\n');+ expect(stdout.writableEnded).toBe(false);+ } finally {+ stdout.destroy();+ }+ });+test.skipIf(process.platform === "win32")("streams a large stdout export through a slow destination without buffering or status noise",async () => {@@ -893,9 +920,11 @@ describe("CLI", () => {let bytes = 0;let writes = 0;let drains = 0;+ let emptyWrites = 0;const stdout = new Writable({highWaterMark: 32 * 1024,write(chunk, _encoding, callback) {+ if (chunk.length === 0) emptyWrites += 1;bytes += chunk.length;writes += 1;setTimeout(callback, 1);@@ -926,6 +955,7 @@ describe("CLI", () => {expect(bytes).toBe(expectedBytes);expect(writes).toBeGreaterThan(1);expect(drains).toBeGreaterThan(0);+ expect(emptyWrites).toBe(0);expect(stderr.text()).toBe("");const lightweight = capture();@@ -1045,6 +1075,31 @@ describe("CLI", () => {}});+ test("explains a missing export-output directory", async () => {+ const root = await mkdtemp(+ join(tmpdir(), "codex-security-export-missing-"),+ );+ try {+ const output = join(root, "reports", "results.sarif");+ const stderr = capture();+ expect(+ await main(+ ["export", "scan", "--output", output],+ capture().stream,+ stderr.stream,+ dependencies(),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain(+ `Export output directory does not exist: ${join(root, "reports")}`,+ );+ expect(stderr.text()).toContain("Create the directory and retry");+ expect(stderr.text()).not.toContain("ENOENT");+ } finally {+ await rm(root, { recursive: true, force: true });+ }+ });+test("rejects a repository-controlled output symlink without following it", async () => {const directory = await mkdtemp(join(tmpdir(), "codex-security-export-"));try {@@ -1760,6 +1815,65 @@ describe("CLI", () => {expect(stdout.text()).toContain("completeness: complete");});+ test("reports isolated observer failures without failing the scan", async () => {+ const stdout = capture();+ const stderr = capture();+ const deps = dependencies();+ deps.createSecurity = () => ({+ run: async (_repository, options) => {+ options?.onObserverError?.(+ "onWorkerStatus",+ new Error(`status observer failed ${SYNTHETIC_CREDENTIALS}`),+ );+ return fakeResult();+ },+ close: async () => {},+ preflight: async () => fakePreflight(),+ });++ expect(+ await main(["scan", ".", "--json"], stdout.stream, stderr.stream, deps),+ ).toBe(0);+ expect(JSON.parse(stdout.text())).toEqual(fakeResult().toJSON());+ expect(stderr.text()).toContain(+ `codex-security: warning: onWorkerStatus observer failed: status observer failed ${REDACTED_CREDENTIALS}`,+ );+ expect(stderr.text()).not.toContain("SYNTHETIC_OPENAI_VALUE_123");+ });++ test("maps failed scan stdout writes to the runtime-error exit code", async () => {+ const stdout = new Writable({+ write(_chunk, _encoding, callback) {+ callback(new Error("SYNTHETIC_SCAN_STDOUT_WRITE_FAILED"));+ },+ });+ const stderr = capture();++ expect(+ await main(["scan", "--json"], stdout, stderr.stream, dependencies()),+ ).toBe(2);+ expect(stderr.text()).toContain("SYNTHETIC_SCAN_STDOUT_WRITE_FAILED");+ });++ test("maps failed export stdout writes to the runtime-error exit code", async () => {+ const stdout = new Writable({+ write(_chunk, _encoding, callback) {+ callback(new Error("SYNTHETIC_EXPORT_STDOUT_WRITE_FAILED"));+ },+ });+ const stderr = capture();++ expect(+ await main(+ ["export", "scan", "--output", "-"],+ stdout,+ stderr.stream,+ dependencies(),+ ),+ ).toBe(2);+ expect(stderr.text()).toContain("SYNTHETIC_EXPORT_STDOUT_WRITE_FAILED");+ });+test("reports partial worker capacity on stderr without changing JSON stdout", async () => {const stdout = capture();const stderr = capture();diff --git a/sdk/typescript/tests-ts/skeleton.test.ts b/sdk/typescript/tests-ts/skeleton.test.tsindex 0bc3f5ca4..cc5df587b 100644--- a/sdk/typescript/tests-ts/skeleton.test.ts+++ b/sdk/typescript/tests-ts/skeleton.test.ts@@ -1,3 +1,4 @@+import { readFile } from "node:fs/promises";import { describe, expect, test } from "bun:test";import { CodexSecurity, CodexSecurityError, VERSION } from "../src/index.js";import type {@@ -51,13 +52,16 @@ describe("TypeScript package skeleton", () => {});test("exports the async client and curated error base", async () => {+ const packageJson = JSON.parse(+ await readFile(new URL("../package.json", import.meta.url), "utf8"),+ );const client = new CodexSecurity({ pluginPath: "/tmp/plugin" });expect(client.config.pluginPath).toBe("/tmp/plugin");expect(client.metadata).toEqual({sdk: "@openai/codex-sdk",- sdkVersion: "0.144.6",+ sdkVersion: packageJson.dependencies["@openai/codex-sdk"],executable: "@openai/codex",- executableVersion: "0.144.6",+ executableVersion: packageJson.dependencies["@openai/codex"],});expect(new CodexSecurityError("failure").name).toBe("CodexSecurityError");await client.close();diff --git a/sdk/typescript/tests-ts/targets.test.ts b/sdk/typescript/tests-ts/targets.test.tsindex 2598b37b3..3c104094c 100644--- a/sdk/typescript/tests-ts/targets.test.ts+++ b/sdk/typescript/tests-ts/targets.test.ts@@ -352,7 +352,7 @@ describe("scan target normalization", () => {test("keeps repeated home separators anchored under the home directory", async () => {const root = await mkdtemp(join(tmpdir(), "codex-security-home-"));temporaryDirectories.push(root);- const project = join(root, "project");+ const project = join(await realpath(root), "project");await mkdir(project);const script = `const { normalizeRepository } = await import(process.argv[1]);