Approvals, Sandboxing, and Security

Sandbox behavior, approvals, cyber-safety, and security-specific guidance.

Codex Security CLI FAQ

Source: Codex Security CLI FAQ

Find answers to common questions about scanning repositories and managing security findings from the terminal. For installation and a first scan, start with the CLI quickstart.

Repository scans

Who can use the CLI

The @openai/codex-security package is public.

Running scans requires Codex Security access. For best results, use an account verified for Trusted Access for Cyber.

Why does a scan use an API key after sign-in

When your environment includes OPENAI_API_KEY or CODEX_API_KEY, scans without an interactive terminal and JSON and JSONL scans use the environment API key by default, even after a successful ChatGPT or access-token login. Interactive scans with text output ask you to choose when a ChatGPT sign-in is also available. Dry runs don't prompt or load credentials.

To use your stored credentials for a scan, select them explicitly:

npx @openai/codex-security scan . --auth chatgpt

To require an API key from OPENAI_API_KEY or CODEX_API_KEY:

npx @openai/codex-security scan . --auth api-key

To make your stored credentials the automatic default, run unset OPENAI_API_KEY CODEX_API_KEY. For all supported authentication modes, see the CLI reference.

How does bulk repository scanning work

Sign in with GitHub CLI:

gh auth login

Discover and select repositories from a GitHub account or organization:

npx @openai/codex-security bulk-scan

For a prepared list, provide a repository CSV and an output directory:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4

See Run bulk security scans for GitHub discovery, the CSV format, campaign results, and available options.

Can an interrupted bulk scan resume

Yes. Run the same bulk-scan command with the original CSV and output directory. Codex Security skips completed repositories.

Add --max-attempts 3 to retry temporary repository or scan errors:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

A completed scan with partial or unknown coverage keeps its results and causes the campaign to exit with code 2. It isn't retried, even with --max-attempts.

How can a scan use architecture and security policies

Pass architecture documents, threat models, or security policies with --knowledge-base:

npx @openai/codex-security scan . \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies

Codex Security uses these documents as context for the current scan. For supported file types and directory behavior, see Add security context.

Findings and coverage

Where can teams find earlier scan results

List saved scans for your repository:

npx @openai/codex-security scans list /path/to/repository

Use a scan ID from the results to inspect its findings:

npx @openai/codex-security scans show SCAN_ID

Each completed scan keeps its report, findings, coverage, and supporting artifacts together. See Scan artifacts for the full layout.

To inspect saved scan and worker events, run scans logs SCAN_ID. These logs aren't redacted and can contain source code or credentials.

What if the CLI can't save scan history

Codex Security keeps scan history in a workbench database. If the default state directory isn't writable, choose a private directory outside the repository:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

How do scans distinguish new and known findings

List the open findings from all scans of a repository:

npx @openai/codex-security findings list /path/to/repository

The list identifies findings confirmed in the latest scan and earlier open findings that the scan didn't confirm.

Compare findings across the two scans:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

The comparison automatically matches findings by root cause, reuses saved matches, and identifies new, persisting, reopened, resolved, and unknown findings. A finding counts as resolved only when the later scan covers its original target and affected path without coverage gaps.

How does false-positive feedback work

Inspect the saved scan to find the occurrence ID:

npx @openai/codex-security scans show SCAN_ID

Record why that finding doesn't apply:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Future scans of the same repository receive that explanation as context. They still independently check the current source, controls, and reachability. A dismissal doesn't suppress a rule, path, or vulnerability class.

For command details, see the findings reference.

Why can repeat scans return different findings

AI-assisted scans can vary, even with the same scan configuration. Start by rerunning your baseline scan:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

The rerun keeps the original scan configuration and requires the same plugin version. If the installed plugin has changed, the command stops.

Compare the baseline with the new scan:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Provide shared architecture and security guidance when missing context may contribute to the variation. Matching can identify the same underlying finding across runs, but it doesn't make scans deterministic. Directly recheck any important finding that disappears.

How can a team confirm that a fix worked

After applying a fix, rerun the original scan:

npx @openai/codex-security scans rerun BEFORE_SCAN_ID

Compare the original findings with the new scan:

npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID

Confirm that the new scan covers the original target and affected path without coverage gaps. Then directly recheck the original finding against the current checkout:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

A missing finding or scan comparison alone doesn't prove that a fix worked.

What does incomplete coverage mean

Coverage can be complete, partial, or unknown. Review coverage.json for excluded paths, deferred surfaces, and open questions before treating a scan as evidence of review.

Scans with partial or unknown coverage return exit code 2, even without a severity policy. They still keep any available findings and coverage. A later scan can't establish that an earlier finding no longer exists when it doesn't cover that finding's original path.

Automation and cost

How do deep-scan time limits work

Set a worker deadline when starting a deep scan:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

The default is 96 hours. Use any positive value up to 96, including fractions. At the deadline, Codex Security stops unfinished workers, keeps completed standard-scan results, and aggregates them into the final report. If no worker finishes source review, the report records partial coverage and the CLI returns exit code 2.

For persistent settings or bulk campaigns, set max_time_hours under [deep_scan] in the deep-scan configuration.

How do scan cost limits work

Set an estimated cost limit in USD before starting the scan:

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

The limit is an estimate, not a hard spending cap. Requests already in progress can finish above it. If a deep scan reaches the limit after Codex Security aggregates completed worker results, the CLI saves the completed report with partial coverage and exits with code 2. Otherwise, it preserves any available partial output.

Can scans check commits and pull requests

Install a pre-commit security check for staged and unstaged changes:

npx @openai/codex-security install-hook

For pull-request checks, scan the committed changes and set a severity threshold:

npx @openai/codex-security scan . \
  --diff origin/main \
  --fail-on-severity high

A complete scan returns exit code 1 when it finds an issue at or above the selected severity. See Run scans in CI for the complete GitHub Actions workflow, artifact handling, and SARIF export.

Can another application run scans directly

Yes. Use the TypeScript SDK to start scans, select targets, inspect findings and coverage, track progress, and apply cost controls from an application or developer tool.

Codex Security CLI quickstart

Source: Codex Security CLI quickstart

Codex Security helps security and engineering teams find, confirm, and fix vulnerabilities. Use its command-line interface (CLI) to scan repositories you own or have permission to assess, review findings over time, and check changes before they land.

The @openai/codex-security package is public. Running scans requires Codex Security access. For an interactive scan in Codex, start with the Codex Security plugin quickstart. For connected GitHub repositories, see Codex Security cloud setup.

Check the prerequisites

The CLI requires Node.js 22 (22.13.0 or later), 24, or 26. Scans, bulk scans, exports, scan history, and saved findings also require Python 3.10 or later. For more detail, see Authentication and prerequisites.

Set up and verify the CLI

Run the CLI with npx and check its version:

npx @openai/codex-security --version

To see both the package version and the version of its bundled plugin, run:

npx @openai/codex-security info --json

See the CLI and SDK releases for package changes.

List the available commands:

npx @openai/codex-security --help

See also CLI reference.

Sign in

For local use, sign in with your ChatGPT account:

npx @openai/codex-security login

On a remote or headless machine, use device authentication:

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

For CI and other automated workflows, set an OpenAI API key: