Codex Security: Scan, validate, and fix code vulnerabilities with CLI and SDK
A code-vulnerability CLI and SDK for development teams that validates findings and generates patches instead of only reporting results.
GitHub openai/codex-security Updated 2026-11-12 Branch main Stars 11.7K Forks 937
TypeScript Python JavaScript Rust Shell Code security Codex Security CLI TypeScript SDK GitHub Actions CI

🧭 Decision Guide

Try it if you

  • You need to inspect an entire repository, the src path, or Git changes from origin/main to HEAD with cs scan.
    The README's Quick start and Scan options sections list cs scan ., --path, and --diff origin/main.
  • You want scan results to continue into patch generation, fix verification, or SECURITY.md policy workflows.
    The README's Features, Generate SECURITY.md, and Use in Codex sections explicitly describe these workflows.
  • You need to call security scanning from a TypeScript project instead of only running a CLI command.
    The TypeScript SDK section shows npm install @openai/codex-security and a CodexSecurity.run example.
  • You need weekly repository scans on GitHub-hosted Ubuntu.
    The GitHub Actions section provides a weekly repository scan example.

Skip it if you

  • Your environment cannot meet the Node.js 22.13.0+, 24.x, or 26.x and Python 3.10+ requirements.
    The Quick start section explicitly lists the Node.js and Python version requirements.
  • You require a local browser dashboard or the serve command to manage scan results.
    The Findings storage and deduplication section says the local serve command and browser dashboard have been removed.
  • Your GitHub Action must fail the CI job when security findings are reported.
    The GitHub Actions section says the example reports findings without failing the job and refers threshold behavior to the Action guide.
  • Your account cannot obtain protected-finding capabilities that require Trusted Access for Cyber.
    The Scan options section says some cybersecurity requests and protected findings require Trusted Access for Cyber.

Requirements

  • Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x.
  • Python 3.10+; Python 3.10 also requires tomli.
  • CLI login requires cs login; CI scan processes need OPENAI_API_KEY or CODEX_API_KEY.
  • The GitHub Action example requires the CODEX_SECURITY_API_KEY repository secret and GitHub-hosted Ubuntu.
  • TypeScript SDK projects need @openai/codex-security installed.

First step (verbatim from README)

npm install --global @openai/codex-security

Watch out

  • cs and codex-security run the same CLI; use codex-security if the short name conflicts.
    The Quick start section explicitly states that both commands run the same CLI.
  • When npm reports EEXIST, the README says to use npx @openai/codex-security.
    The Quick start section provides the EEXIST workaround.
  • Deep scans repeat Standard scans, and the README points to separate Deep Scan limits documentation.
    The Features and Scan options sections describe the repetition and limits documentation.
  • The GitHub Action example estimates $5 per scan, but in-progress requests can exceed the limit.
    The GitHub Actions section states both the estimated $5 limit and possible overage.
  • Linked Git worktrees must keep CODEX_SECURITY_STATE_DIR stable to share history and sign-in scope.
    The TypeScript SDK section states the condition for shared scan history and saved findings.

Alternatives

  • Codex Security GitHub Action:Use it when scans should run in a GitHub Actions weekly workflow instead of being run manually with cs scan.
    GitHub Actions
  • Existing third-party scanners with Scanner import guides:Use existing third-party scanners when their findings need to be previewed, saved, or published through Codex Security.
    Scanner import guides

Not stated in the README

  • The README does not specify the exact vulnerability-detection coverage for supported programming languages.
  • The README does not specify actual billing, free quotas, or Codex Security Cloud pricing.
  • The README provides no accuracy, false-positive, or benchmark figures.
  • The README does not describe exact source-code transmission, retention, or processing policies.
  • The README does not state whether fully offline scanning or self-hosted model backends are supported.
  • The README does not specify Codex Security Cloud account availability or supported regions.

💡 Deep Analysis

6
Yes I maintain root and component-level `SECURITY.md` files and provide `architecture.md` as context. I require candidate vulnerabilities to be validated before patches are generated and fixes are verified. Can this project cover that workflow?
For: An application security engineer responsible for repository- and component-level vulnerabilities, using SECURITY.md, architecture documents, and threat models, and requiring candidate validation before patch generation

Yes, because the README explicitly connects policy context, finding validation, patch generation, and fix verification into one workflow.

  • The “Features” section lists validation of candidate findings, patch generation, and verification of existing fixes, matching your required sequence.
  • “Quick start” says scans use root and component SECURITY.md guidance. The command cs policy . --path services/api --knowledge-base architecture.md can draft or revise policy for a component with architecture context.
  • “Use in Codex” instructs users to read source evidence and exclusions in the report before requesting a patch or asking Codex to verify an existing fix.
  • Threat models are saved with results and can be exported using cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md, supporting later review.

The README requires review of generated policy drafts and copying only confirmed content. It does not guarantee that AI-generated patches pass tests, nor does it define approval, regression-testing, or vulnerability-confirmation compliance criteria.

  • README “Features”: “Validate candidate findings, generate patches, and verify existing fixes”
  • README “Quick start”: “Scans use existing root and component `SECURITY.md` guidance”
  • README “Generate SECURITY.md”: `cs policy . --path services/api --knowledge-base architecture.md`
  • README “Save and export threat models”: `cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md`
cs policy . --path services/api --knowledge-base architecture.md
Not stated in the README:Whether patch generation supports specified test commands, coding-style constraints, or approval gates;The decision criteria, evidence format, and auditable state transitions for validating candidate vulnerabilities;Whether generated threat models support versioning, access control, and sensitive-data redaction
It depends I need to generate a `SECURITY.md` for `services/api` using `architecture.md` as context without overwriting existing vulnerability-reporting instructions, and separately export the threat model. Is the project’s policy-artifact workflow reliable for this?
For: An application security lead integrating generated SECURITY.md files and threat models into a TypeScript security platform, while preserving existing vulnerability-reporting instructions and exporting threat models separately

It depends. The README clearly defines where policy drafts and threat models are saved, but it leaves final review and copying to the operator.

  • cs policy . --path services/api --knowledge-base architecture.md generates or revises policy for a component with architecture context, matching your requirement.
  • The README says the command saves the draft outside the repository and leaves existing files unchanged. It then requires reviewing the diff and notes, editing the draft, and copying only the confirmed SECURITY.md.
  • The same section says to preserve existing vulnerability-reporting instructions and warns that .github/SECURITY.md or docs/SECURITY.md do not automatically provide repository-wide scan guidance.
  • Scans and policy generation save threat models, which can be exported separately with cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md without starting another analysis.

This fits an auditable human-confirmation chain, but not an expectation of automatic secure merging. The README does not specify draft diff format, conflict handling, threat-model versioning, or access control.

  • README “Generate SECURITY.md”: `cs policy . --path services/api --knowledge-base architecture.md`
  • README “Generate SECURITY.md”: “saves its draft outside the repository and leaves existing files unchanged”
  • README “Generate SECURITY.md”: “preserve its vulnerability-reporting instructions”
  • README “Save and export threat models”: `cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md`
cs policy . --path services/api --knowledge-base architecture.md
Not stated in the README:Whether structured merging or conflict reporting is provided when a policy draft conflicts with an existing SECURITY.md;Whether threat models have versioning, provenance tracking, and cross-scan comparison;Whether policies and threat models stored outside the repository receive default access control or encryption
Yes I am integrating the Codex Security SDK into a TypeScript project running on Node.js 22.13.0+. I need asynchronous scans, access to reportPath, and reliable resource cleanup after each task. Is it suitable for this automation layer?
For: An engineer maintaining an internal security platform in a TypeScript project on Node.js 22.13.0+, who wants to run repository scans through an SDK and consume report paths

