Do not make Codex Security CLI a required check on day one: From first scan to CI¶
Deployment decision
| Stage | Decision |
|---|---|
| Local evaluation | Run --dry-run, fix the output and cost boundaries, then evaluate in report-only mode |
| Pull-request CI | Scan only trusted same-repository pull requests and require human triage |
| Required check | Enable only after measuring coverage and false-positive handling, with exit code 2 treated as failure |
Apache-2.0 distribution of the CLI and SDK does not include scan access or model usage. Begin without merge enforcement, then increase enforcement after the evidence path is reliable.
Published: 2026-07-31
OpenAI has published the codex-security repository for vulnerability discovery, validation, and remediation assistance. It includes a CLI and TypeScript SDK under the Apache License 2.0.12
The operational decision is more complicated than adding an open-source tool to CI. The client source is public, but an actual scan still requires Codex Security access.3
For this article, SmartScope installed the npm latest version, 0.1.4, as observed on July 31, 2026, then verified the version command and --dry-run. We did not run a paid, access-controlled vulnerability scan, so this article does not claim measured detection rates or scan duration.
Open source distribution does not include scan access or usage cost¶
@openai/codex-security is a public Node.js package that exposes the codex-security command and a TypeScript SDK. The official README lists macOS, Linux, and Windows support and requires a supported Node.js 22.13-or-later line plus Python 3.10 or later.1
Being able to authenticate the CLI does not prove that the account has scan access. The official documentation says that running scans requires Codex Security access and that some account or repository targets may require Trusted Access for Cyber.34
The --max-cost option is an estimated limit rather than a strict hard cap. Requests already in flight can finish above the specified amount, which is one reason not to begin with unattended scans across every repository.5
| What is open | What remains a separate decision |
|---|---|
| CLI and TypeScript SDK source | Codex Security access |
| Apache-2.0 license | Model usage and budget policy |
| Local and CI integration machinery | Source transmission, retention, and internal approval |
| SARIF, JSON, and CSV export | Receiving-platform features such as GitHub Code Security |
Fix the output boundary and cost estimate before the first scan¶
In an evaluation environment, pin the package version and inspect the configuration before invoking a model. The commands below use the version observed on July 31, 2026.
npm install @openai/codex-security@0.1.4
npx @openai/codex-security --version
npx @openai/codex-security login
npx @openai/codex-security scan . --dry-run
--dry-run checks inputs and configuration without credential verification, Python runtime startup, or network access. In our smoke test, version 0.1.4 was reported and preflight printed the repository, mode, output directory, authentication method, model, and effort.5
When moving to an actual scan, put results outside the target repository and any enclosing worktree. Results can contain source excerpts, vulnerability detail, and reproduction or remediation information, so they should not be uploaded as public artifacts by default.4
SCAN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-security.XXXXXX")"
npx @openai/codex-security scan . \
--output-dir "$SCAN_DIR" \
--max-cost 5
Record more than the number of findings. A useful evaluation ledger includes target coverage, complete versus incomplete state, duration, estimated cost, human-reproduced findings, and reasons for false-positive decisions.
Begin CI with report-only scans of trusted same-repository pull requests¶
The official CI guide limits its pattern to trusted pull requests from the same repository. It avoids exposing secrets to forks or Dependabot, installs a reviewed pinned CLI before checkout, and disables checkout credential persistence.6
The core command for scanning committed pull-request changes is small. The fragment below is not a complete secure workflow; event conditions, permissions, tool pinning, and artifact retention should follow the full official example.
codex-security scan . \
--diff "$BASE_REVISION" --head "$HEAD_SHA" \
--auth api-key --output-dir "$SCAN_DIR" \
--json > "$RUNNER_TEMP/codex-security.json"
Do not add --fail-on-severity during the initial rollout. Review results as a restricted artifact or SARIF report, noting that SARIF upload for private or internal repositories can depend on GitHub Code Security eligibility.6
If the latest CLI version and the version pinned in official examples differ, do not upgrade mechanically. Review the changes and dependencies, then pin the version your team approved.
Enable a severity gate only after measuring coverage and triage quality¶
Scans are report-only by default. Adding --fail-on-severity high makes a completed scan return exit code 1 when it finds an issue at or above that threshold.5
codex-security scan . \
--diff "$BASE_REVISION" --head "$HEAD_SHA" \
--fail-on-severity high \
--auth api-key --output-dir "$SCAN_DIR"
Exit code 1 is not the only failure state that matters. Invalid input, runtime failure, and incomplete coverage return exit code 2, which must not be interpreted as no vulnerabilities found.
| Exit code | Meaning | CI treatment |
|---|---|---|
| 0 | Completed and passed the configured severity gate | Continue |
| 1 | Found an issue at or above the threshold | Stop for human triage |
| 2 | Input, runtime, or incomplete coverage | Stop because the scan failed |
| 130 / 143 | Interrupt or termination signal | Inspect the retry condition |
A few green runs are not enough to justify a required check. The team should first prove that incomplete scans are visible, false-positive decisions have reasons, artifact access is restricted, and timeout and budget-overrun policies are explicit.
Use rerun, compare, and validate for different remediation questions¶
A finding disappearing from one later scan does not necessarily prove remediation. If scope changed or later coverage was incomplete, the finding can be unknown rather than resolved.5
Codex Security CLI separates scan history, rerun, match, compare, and validate. Re-evaluating a target, pairing findings across scans, classifying changes, and validating a specific fix answer different questions.
codex-security scans rerun "$SCAN_ID"
codex-security scans match "$BEFORE_ID" "$AFTER_ID"
codex-security scans compare "$BEFORE_ID" "$AFTER_ID"
codex-security validate findings.json "target finding"
The scans are nondeterministic, so rerun does not guarantee an identical result. Final acceptance should still include reproduction steps, targeted tests, existing SAST, dependency scanning, secret scanning, and human review.
Treat the patch command as a write to the current worktree. Run it on a clean, dedicated branch or worktree, review the diff, and execute the relevant tests.8
The TypeScript SDK can become a control plane for multiple repositories¶
The TypeScript SDK offers more than a different spelling of the CLI. It exposes preflight, run, lifecycle callbacks, AbortSignal, targets, output location, and cost controls.7
import { CodexSecurity } from "@openai/codex-security";
const security = new CodexSecurity();
await security.preflight({ repository: process.cwd() });
const result = await security.run({
repository: process.cwd(),
maxCostUsd: 5,
});
The SDK is useful when multiple repositories need common approval, budget, retention, and notification policies. For a first evaluation in one repository, an explicit CLI invocation and saved result are usually easier to audit.
Choose between Codex Security and Claude Security by execution surface and evidence¶
Codex Security and Claude Security both use model reasoning for vulnerability discovery, but their operational centers differ. The Claude Security plugin runs a multi-agent scan inside a Claude Code session and produces a threat model, independent finding review, and patches for manual application.9
Codex Security CLI targets a repository, selected paths, a commit diff, or a working tree. It adds scan history, comparisons, false-positive state, SARIF, and severity-based exits, which fit CI and multi-repository evidence management.
| Dimension | Codex Security CLI / SDK | Claude Security plugin |
|---|---|---|
| Primary surface | Shell, CI, or Node.js program | Claude Code session |
| Targeting | Repository, path, diff, working tree | Full repository or diff |
| Evidence | History, JSON, CSV, SARIF, compare | Timestamped scan results and patches |
| Enforcement | Report-only or severity exit | Human acceptance of results and patches |
| Strong fit | Scheduled runs, CI, multi-repository governance | Interactive deep analysis and threat modeling |
Anthropic's separate Claude Code Security Review Action is an older CI path centered on pull-request diffs and comments. Its repository warns that it is not hardened against prompt injection and limits use to trusted pull requests, so it should not be conflated with the current plugin.10
Keep existing SAST and human review¶
Codex Security CLI can extend discovery into context-dependent vulnerabilities that conventional scanners may miss. That benefit does not make a nondeterministic model a replacement for deterministic rule engines or accountable human review.
A safe sequence is local --dry-run, a cost-bounded repository evaluation, report-only diff scans for trusted pull requests, human triage, a severity gate, and post-fix validate. This sequence turns an open-source release into an engineering control with explicit stopping conditions and evidence.
Related Articles¶
- Design AI security review as three separate stages
- Multi-agent scans with the Claude Security plugin
- Use Codex CLI safely in GitHub Actions
OpenAI, Codex Security repository, accessed July 31, 2026. ↩↩
OpenAI, Codex Security Apache License 2.0, accessed July 31, 2026. ↩
OpenAI, Codex Security overview, accessed July 31, 2026. ↩↩
OpenAI, Codex Security CLI quickstart, accessed July 31, 2026. ↩↩
OpenAI, Codex Security CLI reference, accessed July 31, 2026. ↩↩↩↩
OpenAI, Run Codex Security in CI, accessed July 31, 2026. ↩↩
OpenAI, Codex Security TypeScript SDK, accessed July 31, 2026. ↩
OpenAI, Codex Security CLI patch implementation, accessed July 31, 2026. ↩
Anthropic, Scan your codebase for vulnerabilities, accessed July 31, 2026. ↩
Anthropic, Claude Code Security Review, accessed July 31, 2026. ↩