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

feat: allow configuring the findings embeddings URL (#765)

Kyle Brownd9ffc9cafdf0
diff --git a/.env.example b/.env.example
index 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/embeddings
diff --git a/compose.findings.yaml b/compose.findings.yaml
index 9903964cb..b6a29c5d3 100644
--- a/compose.findings.yaml
+++ b/compose.findings.yaml
@@ -11,6 +11,7 @@ services:
CODEX_SECURITY_STATE_DIR: /state
OPENAI_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.md
index 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` and
1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
bundled `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 if
changing these settings. Compose binds only to host loopback; the API has no
authentication. 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 backups
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 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.ts
index 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.ts
index 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.ts
index 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);