🧭 Decision Guide
Why trending now: Cannot be determined from the provided material
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?
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.mdguidance. The commandcs policy . --path services/api --knowledge-base architecture.mdcan 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
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?
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.mdgenerates 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.mdordocs/SECURITY.mddo 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.mdwithout 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
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?
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"), andresult.reportPath, matching your asynchronous task and report-consumption requirements. - The same example calls
await security.close()infinally, 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
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?
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 showto 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.mdguidance. - For multiple Git worktrees, keeping
CODEX_SECURITY_STATE_DIRstable 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 .
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?
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_KEYorCODEX_API_KEYin 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
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?
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
✨ 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