Codex Security CLI and SDK: an OpenAI scanner for finding and fixing vulnerabilities

What Codex Security actually does, and who it is for

The package is `@openai/codex-security`, published on npm, written in TypeScript, licensed Apache-2.0, and maintained under the openai organisation. The README describes it as a CLI and TypeScript SDK for defining security policy and finding, validating, and fixing security vulnerabilities in your code. That sentence contains three verbs, and they are not equally supported. Finding is the core loop. Validating appears through the findings service and the dedupe command. Fixing is implied by the report output rather than spelled out in the README.

The audience is narrower than "anyone doing application security". The quick start requires Node.js 22.13.0 or later and Python 3.10 or later, which rules out older build images. The primary interface is a command line plus a TypeScript import, so the natural user is a platform or security engineer wiring a scan into an existing pipeline, not an analyst clicking through a dashboard. The dashboard that does exist is read-only and lives inside the findings service.

One access constraint sits in the README rather than in a footnote: some cybersecurity requests and protected findings require approval through Trusted Access for Cyber, and the README points to chatgpt.com/cyber to join. If your work touches that category, the tool is not simply a `npm install` away.

How a scan runs: directory in, report path out

The mechanism visible in the README is a directory-oriented scan. You point the CLI at a path, it runs a discovery process, and it produces a report. The SDK exposes the same operation with a result object whose `reportPath` you read after the call. There is no repository index, no agent you install into your source tree, and no daemon required for the basic path.

The SDK options reveal the shape of the engine. `mode: "deep"` selects a heavier run. `workers: 2` and `subagents: 0` control concurrency. `stopAfterNoNew: 3` and `maxDiscoveryRuns: 10` bound how long the search continues when it stops finding new things. `maxTimeHours: 1.5` is a wall-clock ceiling. Those names tell you the scan is iterative: it keeps running discovery rounds until either the budget runs out or three consecutive rounds add nothing. That is a sensible design for a search problem, and it also means scan cost is a function of how much the model keeps finding, not of repository size alone.

Inference does not have to come from OpenAI. The README shows `--provider` flags for amazon-bedrock, openrouter, and fireworks, each paired with a `--model` value such as `openai.gpt-5.6-luna` or `anthropic/claude-sonnet-4.5`. Each provider needs its own environment variable: `AWS_BEARER_TOKEN_BEDROCK` plus `AWS_REGION`, `OPENROUTER_API_KEY`, or `FIREWORKS_API_KEY`.

Installing Codex Security and running a first scan

The README gives the install as a single npm command. The package is installed globally or into a project, and the binary is `codex-security`.

npm install @openai/codex-security
codex-security login
codex-security scan /path/to/directory

After `login` completes, `scan` walks the directory you name and writes a report. For CI you skip `login` entirely and set `OPENAI_API_KEY` in the environment instead, which is the pattern the README recommends.

If you would rather drive it from code, the SDK mirrors the CLI. Construct the client, call `run`, and read the report path. The second call shows the tuning knobs in context.

