OpenAI Codex Security CLI: AI Vulnerability Scanning Guide
A hands-on guide to @openai/codex-security, the open-source CLI and TypeScript SDK for OpenAI's security agent: the find-validate-patch pipeline, key commands, pre-commit hooks, CI integration with --fail-on-severity and SARIF export, cost controls, and requirements — based on the repository's primary sources.
Codex Security is OpenAI's application-security agent: it reads your codebase, understands how the application works, then runs a find → validate-in-sandbox → patch pipeline that filters out false positives before proposing fixes. Rebranded from 'Aardvark' and announced as a research preview in March 2026, it took a major step on July 13, 2026, when its CLI and TypeScript SDK (@openai/codex-security) were open-sourced on GitHub under Apache-2.0. This guide is based on the repository's primary sources — README and implementation.
What Codex Security Is
Traditional SAST tools drown teams in false positives. Codex Security works in three stages: it reads the repository and ranks likely vulnerabilities (ranking and file-review phases), validates candidates in a sandbox to discard false positives (validation and attack-path phases), and generates candidate patches for what remains. Scan progress is reported phase by phase.
What the Open-Source Release Changes
- CLI + TypeScript SDK open-sourced (Apache-2.0, v0.1.1, ESM-only), distributed as @openai/codex-security on npm
- Run scans locally, in CI, or on your own infra: one command — npx codex-security scan .
- Two auth paths: ChatGPT sign-in locally (login, --device-auth for headless) or OPENAI_API_KEY / CODEX_API_KEY in CI, with explicit --auth chatgpt|api-key selection
- Docker image for noninteractive, resumable bulk scans from a CSV of repositories (bulk-scan)
- Access to the Codex Security service is still required (research preview targets ChatGPT Enterprise / Business / Education) — the client is open, the brain is in the cloud
Requirements and Quick Start
Requires Node.js 22+ and Python 3.10+ (macOS / Linux / Windows).
npm install @openai/codex-security
npx codex-security login # set OPENAI_API_KEY in CI
npx codex-security scan .
Output directories must live outside the repository (private, chmod 700 on macOS/Linux) because results include source excerpts, vulnerability details, and reproduction steps. The SDK mirrors the CLI: new CodexSecurity() → security.run(path), with preflight() validation and AbortSignal cancellation.
Key Commands
| Command | Purpose |
|---|---|
scan <path> | Scan a repo, paths, committed diff (--diff), or working tree |
scan --knowledge-base <path> | Feed threat models / architecture docs (MD, PDF, Word) as context |
install-hook | Pre-commit hook scanning staged and unstaged changes |
bulk-scan <csv> | Parallel scans across many repositories (--workers) |
scans list / show / rerun | Scan history operations |
scans match / compare | Track findings across scans |
export --export-format sarif | SARIF / CSV / JSON export (GitHub Code Scanning) |
validate / patch <findings> "finding" | Re-validate or generate a patch for a specific finding |
CI Integration: Report-Only by Default, Exit Codes Done Right
Scans are report-only unless you pass --fail-on-severity high (exit 1 at or above the threshold). Notably, incomplete or failed scans exit 2, so an error can never masquerade as a pass. install-hook respects core.hooksPath and never replaces existing hooks. SARIF export feeds GitHub Code Scanning directly.
Cost and Models
Scans default to gpt-5.6-sol at extra-high reasoning effort, switchable via --model gpt-5.6-terra. Every scan records its model, tokens, and estimated cost, and --max-cost 5 caps spend per scan. See our GPT-5.6 API pricing comparison for budgeting; --dry-run shows the effective configuration without touching the network.
Caveats
- Only the client is open source — the scanning brain is a gated cloud service (research preview: Enterprise / Business / Education)
- v0.1.1: the public API may change between minors before 1.0
- Scan only repositories you own or are authorized to assess
- Results contain reproduction steps — plan storage and access control
- Vulnerabilities in the tool itself go to OpenAI's Bugcrowd program, not GitHub Issues
New to Codex? Start with our Codex beginner's guide and AGENTS.md configuration guide; for adjacent AI review tooling, see crit.md.
Is Codex Security free?
The CLI/SDK is free open source (Apache-2.0), but running scans requires access to the Codex Security service — research preview for ChatGPT Enterprise/Business/Education, or API-key usage in CI where each scan records token usage and estimated cost, cappable with --max-cost.
How is it different from existing SAST tools?
The validation phase: candidates are exercised in a sandbox to discard false positives before reporting, and patches are proposed for what remains. It complements rather than replaces DAST and runtime testing.
How do I wire it into CI?
Set OPENAI_API_KEY and run npx codex-security scan . --fail-on-severity high. Findings at/above the threshold exit 1; incomplete scans exit 2 so errors can't pass silently. Export SARIF for GitHub Code Scanning.
Takeaway
Open-sourcing the client turns the find-validate-patch pipeline into something you can put in a terminal, a pre-commit hook, and a CI job. The pragmatic touches — validated findings, report-only defaults, separated exit codes, cost caps — are what it takes to turn security scanning from an occasional audit into a per-commit habit. Start with --dry-run, then the hook, then CI.
Feel free to contact us
Contact Us