Updated 2026-11-15. Codex Security is OpenAI's CLI and TypeScript SDK for finding, validating and fixing vulnerabilities. It needs Node 22.13 or later, or Node 24 or 26, and either a sign-in or an API key in CI. Here is the first run, a CI gate, and the sandbox failure that stops it on Ubuntu 24.04.
# Copy-paste starter. Validate the target before spending anything on a scan. npx @openai/codex-security scan . --dry-run # preflight only, no scan starts npx @openai/codex-security login # local scans sign in with ChatGPT npx @openai/codex-security scan . # writes a Markdown report
Codex Security helps you find, investigate and fix vulnerabilities, and the case for it grows with how much code you did not write by hand, which is a risk pattern with its own failure modes. It runs as a security workflow inside Codex, or as a CLI, a TypeScript SDK and a GitHub Action. The feature list is specific about the parts that matter in review: scans cover a whole repository, selected paths or Git changes; deep scans repeat standard scans and return their findings deduplicated; it validates candidate findings, generates patches and verifies existing fixes. It also drafts a SECURITY.md policy, saves threat models, imports findings from GitHub, Semgrep, Snyk, Sonar, Trivy and Endor Labs, and exports SARIF, JSON and CSV [1].
SECURITY.md
The installed CLI at version 0.10.0 lists its own surface, which is the fastest way to see whether this fits your workflow [2]:
Usage: codex-security <command> Aliases: cs Get started: codex-security scan . --dry-run codex-security login codex-security scan . codex-security scans show Scan and remediate: scan Scan a repository, selected paths, or Git changes. policy Draft SECURITY.md for review. validate Assess candidate security findings using source evidence only. patch Patch one or more security issues. verify-fix Verify existing security fixes without changing the repository. Review results: scans Review saved scans (default: list). findings Review saved findings (default: list). classify-severity Assess severity for saved findings or canonical records. dedupe Find duplicates against the saved findings corpus. suggest-owners Suggest finding owners from CODEOWNERS and Git history. Import and share: import Collect findings from GitHub, Semgrep, Snyk or Sonar. publish Publish Codex Security findings. export Export saved findings or a threat model without running an analysis. Automate: bulk-scan Discover and scan multiple repositories. scan-components Scan project components independently and combine their results.
cs and codex-security are the same command. If the short name collides with something else on your machine, use the long one [1].
cs
codex-security
engines
tomli
codex-security login
OPENAI_API_KEY
CODEX_API_KEY
Sign-in is the step where a scan either has a credential to use or does not, and on a build machine that credential is the part to place deliberately, in the same way an approved command can leave one behind in a settings file. The install is a global npm package, with a fallback the README names for a reason worth repeating: if the global install fails or reports an EEXIST conflict, use npx @openai/codex-security in place of cs for both signing in and scanning [1]. Running through npx is what this guide uses.
EEXIST
npx @openai/codex-security
npx
Two environment failures I hit here are worth knowing before you blame the tool. The first is an npm registry that points at a mirror which does not resolve, in which case every install fails with ENOTFOUND and no package is ever downloaded. Overriding the registry for the one command is enough:
ENOTFOUND
npm_config_registry=https://registry.npmjs.org npx --yes @openai/codex-security --help
The second is extracting the published tarball by hand and running it without its dependencies. The package starts and then stops at the first missing module, so the failure names a dependency rather than the CLI:
codex-security: Failed to start Codex Security: Cannot find package 'incur' imported from /tmp/cs-lab/package/dist/cli.js
Neither failure is a Codex Security bug. Both look like one if you meet them first.
Every scan starts by validating its inputs, and --dry-run lets you see that validation without starting an analysis [2]. On a scratch repository with no configuration and no sign-in, it prints this and exits 0:
--dry-run
[00:00] Validating scan inputs [00:00] Preflight complete dryRun: true repository: /tmp/cs-lab/repo target: kind: repository paths: [] mode: standard outputDir: null stateDirectory: /home/agentuser/.codex/state/plugins/codex-security authentication: method: stored_credentials verified: false model: gpt-5.6-sol reasoningEffort: xhigh
Read that block as the answer to four questions. target.kind: repository with an empty paths list means a whole-repository scan. mode: standard is the default, and deep is opt-in. authentication.verified: false is the sign-in you have not done yet, which is why a real scan after this fails. The last two lines name the model and reasoning effort the scan will use, and stateDirectory is where credentials and scan history live.
target.kind: repository
paths
mode: standard
deep
authentication.verified: false
stateDirectory
That state directory is worth setting deliberately. Stored credentials live in $CODEX_SECURITY_STATE_DIR/codex-home, or under $CODEX_HOME/state/plugins/codex-security/codex-home, and the CLI reference says to keep that private home outside the target repository and outside every enclosing Git worktree [2]. A new state directory starts fresh history and does not migrate existing credentials or reports, so pick it once.
$CODEX_SECURITY_STATE_DIR/codex-home
$CODEX_HOME/state/plugins/codex-security/codex-home
If you ask for a scan that does not exist yet, the CLI says so plainly:
codex-security: No completed scans found for the current repository. Use codex-security scans list to find failed or active scans, then pass a scan ID to scans show and scans logs.
That distinction, completed scans here and failed or active scans in scans list, is the first thing to remember when a scan seems to have vanished.
scans list
The exit codes are the part to get right, because they decide whether a pipeline fails for the reason you think [2]:
0
--fail-on-severity high
1
2
The reference makes the point that exit codes alone are not enough in automation: use manifest.scan.status together with the command exit code so that an execution failure is not read as a findings-policy violation. Scope exclusions, skipped files and follow-up notes do not fail a scan or bypass the findings threshold [2].
manifest.scan.status
Scope a scan to the change under review rather than the whole history. Both of these need Git, and both reject a checkout that is not clean at the requested revision before scanning begins [2]:
# Committed changes from a base revision to HEAD. codex-security scan . --diff origin/main # Staged and unstaged changes against a base. codex-security scan . --working-tree # A penalty-free dry run of the same scope, which is safe in a pipeline. codex-security scan . --diff origin/main --dry-run --json
Cost and time limits belong in the same command, because a scan that runs long or costs more than you planned is a pipeline problem rather than a security result, which is the same trap as any unattended agent that keeps buying work. --max-time sets an advisory investigation allowance in minutes, and --max-cost caps spend on a model whose pricing the tool knows, so the CLI reference advises choosing a model with built-in pricing when you set a cost limit [2].
--max-time
--max-cost
The GitHub Action is the shorter path for a repository you already own. Add an OpenAI API key as the repository secret CODEX_SECURITY_API_KEY, copy the weekly workflow to .github/workflows/codex-security.yml, and replace REPLACE_WITH_REVIEWED_COMMIT with the reviewed distribution commit SHA from an Action release [1]. That last step is the one not to skip, since it is what pins the Action to a commit you have looked at. The example uses an estimated $5 limit per scan and reports findings without failing the job, and the documentation warns that requests already in progress can exceed the limit [1].
CODEX_SECURITY_API_KEY
.github/workflows/codex-security.yml
REPLACE_WITH_REVIEWED_COMMIT
For a machine-readable result, scans also try to write SARIF to <scan-dir>/exports/results.sarif. That export is optional, so a scan can complete successfully without it, and the export command retries it from the saved results [2]. This is the difference between a security report a human reads and a result your existing code scanning view can display.
<scan-dir>/exports/results.sarif
export
This is the failure worth planning for, because it stops the first real scan on a common platform. Running a scan on Ubuntu 24.04 produced this:
Codex could not run a command in its sandbox: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted To reproduce, run '/home/agentuser/.npm/_npx/f4a9a6fe740fa973/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex sandbox -- /home/agentuser/.npm/_npx/f4a9a6fe740fa973/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex --version'. On Linux this usually means unprivileged user namespaces are restricted (kernel.apparmor_restrict_unprivileged_userns=1 on Ubuntu 24.04 and later), which Bubblewrap needs; inside the container image, use the AppArmor profile and Compose override from the SDK README.
The error carries its own reproduction command, which is unusual and useful, and it is the same class of problem as any agent tool call that a host refuses to sandbox. It also names the cause precisely, and on this machine that cause is present:
$ cat /proc/sys/kernel/apparmor_restrict_unprivileged_userns 1 $ uname -r 6.8.0-101-generic $ bwrap --dev-bind / / --ro-bind /usr /usr true bwrap: setting up uid map: Permission denied
So the tool is not the problem. The sandbox helper, Bubblewrap, cannot create a user namespace because AppArmor restricts unprivileged user namespaces on this kernel, and the CLI refuses to run the scan inside a sandbox it cannot construct. Note that sysctl may not exist on a minimal image, in which case reading /proc/sys/kernel/apparmor_restrict_unprivileged_userns directly works.
sysctl
/proc/sys/kernel/apparmor_restrict_unprivileged_userns
OpenAI's own troubleshooting section covers this shape of error in one line: sandbox startup errors include the native diagnostic followed by a command to reproduce it, and the Linux namespace and AppArmor guidance appears only on Linux [2]. The fix the message points at is the AppArmor profile and Compose override from the SDK README, which is the path for a container image you control. On a workstation you manage, the same kernel setting is the thing to discuss with whoever owns the machine, since it exists to protect the host from unprivileged namespace escapes.
One more detail from the same section is worth keeping next to this, because it looks like a second bug and is not one. If a scan reports that its state directory overlaps a protected root, choose a private directory in a separate tree, such as a sibling of the protected root, and set CODEX_SECURITY_STATE_DIR to it. The SDK exposes that case as OutputInsideProtectedRootError with a pathKind of "state" [2].
CODEX_SECURITY_STATE_DIR
OutputInsideProtectedRootError
pathKind
"state"
The TypeScript API is short enough to show whole. Install it in the project and wrap the run in try and finally, because the client holds resources and the close call is what releases them [1]:
try
finally
close
import { CodexSecurity } from "@openai/codex-security"; const security = new CodexSecurity(); try { const result = await security.run("/path/to/repository"); console.log(result.reportPath); } finally { await security.close(); }
The SDK guide covers deep-scan configuration, validation, severity classification, owner suggestions and result handling [3]. Two behaviours to design around: linked Git worktrees share scan history and saved findings only when they use the same Codex Security state directory, so keep CODEX_SECURITY_STATE_DIR stable if you want that shared history; and scan history plus local project files do not load automatically for SDK calls and saved reruns [1][2].
Policy generation is separate from scanning and exists so that a scan has guidance to follow. codex-security policy . drafts a SECURITY.md, saving the draft outside the repository and leaving existing files unchanged, and the instruction is to review the diff, edit the draft, then copy only SECURITY.md to the displayed policy target [1]. A component-scoped run can also produce a threat model, a project specification and the previous policy for comparison [2]:
codex-security policy .
codex-security policy . --path services/api --headless \ --output-dir /path/outside/repository/api-policy --json
Keep the saved architecture and threat-model documents outside the repository as the README instructs, and preserve any existing vulnerability-reporting instructions when you revise the file. Files at .github/SECURITY.md or docs/SECURITY.md often contain reporting instructions, and those locations do not automatically provide repository-wide scan guidance [1].
.github/SECURITY.md
docs/SECURITY.md
Project configuration is the last piece for a team. A trusted YAML or JSON file is selected with -c or through CODEX_SECURITY_PROJECT_CONFIG, and the CLI reference is careful about how it is found: an explicit -c wins, and without either path no file is discovered at all. scan, bulk-scan, scan-components and info accept project files; SDK calls and saved reruns do not load them automatically [2]. Treat the selected file as trusted operator configuration, the same way you would treat any file that can start a process on the build machine. A scan that becomes part of how a team ships is a rollout decision before it is a tool choice.
-c
CODEX_SECURITY_PROJECT_CONFIG
scan
bulk-scan
scan-components
info
Does Codex Security need Codex installed? No. The CLI is a standalone npm package, and the security workflows are also available inside a Codex session [1]. The GitHub Action runs the scan on GitHub-hosted Ubuntu without Codex on your machine.
Can I scan only the changed files in a pull request? Yes, with --diff <base> for committed changes or --working-tree for staged and unstaged edits. Both need Git and a checkout that is clean at the requested revision, and a dirty checkout is rejected before scanning [2].
--diff <base>
--working-tree
How does a scan fail a pipeline? A completed scan exits 0, --fail-on-severity high exits 1 when a high or critical finding is present, and execution, target-integrity or required-output failures exit 2. Check manifest.scan.status alongside the exit code so the two are not confused [2].
What happens if the SARIF export fails? The scan can still complete, because the export is optional. The export command writes or retries SARIF from the saved results afterwards [2].
Why does the scan stop on my server with a bwrap error? The sandbox helper cannot create an unprivileged user namespace. On Ubuntu 24.04 and later, AppArmor restricts those namespaces and the scan refuses to run unsandboxed. Use the AppArmor profile and Compose override from the SDK README in a container, or change the kernel setting on a machine you own [2].
bwrap
Is access restricted for some findings? Some cybersecurity requests and protected findings require Trusted Access for Cyber, and the CLI has separate paths for Daybreak access [1][2]. That gate is the same safeguard a general model applies to security work.
Do I need Codex Security Cloud? No. Cloud is an optional connection and local scans work without it. Reading existing Cloud findings is a separate capability that the Security plugin's $cloud-findings skill provides when Cloud is available to your account [1].
$cloud-findings
[1] OpenAI, Codex Security README, the package's own documentation, fetched 2026-11-15. Source of the feature list, the install and npx fallback, the quick start and scan options, the cs alias, sign-in and CI key handling, the SDK example, policy generation and the GitHub Action setup including the secret name, commit pinning and the estimated limit per scan.
[2] OpenAI, Codex Security CLI reference, fetched 2026-11-15, 162 KB. Source of authentication methods including login --with-api-key, the exit-code table and its warning about manifest.scan.status, scan scope rules for --diff and --working-tree, the state directory and CODEX_SECURITY_STATE_DIR behaviour, project-file discovery, cost and investigation limits, the SARIF path, policy artifacts, and the troubleshooting section quoted for sandbox startup errors and overlapping state directories. I also read the same page through the installed package at version 0.10.0.
login --with-api-key
--diff
[3] OpenAI, TypeScript SDK guide, fetched 2026-11-15. Source for the SDK surface beyond the README example: deep-scan configuration, validation, severity classification, owner suggestions and result handling.
[4] OpenAI, CI guide, fetched 2026-11-15, referenced for running scans in continuous integration.
[5] OpenAI, agent workflows, fetched 2026-11-15, referenced for task selection, setup and recovery when the workflow runs inside a Codex session.
[6] OpenAI, project configuration, fetched 2026-11-15, referenced for the trusted YAML or JSON file that scan, bulk-scan, scan-components and info accept.
[7] OpenAI, GitHub Action guide, fetched 2026-11-15, referenced for severity thresholds, pull request checks and runner requirements.
[8] OpenAI, Codex Security CLI documentation, the same CLI documentation on OpenAI's site, cited by the CLI itself in its help output.
Maxpertise is an AI-native engineering company. We embed native AI engineers inside your team, live in about 10 days. Please enable JavaScript to view the site, or email contact@maxpertise.net.