Yes, it is suitable because the project exposes a TypeScript SDK specifically for scan execution and report handling.

  • The “TypeScript SDK” section shows CodexSecurity, security.run("/path/to/repository"), and result.reportPath, matching your asynchronous task and report-consumption requirements.
  • The same example calls await security.close() in finally, making lifecycle cleanup part of the expected SDK usage.
  • The SDK guide also covers deep-scan configuration, validation, severity classification, owner suggestions, and result handling, which are useful primitives for an internal platform.
  • The project is primarily TypeScript, publishes @openai/codex-security, and uses Apache License 2.0, reducing integration friction.

The README does not specify concurrency limits, typed error classes, cancellation support, or report-file retention behavior. Those details still need validation before building a production-grade orchestration layer.

  • README “TypeScript SDK”: `const result = await security.run("/path/to/repository")`
  • README “TypeScript SDK”: `finally { await security.close(); }`
  • Project data: main_language is TypeScript; license is Apache License 2.0
npm install @openai/codex-security
Not stated in the README:Whether the SDK supports concurrency limits, task cancellation, and retry policies;Whether files referenced by reportPath are automatically cleaned up and how long source evidence is retained;The SDK error types and programmable error codes for authentication failures
Yes In a TypeScript repository, I use Codex to focus on authentication and authorization. I want results stored locally and need source evidence, exclusions, and coverage limits. Is this local workflow suitable?
For: A TypeScript developer using Codex to review authentication and authorization code who wants to inspect source evidence and coverage limits locally without connecting to Cloud

Yes. The Codex workflow saves reports and findings, requires inspection of source evidence and coverage limits before remediation, and does not require a Cloud connection for the basic local workflow.

  • “Use in Codex” provides an example focused on authentication and authorization and asks for a saved report, source evidence, and coverage limits.
  • After completion, the scan saves a report and findings. The README instructs users to open the Markdown file at the displayed REPORT path and use cs scans show to retrieve the latest completed scan.
  • Project insights explicitly state that local scanning does not depend on a Cloud connection, while the README says scans use root and component SECURITY.md guidance.
  • For multiple Git worktrees, keeping CODEX_SECURITY_STATE_DIR stable shares scan history, saved findings, and sign-in scope.

However, local execution does not necessarily mean that source code stays entirely local: the project depends on OpenAI API or Codex authentication. The README does not define source-upload behavior, retention, offline-model support, or report encryption.

  • README “Use in Codex”: focus on authentication and authorization; return a saved report, source evidence, and coverage limits
  • README “Quick start”: open the Markdown file at the REPORT path; use `cs scans show`
  • README “TypeScript SDK”: keep `CODEX_SECURITY_STATE_DIR` stable to retain shared history and sign-in scope
  • Project insight user_experience.usage_limitations: local scanning and Cloud connectivity are optional, but OpenAI API or Codex authentication is required
cs scan .
Not stated in the README:Whether source code and vulnerability details are sent to OpenAI services, and what regions and retention policies apply;Whether a fully offline Codex model or local inference mode exists;Whether reports, findings, and authentication data in the local state directory are encrypted by default
It depends I use `OPENAI_API_KEY` in CI across multiple GitHub repositories. I want each run to review only the Git diff from `origin/main` to HEAD, and I do not want Deep Scan on every commit. Does Codex Security fit this pipeline constraint?
For: A DevSecOps engineer responsible for CI across multiple GitHub repositories, using `OPENAI_API_KEY`, who wants to scan changes from origin/main to HEAD instead of scanning every repository in full

It depends. The project supports diff-based scanning, but you still need to control CI cost, timing, and authentication behavior.

  • The README’s “Scan options” section provides cs scan . --diff origin/main, allowing the scan scope to be restricted to changes between the baseline and HEAD.
  • It also provides Standard and Deep modes. Deep mode repeats Standard scans and deduplicates findings, so it is better treated as an intentional workflow rather than an unconditional per-commit step.
  • CI authentication is explicitly supported through OPENAI_API_KEY or CODEX_API_KEY in the scan process environment.
  • GitHub Actions, bulk scans, and SARIF/JSON/CSV exports are supported, while the project insights note that Deep Scan and bulk execution can increase time and API cost.

