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(typescript): add findings service plumbing (#653)
Kyle Brown406de5cc46a3
diff --git a/.github/workflows/container-ci.yml b/.github/workflows/container-ci.ymlindex 366d1e11e..dcfd6f840 100644--- a/.github/workflows/container-ci.yml+++ b/.github/workflows/container-ci.yml@@ -10,6 +10,7 @@ on:- Dockerfile.dockerignore- compose.yaml- compose.apparmor.yaml+ - compose.findings.yaml- docker/**- plugins/codex-security/**- sdk/typescript/**@@ -21,6 +22,7 @@ on:- Dockerfile.dockerignore- compose.yaml- compose.apparmor.yaml+ - compose.findings.yaml- docker/**- plugins/codex-security/**- sdk/typescript/**@@ -101,6 +103,60 @@ jobs:docker run --rm codex-security:ci bulk-scan --helpdocker run --rm codex-security:ci info --json+ - name: Verify findings service and persistent SQLite storage+ shell: bash+ run: |+ set -euo pipefail+ compose=(docker compose -p findings-ci -f compose.findings.yaml)+ trap '"${compose[@]}" logs; "${compose[@]}" down --volumes' EXIT+ "${compose[@]}" up --build --detach+ check_routes() {+ "${compose[@]}" exec -T findings node --input-type=module <<'JS'+ import assert from "node:assert/strict";+ import { setTimeout } from "node:timers/promises";+ const base = "http://127.0.0.1:3000";+ for (let attempt = 0; ; attempt++) {+ try {+ await fetch(`${base}/v1/findings`, { signal: AbortSignal.timeout(1000) });+ break;+ } catch (error) {+ if (attempt === 100) throw error;+ await setTimeout(100);+ }+ }+ for (const [method, path] of [+ ["GET", "/v1/findings?limit=50&offset=0"],+ ["POST", "/v1/bulk/findings"],+ ]) {+ const response = await fetch(`${base}${path}`, {+ method,+ ...(method === "POST" ? { body: '{"findings":[]}' } : {}),+ });+ assert.equal(response.status, 501);+ assert.deepEqual(await response.json(), { error: "not_implemented" });+ }+ JS+ }+ check_routes+ test "$(curl --silent --output /dev/null --write-out '%{http_code}' http://127.0.0.1:3000/v1/findings)" = 501+ "${compose[@]}" exec -T findings python3 - <<'PY'+ import sqlite3+ with sqlite3.connect("/state/workbench.sqlite3") as db:+ assert db.execute("SELECT COUNT(*) FROM schema_migrations").fetchone()[0] > 0+ assert db.execute("SELECT COUNT(*) FROM findings").fetchone()[0] == 0+ db.execute("INSERT INTO findings (id, fingerprint, rule_id, identity_anchor, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)", ("example-finding", "example-fingerprint", "example-rule", "example-anchor", "2026-01-01", "2026-01-01"))+ PY+ "${compose[@]}" stop --timeout 10+ container_id=$("${compose[@]}" ps --all --quiet findings)+ test "$(docker inspect --format '{{.State.ExitCode}}' "$container_id")" = 0+ "${compose[@]}" up --detach --force-recreate+ check_routes+ "${compose[@]}" exec -T findings python3 - <<'PY'+ import sqlite3+ with sqlite3.connect("/state/workbench.sqlite3") as db:+ assert db.execute("SELECT id FROM findings").fetchall() == [("example-finding",)]+ PY+- name: Validate hardened customer Compose configurationenv:CODEX_SECURITY_IMAGE: codex-security:cidiff --git a/Dockerfile b/Dockerfileindex 43ba910ae..c8825e2b0 100644--- a/Dockerfile+++ b/Dockerfile@@ -19,7 +19,7 @@ RUN pnpm run types \&& pnpm pack --pack-destination /build/package \&& node scripts/check-package.mjs /build/package/*.tgz-FROM node:22-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3+FROM node:22-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3 AS runtimeLABEL org.opencontainers.image.title="Codex Security" \org.opencontainers.image.description="Noninteractive, resumable Codex Security CSV repository scans" \@@ -59,5 +59,21 @@ ENV CODEX_HOME=/state \USER 10001:10001WORKDIR /state+FROM runtime AS findings-service++LABEL org.opencontainers.image.description="Codex Security findings API"++ENV HOST=0.0.0.0 \+ PORT=3000 \+ CODEX_SECURITY_STATE_DIR=/state++WORKDIR /usr/local/lib/node_modules/@openai/codex-security+EXPOSE 3000++ENTRYPOINT ["node"]+CMD ["dist/server/index.js"]++FROM runtime AS scanner+ENTRYPOINT ["/usr/local/bin/codex-security-entrypoint"]CMD ["--help"]diff --git a/README.md b/README.mdindex 3c97d1505..37884b096 100644--- a/README.md+++ b/README.md@@ -46,6 +46,12 @@ await security.close();Use the included Docker Compose configuration for scans of many repositories. See the [container quick start](sdk/typescript/README.md#containerized-bulk-scans) for more detail.+## Findings service (preview)++The [findings service](sdk/typescript/README.md#findings-service-preview) runs+from the SDK in Docker with persistent SQLite storage. Its two HTTP endpoints+are currently stubs; they do not insert findings or run deduplication.+## Other providersTo use another inference provider, set its API key and select a model:diff --git a/compose.findings.yaml b/compose.findings.yamlnew file mode 100644index 000000000..31c1f9fd0--- /dev/null+++ b/compose.findings.yaml@@ -0,0 +1,14 @@+services:+ findings:+ build:+ context: .+ target: findings-service+ init: true+ env_file: docker/findings.env+ ports:+ - "127.0.0.1:3000:3000"+ volumes:+ - findings-state:/state++volumes:+ findings-state:diff --git a/docker/findings.env b/docker/findings.envnew file mode 100644index 000000000..c4f8a8a9e--- /dev/null+++ b/docker/findings.env@@ -0,0 +1,3 @@+HOST=0.0.0.0+PORT=3000+CODEX_SECURITY_STATE_DIR=/statediff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex fb5e5968e..d73910d4b 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -910,6 +910,70 @@ command manifest, `scan --schema --format json` for a command schema, andMCP exposes only the read-only `info` command because the transport cannotcancel active scans.+## Findings service (preview)++From the repository root, build and start the findings API:++```bash+docker compose -f compose.findings.yaml up --build -d+curl -i http://127.0.0.1:3000/v1/findings+```++The `findings-service` Docker target starts the compiled SDK server used by the+packaged `start:server` script, without invoking the CLI. Docker runs Node+directly so stop signals reach the server. The existing default Docker target+and bulk-scan Compose configuration are unchanged.++This first stage only initializes storage and serves mocked endpoints:++| Method | Path | Current behavior |+| ------ | ------------------- | --------------------------------- |+| `GET` | `/v1/findings` | Log the route and return HTTP 501 |+| `POST` | `/v1/bulk/findings` | Log the route and return HTTP 501 |++Each stub returns `{"error":"not_implemented"}`; unknown routes return HTTP 404+with `{"error":"not_found"}`. Request bodies are not processed or logged. No+findings or embeddings are written by these endpoints.++Storage initializes before the server listens. The SQLite adapter reuses the+bundled workbench's schema and migrations at+`$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. The `findings-state` named volume+persists that database across container restarts. Stop the service with+`docker compose -f compose.findings.yaml down`; add `--volumes` only when you+intend to delete the stored data.++`docker/findings.env` contains non-secret container defaults: `HOST=0.0.0.0`,+`PORT=3000`, and `CODEX_SECURITY_STATE_DIR=/state`. Compose publishes the port+only on the host's loopback interface. There is no API authentication in this+preview. Do not expose it to an untrusted network; use an authenticated proxy+before sharing access. No model credentials are needed for the stubs.++To run locally, use Node.js and Python 3 as described in the prerequisites.+From `sdk/typescript`, install dependencies, build, and start:++```bash+pnpm install --frozen-lockfile+pnpm run build+pnpm run start:server+```++Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing+`CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;+without a state override, the service uses the same default state directory as+the CLI. These settings also work on Windows.++HTTP routing, server startup, and the SQLite adapter live separately under+`src/server/`. Startup accepts a `FindingsStore` interface; the SQLite+implementation owns workbench access. The interface currently covers only+initialization, and will grow with actual data operations rather than with+unused provider abstractions.++The next stage will persist the existing `Finding` model and embeddings in+SQLite, return IDs from bulk insertion, and list findings with pagination+defaulting to 50. A later stage will add candidate retrieval to the API and run+screening, independent pair review, and whole-group review locally through the+SDK and CLI. None of those operations are implemented in this preview.+## Containerized bulk scansCreate `repositories.csv` as described under [Bulk scans](#bulk-scans).diff --git a/sdk/typescript/package.json b/sdk/typescript/package.jsonindex 13e4b8306..efd49998e 100644--- a/sdk/typescript/package.json+++ b/sdk/typescript/package.json@@ -53,6 +53,7 @@"generate:models:check": "node scripts/generate-models.cjs --check","lint": "tsc --noEmit","prepack": "node --run build:plugin && node --run build",+ "start:server": "node dist/server/index.js","test": "node --run build:plugin && bun test --timeout 30000 ./tests-ts","test:ci": "node -e \"require('node:fs').mkdirSync('reports',{recursive:true})\" && pnpm run test --coverage --coverage-reporter=text --coverage-reporter=lcov --reporter=junit --reporter-outfile=reports/junit.xml","test:mcp": "node --run build:plugin && npm --prefix ../../plugins/codex-security/mcp-app run test:mcp",diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjsindex 531f8146d..ab48965a5 100644--- a/sdk/typescript/scripts/check-package.mjs+++ b/sdk/typescript/scripts/check-package.mjs@@ -195,6 +195,11 @@ const distFiles = new Set("scan-history-renderer","scan-logs","scan-sessions",+ "server/index",+ "server/routes",+ "server/server",+ "server/sqlite-store",+ "server/storage","targets","thread-source","trusted-executable",@@ -217,6 +222,7 @@ for (const file of files) {? normalized === "package" ||normalized === "package/bin" ||normalized === "package/dist" ||+ normalized === "package/dist/server" ||pluginDirectories.has(normalized): allowedRoot.has(normalized) ||distFiles.has(normalized) ||diff --git a/sdk/typescript/src/server/index.ts b/sdk/typescript/src/server/index.tsnew file mode 100644index 000000000..d06bd9f20--- /dev/null+++ b/sdk/typescript/src/server/index.ts@@ -0,0 +1,34 @@+import { startFindingsServer } from "./server.js";+import { SqliteFindingsStore } from "./sqlite-store.js";++async function main(): Promise<void> {+ const host = process.env["HOST"] ?? "127.0.0.1";+ const port = Number(process.env["PORT"] ?? 3000);+ const server = await startFindingsServer({+ store: new SqliteFindingsStore(),+ host,+ port,+ });+ const address = server.address();+ if (address !== null && typeof address !== "string") {+ console.log(+ `Findings service listening on ${address.address}:${address.port}`,+ );+ }++ const shutdown = () => {+ server.close((error) => {+ if (error !== undefined) {+ console.error(error);+ process.exitCode = 1;+ }+ });+ };+ process.once("SIGINT", shutdown);+ process.once("SIGTERM", shutdown);+}++main().catch((error: unknown) => {+ console.error(error);+ process.exitCode = 1;+});diff --git a/sdk/typescript/src/server/routes.ts b/sdk/typescript/src/server/routes.tsnew file mode 100644index 000000000..7e9b89ea9--- /dev/null+++ b/sdk/typescript/src/server/routes.ts@@ -0,0 +1,22 @@+import type { IncomingMessage, ServerResponse } from "node:http";++export function handleFindingsRequest(+ request: IncomingMessage,+ response: ServerResponse,+): void {+ const path = request.url?.split("?", 1)[0];+ const route = `${request.method} ${path}`;+ request.resume();++ switch (route) {+ case "GET /v1/findings":+ case "POST /v1/bulk/findings":+ console.log(route);+ response.writeHead(501, { "Content-Type": "application/json" });+ response.end(JSON.stringify({ error: "not_implemented" }));+ return;+ default:+ response.writeHead(404, { "Content-Type": "application/json" });+ response.end(JSON.stringify({ error: "not_found" }));+ }+}diff --git a/sdk/typescript/src/server/server.ts b/sdk/typescript/src/server/server.tsnew file mode 100644index 000000000..32148acb0--- /dev/null+++ b/sdk/typescript/src/server/server.ts@@ -0,0 +1,16 @@+import { once } from "node:events";+import { createServer, type Server } from "node:http";+import { handleFindingsRequest } from "./routes.js";+import type { FindingsStore } from "./storage.js";++export async function startFindingsServer(options: {+ store: FindingsStore;+ host: string;+ port: number;+}): Promise<Server> {+ await options.store.initialize();+ const server = createServer(handleFindingsRequest);+ server.listen(options.port, options.host);+ await once(server, "listening");+ return server;+}diff --git a/sdk/typescript/src/server/sqlite-store.ts b/sdk/typescript/src/server/sqlite-store.tsnew file mode 100644index 000000000..0cd591275--- /dev/null+++ b/sdk/typescript/src/server/sqlite-store.ts@@ -0,0 +1,31 @@+import {+ bundledPluginRoot,+ codexSecurityStateDirectory,+ resolvePluginPython,+ runWorkbench,+} from "../runtime.js";+import type { FindingsStore } from "./storage.js";++export class SqliteFindingsStore implements FindingsStore {+ constructor(private readonly environment: NodeJS.ProcessEnv = process.env) {}++ async initialize(): Promise<void> {+ const environment = {+ ...this.environment,+ CODEX_SECURITY_STATE_DIR: codexSecurityStateDirectory(this.environment),+ };+ const [python, pluginRoot] = await Promise.all([+ resolvePluginPython({ environment }),+ bundledPluginRoot(),+ ]);+ await runWorkbench(+ {+ python,+ pluginRoot,+ environment,+ failureMessage: "Could not initialize the findings database",+ },+ ["database-info"],+ );+ }+}diff --git a/sdk/typescript/src/server/storage.ts b/sdk/typescript/src/server/storage.tsnew file mode 100644index 000000000..d69730613--- /dev/null+++ b/sdk/typescript/src/server/storage.ts@@ -0,0 +1,3 @@+export interface FindingsStore {+ initialize(): Promise<void>;+}diff --git a/sdk/typescript/tests-ts/findings-server.test.ts b/sdk/typescript/tests-ts/findings-server.test.tsnew file mode 100644index 000000000..592976e9c--- /dev/null+++ b/sdk/typescript/tests-ts/findings-server.test.ts@@ -0,0 +1,149 @@+import { mkdtemp, rm, writeFile } from "node:fs/promises";+import type { Server } from "node:http";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, spyOn, test } from "bun:test";+import { resolvePluginPython, runCodexCommand } from "../src/runtime.js";+import { startFindingsServer } from "../src/server/server.js";+import { SqliteFindingsStore } from "../src/server/sqlite-store.js";++const servers: Server[] = [];+const directories: string[] = [];++afterEach(async () => {+ for (const server of servers.splice(0)) {+ await new Promise<void>((resolve, reject) => {+ server.close((error) =>+ error === undefined ? resolve() : reject(error),+ );+ });+ }+ for (const directory of directories.splice(0)) {+ await rm(directory, { recursive: true, force: true });+ }+});++test("serves only the two mock routes after storage is initialized", async () => {+ let initialized = false;+ const server = await startFindingsServer({+ host: "127.0.0.1",+ port: 0,+ store: {+ async initialize() {+ initialized = true;+ },+ },+ });+ servers.push(server);+ expect(initialized).toBe(true);+ const address = server.address();+ if (address === null || typeof address === "string")+ throw new Error("No port");+ const base = `http://127.0.0.1:${address.port}`;+ const log = spyOn(console, "log").mockImplementation(() => undefined);+ try {+ for (const [method, path] of [+ ["GET", "/v1/findings?limit=50&offset=0"],+ ["POST", "/v1/bulk/findings"],+ ] as const) {+ const response = await fetch(`${base}${path}`, {+ method,+ ...(method === "POST" ? { body: "synthetic request body" } : {}),+ });+ expect(response.status).toBe(501);+ expect(response.headers.get("content-type")).toBe("application/json");+ expect(await response.json()).toEqual({ error: "not_implemented" });+ }+ expect(log.mock.calls).toEqual([+ ["GET /v1/findings"],+ ["POST /v1/bulk/findings"],+ ]);++ for (const [method, path] of [+ ["GET", "/unknown"],+ ["POST", "/v1/findings"],+ ["GET", "/v1/bulk/findings"],+ ["POST", "/v1/bulk/findings/dedupe"],+ ]) {+ const response = await fetch(`${base}${path}`, { method });+ expect(response.status).toBe(404);+ expect(await response.json()).toEqual({ error: "not_found" });+ }+ } finally {+ log.mockRestore();+ }+});++test("does not start when storage initialization fails", async () => {+ await expect(+ startFindingsServer({+ host: "127.0.0.1",+ port: 0,+ store: {+ async initialize() {+ throw new Error("Storage unavailable");+ },+ },+ }),+ ).rejects.toThrow("Storage unavailable");+});++test("initializes and reopens the CLI database without losing findings", async () => {+ const directory = await mkdtemp(join(tmpdir(), "findings-store-"));+ directories.push(directory);+ const environment = {+ ...process.env,+ CODEX_SECURITY_STATE_DIR: join(directory, "state with spaces"),+ };+ const store = new SqliteFindingsStore(environment);+ await store.initialize();+ const python = await resolvePluginPython({ environment });+ const database = join(+ environment.CODEX_SECURITY_STATE_DIR,+ "workbench.sqlite3",+ );+ const inserted = await runCodexCommand(+ { command: python },+ [+ "-c",+ `import sqlite3, sys+with sqlite3.connect(sys.argv[1]) as db:+ assert db.execute("SELECT COUNT(*) FROM schema_migrations").fetchone()[0] > 0+ db.execute("INSERT INTO findings (id, fingerprint, rule_id, identity_anchor, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)", ("example-finding", "example-fingerprint", "example-rule", "example-anchor", "2026-01-01", "2026-01-01"))+`,+ database,+ ],+ environment,+ );+ expect(inserted.success).toBe(true);++ await store.initialize();+ const reopened = await runCodexCommand(+ { command: python },+ [+ "-c",+ `import sqlite3, sys+with sqlite3.connect(sys.argv[1]) as db:+ assert db.execute("SELECT id FROM findings").fetchall() == [("example-finding",)]+ assert db.execute("PRAGMA journal_mode").fetchone()[0] == "wal"+`,+ database,+ ],+ environment,+ );+ expect(reopened.success).toBe(true);+});++test("reports a database startup failure for an unusable state path", async () => {+ const directory = await mkdtemp(join(tmpdir(), "findings-store-"));+ directories.push(directory);+ const state = join(directory, "not-a-directory");+ await writeFile(state, "synthetic file");+ const store = new SqliteFindingsStore({+ ...process.env,+ CODEX_SECURITY_STATE_DIR: state,+ });+ await expect(store.initialize()).rejects.toThrow(+ "Could not initialize the findings database",+ );+});