OpenAI just open-sourced Codex Security

Jul 29, 2026 03:52 AM - 2 hours ago 1

Codex Security is an open-source CLI and TypeScript SDK for finding, validating, and reviewing information issues successful codification you ain aliases person support to assess.

Note

This package follows semantic versioning. Its nationalist API whitethorn alteration between minor versions earlier 1.0.0.

The SDK and CLI support macOS, Linux, and Windows and require Node.js 22 or later. Scanning and exporting findings besides require Python 3.10 aliases later. If you usage Python 3.10, instal the tomli package. Python is not needed to install the package aliases tally --help and --version.

Sign successful pinch your OpenAI relationship aliases supply an OpenAI API cardinal earlier moving a scan. Scan only repositories you ain aliases person definitive support to assess.

npm instal @openai/codex-security npx codex-security login npx codex-security scan /path/to/repo

Run npx codex-security --help to spot each commands and npx codex-security scan --help for scan options.

On a distant aliases headless machine, usage npx codex-security login --device-auth. For CI and different unattended scans, group OPENAI_API_KEY aliases CODEX_API_KEY using your shell, CI secret, aliases concealed manager.

On Windows, group an API cardinal successful PowerShell with:

$env:OPENAI_API_KEY = "<your-api-key>" npx codex-security scan C:\code\repository

To shop an API key, walk it connected stdin:

printenv OPENAI_API_KEY | npx codex-security login --with-api-key

Use npx codex-security login position to cheque the stored sign-in and npx codex-security logout to region it. Codex Security reuses an existing file-based Codex sign-in. If Codex stores credentials successful the strategy keyring, run npx codex-security login erstwhile earlier scanning.

An situation API cardinal takes precedence complete a stored sign-in. Unset both OPENAI_API_KEY and CODEX_API_KEY to usage your ChatGPT sign-in. The login status bid reports the effective credential root without printing its value, including erstwhile nary stored sign-in exists.

Scan a subset of a repository aliases constitute machine-readable results:

npx codex-security scan /path/to/repo --model gpt-5.6-terra npx codex-security scan /path/to/repo --path src --path tests npx codex-security scan /path/to/repo --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf npx codex-security scan /path/to/repo --diff origin/main --json npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results npx codex-security scan /path/to/repo --output-dir /path/outside/repo/results --archive-existing npx codex-security scan /path/to/repo --dry-run npx codex-security scan /path/to/repo --fail-on-severity high npx codex-security install-hook npx codex-security bulk-scan npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans npx codex-security scans database /path/to/repo npx codex-security scans database --scan-root /path/outside/repo/results npx codex-security scans show SCAN_ID npx codex-security scans rerun SCAN_ID npx codex-security scans lucifer PREVIOUS_SCAN_ID CURRENT_SCAN_ID npx codex-security scans lucifer --all npx codex-security scans comparison PREVIOUS_SCAN_ID CURRENT_SCAN_ID npx codex-security export /path/outside/repo/results --export-format sarif --output /path/outside/repo/results.sarif npx codex-security export /path/outside/repo/results --export-format csv --output /path/outside/repo/findings.csv npx codex-security export /path/outside/repo/results --export-format json --output /path/outside/repo/findings.json npx codex-security validate /path/outside/repo/findings.json "Possible SQL injection successful src/query.ts:42" npx codex-security spot /path/outside/repo/findings.json "Missing authorization cheque successful src/routes.ts:18"

install-hook scans staged and unstaged changes earlier each commit. It respects core.hooksPath, does not switch an existing hook, and blocks high-severity findings aliases grounded scans. Set --fail-on-severity to alteration the threshold.

Use npx codex-security --version for the CLI type and npx codex-security info --json for package, plugin, and runtime versions, the default exemplary and reasoning effort, and the adjacent scan command. Add --dry-run to inspect the effective exemplary and reasoning effort without initializing Codex aliases contacting the network.

The output directory must beryllium extracurricular the scanned directory and immoderate enclosing Git worktree. On macOS and Linux, an existing output directory must beryllium backstage to the existent personification (chmod 700). Scan artifacts tin incorporate root excerpts, vulnerability details, and reproduction steps. Keep them retired of repositories, public rumor reports, and shared locations.

When SARIF is produced, it is written to <scan-dir>/exports/results.sarif. Use npx codex-security scan --help for all target, output, and runtime options.

Repeat --knowledge-base PATH for aggregate files aliases directories. Directories are searched recursively for Markdown, text, PDF, and Word (.docx) files.

Sign successful pinch gh auth login, past tally npx codex-security bulk-scan to discover GitHub repositories pushed successful the past 90 days. Archived repositories and forks are excluded. Search the repository list, prime the repositories to scan, and corroborate earlier scanning. Private checkouts reuse your GitHub CLI sign-in without changing your world Git configuration. For automation aliases an existing repository list, walk a CSV containing id, repository, and afloat immutable revision columns and specify --output-dir. Use npx codex-security bulk-scan --help for each options.

