Purpose
@openai/codex-security is a CLI and TypeScript SDK provided by OpenAI for finding, validating, and fixing security vulnerabilities in code. It is aimed at developers and teams that need automated security review, can scan repositories, selected paths, or Git changes, and supports a deep scan mode that runs discovery workers in parallel on the repository and selected paths.
Main capabilities
- Scanning and discovery: scan repositories, selected paths, or Git changes; deep scan runs discovery workers in parallel.
- Validation and remediation: validate candidate findings, generate patches, and verify existing fixes.
- Policy and threat model: draft a SECURITY.md policy, save threat models for later review.
- Findings management: browse saved scans and findings, identify duplicates, assess severity by custom criteria, suggest owners from source and Git history.
- Integration and export: import GitHub code scanning alerts, export SARIF, JSON, or CSV, publish findings to Linear or a findings service.
- Automation: automate scanning across repositories or project components in CI and containers.
- Cloud findings reading: when the account has Codex Security Cloud available, the Security plugin's $cloud-findings skill can read findings, reports, recorded assignments and validations, and scan status in Codex desktop or Codex CLI; cloud connection is optional, and local scanning requires no cloud.
Usage
Environment requirements: Node.js 22.13.0+ (within 22.x), or Node.js 24.x or 26.x, and Python 3.10+. Python 3.10 also requires tomli.
Install the CLI globally and log in:
npm install -g @openai/codex-security
cs login
cs is a short alias for codex-security, and both run the same CLI. Installation creates two commands in the npm global executable directory, which must be in PATH. If cs already resolves to another tool, use codex-security instead. If npm reports an EEXIST error for cs, you can use npx @openai/codex-security without a global install.
Optional: draft SECURITY.md from the repository, explaining what counts as a security issue in the project:
cs policy
The draft is saved outside the repository. Review the diff and explanation, edit the draft, then copy only SECURITY.md to the displayed Policy target. Skipping this step preserves the current policy or scans without a policy.
Run a scan from the repository directory:
cs scan
If you have Daybreak Blue access, add --cyber-access-program daybreak_blue to the scan command; otherwise omit the flag or use --cyber-access-program standard.
When no global install is needed, replace cs in the examples with npx @openai/codex-security, for example:
npx @openai/codex-security scan
In CI, set OPENAI_API_KEY or CODEX_API_KEY in the scan process environment. On remote or headless machines, if the workspace allows it, use login --device-auth, or log in via SSH. Some cybersecurity requests and protected findings require Trusted Access for Cyber approval.
Choose scope and scan mode: use cs --help to browse commands, or cs scan --help to view scan options, cost limits, and post-scan patching. For applications spanning multiple repositories, see "review one system across repositories". For independent repository reviews, use batch scanning, which can be completed in a single resumable activity.
Install the package locally in a TypeScript project:
npm install @openai/codex-security
Then import:
import { ... } from '@openai/codex-security';
The SDK guide covers deep scan configuration, validation, severity classification, owner suggestions, and result handling.
Read existing cloud findings: When Codex Security Cloud is available for the account, the Security plugin's $cloud-findings skill can read findings, reports, recorded assignments and validations, and scan status. See Cloud connection setup and CLI reads for authentication requirements and read-only examples.
Generate SECURITY.md: Use policy to draft a new SECURITY.md or update an existing file. Use --path to select components:
cs policy --path <component>
The command saves the draft outside the repository and does not change existing files. Review the diff and description, edit the draft, then copy only SECURITY.md to the displayed Policy target. Keep saved architecture and threat model documents outside the repository. Scans use the root and component SECURITY.md files. If the current policy needs no changes, keep it. When updating, preserve its vulnerability reporting instructions. If the command indicates the policy is already up to date, no copy is needed. Files located at .github/SECURITY.md or docs/SECURITY.md usually contain reporting instructions; preserve them when drafting policy; these locations do not automatically provide repository-wide scan guidance. See the policy guide for policy locations, unanswered questions, saved artifacts, and SDK usage.
Save and export threat models: Scans and policy generation save threat models along with results. Export a saved model without analyzing again:
cs export --scan <scan-id>
Omitting --scan uses the most recently completed scan of the current repository. The export guide also covers findings, SARIF output for CI, and the offline TypeScript API.
Use the GitHub Action to run scheduled, manual, or pull request scans. For weekly repository scans, add the OpenAI API key as the repository secret CODEX_SECURITY_API_KEY, then save this workflow to .github/workflows/codex-security.yml. Replace REPLACE_WITH_REVIEWED_COMMIT with the full SHA of the Action commit. This workflow requests Daybreak Blue. Use an API key for a project with Blue enabled; if you do not have Daybreak access, omit cyber-access-program or set it to standard. Findings are report-only by default. Setting a severity threshold can cause reported findings at or above that threshold to fail. Scanner and required reporting errors fail the job; intentional file exclusions and investigation notes do not. See Action setup and input reference for PR scans, severity thresholds, and report uploads.
Containerized batch scanning: Use the included Docker Compose configuration to scan a list of repositories; it preserves results and authentication between runs. See the container quick start. Workflow runners run individual CLI stages in containers and can connect to a separately deployed findings service.
Findings storage and deduplication: The findings guide covers local storage, deduplication, and compatibility with standalone operational endpoints via publish scan --to custom and an explicit --findings-url. The local serve command and browser dashboard have been removed; existing databases and scan artifacts remain usable.
Other providers: Scanning supports OpenAI, Amazon Bedrock, OpenRouter, and Fireworks AI. Bedrock uses AWS credentials and does not require a separate OpenAI login. See Bedrock setup for AWS profiles, regions, and model access. For OpenRouter and Fireworks AI, set the provider's API key and select a supported model. See provider configuration examples.
When to use
- Automatically discover and fix during the development processSecurity vulnerabilities.
- Run scheduled, manual, or pull request scans in CI.
- Perform bulk scans across multiple repositories or project components.
- Manage security findings, deduplicate, assess severity, and assign owners.
- Generate and maintain SECURITY.md policies and threat models.
- Export findings as SARIF, JSON, or CSV, or publish to Linear or a findings service.
Limitations
- Requires Node.js 22.13.0+ (22.x) or 24.x/26.x, and Python 3.10+; Python 3.10 also requires tomli.
- Some cybersecurity requests and protected findings require Trusted Access for Cyber approval.
- Daybreak Blue related features require the corresponding access permissions.
- Cloud connection is optional; local scanning requires no cloud; cloud features require an account with Codex Security Cloud available.
- The local serve command and browser dashboard have been removed.
- Other provider support includes OpenAI, Amazon Bedrock, OpenRouter, and Fireworks AI, requiring corresponding credentials and models.
- Information regarding charges, pricing, specific effects, etc. is not provided in the materials.
