openai/codex-security

openai/codex-security

Description: SDKs and CLI for Codex Security

Language: TypeScript

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 2

Created: 2026-07-13T22:00:13Z

Pushed: 2026-07-28T06:39:55Z

Default branch: main

Fork: no

Archived: no

README:

Codex Security

Codex Security is an open-source CLI and TypeScript SDK for finding, validating, and reviewing security issues in code you own or have permission to assess.

> [!NOTE] > This package follows semantic versioning. Its public API may change between > minor versions before 1.0.0.

Requirements

The SDK and CLI support macOS, Linux, and Windows and require Node.js 22 or later. Scanning and exporting findings also require Python 3.10 or later. If you use Python 3.10, install the tomli package. Python is not needed to install the package or run --help and --version.

Sign in with your OpenAI account or provide an OpenAI API key before running a scan. Scan only repositories you own or have explicit permission to assess.

Install and scan

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

Run npx codex-security --help to see all commands and npx codex-security scan --help for scan options.

On a remote or headless machine, use npx codex-security login --device-auth. For CI and other unattended scans, set OPENAI_API_KEY or CODEX_API_KEY using your shell, CI secret, or secret manager.

On Windows, set an API key in PowerShell with:

$env:OPENAI_API_KEY = ""
npx codex-security scan C:\code\repository

To store an API key, pass it on stdin:

printenv OPENAI_API_KEY | npx codex-security login --with-api-key

Use npx codex-security login status to check the stored sign-in and npx codex-security logout to remove it. Codex Security reuses an existing file-based Codex sign-in. If Codex stores credentials in the system keyring, run npx codex-security login once before scanning.

An environment API key takes precedence over a stored sign-in. Unset both OPENAI_API_KEY and CODEX_API_KEY to use your ChatGPT sign-in. The login status command reports the effective credential source without printing its value, including when no stored sign-in exists.

Scan a subset of a repository or write machine-readable results:

npx codex-security scan /path/to/repo --model gpt-5.6-terra
npx codex-security scan /path/to/repo --path src --path tests
npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
npx codex-security scan /path/to/repo --diff origin/main --json
npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results
npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results --archive-existing
npx codex-security scan /path/to/repo --dry-run
npx codex-security scan /path/to/repo --fail-on-severity high
npx codex-security install-hook
npx codex-security bulk-scan
npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans
npx codex-security scans list /path/to/repo
npx codex-security scans list --scan-root /path/outside/repo/results
npx codex-security scans show SCAN_ID
npx codex-security scans rerun SCAN_ID
npx codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx codex-security scans match --all
npx codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif
npx codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv
npx codex-security export /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json
npx codex-security validate /path/outside/repo/findings.json "Possible SQL injection in src/query.ts:42"
npx codex-security patch /path/outside/repo/findings.json "Missing authorization check in src/routes.ts:18"

install-hook scans staged and unstaged changes before each commit. It respects core.hooksPath, does not replace an existing hook, and blocks high-severity findings or failed scans. Set --fail-on-severity to change the threshold.

Use npx codex-security --version for the CLI version and npx codex-security info --json for package, plugin, and runtime versions, the default model and reasoning effort, and the next scan command. Add --dry-run to inspect the effective model and reasoning effort without initializing Codex or contacting the network.

The output directory must be outside the scanned directory and any enclosing Git worktree. On macOS and Linux, an existing output directory must be private to the current user (chmod 700). Scan artifacts can contain source excerpts, vulnerability details, and reproduction steps. Keep them out of repositories, public issue reports, and shared locations.

When SARIF is produced, it is written to /exports/results.sarif. Use npx codex-security scan --help for all target, output, and runtime options.

Repeat --knowledge-base PATH for multiple files or directories. Directories are searched recursively for Markdown, text, PDF, and Word (.docx) files.

Sign in with gh auth login, then run npx codex-security bulk-scan to discover GitHub repositories pushed in the last 90 days. Archived repositories and forks are excluded. Search the repository list, select the repositories to scan, and confirm before scanning. Private checkouts reuse your GitHub CLI sign-in without changing your global Git configuration. For automation or an existing repository list, pass a CSV containing id, repository, and full immutable revision columns and specify --output-dir. Use npx codex-security bulk-scan --help for all options.

The CLI uses Incur for agent-friendly discovery and structured output. Use --llms for the command manifest, scan --schema --format json for a command schema, register an MCP server with mcp add, sync agent skills with skills add, and use completions bash|zsh|fish for shell completions. Scan results support --format toon|json|yaml|jsonl and --full-output. Use info --json for SDK and bundled-plugin metadata. MCP exposes only this read-only metadata command; scans, authentication, exports, validation, and patching remain CLI-only because the MCP transport cannot cancel active scans.

If the output directory already contains...