openai/codex-securityOpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
@openai/codex-security is a CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities in your code.
See the Codex Security documentation for more details.
Some cybersecurity requests and protected findings require approval through Trusted Access for Cyber. To apply or check your access, visit chatgpt.com/cyber.
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 . --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
npx @openai/codex-security scan . --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5
For CI, set OPENAI_API_KEY or CODEX_API_KEY instead of signing in.
Environment API keys are passed directly to the current scan and are never
stored in Codex's credential home or system keyring.
Deep-scan discovery stops after 96 hours by default. Set --max-time-hours to
any positive number of hours, including fractional hours, up to 96. Completed
findings are preserved and returned when the limit is reached.
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
export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
export AWS_REGION="us-east-2"
npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna
Amazon Bedrock also supports standard AWS access keys, profiles, web identity, container credentials, and the default AWS credential chain.
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.
findings list [repository] shows open findings across a repository's scans
and identifies findings not confirmed in its latest scan.
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.
Publish every finding from a completed scan to a Linear team:
npx @openai/codex-security publish scan /path/to/scan \
--to linear \
--linear-team TEAM_ID
Add --project PROJECT_ID to place the issues in a Linear project, or omit it
to create issues directly in the team. Omit the scan directory to select a
completed scan interactively. You can also set CODEX_SECURITY_LINEAR_TEAM and
the optional CODEX_SECURITY_LINEAR_PROJECT instead of passing the destination
flags. Add --dry-run to preview the issues or --json to return
machine-readable results.
By default, publishing uses your existing Codex sign-in and connected Linear
app without a separate Linear token. To publish directly through the Linear API
instead, set CODEX_SECURITY_LINEAR_API_KEY to a Linear personal API key.
Direct publication leaves issues unassigned by default; pass
--linear-assignee EMAIL_OR_USER_ID to select a Linear user:
export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
npx @openai/codex-security publish scan /path/to/scan \
--to linear \
--linear-team TEAM_ID \
--project PROJECT_ID \
--linear-assignee [email protected]
Use --linear-assignee USER_ID to select a Linear user ID instead of an email
address, or omit the flag to leave the issues unassigned.
--linear-api-key KEY also selects direct publication and takes precedence
over the environment variable. Prefer the environment variable to keep API keys
out of shell history and process listings. Every finding creates a new issue
containing the scan ID, affected code locations, source snippets, and
remediation guidance. Choose a destination authorized to receive the
repository's source code and vulnerability details.
Add --verbose to print scan diagnostics to stderr:
npx @openai/codex-security scan . --verbose
CODEX_SECURITY_LOG_LEVEL=debug also enables diagnostics;
LOG_LEVEL=debug is its fallback. JSON results remain on stdout.
Verbose diagnostics may contain sensitive data. Review local logs before sharing them. Saved failure summaries, bulk-scan receipts, and the interactive dashboard omit messages that contain recognizable credentials.
Use npx @openai/codex-security scans logs SCAN_ID to inspect saved session
events from a scan and its workers.
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,
maxTimeHours: 1.5,
});
console.log(result.reportPath);
await security.close();
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.
Use --scan-prompt-file PATH to add shared scan instructions, and add a prompt
CSV column for repository-specific instructions. Use
--post-scan-prompt-file PATH to run a follow-up after each scan, including
incomplete or failed scans.
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.