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: allow configuring the findings embeddings URL (#765)
Kyle Brownd9ffc9cafdf0
diff --git a/.env.example b/.env.exampleindex 620f51f3d..00e66c9b4 100644--- a/.env.example+++ b/.env.example@@ -1,3 +1,6 @@# Copy to .env in the repository root and set your API key.# Docker Compose passes it to the findings service. Never commit .env.OPENAI_API_KEY=++# Optional full embeddings endpoint URL; unset or empty uses the default below.+# CODEX_SECURITY_EMBEDDINGS_URL=https://api.openai.com/v1/embeddingsdiff --git a/compose.findings.yaml b/compose.findings.yamlindex 9903964cb..b6a29c5d3 100644--- a/compose.findings.yaml+++ b/compose.findings.yaml@@ -11,6 +11,7 @@ services:CODEX_SECURITY_STATE_DIR: /stateOPENAI_API_KEY:CODEX_API_KEY:+ CODEX_SECURITY_EMBEDDINGS_URL:ports:- "127.0.0.1:3000:3000"volumes:diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex fcf99c146..6dcdab97d 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -478,6 +478,7 @@ restrictions.| Variable | Effect || --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ || `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |+| `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). || `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. || `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. || `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |@@ -1356,6 +1357,18 @@ precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using`CODEX_API_KEY` instead. Listing and empty imports do not require a key.A Codex ChatGPT login is not an embedding API credential.+Set `CODEX_SECURITY_EMBEDDINGS_URL` to override the full embeddings endpoint URL,+including its path and any query parameters. Unset or empty values use+`https://api.openai.com/v1/embeddings`. Export it before `codex-security serve`,+or set it in `.env` for Docker Compose, which passes it to the service. For example:++```bash+CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve+```++The configured endpoint receives the finding inputs and the API key as a bearer+token and must support the same OpenAI embeddings request and response format.+The service calls the OpenAI embeddings API with `text-embedding-3-large` and1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'sbundled `cl100k_base` encoding. Long inputs are split without truncation;@@ -1385,8 +1398,8 @@ The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and`CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned ifchanging these settings. Compose binds only to host loopback; the API has noauthentication. Use an authenticated TLS proxy before sharing access. Finding-JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and-generated embeddings stay in the local volume.+JSON is sent to the configured embeddings endpoint (`api.openai.com` over HTTPS+by default); the database and generated embeddings stay in the local volume.### Upgrades and backupsdiff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.tsindex f97806ea0..fa9c228dc 100644--- a/sdk/typescript/src/cli.ts+++ b/sdk/typescript/src/cli.ts@@ -4375,7 +4375,7 @@ export async function main(}).command("serve", {description:- "Start the findings HTTP service (HOST=127.0.0.1, PORT=3000).",+ "Start the findings HTTP service (HOST=127.0.0.1, PORT=3000). CODEX_SECURITY_EMBEDDINGS_URL overrides the embeddings endpoint (default: https://api.openai.com/v1/embeddings).",destructive: true,mcp: false,options: z.object({diff --git a/sdk/typescript/src/server/embeddings.ts b/sdk/typescript/src/server/embeddings.tsindex 8de96771a..ca50e8a05 100644--- a/sdk/typescript/src/server/embeddings.ts+++ b/sdk/typescript/src/server/embeddings.ts@@ -28,6 +28,7 @@ export class OpenAiFindingEmbedder implements FindingEmbedder {url: string,init: RequestInit,) => Promise<Response> = fetch,+ private readonly url: string = "https://api.openai.com/v1/embeddings",) {}async embed(findings: readonly Finding[]): Promise<FindingEmbedding[]> {@@ -79,7 +80,7 @@ export class OpenAiFindingEmbedder implements FindingEmbedder {): Promise<void> {let response: Response;try {- response = await this.request("https://api.openai.com/v1/embeddings", {+ response = await this.request(this.url, {method: "POST",headers: {Authorization: `Bearer ${this.apiKey}`,diff --git a/sdk/typescript/src/server/serve.ts b/sdk/typescript/src/server/serve.tsindex f7a6a9c10..3b718fbbd 100644--- a/sdk/typescript/src/server/serve.ts+++ b/sdk/typescript/src/server/serve.ts@@ -12,6 +12,8 @@ export async function serveFindings(store: new SqliteFindingsStore(environment),embeddings: new OpenAiFindingEmbedder(environment["OPENAI_API_KEY"] ?? environment["CODEX_API_KEY"],+ fetch,+ environment["CODEX_SECURITY_EMBEDDINGS_URL"] || undefined,),host,port,diff --git a/sdk/typescript/tests-ts/cli-serve.test.ts b/sdk/typescript/tests-ts/cli-serve.test.tsindex 8de6bce04..36f7795d0 100644--- a/sdk/typescript/tests-ts/cli-serve.test.ts+++ b/sdk/typescript/tests-ts/cli-serve.test.ts@@ -1,38 +1,90 @@import { spawn } from "node:child_process";import { once } from "node:events";-import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";+import { createServer } from "node:http";import { tmpdir } from "node:os";import { join } from "node:path";import { createInterface } from "node:readline";import { expect, test } from "bun:test";import { main } from "../src/cli.js";+import type { FindingsDocument } from "../src/models.js";+import {+ EMBEDDING_DIMENSIONS,+ EMBEDDING_MODEL,+} from "../src/server/embeddings.js";import { capture, dependencies } from "./cli-fixtures.js";+import { PLUGIN_ROOT } from "./plugin-root.js";import { runCommand } from "./support/shell.js";const packageRoot = join(import.meta.dir, "..");const cli = join(packageRoot, "src", "cli.ts");-for (const [name, args, port] of [+for (const [name, args, port, customEmbeddings] of [["CLI", [cli, "serve"], "0"],["CLI --port overrides PORT", [cli, "serve", "--port", "0"], "invalid"],["CLI --port=0 overrides PORT", [cli, "serve", "--port=0"], "invalid"],+ ["CLI with custom embeddings URL", [cli, "serve"], "0", true],["standalone entrypoint",[join(packageRoot, "src", "server", "index.ts")],"0",],+ [+ "standalone entrypoint with custom embeddings URL",+ [join(packageRoot, "src", "server", "index.ts")],+ "0",+ true,+ ],] as const) {test(`${name} serves findings with isolated state and shuts down`, async () => {const root = await mkdtemp(join(tmpdir(), "codex-security-serve-"));const state = join(root, "state with spaces");+ const requests: {+ url: string | undefined;+ authorization: string | undefined;+ }[] = [];+ const provider = customEmbeddings+ ? createServer((request, response) => {+ requests.push({+ url: request.url,+ authorization: request.headers.authorization,+ });+ request.resume();+ response.setHeader("Content-Type", "application/json");+ response.end(+ JSON.stringify({+ model: EMBEDDING_MODEL,+ data: [+ {+ index: 0,+ embedding: Array.from(+ { length: EMBEDDING_DIMENSIONS },+ (_, index) => (index === 0 ? 1 : 0),+ ),+ },+ ],+ }),+ );+ })+ : undefined;+ let embeddingsUrl = "";+ if (provider) {+ provider.listen(0, "127.0.0.1");+ await once(provider, "listening");+ const address = provider.address();+ if (!address || typeof address === "string")+ throw new Error("No provider port");+ embeddingsUrl = `http://127.0.0.1:${address.port}/custom/embeddings?api-version=test`;+ }const child = spawn(process.execPath, [...args], {env: {...process.env,CODEX_SECURITY_STATE_DIR: state,HOST: "127.0.0.1",PORT: port,- OPENAI_API_KEY: "",+ OPENAI_API_KEY: customEmbeddings ? "synthetic-key" : "",CODEX_API_KEY: "",+ CODEX_SECURITY_EMBEDDINGS_URL: embeddingsUrl,},stdio: ["ignore", "pipe", "pipe"],timeout: 20_000,@@ -57,6 +109,29 @@ for (const [name, args, port] of [const response = await fetch(`${base}/v1/findings`);expect(response.status).toBe(200);expect(await response.json()).toMatchObject({ findings: [], total: 0 });+ if (customEmbeddings) {+ const document = JSON.parse(+ await readFile(+ join(PLUGIN_ROOT, "examples/completed-scan/findings.json"),+ "utf8",+ ),+ ) as FindingsDocument;+ const imported = await fetch(`${base}/v1/bulk/findings`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({+ repositoryId: "synthetic-repository",+ findings: [document.findings[0]],+ }),+ });+ expect(imported.status, await imported.text()).toBe(201);+ expect(requests).toEqual([+ {+ url: "/custom/embeddings?api-version=test",+ authorization: "Bearer synthetic-key",+ },+ ]);+ }expect((await stat(join(state, "workbench.sqlite3"))).isFile()).toBe(true,);@@ -70,6 +145,10 @@ for (const [name, args, port] of [child.kill("SIGKILL");}await exited;+ if (provider)+ await new Promise<void>((resolve, reject) =>+ provider.close((error) => (error ? reject(error) : resolve())),+ );await rm(root, { recursive: true, force: true });}}, 30_000);