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
feat(sdk): attribute Responses traffic to SDK and CLI (#350)
mldangelo-oai30e4a11be9a3
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 0df4d1a42..0a4929e7d 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -258,6 +258,12 @@ export interface CodexSecurityMetadata {executableVersion: string;}+export type CodexSecuritySurface = "cli" | "sdk";++interface CodexSecurityRuntimeOptions {+ surface: CodexSecuritySurface;+}+interface ClientDependencies {createCodex(options: CodexOptions): CodexClientLike;environment: ProcessEnvironment;@@ -298,6 +304,7 @@ export class CodexSecurity {};readonly #dependencies: ClientDependencies;+ readonly #surface: CodexSecuritySurface;readonly #loginHandles = new Set<CodexLoginHandle>();readonly #abortController = new AbortController();#activeOperation: Promise<unknown> | null = null;@@ -308,12 +315,20 @@ export class CodexSecurity {#closePromise: Promise<void> | null = null;public constructor(config?: CodexSecurityConfig);+ /** @internal */+ public constructor(+ config: CodexSecurityConfig,+ dependencies: ClientDependencies,+ runtimeOptions: CodexSecurityRuntimeOptions,+ );public constructor(config: CodexSecurityConfig = {},dependencies: ClientDependencies = DEFAULT_DEPENDENCIES,+ runtimeOptions: CodexSecurityRuntimeOptions = { surface: "sdk" },) {this.config = structuredClone(config);this.#dependencies = dependencies;+ this.#surface = runtimeOptions.surface;}public async run(@@ -953,6 +968,9 @@ export class CodexSecurity {...(sdkCodexConfig as NonNullable<CodexOptions["config"]>),default_permissions: SCAN_PERMISSION_PROFILE,allow_login_shell: false,+ responses_api_metadata: {+ codex_security_surface: this.#surface,+ },},});const thread = codex.startThread({@@ -1686,6 +1704,19 @@ async function prepareDeepScanConfig();}+export function createSecurity(+ config: CodexSecurityConfig = {},+): CodexSecurity {+ return createSecurityInternal(config, { surface: "sdk" });+}++export function createSecurityInternal(+ config: CodexSecurityConfig = {},+ runtimeOptions: CodexSecurityRuntimeOptions,+): CodexSecurity {+ return new CodexSecurity(config, DEFAULT_DEPENDENCIES, runtimeOptions);+}+export async function initialCredentialsAvailable(environment: ProcessEnvironment,ambientHome: string,diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex 00f1024be..fce97c7cc 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -32,6 +32,7 @@ import { parse as parseToml } from "smol-toml";import {classifyConnectionFailure,CodexSecurity,+ createSecurityInternal,scanAuthentication,type DeepScanOptions,type ScanAuthMode,@@ -86,7 +87,8 @@ import {type CodexCommand,} from "./runtime.js";import {- matchScanFindings,+ matchScanFindingsInternal,+ type matchScanFindings,type ScanComparisonInput,} from "./scan-comparison.js";import { readScanLogs } from "./scan-logs.js";@@ -359,7 +361,8 @@ interface CliDependencies {}const DEFAULT_DEPENDENCIES: CliDependencies = {- createSecurity: (config) => new CodexSecurity(config),+ createSecurity: (config) =>+ createSecurityInternal(config, { surface: "cli" }),environment: process.env,prepareAuthenticationHome: prepareCodexSecurityCredentialHome,checkForUpdate: () => checkForUpdate({ environment: process.env }),@@ -484,7 +487,8 @@ const DEFAULT_DEPENDENCIES: CliDependencies = {args,);},- matchFindings: matchScanFindings,+ matchFindings: (input, options) =>+ matchScanFindingsInternal(input, options, { surface: "cli" }),};export async function runCodexSkillCommand(@@ -2368,6 +2372,8 @@ async function runSkill(`model_reasoning_effort=${JSON.stringify(reasoningEffort)}`,"--config",'approval_policy="never"',+ "--config",+ 'responses_api_metadata.codex_security_surface="cli"',"--sandbox","workspace-write","--skip-git-repo-check",diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex f1ef3a1e6..154867eb5 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -1,4 +1,4 @@-export { CodexSecurity } from "./api.js";+export { CodexSecurity, createSecurity } from "./api.js";export { estimateScanCost } from "./cost.js";export type { ScanCost } from "./cost.js";export type { ScanActivity, ScanActivityStatus } from "./scan-activity.js";diff --git a/sdk/typescript/src/scan-comparison.ts b/sdk/typescript/src/scan-comparison.tsindex bcea7ed94..80eb97ea4 100644--- a/sdk/typescript/src/scan-comparison.ts+++ b/sdk/typescript/src/scan-comparison.ts@@ -8,6 +8,7 @@ import {type TurnOptions,} from "@openai/codex-sdk";import { z } from "incur";+import type { CodexSecuritySurface } from "./api.js";import { accountStatus } from "./auth.js";import { CodexSecurityError } from "./errors.js";import {@@ -75,6 +76,14 @@ export type ScanComparisonResult = z.infer<typeof comparisonSchema>;export async function matchScanFindings(input: ScanComparisonInput,options: ScanComparisonOptions = {},+): Promise<ScanComparisonResult> {+ return await matchScanFindingsInternal(input, options, { surface: "sdk" });+}++export async function matchScanFindingsInternal(+ input: ScanComparisonInput,+ options: ScanComparisonOptions = {},+ runtimeOptions: { surface: CodexSecuritySurface },): Promise<ScanComparisonResult> {const codex =options.codex ??@@ -86,6 +95,9 @@ export async function matchScanFindings(),config: {allow_login_shell: false,+ responses_api_metadata: {+ codex_security_surface: runtimeOptions.surface,+ },"features.apps": false,"features.code_mode": false,"features.code_mode_only": false,diff --git a/sdk/typescript/tests-ts/api-environment.test.ts b/sdk/typescript/tests-ts/api-environment.test.tsnew file mode 100644index 000000000..cb6ece735--- /dev/null+++ b/sdk/typescript/tests-ts/api-environment.test.ts@@ -0,0 +1,20 @@+import { describe, expect, test } from "bun:test";+import { environmentValue } from "../src/api.js";++describe("environmentValue", () => {+ test("treats empty values as unset and finds case variants", () => {+ expect(environmentValue({ CODEX_HOME: "" }, "CODEX_HOME")).toBeUndefined();+ expect(+ environmentValue({ CODEX_HOME: " " }, "CODEX_HOME"),+ ).toBeUndefined();+ expect(+ environmentValue(+ { CODEX_HOME: "", Codex_Home: "/ambient" },+ "CODEX_HOME",+ ),+ ).toBe("/ambient");+ expect(environmentValue({ Home: "/shell-home" }, "HOME")).toBe(+ "/shell-home",+ );+ });+});diff --git a/sdk/typescript/tests-ts/api-surface.test.ts b/sdk/typescript/tests-ts/api-surface.test.tsnew file mode 100644index 000000000..c8710bbd4--- /dev/null+++ b/sdk/typescript/tests-ts/api-surface.test.ts@@ -0,0 +1,116 @@+import { mkdir } from "node:fs/promises";+import { join } from "node:path";+import type { CodexOptions } from "@openai/codex-sdk";+import { afterEach, describe, expect, test } from "bun:test";+import { CodexSecurity } from "../src/index.js";+import { PLUGIN_ROOT } from "./plugin-root.js";+import {+ completedEvents,+ createApiTestFixtures,+} from "./support/api-events.js";++const fixtures = createApiTestFixtures();+const InternalCodexSecurity = CodexSecurity as unknown as new (+ config: Record<string, unknown>,+ dependencies: Record<string, unknown>,+ runtimeOptions?: { surface: "cli" | "sdk" },+) => CodexSecurity;++afterEach(async () => {+ await fixtures.cleanup();+});++function preparedRuntime(codexHome: string): Record<string, unknown> {+ return {+ codexHome,+ plugin: {+ pluginRoot: PLUGIN_ROOT,+ marketplaceRoot: PLUGIN_ROOT,+ installedRoot: PLUGIN_ROOT,+ marketplaceName: "codex-security-sdk",+ name: "codex-security",+ version: "0.1.0",+ },+ environment: {},+ credentialsAvailable: true,+ };+}++function mockWorkbench(args: readonly string[]) {+ if (args[0] === "register-cli-scan") {+ return {+ scanId: "scan_example_001",+ targetId: "target_sha256_example",+ targetRevision: "deadbeef",+ scanDir: args[args.indexOf("--scan-dir") + 1],+ contract: { target: { allowedKinds: ["git_revision"] } },+ };+ }+ if (args[0] === "get-scan-feedback") {+ return {+ scanId: "scan_example_001",+ targetId: "target_sha256_example",+ falsePositives: [],+ };+ }+ return {};+}++async function scanResponseSurface(runtimeOptions?: {+ surface: "cli" | "sdk";+}): Promise<string | undefined> {+ const root = await fixtures.temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ await mkdir(repository);+ await mkdir(codexHome);+ await mkdir(scanDir, { mode: 0o700 });+ let codexOptions: CodexOptions | null = null;++ const client = new InternalCodexSecurity(+ {},+ {+ environment: {},+ prepareRuntime: async () => preparedRuntime(codexHome),+ resolvePluginPython: async () => "/managed/python",+ prepareOutputDir: async () => scanDir,+ repositoryRevision: async () => "deadbeef",+ runWorkbench: async (_options: unknown, args: readonly string[]) =>+ mockWorkbench(args),+ createCodex: (options: CodexOptions) => {+ codexOptions = options;+ return {+ startThread: () => ({+ id: null,+ async runStreamed() {+ await fixtures.copyCompletedScan(root);+ return { events: completedEvents() };+ },+ }),+ };+ },+ },+ runtimeOptions,+ );++ await client.run(repository);+ await client.close();+ return (+ (codexOptions as CodexOptions | null)?.config?.[+ "responses_api_metadata"+ ] as Record<string, string> | undefined+ )?.["codex_security_surface"];+}++describe("CodexSecurity Responses metadata", () => {+ test("SDK runtime scans use sdk metadata", async () => {+ expect(await scanResponseSurface()).toBe("sdk");+ });++ test("CLI runtime scans use cli metadata instead of sdk metadata", async () => {+ const surface = await scanResponseSurface({ surface: "cli" });+ expect(surface).toBe("cli");+ expect(surface).not.toBe("sdk");+ });+});diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex 9df4a129e..b0069a835 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -37,7 +37,6 @@ import {} from "../src/index.js";import {classifyConnectionFailure,- environmentValue,initialCredentialsAvailable,} from "../src/api.js";import {@@ -287,22 +286,6 @@ describe("CodexSecurity orchestration", () => {);});- test("treats empty environment variables as unset and finds case variants", () => {- expect(environmentValue({ CODEX_HOME: "" }, "CODEX_HOME")).toBeUndefined();- expect(- environmentValue({ CODEX_HOME: " " }, "CODEX_HOME"),- ).toBeUndefined();- expect(- environmentValue(- { CODEX_HOME: "", Codex_Home: "/ambient" },- "CODEX_HOME",- ),- ).toBe("/ambient");- expect(environmentValue({ Home: "/shell-home" }, "HOME")).toBe(- "/shell-home",- );- });-test("selects a real-scan target in the active repository layout", async () => {await expect(stat(join(REPOSITORY_ROOT, INTEGRATION_TARGET)),diff --git a/sdk/typescript/tests-ts/cli-skills.test.ts b/sdk/typescript/tests-ts/cli-skills.test.tsindex 08ed7ff4f..f705898a8 100644--- a/sdk/typescript/tests-ts/cli-skills.test.ts+++ b/sdk/typescript/tests-ts/cli-skills.test.ts@@ -60,6 +60,8 @@ describe("CLI skill commands", () => {'model_reasoning_effort="xhigh"',"--config",'approval_policy="never"',+ "--config",+ 'responses_api_metadata.codex_security_surface="cli"',"--sandbox","workspace-write","--skip-git-repo-check",