import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();
const result = await security.run("/path/to/directory");
await security.run("/path/to/directory", {
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

console.log(result.reportPath);
await security.close();

Note the `close()` call. The client holds resources, so a long-lived process needs to release them. The README does not describe what happens if you skip it.

The second workflow worth trying early is policy generation, which is separate from scanning. It drafts guidance for future scans rather than running one.

codex-security policy .
codex-security policy . --path services/api --knowledge-base architecture.md

The README is explicit that this saves a draft outside the checkout and does not install it or run a vulnerability scan. It also warns that supporting architecture, threat-model, and review documents stay outside the repository and may contain sensitive details. Treat the output as a proposal you review, not a file that appears in your tree.

The findings service is where the design gets interesting, and where the caveats start

Running `codex-security serve` starts a findings service without Docker. The README labels it preview, and that label should govern how you treat it. It runs from the same `ghcr.io/openai/codex-security` image as the scanner, in a separate container with its own state volume configured by `compose.findings.yaml`. Findings and embeddings go into SQLite. The service lists findings with pagination, and its read-only dashboard at `/dashboard` refreshes every five seconds.

The part that distinguishes this from a plain scanner is duplicate detection. The service returns potential duplicates by embedding similarity, scoped either to one repository or to all repositories when you ask for the broader scope. A publish step uploads completed findings and their repository ID: `codex-security publish scan --to custom --findings-url http://localhost:3000`. The SDK and the `codex-security dedupe` command then retrieve candidates, run independent Codex reviews locally, and persist accepted duplicate groups. The `--all-repositories` flag is what opts into the wider scope.

Severity is handled separately from the scan itself. `codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md` assesses selected findings against your own policy before you publish tickets. Classification checkpoints each finding in SQLite and reuses matching assessments on reruns, with `--reprocess` forcing reassessment. The README states that original scan severity stays unchanged. That separation is a good decision: your severity model and the scanner's default model can disagree without either overwriting the other.

The caveat is the word preview. SQLite as the store, a dashboard that refreshes on a five-second timer, and a duplicate workflow that runs reviews locally all point to a single-node setup. The README does not describe replication, backup, or what happens to the state volume when the container is replaced.

Bulk scanning many repositories with Docker Compose

For fleets rather than single repositories, the repository ships a Compose configuration that runs the `bulk-scan` command against a CSV of repositories. The compose file mounts three paths: the CSV at `/input/repositories.csv` read-only, results at `/output`, and state at `/state`. Each is overridable through an environment variable, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE`, all with defaults of `./repositories.csv`, `./results`, and `./state`.

The container hardening is more deliberate than most Compose examples. It drops all capabilities with `cap_drop: ALL`, sets `no-new-privileges:true`, and applies a seccomp profile from `./docker/codex-security-seccomp.json` unless you override `CODEX_SECURITY_SECCOMP`. It runs as user `10001:10001` by default. The bind mounts use `create_host_path: false`, which means Compose will not silently create a missing directory for you; if the CSV or output directory is absent, the mount fails rather than producing an empty run. That is the right default for a scanner, since a typo in a path should be loud.

The environment block names `CODEX_API_KEY`, `CODEX_SECURITY_GIT_HOST`, `GH_TOKEN`, `GITHUB_TOKEN`, and `OPENAI_API_KEY`. The presence of `GH_TOKEN` and `GITHUB_TOKEN` alongside a git host variable indicates cloning happens inside the container, which is why the image installs `git` and `openssh-client`. The README also mentions a separate workflow runner Compose example for running individual CLI stages with durable state and access to a separately deployed findings service. The README does not explain how to authenticate the clone for private repositories beyond those token variables.

Where Codex Security is the wrong choice

The README does not document rollback. There is no described way to undo a published finding, revert a persisted duplicate group, or restore the SQLite state after a bad classification run. The `--reprocess` flag forces reassessment of severity, and that is the only recovery path named. If your process requires an auditable undo for every state change, this is a gap you have to close yourself.

There is no published accuracy data. No false-positive rate, no recall figure, no comparison against a labelled corpus appears in the README or the release notes. The `stopAfterNoNew` and `maxDiscoveryRuns` parameters show the scan is heuristic in when it stops, but nothing quantifies result quality. For a security tool, that means you cannot size the triage burden from the documentation alone.

The version number is 0.1.x, with `npm-v0.1.26` released on 2026-09-08. The findings service is labelled preview. A team that needs a scanner with a stable configuration schema and a long support window should weigh that against the Apache-2.0 source, which at least lets you read the implementation. The README funnels full documentation to an external site, so the repository itself is not the complete reference.

Finally, the Trusted Access for Cyber gate applies to some requests and protected findings. If your workload falls in that category, availability depends on program approval rather than on npm.

How this differs from a rules-based scanner

The obvious comparison is a conventional static analysis tool with a rule set: Semgrep, CodeQL, or a hosted code-scanning service. Those tools match patterns and dataflow queries against a fixed engine. You can read the rules, reason about why a finding fired, and predict what a new rule will catch. Their output is deterministic for a given rule version.

Codex Security works differently. The scan is an iterative discovery process driven by a model, bounded by `stopAfterNoNew` and `maxDiscoveryRuns` rather than by a rule set. The README shows provider and model selection as first-class flags, which only makes sense if the model is doing the reasoning. The consequence is that two runs over the same directory are not guaranteed to produce the same findings, and the reason a finding appeared is not a rule you can point at. The dedupe step reinforces this: it retrieves embedding-similar candidates and then runs independent Codex reviews locally to decide which are genuine duplicates. That is a probabilistic pipeline with a review stage, not a matcher.

The trade-off is legibility against coverage of things nobody wrote a rule for. A rules engine tells you exactly why it stayed silent. This tool's silence is harder to interpret, and the README offers no way to ask it why a given file produced nothing.

Maintenance, upgrade cost, and the licence

The repository is not archived, and the last push was on 2026-09-14. Release cadence over the visible window is fast: 0.1.24 on 2026-08-29, 0.1.25 on 2026-09-02, and 0.1.26 on 2026-09-08. Three releases in under two weeks at the 0.1.x stage means the surface is still moving. Pin a version in CI rather than tracking latest, and read `CHANGELOG.md` before each bump, because the repository ships one and it is the cheapest way to see what changed.

Upgrade cost concentrates in three places. The findings service stores state in SQLite, so a schema change between versions can affect existing data. The SDK options are typed, so a renamed parameter surfaces as a compile error rather than a silent behaviour change, which is a point in favour of driving it from TypeScript. The Docker image carries pinned base digests in the Dockerfile, so rebuilding after an upgrade is deliberate rather than automatic.

The licence is Apache-2.0. That permits commercial use and modification and includes an express patent grant, which matters for a security product. It does not answer the separate question of what the model providers' terms require when you point `--provider` at Bedrock, OpenRouter, or Fireworks; those are governed by each provider's own agreement, and nothing in the README addresses it. This is not legal advice, and the licence file in the repository is the authority.

Editorial conclusion

Adopt Codex Security if you already run Node.js 22.13.0 or later, want a scriptable scan stage in CI, and are willing to treat the findings service as a preview rather than production infrastructure. Do not adopt it if you need a documented rollback story, a published benchmark, or a scanner you can audit rule by rule. Before you commit, run codex-security policy . against a scratch checkout and confirm where the draft lands, because the README states the command saves it outside the checkout rather than installing it, and that single behaviour decides whether the tool fits your review process.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. openai/codex-security on GitHub
3. Project website
4. README
5. Releases