OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
docs: Update README.md (#639)
ianw-oai18987754afe1
diff --git a/README.md b/README.mdindex 9fe844e16..bbf96c5d6 100644--- a/README.md+++ b/README.md@@ -2,206 +2,34 @@`@openai/codex-security` is a CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities in your code.-**See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for more details.--See [GitHub Releases](https://github.com/openai/codex-security/releases) for-the canonical changelog and upgrade notes.+**ππ See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for full documentation.Some cybersecurity requests and protected findings require approval through-Trusted Access for Cyber. To apply or check your access, visit+Trusted Access for Cyber. To join the program, visit[chatgpt.com/cyber](https://chatgpt.com/cyber).## Quick start-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.+Requires Node.js 22.13.0 or later and Python 3.10 or later.```bashnpm install @openai/codex-security-npx @openai/codex-security login-npx @openai/codex-security scan .-npx @openai/codex-security scan . --patch-npx @openai/codex-security scan . --patch --patch-severity high --json-npx @openai/codex-security scan . --patch --patch-severity high --create-pr-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 . --validation-prompt-file validation.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.--Use `--validation-prompt-file` to replace final validation with your own setup,-testing, and cleanup instructions. This works for standard and diff scans;-Deep scans do not support it. See [custom validation](sdk/typescript/README.md#custom-validation).-For a runnable local example, see the [custom validation demo](examples/custom-validation/README.md).-Environment API keys are passed directly to the current scan and are never-stored in Codex's credential home or system keyring.--After showing the findings summary, interactive scans with findings ask whether-to open a finding browser where you can inspect full details, choose a severity-threshold, select individual findings, and add patch instructions for each one.-Each selected finding runs in its own saved Codex desktop task.-Use `--patch --patch-severity high` to fix high and critical findings. Add-`--create-pr`, or enable the pull request option during review, to commit the-verified files and open a draft GitHub pull request. Ordinary scans do not-change repository files.--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.--For a monorepo, run separate standard scans and combine their results by root-cause:--```bash-npx @openai/codex-security scan-components . \- --component apps/api --component apps/web \- --output-dir /path/outside/repository/results-```--Use `--auto` to let Codex choose the components, or `--auto --plan-only` to-review the split first. See [component scans](sdk/typescript/README.md#scan-project-components)-for reusable plans, combined reports, and coverage details.--To use another inference provider, set its API key and select a model:--```bash-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:--```bash-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:--```bash-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.--Applications can attribute API-key scans to an end user with-`scan --safety-identifier ID` or the SDK's per-run `safetyIdentifier` option.-See [Safety ID setup and runtime requirements](sdk/typescript/README.md#attribute-scans-to-end-users).--`findings list [repository]` shows open findings across a repository's scans-and identifies findings not confirmed in its latest scan.--Use `patch OCCURRENCE_ID` to fix one saved finding, or-`patch --scan SCAN_ID --severity high` to fix selected findings from a saved-scan. Add `--json` for structured results or `--create-pr` to open a draft-GitHub pull request after verification. If publication fails, use the printed-`patch --resume-pr BRANCH` command to retry without running Codex again.--Use `patch --linear-issue SEC-123` to import and fix a Linear issue, or-`patch --linear-project "Security backlog" --linear-filter '{"labels":{"name":{"eq":"security"}}}'`-to fix matching open issues from a project. Set-`CODEX_SECURITY_LINEAR_API_KEY` to authorize read-only Linear access.--`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 scan findings--Publish every finding from a completed scan to a Linear team:--```bash-npx @openai/codex-security publish scan --scan SCAN_ID \- --to linear \- --linear-team TEAM_ID-```--Add `--linear-project PROJECT_ID` to place the issues in a Linear project, or-omit it to create issues directly in the team. The existing `--project` flag-remains an alias. Omit `--scan` to select a completed scan interactively. Use-`scans list --json` to find saved scan IDs, or pass `--scan latest` for the-current repository's latest completed scan. External scan artifacts can still-be supplied with `--scan-dir PATH` or a positional directory.-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:--```bash-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 \- --linear-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.--## Verbose diagnostics--Add `--verbose` to print scan diagnostics to stderr:--```bash-npx @openai/codex-security scan . --verbose+codex-security login+codex-security scan /path/to/directory```-`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 normal-activity feed 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. Press `d` during a scan to inspect-unredacted details; `a`, `m`, and `1`β`9` select all, main, or worker-sessions. These events can contain credentials.+For CI, set `OPENAI_API_KEY` instead of signing in.## TypeScript SDK+Codex Security is a Javascript package:+```tsimport { CodexSecurity } from "@openai/codex-security";const security = new CodexSecurity();-const result = await security.run(".");-await security.run(".", {+const result = await security.run("/path/to/directory");+await security.run("/path/to/directory", {mode: "deep",workers: 2,subagents: 0,@@ -216,21 +44,25 @@ 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](sdk/typescript/README.md#containerized-bulk-scans)-for authentication, private result storage, and optional Ubuntu AppArmor-hardening.+Use the included Docker Compose configuration for scans of many repositories. See the [container quick start](sdk/typescript/README.md#containerized-bulk-scans) for more detail.++## Other providers+++To use another inference provider, set its API key and select a model:-Pass `--knowledge-base PATH` to share security documents with every repository;-repeat the option for multiple files or directories.+```bash+export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"+export AWS_REGION="us-east-2"+codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna++export OPENROUTER_API_KEY="<your-openrouter-api-key>"+codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5++export FIREWORKS_API_KEY="<your-fireworks-api-key>"+codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b+```-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.+## Documentation-For complete command help, runtime defaults, native multi-agent worker limits,-environment variables, deep-scan configuration, and SDK options, see the-[package README](sdk/typescript/README.md) and the-[official CLI reference](https://learn.chatgpt.com/docs/security/cli/reference).+**ππ See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for full documentation.