How to scan your code with the Codex Security CLI

OpenAI released an open-source CLI that uses Codex to find security vulnerabilities in your code.

It’s called Codex Security.

You can use it to scan one repository, review the changes in a pull request, track findings across multiple scans, validate fixes, and scan many GitHub repositories in one run.

The package is public, but running a scan still requires access to Codex Security.

Install Codex Security

You need Node.js 22.13 or newer on the 22.x line, or Node.js 24 or 26. You also need Python 3.10 or later.

On Python 3.10, install tomli:

python -m pip install tomli

Run the public package with npx and verify the version:

npx @openai/codex-security --version

Then sign in with your ChatGPT account:

npx @openai/codex-security login

On a remote machine, use device authentication:

npx @openai/codex-security login --device-auth

For CI, use an OpenAI API key instead. Keep the key in your CI secret manager.

Run your first security scan

Go to the repository you want to check and run:

npx @openai/codex-security scan .

The CLI scans the current repository and creates a report with its findings, severity levels, evidence, affected locations, coverage, and remediation guidance.

The report is only part of the result.

Codex Security also creates a coverage file. It tells you which surfaces were reviewed, what was excluded, what work was deferred, and which questions remain open.

Coverage can be complete, partial, or unknown. Check this before trusting an empty report. Zero findings means little if the scan skipped an important service.

It also keeps the scan history. You can list earlier scans with:

npx @openai/codex-security scans list .

Then inspect one of them:

npx @openai/codex-security scans show SCAN_ID

The official quickstart recommends putting scan results in a private directory outside the repository. Reports may contain source excerpts and vulnerability details.

You can check the target and output directory before starting a real scan:

npx @openai/codex-security scan . \
  --output-dir ../codex-security-results \
  --dry-run

Remove --dry-run when everything looks correct.

Scan only your current changes

You don’t always need to scan the entire codebase.

To review your staged and unstaged changes, run:

npx @openai/codex-security scan . --working-tree --base HEAD

You can also scan the committed changes between two Git revisions:

npx @openai/codex-security scan . \
  --diff origin/master \
  --head HEAD

This is useful in CI because the scan can focus on the exact changes in a pull request.

Codex Security also has a deep mode for a repository or selected path:

npx @openai/codex-security scan . --mode deep

Start with the standard scan. Use deep mode when the extra time and cost make sense.

You can put a hard limit on model spending:

npx @openai/codex-security scan . --max-cost 5

Requests already running may take the final cost slightly above the limit.

Give the scan useful context

A scanner cannot infer every rule in your application.

For example, it may not know that a webhook must verify its signature before reading trusted fields. It may also miss that a public identifier is harmless while a course URL acts like a password.

You can pass architecture notes, a threat model, or security policies as a knowledge base:

npx @openai/codex-security scan . \
  --knowledge-base docs/architecture.md \
  --knowledge-base docs/security

Keep these files short and factual. Explain where untrusted input enters, which actions need authorization, and which data is sensitive.

You can also focus the scan with your own instructions:

npx @openai/codex-security scan . \
  --scan-prompt-file security-scan.md

I would use this for rules that matter in one project. General advice such as “find security bugs” adds little. A rule like “every purchase webhook must verify its Paddle signature before causing side effects” gives the scan something concrete to check.

Track findings across scans

Finding a vulnerability is only the first step. You also need to know whether it is new, still present, reopened, or resolved.

First match findings from two scans:

npx @openai/codex-security scans match OLD_SCAN_ID NEW_SCAN_ID

Then compare them:

npx @openai/codex-security scans compare OLD_SCAN_ID NEW_SCAN_ID

This gives you a history instead of a new disconnected report every time.

Be careful with a finding that disappears. AI-assisted scans can vary between runs. A missing finding does not prove that the vulnerability was fixed.

For an important finding, validate it directly against the current code:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

The CLI can also propose a patch:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Review and test generated patches before applying them.

Scan several GitHub repositories

Codex Security can also scan several GitHub repositories in one campaign.

First sign in with the GitHub CLI:

gh auth login

Then start the interactive repository picker:

npx @openai/codex-security bulk-scan