The diff workflow fits your constraint, but the README does not define the full GitHub Action permission model, failure thresholds, concurrency limits, or how cross-repository dependencies are covered by a diff scan.

  • README “Scan options”: `cs scan . --diff origin/main`
  • README “Quick start”: “For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`”
  • README “Features”: GitHub Actions, bulk scans, and SARIF, JSON, and CSV exports are supported
  • Project insight user_experience.usage_limitations: Deep Scan and bulk scans may increase time and API cost
cs scan . --diff origin/main
Not stated in the README:The README does not provide the complete GitHub Action YAML, permission requirements, or recommended commit-SHA pinning details;It does not state whether diff scans follow unchanged cross-repository or external components called by modified code;The severity level that blocks a CI pipeline must be configured or confirmed separately
Yes I need to review duplicate findings across multiple repositories, classify them using my own severity rubric, and export the results as SARIF. Is this project better suited than a scanner that only emits rule matches?
For: An application security engineer managing findings across multiple repositories who needs deduplication, severity classification, and SARIF export into an existing CI or security platform

Yes, especially when you need to manage findings rather than merely receive rule matches; however, it remains a security analysis and orchestration layer rather than a complete vulnerability-management platform.

  • The “Features” section covers browsing saved scans and findings, identifying duplicates, assessing severity against your own rubric, and suggesting owners from source and Git history.
  • Repository, selected-path, and Git-change scans are supported, along with bulk scans for multi-repository or component reviews.
  • “Save and export threat models” explicitly mentions SARIF output, while “Features” also lists JSON, CSV, and tracking integrations with Linear, Jira, and GitHub.
  • Project insights state that local state, scan history, and findings are saved and can be shared across related Git worktrees.

The README does not specify cross-repository deduplication keys, the full configuration format for severity rubrics, SARIF custom-field mapping, or a multi-tenant permission model.

  • README “Features”: “identify duplicates”, “assess severity against your own rubric”, and “suggest owners from source and Git history”
  • README “Features”: bulk scans, Linear, Jira, GitHub, and SARIF, JSON, and CSV are supported
  • Project insight solution_analysis.architectural_strengths: local state storage, scan history, and optional Cloud connectivity
cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
Not stated in the README:The README does not show the exact command parameters or field mapping for exporting findings as SARIF;It does not define which stable identifiers are used for cross-repository or cross-component deduplication;It does not describe permission isolation for findings between teams or tenants

✨ Highlights

  • The CLI scans repositories, selected paths, and Git changes
  • It validates findings, generates patches, and verifies fixes
  • The TypeScript SDK and GitHub Action support automation
  • The GitHub Action example estimates a $5 limit per scan

🔧 Engineering

  • The Codex Security CLI uses cs scan for repositories, paths, or Git diffs
  • Deep scans repeat Standard scans and deduplicate findings
  • The TypeScript SDK provides run, validation, and result-handling APIs
  • It exports SARIF, JSON, and CSV and integrates with Linear, Jira, and GitHub

⚠️ Risks

  • The runtime requires Node.js 22.13.0+, 24.x, or 26.x
  • Python 3.10 environments also require the tomli dependency
  • The GitHub Action example reports findings without failing the job
  • Protected findings may require Trusted Access for Cyber
  • The local serve command and browser dashboard have been removed

👥 For who?

  • Development teams scanning TypeScript or Python repositories from a terminal
  • Automation systems that need to embed scans through the TypeScript SDK
  • Repository maintainers running weekly scans on GitHub-hosted Ubuntu
  • Teams that track security findings in Linear, Jira, or GitHub