The CLI uses Incur for agent-friendly discovery and system output. Use --llms for the bid manifest, scan --schema --format json for a bid schema, registry an MCP server with mcp add, sync supplier skills pinch skills add, and use completions bash|zsh|fish for shell completions. Scan results support --format toon|json|yaml|jsonl and --full-output. Use info --json for SDK and bundled-plugin metadata. MCP exposes only this read-only metadata command; scans, authentication, exports, validation, and patching stay CLI-only because the MCP carrier cannot cancel progressive scans.

If the output directory already contains results, adhd --archive-existing. The CLI moves them to <output-dir>.previous-<timestamp>-<id> and starts the scan successful a new, quiet directory astatine the original path. Add --dry-run to see the destination without moving files.

Scans are report-only by default. Use --fail-on-severity successful CI to exit 1 when a completed scan contains a uncovering astatine aliases supra the selected severity. Incomplete sum and CLI/runtime errors exit 2. Incomplete scans still write the disposable quality aliases JSON consequence to stdout and a sum informing to stderr, including successful report-only mode.

For CI, prevention machine-readable output extracurricular the checked-out repository and apply a severity policy. Incomplete sum and runtime errors still exit nonzero:

SCAN_ROOT="$(mktemp -d)" npx codex-security scan . \ --diff origin/main \ --output-dir "$SCAN_ROOT/results" \ --json \ --fail-on-severity precocious > "$SCAN_ROOT/findings.json"

JSON scans stay noninteractive, including erstwhile stderr is simply a terminal. Commands that tally Codex interactively (validate, patch, login, and logout) reject --json. Write CSV exports to a record erstwhile JSON output is selected.

Scans usage gpt-5.6-sol pinch extra-high reasoning effort by default. Switch models pinch --model. Use --codex for different Codex settings:

npx codex-security scan . --model gpt-5.6-terra --codex 'model_reasoning_effort="high"'

Scans study their requested paths and existent ranking, file-review, validation, and attack-path phases. Completion shows uncovering severity, coverage, elapsed time, disposable token and worker counts, the results directory, and the next useful command. Progress remains connected stderr; JSON results stay connected stdout.

Create a client, take a backstage output directory extracurricular the repository, and close the customer aft the scan:

import { CodexSecurity } from "@openai/codex-security"; const security = new CodexSecurity(); try { const result = await security.run("/path/to/repository", { outputDir: "/path/outside/repository/results", }); console.log(result.reportPath); console.log(result.findings.findings.length); } finally { await security.close(); }

The SDK besides supports way and diff targets, preflight, advancement callbacks, cancellation, information knowledge bases, and typed scan results.

The included Docker image runs noninteractive bulk scans from a supplied CSV on a Linux Docker host. The included compose.yaml configures the image, persistent files, and a hardened Codex bid sandbox.

Configure a Docker bulk scan

Create a repositories.csv pinch 1 full, immutable Git perpetrate per repository:

id,repository,revision payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567

Create private, persistent consequence and authentication directories, and fto the container constitute files arsenic your existent user:

mkdir -p results state chmod 700 results state export CODEX_SECURITY_USER="$(id -u):$(id -g)" docker constitute build codex-security

For a one-time sign-in from a distant aliases headless Docker host, run:

docker constitute tally --rm codex-security login --device-auth

Open the displayed verification URL successful your browser and participate the one-time code. The login remains successful state/ aft the instrumentality exits.

Alternatively, supply OPENAI_API_KEY aliases CODEX_API_KEY done your host environment aliases concealed manager. For backstage repositories, supply GH_TOKEN or GITHUB_TOKEN the aforesaid way. Compose passes only the named, configured credentials to the container.

Start a resumable, four-worker scan pinch the default command:

docker constitute tally --rm codex-security

Full-repository scans tin return tens of minutes per repository astatine the default extra-high reasoning setting. Run ample campaigns arsenic asynchronous batch jobs and support the results and authentication directories mounted passim the run.

Completed reports, per-repository findings, and the scan manifest look in results/ connected the host. The workbench authorities for that run remains in results/.codex-security-state/; the reusable Codex login remains separately in state/. This allows a caller results directory to commencement a abstracted run with the aforesaid login without colliding pinch an earlier scan. Rerun the aforesaid command with the original CSV and the aforesaid results/ and state/ directories to resume an interrupted scan.

To take a different number of parallel workers aliases retry grounded repositories, override the default scan command:

docker constitute tally --rm codex-security \ bulk-scan /input/repositories.csv \ --output-dir /output \ --workers 8 \ --max-attempts 2

