codex-security

What it is

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

How it works

The package provides a CLI with commands such as login and scan, supports multiple inference providers via API keys and model selection, and includes a TypeScript SDK with a CodexSecurity class to run scans programmatically. It stores scan history in a private workbench state directory and supports noninteractive/CI usage with API keys. It also offers a containerized bulk scan workflow and environment variable controls for logging and credentials.

Getting started

Requires Node.js 22.13.0 or later in the 22.x release line, Node.js 24.x, or Node.js 26.x; Python 3.10 or later; and access to Codex Security.

npm install @openai/codex-security
npx @openai/codex-security login
npx @openai/codex-security scan .
npx @openai/codex-security scan . --model gpt-5.6-terra --effort high
npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10

For CI, set OPENAI_API_KEY or CODEX_API_KEY instead of signing in.

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

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

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

Local sign-in honors Codex's configured credential backend, including a system keyring required by a managed device. Codex Security keeps login and scan credentials in the same private, persistent state directory.

If both a ChatGPT sign-in and an API key are available, interactive scans ask which credential to use. CI and other noninteractive scans keep the existing API-key precedence. Select a credential explicitly when needed:

npx @openai/codex-security scan . --auth chatgpt
npx @openai/codex-security scan . --auth api-key

To make your ChatGPT sign-in the automatic default, unset any configured API keys:

unset OPENAI_API_KEY CODEX_API_KEY

Scan history is stored in the Codex Security workbench state directory. If that directory cannot be written, set CODEX_SECURITY_STATE_DIR to a writable directory outside the repository.

scans compare BEFORE_SCAN_ID AFTER_SCAN_ID automatically matches findings by root cause, reuses saved matches, and identifies new, persisting, reopened, resolved, or unknown findings. Missing findings remain unknown when coverage is incomplete or their original location was not reviewed.

TypeScript SDK

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

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

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

Containerized bulk scans

Use the official image and included Docker Compose configuration for noninteractive, resumable scans of repositories pinned to immutable Git revisions. See the container quick start for authentication, private result storage, and optional Ubuntu AppArmor hardening.

Pass --knowledge-base PATH to share security documents with every repository; repeat the option for multiple files or directories.

For complete command help, runtime defaults, native multi-agent worker limits, environment variables, deep-scan configuration, and SDK options, see the package README and the official CLI reference.