You choose a GitHub account or organization, filter the repository list, select what to scan, and confirm the output directory.

The CLI ignores archived repositories and forks. It also records the exact commit used for every selected repository. Interrupted campaigns can resume from their existing output directory.

For repeatable or automated campaigns, you can provide a CSV containing repository URLs and full commit hashes. See the bulk scan guide for the format.

Add a check before every commit

Codex Security can install a Git pre-commit check:

npx @openai/codex-security install-hook

The hook scans staged and unstaged changes. By default, it blocks the commit when it finds a high-severity issue or the scan fails.

You can choose a different threshold:

npx @openai/codex-security install-hook . --fail-on-severity medium

This can be useful, but remember that every commit now depends on a security scan. I would try it on a real project before making it part of the team’s default workflow.

Use Codex Security in CI

In CI, run a diff scan and return a non-zero exit code when a finding reaches your chosen severity:

npx @openai/codex-security scan . \
  --diff "$BASE_REVISION" \
  --head "$HEAD_REVISION" \
  --fail-on-severity high \
  --json

The CLI can export CSV, JSON, or SARIF. SARIF lets GitHub show findings in its code security interface.

OpenAI provides a complete GitHub Actions example. It keeps the API key scoped to the scan step, installs the CLI outside the repository checkout, scans the pull request diff, uploads SARIF, and preserves the report as an artifact.

My advice is to start with advisory results. Review the quality, runtime, cost, and false positives. Add a blocking severity policy only after you know how the tool behaves in your codebase.

Codex Security compared with DeepSec

Codex Security and DeepSec both use coding agents to investigate security problems. Both can scan a complete repository, review current changes, save findings, and recheck results.

The difference is how they organize the work.

Codex Security gives you a direct workflow. You run one command, point it at a repository or diff, and get a report. It has built-in scan history, validation, patch generation, bulk repository scans, Git hooks, CI output, and SARIF export.

DeepSec creates a .deepsec/ workspace inside the repository. It first uses local matchers to select interesting files. Coding agents then investigate those candidates. Separate commands handle scanning, processing, revalidation, triage, and reporting.

This makes DeepSec more visible and configurable. You can inspect its generated project description, entry-point inventory, matcher coverage, and custom matchers. You can also choose different coding agents and model providers.

Codex Security does not need that workspace. It is easier to try when you want a security review without adding project configuration.

The tradeoff is control.

I would choose Codex Security when I want the shortest path from a repository to a useful report. I would also choose it for bulk scans, pre-commit checks, or a Codex-based CI workflow.

I would choose DeepSec when I want to inspect and tune how files reach the AI stage. Its matcher pipeline is useful for a large repository where broad agent review would cost too much, or where unusual entry points need custom rules.

DeepSec can also work with Codex. They are not opposites. DeepSec is the review harness, while Codex can be the agent doing the investigation.

How I would use Codex Security

On flaviocopes.com, I would start with a standard full-repository scan.

Most files are static articles and course lessons. The sensitive code is smaller: purchase webhooks, course access recovery, public forms, AI endpoints, and operational scripts.

I would add a short knowledge-base file describing those boundaries. Then I would read the coverage report before looking at finding counts.

After the first review, I would use diff scans for normal changes:

npx @openai/codex-security scan . \
  --diff origin/master \
  --head HEAD

I would keep the scan advisory at first. A high severity label should start an investigation, not automatically block every change.

For a small repository, I would probably stop there. For a large or unusual codebase, I would consider DeepSec when custom matchers and explicit pipeline state justify the extra setup.

Keep a human in the loop

Traditional security scanners are mostly rule-based. They detect known patterns quickly, but often lack application context.

Codex Security can follow code across files, reason about reachability, collect evidence, explain an attack path, propose a fix, and check the result.

That does not make its output correct. It makes the report more useful to investigate.

You still decide what to scan, whether a finding is real, and whether a generated patch is safe. Confirm the complete code path and run the normal tests before applying a fix.

You can read the complete Codex Security CLI reference or inspect the Apache-2.0 licensed source code on GitHub.

Only scan repositories you own or have permission to assess.

Want me to talk about your product? You can sponsor this site.