Codex Security

// Overview

Codex Security is published as the `@openai/codex-security` npm package: a command-line tool and a TypeScript SDK that point a model at a directory and return security findings. The CLI is the fast path — `codex-security login` then `codex-security scan /path/to/directory` — and in CI you set `OPENAI_API_KEY` instead of signing in. It needs Node.js 22.13.0 or later and Python 3.10 or later.

The SDK exposes the same scanner as a `CodexSecurity` class, with a `run()` call that takes the knobs the scan actually turns: a `deep` mode, a worker and subagent count, `stopAfterNoNew` to stop once a run stops producing new findings, and caps on discovery runs and wall-clock hours. It returns a report path. For scanning many repositories at once the repository ships a Docker Compose configuration built on the `ghcr.io/openai/codex-security` image, plus a workflow-runner example that splits the CLI stages so state survives between them.

Around the scanner sits a preview findings service, started with `codex-security serve` or run from the same container image. It stores findings and embeddings in SQLite, paginates them, and serves a read-only dashboard at `/dashboard` that refreshes every five seconds. `codex-security publish scan` uploads completed findings, and `codex-security dedupe` pulls back embedding-similarity candidates, runs independent Codex reviews locally, and persists accepted duplicate groups. A separate `classify-severity` command re-assesses selected findings against a rubric file you supply, checkpointing each one so reruns reuse prior assessments. The project is Apache-2.0; some cybersecurity requests and protected findings require approval through OpenAI's Trusted Access for Cyber programme.

// What it does

• CLI and TypeScript SDK over the same scanner, with `deep` mode, worker/subagent counts and time and discovery-run caps
• Repository, pull-request and CI scanning with `OPENAI_API_KEY` instead of an interactive login
• Preview findings service storing findings and embeddings in SQLite, with a read-only auto-refreshing dashboard
• Embedding-similarity deduplication (`codex-security dedupe`) with independent local Codex reviews of each candidate group
• Policy-driven severity classification against your own rubric markdown, checkpointed per finding
• Containerised bulk scans via Docker Compose and the `ghcr.io/openai/codex-security` image
• Runs against other inference providers — Amazon Bedrock, OpenRouter and Fireworks — with `--provider` and `--model`

// Getting started

Install the npm package, authenticate once, and scan a directory. Node.js 22.13.0+ and Python 3.10+ are required.

npm install @openai/codex-security
codex-security login
codex-security scan /path/to/directory

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();
const result = await security.run("/path/to/directory", {
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

console.log(result.reportPath);
await security.close();

codex-security serve
codex-security publish scan --to custom --findings-url http://localhost:3000

codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Reach for it when you want an LLM security review as a CI gate rather than an interactive chat
• Reach for it when scanning many repositories and you need findings deduplicated instead of re-triaged each run
• Reach for it when your organisation's severity policy differs from the scanner's and you want findings re-graded against it
• Reach for it when you want the scan wired into a TypeScript service rather than shelled out to a CLI

// How Codex Security compares

Codex Security alongside other open-source ai code review & security tools AI/TLDR tracks, ranked by GitHub stars.