codex-security README

The project's README from github.com/openai/codex-security. As one markdown file: README.md.

Codex Security

@openai/codex-security is a CLI and TypeScript SDK for defining security policy and finding, validating, and fixing security vulnerabilities in your code.

👉👉 See the Codex Security documentation for full documentation.

Some cybersecurity requests and protected findings require approval through Trusted Access for Cyber. To join the program, visit chatgpt.com/cyber.

Quick start

Requires Node.js 22.13.0 or later and Python 3.10 or later.

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

For CI, set OPENAI_API_KEY instead of signing in.

Generate SECURITY.md

Draft repository-wide or component-scoped SECURITY.md guidance for future scans:

codex-security policy .
codex-security policy . --path services/api --knowledge-base architecture.md

The command saves a draft outside the checkout; it does not install it or run a vulnerability scan. Review the proposed diff before copying the policy. Supporting architecture, threat-model, and review documents stay outside the repository and may contain sensitive details. See the SDK policy guide for headless generation, saved artifacts, and SDK usage.

TypeScript SDK

Codex Security is a Javascript package:

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

const security = new CodexSecurity();
const result = await security.run("/path/to/directory");
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();

Containerized bulk scans

Use the included Docker Compose configuration for scans of many repositories. See the container quick start for more detail.

For individual CLI stages with durable state and access to a separately deployed findings service, use the same scanner image with the workflow runner Compose example.

Findings service (preview)

Run codex-security serve to start the service without Docker. See running without Docker for prerequisites, credentials, and storage configuration.

The findings service runs from the same ghcr.io/openai/codex-security image as the scanner (or a local source build), with a separate container and state volume configured by compose.findings.yaml. It stores findings and embeddings in SQLite and lists findings with pagination. Its read-only dashboard at /dashboard refreshes every five seconds and shows stored findings and duplicate groups from the service's database. It also returns potential duplicates by embedding similarity within a repository or an explicit all-repository scope. The codex-security publish scan --to custom --findings-url http://localhost:3000 command uploads completed findings and their repository ID. The SDK and codex-security dedupe command retrieve candidates, run independent Codex reviews locally, and persist accepted duplicate groups; --all-repositories opts into the broader scope.

Use codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md to assess selected findings under your own policy before publishing tickets. Scan classification checkpoints each finding in SQLite and reuses matching assessments on reruns; --reprocess forces reassessment. The SDK exposes the same classification operation; original scan severity stays unchanged. See severity classification.

Other providers

To use another inference provider, set its API key and select a model:

export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
export AWS_REGION="us-east-2"
codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5

export FIREWORKS_API_KEY="<your-fireworks-api-key>"
codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b

Documentation

👉👉 See the Codex Security documentation for full documentation.

codex-security (openai/codex-security)

ai-security
Searching Database…

11.1K ·GitHub
Codex-security
What is this?Codex Security is OpenAI's CLI and TypeScript SDK for defining security policy and for finding, validating, and fixing security vulnerabilities in your code.
Is this a CLI tool, an SDK, or both?It is both: a CLI you run from the terminal and a TypeScript SDK you install as a JavaScript package, plus a Docker-based scanner and findings service for larger setups.
How do I get it running?Install the @openai/codex-security npm package and run the quick start to generate a SECURITY.md and start scanning; for bulk scans across many repos, use the included Docker Compose configuration.
What do I need installed first, and do I need to sign in?You need Node.js 22.13.0 or later and Python 3.10 or later; interactively you sign in, but for CI you set an OpenAI API key instead.
Are there any restrictions on what it can scan or report?Some cybersecurity requests and protected findings require approval through OpenAI's Trusted Access for Cyber program before they're available.
Where do my scan findings get stored?The findings service stores findings and their embeddings locally in SQLite, and exposes a read-only dashboard that refreshes every five seconds to show stored findings and duplicate groups.
Can it scan a lot of repositories at once?Yes, there's an included Docker Compose configuration specifically for containerized bulk scans across many repositories using the scanner image.
Am I locked into using OpenAI models?No, you can switch to another inference provider by setting that provider's API key and selecting its model.
What does the classify-severity command do?codex-security classify-severity lets you assess selected findings under your own policy rubric before publishing tickets; results are cached per scan and reused on reruns unless you pass --reprocess.
How do findings get published or shared?The codex-security publish scan --to custom --findings-url command uploads completed findings and their repository ID to the findings service, which also supports deduplication via embedding similarity.
What are similar projects?0, cynative, VulnHunter, strix, mantis, shannon, Myrqen, SkillSpector
Which topics is it in?application-security, devsecops, vulnerability-scanner, ai-security, static-analysis, cli-tool, cybersecurity, security-tools, sqlite, sdk, dashboard, openai
Creator
openai
Size
64 MB
Stars
11.1K
Updated
CommitOct 17Releasenpm-v0.4.0Oct 16
Age
3mo
Commits · 90 Days