Set CODEX_SECURITY_CSV, CODEX_SECURITY_RESULTS, aliases CODEX_SECURITY_STATE to usage existing files aliases directories extracurricular the Compose project. Set CODEX_SECURITY_IMAGE to usage an approved, already-built image. Set CODEX_SECURITY_GIT_HOST erstwhile accessing GitHub Enterprise Server. Keep credentials, repository lists, and results retired of the image and Git; the included disregard files exclude them from image builds and commits. All CSV files, including custom-named repository inventories, are excluded from the Docker build context. Compose mounts the selected CSV astatine runtime instead.

The included Compose configuration drops each Linux capabilities, prevents new privileges, runs arsenic a nonroot user, and applies the supplied default-deny seccomp profile. Codex Security runs each scan bid successful a separate unprivileged Linux sandbox. Docker's default seccomp floor plan blocks the personification and mount namespaces required by that sandbox; the supplied floor plan permits only the needed namespace operations. The Linux big must let unprivileged user namespaces. Some Docker Desktop virtual machines additionally restrict nested mount namespaces, truthful usage a Linux big for accumulation scans.

For environments without Docker Compose, the balanced lower-level invocation is:

docker tally --rm --init \ --user "$(id -u):$(id -g)" \ --cap-drop ALL \ --security-opt no-new-privileges \ --security-opt "seccomp=$PWD/docker/codex-security-seccomp.json" \ --env OPENAI_API_KEY \ --env CODEX_API_KEY \ --env GH_TOKEN \ --env GITHUB_TOKEN \ --env CODEX_SECURITY_GIT_HOST \ --mount "type=bind,source=$PWD/repositories.csv,target=/input/repositories.csv,readonly" \ --mount "type=bind,source=$PWD/results,target=/output" \ --mount "type=bind,source=$PWD/state,target=/state" \ codex-security:local \ bulk-scan /input/repositories.csv \ --output-dir /output

The image configures a noninteractive Git credential helper for github.com when a GitHub token is supplied. The token useful pinch some HTTPS repository URLs and [email protected]: repository URLs without mounting an SSH agent. The image ne'er places that token successful a repository URL, writes it to image layers, or sends it to different Git host. Set CODEX_SECURITY_GIT_HOST to the hostname of a GitHub Enterprise Server lawsuit erstwhile needed.

Use --workers to power concurrent repository scans and --max-attempts to retry failures. The bid returns a nonzero position erstwhile immoderate repository fails.

npx codex-security scans database lists scans for the existent repository. Pass a repository way to inspect different checkout, --scan-root DIR to select by scan artifact directory. scans show SCAN_ID includes saved configuration, findings, and coverage.

History is saved successful the existing Codex Security workbench database under $CODEX_HOME/state/plugins/codex-security. Set CODEX_SECURITY_STATE_DIR to choose a different location.

scans rerun SCAN_ID repeats the aforesaid configuration against the current checkout. scans lucifer BEFORE_SCAN_ID AFTER_SCAN_ID links findings pinch the same guidelines cause; scans lucifer --all includes each disposable completed scan of the existent repository, including different worktrees and clones. Use --force to recompute saved matches.

scans comparison BEFORE_SCAN_ID AFTER_SCAN_ID sounds saved matches and identifies new, persisting, reopened, resolved, aliases chartless findings. Missing findings remain unknown erstwhile sum is incomplete aliases their original location was not reviewed.

Use export to create CSV, JSON, aliases SARIF from a completed, sealed scan without starting Codex aliases loading credentials. JSON preserves the sealed findings document. CSV uses the portable findings columns, marks findings arsenic open, and does not see section workbench triage state. The exporter validates the seal before writing, accepts --output - for stdout, and tin use --source-root /path/to/repo pinch SARIF to adhd source-line fingerprints. Run npx codex-security export --help for each export options.

Use validate to tally the bundled validation accomplishment connected campaigner findings and patch to tally the bundled fix-finding accomplishment connected information issues. Each positional input tin beryllium either a file, whose contents are publication into the request, aliases literal text. Both commands run connected the existent directory.

Canonical scan documents are constricted to 16 MiB for the manifest, 128 MiB for findings, and 32 MiB for coverage. Oversized scans are rejected earlier sealing.

Exit codes are 0 for a completed report-only scan aliases a passing policy, 1 for a completed argumentation violation, 2 for invalid input, incomplete coverage, or a runtime/export error, 130 for interruption, and 143 for termination.

Use --dry-run aliases await security.preflight(...) to validate section scan inputs and study the selected credential root without initializing Codex, loading credentials, aliases starting a scan. Dry runs do not inspect the plugin, probe Python, aliases interaction the network; their authentication metadata is not verified.