# Codex Security

> OpenAI's CLI and TypeScript SDK for finding, validating and fixing security vulnerabilities in a codebase

- Category: AI Coding / AI Code Review & Security
- Language: TypeScript
- Licence: Apache-2.0
- Repository: https://github.com/openai/codex-security
- Website: https://developers.openai.com/codex/security
- Canonical page: https://ai-tldr.dev/tools/codex-security/
- Updated: 2026-07-28

## In short

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 sits in the AI Code Review & Security category of the AI Coding tools and is open-source, written in TypeScript and licensed Apache-2.0.

## 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.

1. Install and scan

   The three commands from the README: install, sign in, scan. In CI, skip the login and set OPENAI_API_KEY.

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

2. Drive it from TypeScript

   The SDK exposes the scanner as a class. `run()` returns a result carrying the report path; the options map to the same scan controls the CLI has.

```ts
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();
```

3. Run the findings service

   Start the preview service without Docker to collect findings across scans. Its dashboard is served at /dashboard and refreshes every five seconds.

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

4. Classify severity against your own policy

   Point the classifier at a rubric markdown file. The original scan severity is left unchanged; `--reprocess` forces reassessment of already-checkpointed findings.

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

## 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

## Version history

- 2026-07-28: OpenAI open-sourced Codex Security under Apache-2.0 — a CLI and TypeScript SDK that scans repositories, reviews pull-request changes, tracks findings over time and plugs into CI as a security gate.