OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
docs(sdk): simplify the TypeScript README (#659)
mldangelo-oaia4413faed7cf
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex a4f59677d..776fdb2c6 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -1,12 +1,9 @@# `@openai/codex-security`-Open-source TypeScript SDK and CLI for running Codex Security scans. The-ESM-only package includes TypeScript declarations, the `codex-security`-executable, and the matching Codex runtime.+Run Codex Security scans from TypeScript or the command line. This ESM-only+package includes TypeScript declarations and the Codex runtime.-> [!NOTE]-> This package follows semantic versioning. Its public API may change between-> minor versions before `1.0.0`.+Before version `1.0.0`, minor releases may change the public API.## Install@@ -15,22 +12,14 @@ npm install @openai/codex-securitynpx @openai/codex-security --version```-The package supports macOS, Linux, and Windows and requires Node.js 22.13.0 or-later in the 22.x release line, Node.js 24.x, or Node.js 26.x. Scans, bulk-scans, exports, scan history, and saved findings also require Python 3.10 or-later. Python 3.10 also requires `tomli`. Use `--python` with `scan`,-`bulk-scan`, or `export`; use `pythonPath` with the SDK. Set `PYTHON` to select-an interpreter for any Python-backed command.--When a newer version is available, the CLI shows the update command for your-installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the-notice. Notices are also disabled in CI and when stderr is not a terminal.+Use Node.js 22.13.0+ (22.x), 24.x, or 26.x on macOS, Linux, or Windows.+Scans, exports, scan history, and saved findings also need Python 3.10++(plus `tomli` on Python 3.10).## Run a scan from TypeScriptSign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or-`CODEX_API_KEY`. Then create a client and scan a repository you own or have-permission to assess:+`CODEX_API_KEY`, then scan a repository you own or have permission to assess:```tsimport { CodexSecurity } from "@openai/codex-security";@@ -49,29 +38,15 @@ try {}```-The SDK supports repository, path, committed-diff, and working-tree targets.-Use `security.preflight()` to validate local inputs, `onWorkerStatus` and-`onReconnect` to observe long-running scans, and an `AbortSignal` to cancel a-scan.--For separate standard scans under one project, the SDK also exports-`runComponentScans({ repository, outputDir, components })`. Each component has-a `name` and `paths` array. Use `auto: true` instead of `components` for-model-assisted planning, and `planOnly: true` to save the plan without scanning.--Successful results include open repository findings in `repositoryFindings`,-when available; `findings` remains the current scan. Matching earlier findings-can make one additional model call, including with a scan cost limit.+`result.findings` contains this scan's findings; `repositoryFindings` also+includes earlier open findings when available. Matching earlier findings can+make one extra model call, even with a cost limit.-Results can contain source excerpts, vulnerability details, and reproduction-steps. Keep result directories and saved reports outside the repository and-limit access to authorized reviewers.+Keep results outside the repository and restrict access: reports can contain+source code, vulnerability details, and reproduction steps.### Validate an existing finding-Use `security.validate()` to assess one finding without running a repository-scan or invoking the Codex Security CLI:-```tsconst security = new CodexSecurity();try {@@ -90,25 +65,23 @@ try {}```-`finding` accepts literal text or a JSON-serializable object, never a file-path. Read files explicitly. Validation uses the CLI's validation skill and-the client's settings and authentication. It leaves repository files unchanged-and does not add a scan to scan history.+Pass literal text or a JSON-serializable object as `finding`, not a file path.+Validation uses the client's settings and credentials without changing+repository files or adding a scan to history.-The result contains `disposition` (`reportable`, `suppressed`, `not_applicable`,-or `deferred`), a Markdown `report`, `threadId`, and `outputDir` for evidence.-The report explains root cause, exploitability, evidence, and proof gaps.-`reportable` can rely on static analysis; `deferred` means insufficient evidence.+Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,+or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.+`reportable` may rely on static analysis; `deferred` means insufficient evidence.+Failed, incomplete, or malformed responses reject the promise.-`outputDir` must be empty and outside the enclosing Git worktree. It defaults-to the Codex Security state directory's `validations/` folder. Pass `auth` to-select authentication or `signal` to cancel. Failed, incomplete, or malformed-responses reject the promise.+`outputDir` must be empty and outside the Git worktree; it defaults to+`validations/` under the state directory. Pass `auth` to select credentials+or `signal` to cancel.### Import GitHub code scanning alerts-Use `importGitHubCodeScanningAlerts()` to read GitHub code scanning findings,-including third-party SARIF uploads, before independent validation:+Import alerts, including third-party SARIF uploads, and validate them against+the matching local checkout:```tsimport {@@ -137,88 +110,80 @@ try {```Each result contains `source`, `repository`, `number`, `url`, and the full-upstream `alert`, including rule/help text, locations, commit/ref, and dismissal-context. Import does not start Codex, register a scan, or change GitHub state.-Validate against the intended local checkout; import does not check out code.+upstream `alert`. Import is read-only and does not start Codex or check out code.-Without `alertNumbers`, `state` defaults to `"open"`; `"closed"`, `"dismissed"`,-`"fixed"`, and `"all"` are also accepted. Exact alert numbers ignore state and-cannot be combined with a nondefault `state`. `ref` selects another branch or-pull-request reference and preserves that reference's alert instance.+Without `alertNumbers`, `state` filters alerts and defaults to `"open"`.+It also accepts `"closed"`, `"dismissed"`, `"fixed"`, and `"all"`. Exact alert+numbers ignore state and reject a nondefault `state`. Use `ref` for another+branch or pull-request reference.-Authentication reuses `gh auth token` (including GitHub CLI token environment-variables) unless `githubToken` is supplied. `githubHost` defaults to `GH_HOST`-or `github.com`; `signal` cancels requests. The token needs read access to code-scanning alerts. Access failures reject the import.+Supply `githubToken` or use your `gh auth token` credentials, including GitHub+CLI token environment variables. `githubHost` defaults to `GH_HOST` or+`github.com`. The token needs read access to code scanning alerts; access+failures reject the import. Pass `signal` to cancel.### SDK configuration and scan options-Pass runtime configuration to the `CodexSecurity` constructor:+Constructor options:-| Option | Description |-| ---------------- | --------------------------------------------------------------------------- |-| `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |-| `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |-| `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |+| Option | Description |+| ---------------- | ----------------------------------------------------------------------- |+| `pluginPath` | Plugin directory or ZIP; defaults to the bundled plugin. |+| `pythonPath` | Python interpreter; overrides `PYTHON`. |+| `codexOverrides` | Supported settings to deep-merge into the isolated Codex configuration. |-Pass scan configuration to `security.run(repository, options)` or+Options for `security.run(repository, options)` and`security.preflight(repository, options)`:-| Option | Description |-| ----------------------- | ------------------------------------------------------------------------------------------ |-| `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |-| `safetyIdentifier` | Stable hashed end-user ID for this scan's model requests; requires API-key authentication. |-| `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |-| `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |-| `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |-| `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |-| `archiveExisting` | Archive results already in `outputDir` before starting a scan. |-| `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |-| `maxTimeHours` | Limit deep-scan discovery to a positive number of hours, up to 96. |-| `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |-| `parentScanId` | Link a rerun to an existing parent scan. |-| `expectedPluginVersion` | Require the original plugin version when replaying a scan. |-| `signal` | Cancel a scan with an `AbortSignal`. |--Progress and lifecycle callbacks are `onAuthentication`, `onCost`,-`onOutputArchived`, `onOutputDirReady`, `onScanStarted`,-`onTrustedAccessStatus`, `onReconnect`, `onSessionEvent`, `onWorkerStatus`,-`onWarning`, and `onObserverError`. `onSessionEvent` receives saved scan and-worker events with their thread IDs and worker numbers. Preflight does not start-the runtime, authenticate, resolve Python, inspect the plugin, or run those-scan-lifecycle callbacks.+| Option | Description |+| ----------------------- | ------------------------------------------------------------------------------ |+| `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |+| `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |+| `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |+| `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |+| `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |+| `outputDir` | Artifact directory outside the enclosing Git worktree. |+| `archiveExisting` | Archive existing results in `outputDir` before scanning. |+| `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |+| `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |+| `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |+| `parentScanId` | Parent scan ID for a rerun. |+| `expectedPluginVersion` | Required original plugin version when replaying a scan. |+| `signal` | `AbortSignal` to cancel a scan. |++Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives+saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.++`preflight` and CLI `--dry-run` check local inputs without starting Codex or+using the network. They don't authenticate, verify model access, resolve Python,+inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.## Authentication-For local use, sign in with ChatGPT:+Sign in with ChatGPT:```bashnpx @openai/codex-security loginnpx @openai/codex-security scan .```-On a remote or headless machine, use device authentication:+Use device authentication on remote or headless machines:```bashnpx @openai/codex-security login --device-auth```-For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,-pass it on stdin:+For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin:```bashprintenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key```-Environment API keys are supplied directly to the current scan and are never-saved to the Codex credential home or system keyring. Only an explicit-`login --with-api-key` stores an API key.--To pass a Codex access token explicitly, use-`login --with-access-token` and provide the token on stdin. An access token-environment variable is not automatically used as a scan API key.+Environment API keys apply to the current scan; only `login --with-api-key`+saves them. Pass Codex access tokens on stdin to `login --with-access-token`.+Access-token environment variables are not scan API keys.-To use another inference provider, set its API key and select its provider:+For other inference providers:```bashexport OPENROUTER_API_KEY="<your-openrouter-api-key>"@@ -232,6 +197,11 @@ export AWS_REGION="us-east-2"npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna```+Bedrock also accepts AWS access keys, profiles, web identity, container+credentials, and the default AWS credential chain. Set `AWS_REGION` and choose+a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`+support `--max-cost`.+On Windows, set the API key in PowerShell:```powershell@@ -239,171 +209,86 @@ $env:OPENAI_API_KEY = "<your-api-key>"npx @openai/codex-security scan C:\code\repository```-Codex Security keeps its sign-in in a private, stable Codex home at-`$CODEX_SECURITY_STATE_DIR/codex-home`, or at-`$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is-configured. On managed Windows devices, inherited access for `SYSTEM` and local-`Administrators` is preserved while protecting the home against future changes-to its parents. Other users and broad groups are rejected, and PowerShell-Constrained Language Mode is supported. Login,-status, logout, and scans use the same home. Codex manages-credentials using its configured file or system-keyring backend and honors-managed-device policies. An existing file-based Codex sign-in is imported only-when the dedicated home does not already contain stored credentials. Logging-out prevents later scans from automatically reimporting that ambient sign-in-until you explicitly log in again.--Scan runtime preparation locks this home even if the process pauses; exiting or-crashing releases the lock. A compatibility heartbeat prevents released-heartbeat-only clients from replacing an active newer owner's lock, but those-clients can still replace a paused newer owner's lock. Finish operations using-older versions before upgrading. Keep `.codex-security-scan.sqlite3` between-operations and never remove it while an operation is running. PID reuse can make-older PID-only locks look live and block recovery. Stop all operations using-this home before manually removing an old `.codex-security-scan.lock` directory.--If a scan says the stored ChatGPT sign-in could not be refreshed, check it with-`npx @openai/codex-security login status` and retry if it recently changed.-Otherwise replace it with `npx @openai/codex-security logout`, then-`npx @openai/codex-security login`. Codex Security does not automatically clear-the sign-in or change managed login restrictions.--An environment API key takes precedence for model authentication by default,-but Codex may still need a valid ChatGPT sign-in to load workspace-managed-policies.-When both a stored ChatGPT sign-in and an environment API key are available, an-interactive scan asks which credential to use. JSON output, dry runs, CI, and-other noninteractive scans never prompt and retain automatic API-key-precedence. Select the credential source explicitly with `--auth`:+Login, logout, and scans share a private credential home:+`$CODEX_SECURITY_STATE_DIR/codex-home`, or+`$CODEX_HOME/state/plugins/codex-security/codex-home`. Codex uses the configured+file or keyring storage and managed-device policies. If this home has no+credentials, it imports an existing file-based Codex sign-in. Logout disables+imports until you log in again.-```bash-npx @openai/codex-security scan . --auth chatgpt-npx @openai/codex-security scan . --auth api-key-```+Finish operations using older versions before upgrading. Runtime preparation+holds the credential-home lock through pauses; exit or crash releases it.+Compatibility heartbeats protect active locks from older heartbeat-only+clients, but those clients can replace a paused client's lock.++Keep `.codex-security-scan.sqlite3` between operations; never remove it during+an operation. PID reuse can make old PID-only locks appear active and block+recovery. Stop all operations using this home before removing an old+`.codex-security-scan.lock` directory manually.-`--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and-`CODEX_API_KEY`. `--auth api-key` requires one of those environment variables.-Omit `--auth`, or pass `--auth auto`, to preserve automatic API-key precedence-for existing CI and unattended scans. The SDK accepts the same selection as-`security.run(repository, { auth: "chatgpt" })` and-`security.preflight(repository, { auth: "chatgpt" })`.+If ChatGPT credentials cannot be refreshed, run `login status`. Retry if the+sign-in recently changed; otherwise run `logout`, then `login`.-To make the stored ChatGPT sign-in the automatic default instead, unset any-configured API-key variables:+Interactive scans ask whether to use ChatGPT or an environment API key when+both are available. The choice applies to that scan. Noninteractive scans,+including CI, JSON output, and dry runs, prefer the API key. Choose with `--auth`:```bash-unset OPENAI_API_KEY CODEX_API_KEY+npx @openai/codex-security scan . --auth chatgpt+npx @openai/codex-security scan . --auth api-key```-The interactive choice applies only to the current scan and is not persisted.--When an environment key is configured, ChatGPT login and-`codex-security login status` identify the effective scan credential source-without printing its value, including when no stored sign-in exists.+`--auth chatgpt` ignores environment API keys. `--auth api-key` requires+`OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; unset both+variables to default to ChatGPT. The SDK uses the same `auth` option on `run`+and `preflight`. Codex may still need ChatGPT credentials to load+workspace-managed policies when using an API key.-Some cybersecurity requests and protected findings require approval through-Trusted Access for Cyber. To apply or check your access, visit+Some cybersecurity requests and protected findings require Trusted Access for+Cyber approval. Apply or check your access at[chatgpt.com/cyber](https://chatgpt.com/cyber).## CLI```bash-npx @openai/codex-security scan-npx @openai/codex-security scan /path/to/repository-npx @openai/codex-security scan /path/to/repository --headless-npx @openai/codex-security scan /path/to/repository --patch-npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --json-npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --create-pr-npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra-npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high+npx @openai/codex-security scan .npx @openai/codex-security scan /path/to/repository --path src --path tests-npx @openai/codex-security scan-components /path/to/repository --component apps/api --component apps/web --output-dir /path/outside/repository/results-npx @openai/codex-security scan-components /path/to/repository --auto --output-dir /path/outside/repository/results-npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf-npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.mdnpx @openai/codex-security scan /path/to/repository --diff origin/main --jsonnpx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results-npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing-npx @openai/codex-security scan /path/to/repository --verbosenpx @openai/codex-security scan /path/to/repository --dry-run-npx @openai/codex-security scan /path/to/repository --fail-on-severity high-npx @openai/codex-security scan /path/to/repository --max-cost 5-npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5-npx @openai/codex-security install-hook-npx @openai/codex-security bulk-scan-npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high-npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3 --max-cost 25-npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf-npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md-npx @openai/codex-security scans list /path/to/repository-npx @openai/codex-security scans list --scan-root /path/outside/repository/results-npx @openai/codex-security scans show-npx @openai/codex-security scans show SCAN_ID-npx @openai/codex-security scans logs-npx @openai/codex-security scans logs SCAN_ID-npx @openai/codex-security scans rerun-npx @openai/codex-security scans rerun SCAN_ID-npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID-npx @openai/codex-security scans match --all-npx @openai/codex-security scans compare-npx @openai/codex-security scans compare PREVIOUS_SCAN_ID-npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID-npx @openai/codex-security findings-npx @openai/codex-security findings list /path/to/repository-npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"-npx @openai/codex-security export-npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif-npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv-npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json-npx @openai/codex-security publish scan /path/outside/repository/results --to linear --linear-team TEAM_ID-npx @openai/codex-security publish scan --to linear --linear-team TEAM_ID-npx @openai/codex-security publish scan --to cloud --csv /path/outside/repository/findings.csv-npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"-npx @openai/codex-security validate "Possible SQL injection" --effort high-npx @openai/codex-security import github example/repository --format json-npx @openai/codex-security verify-fix --linear-issue SEC-123 --json-npx @openai/codex-security verify-fix --linear-project "Security backlog" --linear-filter '{"state":{"type":{"eq":"completed"}}}' --json-npx @openai/codex-security verify-fix --scan SCAN_ID --severity high --json-npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"-npx @openai/codex-security patch "Missing authorization check" --effort high-npx @openai/codex-security patch OCCURRENCE_ID-npx @openai/codex-security patch --scan SCAN_ID --severity high --json-npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr-npx @openai/codex-security patch --resume-pr codex-security/patch-SCAN_ID-npx @openai/codex-security patch --scan latest --severity medium-npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124-npx @openai/codex-security patch --linear-project "Security backlog" --linear-filter '{"labels":{"name":{"eq":"security"}}}'```-Run `npx @openai/codex-security --version` for the installed CLI version or-`npx @openai/codex-security info --json` for the package, bundled plugin, Codex runtime,-default model, reasoning effort, and first-scan command. A scan with `--dry-run`-also reports its effective model and reasoning effort, including `--codex`-overrides, without starting Codex or contacting the network.+Use `scan --help` for options, `--version` for the installed version, and+`info --json` for package, plugin, runtime, and model details. `--dry-run`+runs local preflight checks.-`install-hook` scans staged and unstaged changes before each commit. It respects-`core.hooksPath`, does not replace an existing hook, and blocks high-severity-findings or failed scans. Set `--fail-on-severity` to change the threshold.+### Scan options and output`--path` scopes a scan to one or more paths, `--diff` scans committed changes,and `--working-tree` scans staged and unstaged changes. Deep scans support-repository and path targets. The output directory must be outside the scanned-directory and any enclosing Git worktree. When SARIF is produced, it is written-to-`<scan-dir>/exports/results.sarif`.+repository and path targets.Working-tree snapshots include files from untracked nested Git repositories.Initialized submodules must be clean and checked out at the commit recorded bythe parent repository.-Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`-shares them with every repository. Directories are searched recursively for-Markdown, text, PDF, and Word (`.docx`) files.+Repeat `--knowledge-base PATH` for Markdown, text, PDF, or Word (`.docx`) files.+Directories are searched recursively. Bulk scans share these documents with+every repository.++Use an empty output directory outside the scanned directory and enclosing Git+worktree. On macOS/Linux, existing directories must be private to you+(`chmod 700`). `--archive-existing` moves previous results to+`<output-dir>.previous-<timestamp>-<id>`; add `--dry-run` to preview the move.+SARIF output, when produced, is at `<scan-dir>/exports/results.sarif`.++Scans are report-only by default. Set `--fail-on-severity high` to exit with+`1` if a completed scan finds high or critical issues. Incomplete scans exit+with `2`, writing available results to stdout and a coverage warning to stderr.### Attribute scans to end users-For an application that serves multiple users, pass the originating user's-stable hashed ID on each scan:+When scanning on behalf of users, pass each user's stable hashed ID:```tsawait security.run("/path/to/repository", {@@ -416,23 +301,19 @@ await security.run("/path/to/repository", {codex-security scan /path/to/repository --auth api-key --safety-identifier hashed-user-id```-The ID must contain 1–64 characters and cannot be blank or contain NUL.-Do not use an email address or other personal data. The ID is passed to Codex-for the scan, nested workers, retries, and follow-up work. It is not saved in-shared configuration or the scan recipe. Supply it again for a later rerun.-Concurrent SDK clients can use different IDs without changing `process.env`.+Use a nonblank ID of 1 to 64 characters without NUL or personal data such as+email addresses. It applies to the scan, workers, retries, and follow-up work+without changing shared configuration. Supply it again for reruns.-This requires a Codex runtime with native `--safety-identifier` support and a-plugin that forwards it to workers. The current bundled runtime does not yet-support this option. Use `CODEX_CLI_PATH` to select a compatible build.-The SDK does not check runtime or plugin compatibility; older versions may-omit the identifier. Omitting the option leaves ordinary scans unchanged.-Preflight checks the ID's format; authentication is checked when the scan starts.+The runtime needs native `--safety-identifier` support, and the plugin must+forward it to workers. The bundled runtime doesn't support it yet; choose a+compatible build with `CODEX_CLI_PATH`. The SDK checks the ID's format, not+runtime or plugin compatibility. Older versions may omit the ID.### Scan project components-`scan --path` runs one scan across the selected paths. Use `scan-components`-to run a separate standard scan for each component of one local project:+`scan --path` runs one scan across selected paths. To scan each local project+component separately in standard mode, use `scan-components`:```bashnpx @openai/codex-security scan-components /path/to/project \@@ -440,12 +321,8 @@ npx @openai/codex-security scan-components /path/to/project \--workers 4 --output-dir /path/outside/project/results```-Use `--auth chatgpt` or `--auth api-key` to select credentials for planning,-component scans, and matching. The default is `--auth auto`, as with `scan`.-The SDK accepts the same choice through `scanOptions.auth`.--Use `--auto` instead of `--component` to let Codex propose the split. To review-or edit it first, save a plan, then run that plan into a new output directory:+Use `--auto` instead of `--component` for a proposed split. Save a plan to+review or edit, then run it with a new output directory:```bashnpx @openai/codex-security scan-components /path/to/project \@@ -455,7 +332,7 @@ npx @openai/codex-security scan-components /path/to/project \--output-dir /path/outside/project/results```-A component can contain several repository-relative paths:+Components use repository-relative paths:```json{@@ -466,45 +343,36 @@ A component can contain several repository-relative paths:}```-Automatic planning uses a local file inventory. In Git repositories it follows-Git's ignore rules. Each automatic path must cover at least one inventoried file.-Explicit `--component` and `--components-file` selections keep their existing behavior.-Inventoried files omitted by the model are added to an-`Other files` component. No source files are changed during planning.--In an interactive terminal, one dashboard shows all components and their scan-progress. Use the arrow keys to select a component, Enter to view its activity,-and Esc to return. Other scans continue while you inspect one. Finding counts-are preliminary until cross-component matching finishes. Use `--headless` for-plain status lines; CI and redirected output use those automatically.-Failed or incomplete components are also saved in `retry-components.json`.-Pass that file to `--components-file` with a new output directory to retry them.--Each component keeps its normal scan artifacts under `component-N/`.-The combined `findings.json` uses the same root-cause matcher as `scans match`.-It merges high-confidence matches even when their titles, locations, or-fingerprints differ. Each group keeps its highest-severity finding and all-original scan and occurrence IDs. Match reasons and uncertain pairs are saved;-uncertain findings stay separate. `summary.json` records scan coverage and-whether matching finished. `report.md` links to the component reports.-These combined files are a project summary, not a new sealed scan. Use the-individual scan folders with `export` and `publish`.--The output directory must be empty and outside the project. Failed components-do not stop the others. The command saves the available results and exits with-code `2` if a component fails, coverage is incomplete, or cross-component-matching fails. `--max-cost` applies to each component scan, not planning,-cross-component matching, or the whole project. `--model` and `--effort` also-apply to matching. `--knowledge-base`,-`--scan-prompt-file`, and `--post-scan-prompt-file` work as they do for bulk scans.+Automatic planning respects Git ignore rules and groups omitted files under+`Other files`. Each proposed path must contain an inventoried file. Planning+leaves source files unchanged.++Each component saves artifacts under `component-N/`. Combined `findings.json`+merges high-confidence root-cause matches, keeping the highest severity and+original IDs. Uncertain matches stay separate. `summary.json` records coverage+and matching status; `report.md` links to component reports. Export and publish+from the individual scan folders, not the combined summary.++Use an empty output directory outside the project. Failed components don't+stop others, but failures, incomplete coverage, or failed matching exit with+`2`. Retry failed or incomplete components with+`--components-file retry-components.json` and a new output directory.++`--max-cost` applies per component, excluding planning and matching.+`--model` and `--effort` also apply to matching; `--auth` applies throughout.+Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for+bulk scans.++From TypeScript, use `runComponentScans({ repository, outputDir, components })`.+Use `auto: true` for planning, `planOnly: true` to save the plan without scans,+and `scanOptions.auth` to select credentials.### Configure deep scans-For `scan --mode deep`, `--workers` limits concurrent discovery workers,-`--subagents` controls each worker's subagents, `--stop-after-no-new` stops after-that many runs find no new issues, `--max-discovery-runs` limits total runs, and-`--max-time-hours` limits discovery duration. These options are also available-on SDK scans:+For `scan --mode deep`, `--workers` sets discovery concurrency and `--subagents`+sets subagents per worker. `--stop-after-no-new` stops after that many runs+without new issues. `--max-discovery-runs` and `--max-time-hours` cap discovery+runs and duration. SDK equivalents:```tsawait security.run("/path/to/repository", {@@ -517,73 +385,33 @@ await security.run("/path/to/repository", {});```-Set defaults in `~/.codex/codex-security/config.toml`, or under `$CODEX_HOME`-when it is configured. Explicit CLI and SDK settings override these defaults:+Set defaults in `$CODEX_HOME/codex-security/config.toml`:```toml[deep_scan]-workers = 2-subagents = 0-stop_after_no_new = 3-max_discovery_runs = 10-max_time_hours = 1.5+workers = 4+subagents = 3+stop_after_no_new = 4+stop_after_consecutive_errors = 3+max_discovery_runs = 40+max_time_hours = 96```-The discovery deadline defaults to 96 hours. The configured value may be any-positive number, including fractional hours, up to 96. At the deadline,-in-flight discovery stops and completed findings are reduced and returned.-The 97-hour outer tool-call timeout reserves approximately one hour for final-reduction and result delivery, including at the 96-hour maximum.+CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`+in the file; `--codex` cannot configure this section. Worker and run counts must+be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means+four workers. Unknown keys are rejected.++`max_time_hours` accepts positive values up to 96, including fractional hours.+At the deadline, discovery stops; the scan combines and returns completed findings.`scan --workers` controls discovery workers within one deep scan;`bulk-scan --workers` controls how many repositories are scanned concurrently.-On macOS/Linux, an existing output directory must be private to the current-user (`chmod 700`).--If the output directory already contains results, add `--archive-existing`.-The CLI moves them to `<output-dir>.previous-<timestamp>-<id>` and starts the-scan in a new, empty directory at the original path. Add `--dry-run` to see-the destination without moving files.--Scans are report-only by default. Use `--fail-on-severity` in CI to exit 1 when-a completed scan contains a finding at or above the selected severity.-Incomplete coverage and CLI/runtime errors exit 2 so they cannot be mistaken-for a passing policy. Incomplete scans still write the available human or JSON-result to stdout and a coverage warning to stderr, including in report-only-mode.--Use `--patch` to fix and verify confirmed findings after a complete scan.-`--patch-severity high` selects high and critical findings; the default is low-and above. After showing the findings summary, interactive scans with findings-ask whether to open a color-coded finding browser with complete finding details-and a separate patch-instructions panel. Use the arrow keys to-browse, `Tab` to inspect details, `Space` to select individual findings, `i` to-edit instructions for the focused finding, `1`–`4` to select by severity, and-`r` to optionally create a draft GitHub pull request after patching. Press-`Enter` to patch or `q` to keep the checkout unchanged. Each selected finding-runs in its own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a-saved-finding `patch` command to commit only verified patch files and open a-draft pull request with `gh`. If the push or pull request fails, run the printed-`patch --resume-pr BRANCH` command from the same repository. It uses the saved-commit without running Codex again and refuses to publish if the branch changed.-JSON scan results include `patchSeverity`. Scan and-saved-finding results include one `patches` entry per selected finding with-status `verified`, `no_change`, `blocked`, or `failed`, plus `pullRequest` when-one is created. When `--fail-on-severity` is also set, verified and already-fixed-findings no longer fail the policy.--Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. OpenAI is-the implied provider. Use `--model gpt-5.6-terra` to switch models and-`--effort minimal|low|medium|high|xhigh|max` to set reasoning effort. Repeat-`--codex KEY=VALUE` for other Codex settings; existing-`--codex 'model_reasoning_effort="high"'` overrides remain supported.-### Runtime configuration and worker limits-The standalone CLI and SDK do not load an unrelated user or repository Codex-configuration. Each scan starts with a private runtime and these Codex-defaults:+Scans use these isolated Codex defaults instead of your user or repository+configuration:```tomlapproval_policy = "on-request"@@ -606,9 +434,8 @@ max_concurrent_threads_per_session = 9sandbox = "unelevated"```-Use `--model` and `--effort` for model selection. Repeat-`--codex KEY=VALUE` to deep-merge other TOML values into this isolated-configuration:+Use `--model` to choose a model and `--effort minimal|low|medium|high|xhigh|max`+for reasoning effort. Repeat `--codex KEY=VALUE` for other TOML settings:```bashnpx @openai/codex-security scan . \@@ -617,10 +444,8 @@ npx @openai/codex-security scan . \--codex features.multi_agent_v2.max_concurrent_threads_per_session=4```-The session thread limit includes the parent agent: the default of `9`-provides up to eight delegated worker slots. This limit is separate from-`bulk-scan --workers`, which controls how many repositories run concurrently.-A configured limit is a maximum, not evidence that every worker started.+The thread limit of `9` includes the parent and up to eight delegated workers.+It is separate from deep-scan and bulk-scan worker counts.Quote string values as TOML, for example`--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and@@ -628,280 +453,99 @@ Quote string values as TOML, for example`--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys arerejected.-Plugin and marketplace loading belong to Codex Security. Overrides of-`plugins`, `marketplaces`, or `features.plugins`, including profile-specific-plugin overrides, are rejected; choose `--plugin-path` instead. Native-multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting-and `features.multi_agent_v2.enabled=false` are incompatible and rejected.-`validate` and `patch` accept `--effort` and only the `model` and-`model_reasoning_effort` `--codex` keys; they do not accept general scan-runtime overrides.+Choose plugins with `--plugin-path`. Overrides of `plugins`, `marketplaces`,+or `features.plugins` are rejected, including in profiles. Multi-agent v2 must+stay enabled: `agents.max_threads` and+`features.multi_agent_v2.enabled=false` are rejected.-These overrides cannot replace the scanner-owned approval reviewer or-filesystem profile. Use `--codex 'approval_policy="never"'` to deny approval-requests instead of reviewing them automatically. See-[Local security model](#local-security-model).+`validate` and `patch` accept `--effort` and the `model` and+`model_reasoning_effort` keys in `--codex`, but no other runtime overrides.-### Deep-scan engine configuration+See [Local security model](#local-security-model) for approval and filesystem+restrictions.-Deep scans read `$CODEX_HOME/codex-security/config.toml`, defaulting to-`~/.codex/codex-security/config.toml`:+### Environment variables-```toml-[deep_scan]-workers = 4-subagents = 3-stop_after_no_new = 4-stop_after_consecutive_errors = 3-max_discovery_runs = 40-max_time_hours = 96-```+| Variable | Effect |+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |+| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |+| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |+| `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |+| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |+| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |+| `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |+| `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |+| `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |+| `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |+| `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |+| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |+| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |+| `CI` | Disables interactive update notices. |+| `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |++Custom Codex executables need thread source attribution for `exec` and+`app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;+command shims such as `codex.cmd` fall back to the bundled executable.++Python lookup order: `--python` (on `scan`, `bulk-scan`, or `export`) or SDK+`pythonPath`, then `PYTHON`, the managed Codex runtime, and `python3` or `python`+on `PATH` (`py` also works on Windows). `CODEX_SECURITY_STATE_DIR` overrides+`CODEX_HOME` for state storage. Keep state and results outside the repository.++### Progress and cost++Interactive scans show full-screen progress; CI, redirected output, and+`--headless` use plain status lines. Results go to stdout, progress and+diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for+sensitive information before sharing them.++JSON results, scan history, and bulk-scan receipts record the model, tokens,+and estimated cost. Estimates use+[standard API token prices](https://developers.openai.com/api/docs/models/compare),+including cached input and cache writes, but exclude fees and surcharges.-The default is four discovery workers; the legacy `workers = "auto"` setting-also resolves to four. Set `workers` to a positive integer to choose an explicit-count. `subagents` must be a nonnegative integer;-`stop_after_no_new`, `stop_after_consecutive_errors`, and `max_discovery_runs`-must be positive integers. `max_time_hours` must be a positive finite number no-greater than 96; fractional hours are supported. Unknown `[deep_scan]` keys are-rejected.+`--max-cost USD` stops the scan and its workers when estimated cost exceeds+the limit, though in-flight requests can finish above it. If deep-scan+discovery has finished, the scan returns a sealed partial report without more+model calls and lists unvalidated candidates as follow-up work. Bulk scans+apply the limit per repository attempt.-These settings are separate from Codex's-`features.multi_agent_v2.max_concurrent_threads_per_session` and-`bulk-scan --workers`. Standalone CLI and SDK scans create an isolated-`CODEX_HOME`, import the ambient `[deep_scan]` configuration, and apply explicit-CLI or SDK options on top. Set `stop_after_consecutive_errors` in the-configuration file. Use `--codex` to adjust the Codex session thread limit, not-to set `[deep_scan]` values.+### Bulk scans-### Environment variables+Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select+GitHub repositories pushed in the last 90 days. Forks and archived repositories+are excluded; private checkouts use your GitHub CLI sign-in. The command asks+for an output directory and saves your selection there as `repositories.csv`.+`--output-dir` requires CSV input.-The CLI and SDK recognize the following user-configurable environment:--| Variable | Effect |-| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |-| `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |-| `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default Linear team and project for completed-scan publication. |-| `CODEX_SECURITY_LINEAR_API_KEY` | Patch Linear issues or publish directly with a personal API key. |-| `CODEX_SECURITY_LOG_LEVEL` | CLI-only; set to `debug` for verbose diagnostics. |-| `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |-| `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |-| `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |-| `CODEX_CLI_PATH` | Use another Codex executable for authentication, plugin setup, scans, and nested workers. |-| `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |-| `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |-| `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |-| `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |-| `CI` | Disable interactive update notices in automated environments. |-| `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |--Custom Codex executables must support thread source attribution for both `exec`-and `app-server` requests (Codex 0.149.1 or later).--On Windows, `CODEX_CLI_PATH` must name a native `.exe` or `.com`. Command-shims such as `codex.cmd` automatically use the bundled Codex executable-instead.--Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,-the managed Codex runtime, and finally `python3` or `python` from `PATH` (`py`-is also supported on Windows).-`CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both-state and result paths outside the scanned repository.--The repository's Docker Compose workflow additionally recognizes-`CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,-`CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for-its image, runtime user, seccomp profile, input, results, and state mounts.-Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and-`CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.-These container settings are distinct from standalone CLI flags and-interactive discovery's `GH_HOST`.--Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,-`CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and-`CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are-internal runtime data, not supported user configuration.--Use `--provider openrouter` to send inference through OpenRouter. Set-`OPENROUTER_API_KEY` and specify a supported model with `--model`.--Use `--provider fireworks` to send inference through Fireworks AI. Set-`FIREWORKS_API_KEY` and specify a supported model with `--model`.--Use `--provider amazon-bedrock` to send inference through Amazon Bedrock. Set-`AWS_REGION` and authenticate with `AWS_BEARER_TOKEN_BEDROCK`, standard AWS-access keys, an AWS profile, web identity, container credentials, or the-default AWS credential chain. Specify a supported Bedrock model with `--model`;-OpenAI Bedrock models such as `openai.gpt-5.6-luna` support `--max-cost`.--Scan progress identifies the requested paths and reports actual ranking,-file-review, validation, and attack-path phases as they become available.-Interactive terminals show a full-screen view; CI, redirected output, and-`--headless` use plain timestamped progress lines.-Completion summarizes findings, severity, coverage, elapsed time, available-token and worker counts, estimated cost, the results directory, and the next-useful command.-Progress and summaries use stderr; structured scan results remain on stdout.--Add `--verbose` or set `CODEX_SECURITY_LOG_LEVEL=debug` to print-lifecycle, authentication, progress, and cost diagnostics to stderr.-`LOG_LEVEL=debug` is used only when `CODEX_SECURITY_LOG_LEVEL` is unset.-Structured JSON results remain on stdout. Review sensitive verbose logs before-sharing them. The normal activity feed hides credentials.--Each scan records its model, tokens, and estimated cost in its JSON result,-scan history, and bulk-scan receipt. Estimates use-[standard API token prices](https://developers.openai.com/api/docs/models/compare),-including cached input and cache writes; fees and surcharges are not included.--Use `--max-cost USD` to stop a scan, including its delegated workers, when its-running cost exceeds the limit. If a Deep Scan has already finished discovery,-it returns a sealed partial report with any completed findings and lists-unvalidated candidates as follow-up work. Requests already in progress can-finish above the limit; preparing the partial report makes no additional model-requests. Incomplete coverage retains its existing exit code.-For `bulk-scan`, the limit applies separately to each repository attempt.--Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`-for the complete CLI references.--Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover-GitHub repositories pushed in the last 90 days. Archived-repositories and forks are excluded. Search the repository list, select the-repositories to scan, and confirm before scanning.-Private checkouts reuse your GitHub CLI sign-in without changing your global Git-configuration. The selected repositories are saved to-`<output-dir>/repositories.csv` for review or resumption.--Interactive discovery accepts the same `--workers`, `--mode`, `--max-attempts`,-`--model`, `--effort`, `--plugin-path`, `--python`, and `--codex` settings as-CSV-driven scans. It prompts for the output directory; `--output-dir` is only-valid when a repository CSV is supplied.--To use an existing repository list or run in CI, pass a CSV with required `id`,-`repository`, and `revision` columns. Revisions must be full commit hashes;-optional `scope`, `mode`, and `prompt` columns customize individual scans:+For CI or an existing repository list, pass a CSV with `id`, `repository`, and+`revision` (full commit hash). Optional `scope`, `mode`, and `prompt` columns+customize each scan:```csvid,repository,revision,scope,mode,promptservice,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Focus on authentication and authorization.```-Use `--scan-prompt-file PATH` to add instructions to a scan or every bulk scan.-Bulk scans append each repository's CSV `prompt` after the shared instructions.-Use `--post-scan-prompt-file PATH` to run a follow-up in the same authenticated-session after each scan, including incomplete or failed scans. Canceled scans-and scans stopped at their configured cost limit do not start another turn.--`--workers` sets the number of concurrent repository scans and defaults to-`4`. `--max-attempts` sets how many times each pending repository can run per-invocation and defaults to `1`. Results remain under `--output-dir`; rerun the-same command to resume.--### Publish findings to Cloud--Choose completed scans from your local history:--```bash-npx @openai/codex-security publish scan --to cloud --dry-run --json-```--The picker shows each scan's repository, finding count, age, and scan ID.-Press <kbd>Space</kbd> to select or deselect scans, then press-<kbd>Enter</kbd> to submit. At least one scan is required, and no scans are-selected automatically.--For scripts, repeat `--scan` with saved scan IDs or unique ID prefixes (at-least eight characters):--```bash-npx @openai/codex-security publish scan \- --scan SCAN_ID_A --scan SCAN_ID_B \- --to cloud --dry-run --json-```--Use `scans list --json` to find IDs for the current repository. `--scan latest`-selects its latest completed scan. The CLI resolves IDs through saved history,-processes each selected scan once, and checks that its sealed artifacts match-the selected ID. Picker selections use the order shown; repeated `--scan`-selections use argument order. The artifacts must still be available locally.--`--dry-run` validates the scans and prints their findings without uploading or-requiring a login. Remove `--dry-run` to upload. Live uploads require ChatGPT-credentials explicitly stored in a file. Set this in your Codex `config.toml`,-then sign in with ChatGPT again:--```toml-cli_auth_credentials_store = "file"-```--Automatic and keyring credential storage are not accepted for Cloud-publication, even when an `auth.json` file exists, because that file may be-stale and belong to a different account. The CLI sends one scan at a time,-with each scan's findings and metadata in a separate request.--To publish findings from a CSV instead of a completed scan, pass the CSV-created by `codex-security export --export-format csv`:-```bash-npx @openai/codex-security publish scan --to cloud \- --csv /path/outside/repository/findings.csv+npx @openai/codex-security bulk-scan repositories.csv \+ --output-dir /path/outside/repositories/security-scans --workers 4```-The repository includes a header-only-[findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)-that you can copy and fill in before publishing.--The CSV must have the export columns `occurrence_id`, `finding_id`, `title`,-`summary`, `severity`, `confidence`, `status`, `close_reason`, `note`,-`remediation`, `path`, `start_line`, and `end_line`. Deep-scan exports may also-include `candidate_id`. Use `--dry-run --json` to validate the CSV and inspect-the normalized findings locally without a login or network request.--`--csv` is only supported with `--to cloud` and cannot be combined with a scan-directory, `--scan-dir`, or `--scan`.--For artifacts outside local history, use repeated `--scan-dir PATH` instead.-A single positional directory is still accepted and can be combined with-`--scan-dir`. Do not combine directory inputs with `--scan`. Each directory-must contain one completed, sealed scan; bulk-run directories and-`results.jsonl` files are not accepted. Relative paths start at the current-directory, and `~/...` starts at your home directory. Each resolved directory-is processed once.--For multiple distinct scans, output contains:--- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.-- `failed`: errors with `scanDir` and, for saved selections, `scanId`.-- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command- did not reach before cancellation.--For one distinct scan, the CLI returns the scan result directly,-without the batch fields above.+`--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each+repository's CSV `prompt` follows the shared instructions.+`--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,+even after a failed or incomplete scan, but not after cancellation or a+cost-limit stop.-The CLI continues after a failed scan and exits with code `2` if any scan-fails. Ctrl-C or SIGTERM stops new requests and returns the results collected-so far. When cancellation stops work before every requested publication is-confirmed, the exit code is `130` for Ctrl-C and `143` for SIGTERM. If the-single response or final batch response has already confirmed the complete-publication, the command exits with code `0`. Cloud publication receipts-appear in command output; the CLI does not save them to scan history.--A successful receipt contains one opaque Cloud finding ID for each submitted-finding, in request order. These are not local finding IDs. The CLI verifies-the authenticated response status, count, and ID uniqueness, but cannot map-opaque server IDs back to individual local findings independently.--The CLI never retries an upload automatically. An upload with a missing or-invalid receipt may already have been accepted. Check whether Cloud accepted-that scan before retrying it. Do not resend scans with confirmed receipts.+`--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending+repository per invocation. Rerun the command to resume; `bulk-scan --help`+lists all options.### Custom validation-Use a prompt file to replace the final validation step in a standard or diff-scan. The ordinary source review still runs. The supplied text goes directly-into a separate validation turn and is not sent to discovery workers.-The SDK adapts the bundled discovery workflow without changing the plugin.-An incompatible plugin workflow stops the scan instead of using default validation.+Replace the final validation step of a standard or diff scan with a prompt+file. Source review still runs; discovery workers do not receive this prompt.```bashnpx @openai/codex-security scan . --validation-prompt-file validation.md@@ -916,10 +560,10 @@ const result = await security.run(repository, {});```-Describe setup, allowed test targets, expected evidence, and cleanup in the-prompt. Refer to credentials through environment variables; do not put secrets-in the prompt or validation output. There are no separate setup or teardown-hooks. Deep scans reject this option. Empty candidate sets skip the custom turn.+Put setup, allowed targets, required evidence, and cleanup in the prompt.+There are no separate setup or teardown hooks. Use environment variables for+credentials; keep secrets out of prompts and validation output. Deep scans+reject this option; scans without candidates skip it.The SDK supplies the candidate IDs and requires a `CustomValidationResult`:@@ -948,63 +592,106 @@ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:}```-Each candidate needs exactly one result. The disposition is `reportable`,-`suppressed`, `not_applicable`, or `deferred`. Optional assessment changes use-`{ "level": "medium", "rationale": "..." }` in `severity` or `impact`; use-`null` to retain the original assessment. Finding identity and source locations-do not change. Deferred candidates make coverage partial. Suppressed and-deferred candidates remain in the saved validation artifacts.+Return one result per candidate with disposition `reportable`, `suppressed`,+`not_applicable`, or `deferred`. Set `severity` or `impact` to+`{ "level": "medium", "rationale": "..." }` to revise an assessment, or `null`+to retain it. Identity and source locations stay unchanged.-The scan directory contains `artifacts/custom-validation/candidates.json` and-`results.json`. Setup failure, incomplete output, or invalid output leaves the-scan incomplete. There is no automatic fallback to default validation. When-rerunning a saved custom-validation scan, supply-`scans rerun SCAN_ID --validation-prompt-file validation.md` again.+The scan saves candidates and results, including suppressed and deferred+cases, under `artifacts/custom-validation/`. Coverage is incomplete if setup+fails, output is incomplete or invalid, or any candidate is deferred. An+incompatible plugin stops the scan; validation never falls back to the default.+Repeat `--validation-prompt-file` on reruns.-### Publish completed scans to Linear+### Publish findings to Cloud-Publish every finding from a completed standard, deep, or scoped scan to one-Linear team:+Choose completed scans from local history:```bash-npx @openai/codex-security publish scan --scan SCAN_ID \- --to linear \- --linear-team TEAM_ID+npx @openai/codex-security publish scan --to cloud --dry-run --json```-Linear accepts one scan. Use a saved scan ID, a unique ID prefix, or `latest`.-For external artifacts, a positional directory or `--scan-dir PATH` is also-accepted.+Press Space to select scans, then Enter to submit. Nothing is preselected.-Add `--linear-project PROJECT_ID` to place the issues in a Linear project.-The existing `--project` flag remains an alias. Without a project, issues are-created directly in the selected team.--To choose from all completed scans saved in your local scan history, omit the-scan selector. The selector highlights each repository and shows its finding-count, relative run time, and abbreviated scan ID:+For scripts, repeat `--scan` with saved IDs or unique prefixes of at least+eight characters:```bashnpx @openai/codex-security publish scan \+ --scan SCAN_ID_A --scan SCAN_ID_B \+ --to cloud --dry-run --json+```++Find IDs with `scans list --json`, or use `--scan latest` for the current+repository's latest completed scan. You still need the local sealed artifacts.++`--dry-run` checks inputs and prints findings without logging in or uploading.+Uploads need ChatGPT credentials saved to a file. Set this in Codex+`config.toml`, then sign in with ChatGPT again:++```toml+cli_auth_credentials_store = "file"+```++Cloud publication rejects automatic and keyring storage, even if an+`auth.json` file exists: the file may be stale or belong to another account.++For CSV input, use an export from `codex-security export --export-format csv`:++```bash+npx @openai/codex-security publish scan --to cloud \+ --csv /path/outside/repository/findings.csv+```++The [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)+has the required columns; deep-scan exports may add `candidate_id`. `--csv`+only supports Cloud and cannot be combined with scan IDs or directories.++For artifacts outside local history, pass a directory or repeat `--scan-dir PATH`.+Each directory must contain one completed, sealed scan. Bulk-run directories+and `results.jsonl` files aren't accepted. Don't mix directories with `--scan`.++Multiple scans return:++- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.+- `failed`: errors with `scanDir` and, for saved selections, `scanId`.+- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command+ did not reach before cancellation.++One scan returns its result directly. Uploads run sequentially. A failed upload+doesn't stop the rest, but the command exits with `2` if any failed. Cancellation+stops new requests and returns results so far with `130` (Ctrl-C) or `143`+(SIGTERM), unless all publications were already confirmed.++Save the output: Cloud receipts aren't stored in scan history. They contain+Cloud finding IDs in request order, not local IDs. Uploads aren't retried+automatically. Cloud may have accepted an upload even if its receipt is missing+or invalid. Check Cloud before retrying; never resend a scan with a confirmed+receipt.++### Publish completed scans to Linear++Linear publication accepts one completed scan:++```bash+npx @openai/codex-security publish scan --scan SCAN_ID \--to linear \--linear-team TEAM_ID```-Destination flags take precedence over `CODEX_SECURITY_LINEAR_TEAM` and the-optional `CODEX_SECURITY_LINEAR_PROJECT`. Use `--dry-run` to preview the issue-titles without creating them, or `--json` to return structured publication-results.-Interactive publication shows a full-screen activity view with live Codex-output and issue-creation progress. Other terminals receive plain progress on-stderr, so `--json` output remains machine-readable.+Choose a scan by ID, unique prefix, `latest`, or directory (positional or+`--scan-dir PATH`). Omit the selector for an interactive picker. Live publication+and `--skip-existing` require the scan in local history; a directory-based+`--dry-run` alone does not.-By default, publishing starts Codex with your existing Codex configuration and-connected Linear app. Sign in to Codex and connect Linear before publishing in-this mode. No separate Linear API token is required, and publication does not-use the isolated Codex home created for security scans.+Add `--linear-project PROJECT_ID` (`--project` is an alias) to place issues in+a project. Destination flags override `CODEX_SECURITY_LINEAR_TEAM` and+`CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run` previews issue titles without+contacting Linear; `--json` returns structured results.-To publish directly through the Linear API without starting Codex, configure a-Linear personal API key:+Sign in to Codex and connect Linear to publish with your existing Codex+configuration; publication doesn't use the isolated scan home. To use the+Linear API directly, set a personal API key:```bashexport CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY@@ -1013,73 +700,36 @@ npx @openai/codex-security publish scan /path/to/completed-scan \--linear-team TEAM_ID```-Direct API publication leaves issues unassigned by default. Pass-`--linear-assignee [email protected]` or `--linear-assignee USER_ID` to-assign the issues to a Linear user by email address or user ID.-`--linear-assignee` requires direct API publication.--You can also pass `--linear-api-key KEY`, which takes precedence over-`CODEX_SECURITY_LINEAR_API_KEY`. Prefer the environment variable to avoid-exposing your API key in shell history and process listings. API keys are not-added to successful publication results, scan history, or sealed scan artifacts.-Error messages are preserved as returned. `--dry-run` never contacts Linear in-either mode.+Direct API publication leaves issues unassigned unless `--linear-assignee`+specifies a user ID or email. `--linear-api-key KEY` overrides the environment+variable, but exposes the key in shell history and process listings. Keys are+omitted from saved results and artifacts; error messages are returned unchanged.-Use `publish check` to verify that the completed scan and its findings match-local history, and to see which findings already have recorded Linear issues:+Check scan integrity and recorded publications before publishing:```bashnpx @openai/codex-security publish check /path/to/completed-scan \--to linear --linear-team TEAM_ID --json```-The check does not create issues, migrate scan history, or change sealed scan-artifacts. With a Linear API key, it also makes read-only authentication, team,-optional project, and assignee checks. Without a key, connected-app access is-reported as `not-checked`. Issue-creation permission is always `not-tested`;-successful read access does not prove write permission.--Each finding creates a separate new issue titled-`[Codex Security][HIGH] Finding title`. The issue includes the scan ID,-repository, scanned scope, source locations and code snippets, severity,-confidence, vulnerability classification, summary, and remediation guidance.-Verified immutable Git revisions include source links. Findings are published-concurrently in batches of up to 20. Successful issue identifiers are linked-to their findings in the local scan-history database, and structured results-are read back from that database rather than generated by Codex. The completed-scan must already exist in the local scan history. By default, running-publication again creates another set of issues for the same scan. Add-`--skip-existing` to skip findings with a recorded issue for the exact scan-occurrence, team, and optional project. Combine it with `--dry-run` to preview-only the remaining findings. Results distinguish newly `created` issues from-previously recorded `skipped` issues.--This option uses local publication history; it does not search, update, or-verify the continued existence of remote issues. Recover any retained handoff-from an interrupted or uncertain publication before retrying. Concurrent-publishers and remote creations that were never recorded can still create-duplicates.--Issue descriptions contain source code and vulnerability details. Select a-Linear destination authorized to receive that information. Publication receipts-are stored separately from the sealed scan artifacts.--Before recording a connected-app publication, Codex Security verifies the exact-mutation arguments and reconciles every recognized issue identifier and-non-empty URL in the connector result with its durable handoff. If those claims-conflict, or a completed mutation cannot be verified, publication exits with an-indeterminate recovery error. The private handoff, connector-event evidence,-and partial receipts remain in local state; independently verified sibling-issues may already be recorded in scan history.--Do not immediately rerun an indeterminate publication. Inspect the retained-evidence and the selected Linear destination, reconcile every issue that may-already have been created, and retry only after confirming that no unrecorded-issue would be duplicated. Publication does not perform a fresh remote readback-or recover unrecorded remote creations. The opt-in `--skip-existing` behavior-only skips issues already recorded in local history.--You can also publish a scan from TypeScript:+`publish check` is read-only. With an API key it also checks authentication,+team, project, and assignee access; connected-app access is `not-checked`.+Issue-creation permission is always `not-tested`.++Each finding becomes an issue titled `[Codex Security][HIGH] Finding title`+with source locations, code, evidence, and remediation. Choose a destination+authorized to receive these details. Local history stores successful issue IDs+separately from sealed scan artifacts.++Republishing creates duplicates by default. `--skip-existing` skips recorded+successes for the same occurrence, team, and project, without checking remote+issues. Results distinguish `created` and `skipped` issues. Add `--dry-run`+to preview the remaining findings.++After an interrupted or indeterminate publication, check the retained handoff,+evidence, and Linear destination before retrying. Issues may exist without a+local record. The CLI can't recover those issues, and `--skip-existing` can't+prevent duplicates from them or concurrent publications.```tsimport { publishScan } from "@openai/codex-security";@@ -1087,105 +737,57 @@ import { publishScan } from "@openai/codex-security";const publication = await publishScan("/path/to/completed-scan", {destination: "linear",teamId: "TEAM_ID",- onProgress: (progress) => {- if (progress.type === "handoff_recorded") {- console.error("Saved mutation result", progress.recorded);- } else if (progress.type === "issue_completed") {- console.error(- `Processed ${progress.completed} of ${progress.total} findings.`,- );- }- },});console.log(publication.scanId);console.log(publication.created.length);```-Add `projectId: "PROJECT_ID"` to the options to publish into a specific Linear-project instead of directly to the team. Pass `skipExisting: true` to skip-recorded successes, or import `checkScanPublication` and call it with the same-destination options for a read-only preflight.--Pass `linearApiKey` to publish directly through the Linear API. Omit-`assigneeId` to leave issues unassigned, or supply a Linear user ID or email-address to select an assignee:--```ts-const directPublication = await publishScan("/path/to/completed-scan", {- destination: "linear",- teamId: "TEAM_ID",- linearApiKey: process.env["CODEX_SECURITY_LINEAR_API_KEY"],- assigneeId: "[email protected]",-});-```+Options include `projectId`, `skipExisting`, `linearApiKey` for direct API+publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts+the same destination options for a read-only check.### Scan history and reruns-`scans` or `scans list` lists scans for the current repository. Pass a repository-path to inspect another checkout, or `--scan-root DIR` to list scans whose-artifacts are under a particular root. `scans show` opens the latest completed-scan for the current repository. Pass `SCAN_ID` to inspect another scan. Scan-details include the configuration, results, coverage, and artifact locations. Add-`--show-linked-findings` to include finding links from previous scans.--`scans logs` shows session events from the latest scan, including an active scan.-Pass `SCAN_ID` to select another scan. During a scan, press `d` for live details.-Filter with `a` for all sources, `m` for the main scan, or `1`–`9` for a worker.-Logs and live details can contain source code and credentials.--Every scan history command accepts a full scan ID or a unique prefix of at-least eight characters.--Scan history uses `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3` when-`CODEX_SECURITY_STATE_DIR` is set. Otherwise, it uses-`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`; `CODEX_HOME`-defaults to `~/.codex`. Scan credentials are never stored in the scan-configuration. Recorded failure summaries and bulk-scan receipts omit messages-that contain recognizable credentials.--The scan sandbox permits writes to the selected state directory so SQLite can-maintain its database and journal files. If the host itself cannot write to the-default directory, select a writable directory outside the scanned repository:--```bash-export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state-```--`findings` or `findings list` lists open findings for the current repository.-Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as a-false positive and explain why. Later scans dismiss a matching finding only when-the same reason still applies.--`scans rerun` repeats the latest completed scan against the current checkout.-Pass `SCAN_ID` to rerun another scan.--`scans match BEFORE_SCAN_ID AFTER_SCAN_ID` links findings with the same root-cause; `scans match --all` matches all completed scans of the current repository,-including other worktrees and clones. Saved matches appear in `scans show` and-are reused unless `--force` is passed. Scans without sealed artifacts are skipped.--`scans compare` compares the two latest completed scans. Pass one scan ID to-compare it with the latest completed scan, or two IDs to select both scans. It-matches findings by root cause, reuses saved matches, and reports findings as-new, persisting, reopened, resolved, or unknown. Missing findings are not-treated as resolved when the later scan is incomplete or does not cover their-original scope.--The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery-and structured output. Inspect the command manifest with `--llms`, inspect a-command schema with `scan --schema --format json`, register the CLI as an MCP-server with `mcp add`, sync agent skills with `skills add`, or generate shell-completions with `completions bash|zsh|fish`. 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, bulk repository scans,-authentication, imports, exports, validation, and patching remain CLI-only because the-MCP transport cannot cancel active scans.--For CI, save machine-readable output outside the checked-out repository and-apply a severity policy. Incomplete coverage and runtime errors still exit-nonzero:+Commands default to the current repository. Select scans by full ID or a+unique prefix of at least eight characters.++| Command | Purpose |+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |+| `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |+| `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |+| `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |+| `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |+| `scans match BEFORE AFTER` | Link findings with the same root cause. |+| `scans match --all` | Match completed scans across the repository's worktrees and clones. |+| `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to the latest two completed scans. |+| `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |+| `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |++Matching requires sealed artifacts and reuses saved matches unless you pass+`--force`. Comparisons classify findings as new, persisting, reopened, resolved,+or unknown. Missing findings aren't resolved if the later scan is incomplete+or excludes their original scope. With one ID, `scans compare` compares it+to the latest completed scan.++History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or+`$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Keep this directory+writable and outside the scanned repository. Scan configurations don't store+credentials; session logs and live details can contain them. Press `d` during+a scan for details, then `a` for all sources, `m` for the main scan, or+`1` through `9` for a worker.++### Exports and CI++`export` writes CSV, JSON, or SARIF from a completed, sealed scan, defaulting to+the current repository's latest completed scan. It doesn't start Codex or load+credentials. Use `--output -` for stdout and `--source-root PATH` to add SARIF+source-line fingerprints. `export --help` lists all options.++JSON preserves the sealed findings document. CSV marks findings as open,+omits local triage state, and cannot go to stdout when JSON output is requested.++For CI, save output outside the checkout and set a severity threshold:```bashSCAN_ROOT="$(mktemp -d)"@@ -1196,27 +798,23 @@ npx @openai/codex-security scan . \--fail-on-severity high > "$SCAN_ROOT/findings.json"```-JSON scans never use interactive terminal controls, even when stderr is a TTY.-Saved-finding patch commands support `--json`; literal issue and file patch-commands do not. The `validate`, `login`, and `logout` commands reject `--json`.-Sign-in commands remain interactive. CSV exports cannot be written to stdout-while JSON output is requested.--Use `export` to create CSV, JSON, or SARIF from a completed, sealed scan without-starting Codex or loading credentials. Without a scan directory, it exports the-latest completed scan for the current repository. JSON preserves the sealed findings-document. CSV uses the portable findings columns, marks findings as open, and-does not include local workbench triage state. The exporter validates the seal-before writing, accepts `--output -` for stdout, and can use-`--source-root /path/to/repository` with SARIF to add source-line fingerprints.-Run `npx @openai/codex-security export --help` for all export options.--Use `import github OWNER/REPO` to read existing code scanning alerts for-validation. It defaults to all open alerts on the default branch.-`--github-alert NUMBER` selects exact alerts and can be repeated;-`--github-state open|closed|dismissed|fixed|all` filters lists;-`--github-ref REF` selects a reference. See the [SDK import options](#import-github-code-scanning-alerts)-for authentication and selector behavior.+Scan exit codes are `0` for a completed report-only scan or passing policy,+`1` for a policy violation, `2` for invalid input, incomplete coverage, or a+runtime/export error, `130` for interruption, and `143` for termination.+JSON scans do not use interactive controls. `validate`, `login`, and `logout`+reject `--json`.++`install-hook` scans staged and unstaged changes before each commit. It blocks+on high-severity findings or failed scans, respects `core.hooksPath`, and leaves+existing hooks alone. Change the threshold with `--fail-on-severity`.++### Import alerts from the CLI++`import github OWNER/REPO` reads open code scanning alerts from the default+branch. Repeat `--github-alert NUMBER` for exact alerts. Filter with+`--github-state open|closed|dismissed|fixed|all` or select a reference with+`--github-ref REF`. Authentication follows the+[SDK import options](#import-github-code-scanning-alerts).```bash# Import all open alerts, or a selected subset, as complete JSON.@@ -1228,87 +826,75 @@ npx @openai/codex-security import github example/repository \npx @openai/codex-security validate /path/outside/repository/github-alerts.json```-`--json` aliases `--format json`; output is an alert array (`[]` when empty).-Avoid output-filtering or token-limiting flags when saving validation inputs.-Import is read-only; `validate` assesses the saved content separately. Use the-SDK loop above for a structured disposition per alert.--Use `validate` to run the bundled validation skill on candidate findings and-`patch` to run the bundled fix-finding skill on security issues. Each positional-input can be either a file, whose contents are read into the request, or literal-text. These inputs operate on the current directory. Pass a saved finding or-occurrence ID instead to patch its original repository, or use-`patch --scan SCAN_ID --severity high` for high and critical findings from one-scan. `--scan latest` selects the most recent scan of the current repository.-Saved-finding patch commands accept `--json` and return a verified, already-fixed, blocked, or failed result for each finding. Both commands use the scan-model and reasoning defaults and disable plugins. Patching starts a separate-saved task in the Codex desktop app for each finding. Override the model with-`--codex 'model="gpt-5.6-sol"'` and the-reasoning effort with `--effort high` or-`--codex 'model_reasoning_effort="high"'`.--Use `patch --linear-issue ISSUE` to import a Linear issue by identifier or URL.-Repeat `--linear-issue` to include more issues. Use-`patch --linear-project "PROJECT"` to patch every open issue in a project. Add-`--linear-filter '{"labels":{"name":{"eq":"security"}}}'` to apply a native-Linear issue filter on the server. Completed and canceled issues are excluded-unless the filter explicitly sets `state`. Set `CODEX_SECURITY_LINEAR_API_KEY`-for a personal API key, or `LINEAR_ACCESS_TOKEN` for an OAuth access token.-`LINEAR_API_KEY` is also accepted. `--linear-api-key KEY` overrides these-environment settings; prefer the environment variable to keep keys out of shell-history. Imported content is always literal, and issue URLs must match the-selected workspace. Each imported issue includes its title, description, and-all comments with their source links. Linear access is read-only, and its-credentials are not passed to the patch subprocess.--Use `verify-fix` to check whether an existing security fix actually closes its-original vulnerability without modifying the repository. Pass a finding-description, a saved finding identifier, `--scan SCAN_ID`, `--linear-issue ISSUE`,-or `--linear-project "PROJECT"`. Linear intake uses the same credentials and-`--linear-filter` options as `patch`; explicitly filter for completed issues when-verifying a finished backlog. Verification runs the bundled `verify-fix` skill-in a read-only Codex sandbox and reports `fixed`, `still_vulnerable`, or-`inconclusive` with supporting evidence for every finding. Use `--json` for-structured output. Exit code `0` means every finding is fixed, `1` means at-least one finding remains vulnerable, and `2` means a result is inconclusive or-verification could not complete.--Interactive verification shows the same live agent-activity dashboard used by-scans and Linear publication. Reasoning, repository commands, and progress are-written to stderr; redirected output and CI receive plain progress lines, and-JSON results on stdout remain machine-readable.--Exit codes are `0` for a completed report-only scan or a passing policy, `1`-for a completed policy violation, `2` for invalid input, incomplete coverage, or-a runtime/export error, `130` for interruption, and `143` for termination.--Use `--dry-run` or `await security.preflight(...)` to validate the repository,-target, mode, output location, and Codex overrides without initializing the-runtime or loading credentials. Dry runs do not inspect the plugin or probe its-Python interpreter. The preflight result includes the selected authentication-method and, for an environment API key, its variable name. Authentication and-model access remain unverified until a real scan starts.--Scan progress identifies the selected credential source before Codex starts.-Terminals and noninteractive CI logs also show how to retry with-`--auth chatgpt` when an environment API key overrides the stored sign-in.-Progress remains on stderr so JSON output stays machine readable. Network-failures and rate limits remain retryable; definitive authentication and model-authorization failures stop immediately.+Import is read-only and returns an array (`[]` when empty). `--json` aliases+`--format json`. Save validation inputs without output filters or token limits.+Use the SDK loop for a disposition per alert.-## Containerized bulk scans+### Validate and patch findings-Create `repositories.csv` with one full, immutable Git commit per repository:+`validate` assesses candidates; `patch` fixes and verifies them. Both accept+files or literal text and work in the current directory. Pass a saved finding+or occurrence ID to `patch` to use its original repository.-```csv-id,repository,revision-payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567+```bash+npx @openai/codex-security validate "Possible SQL injection" --effort high+npx @openai/codex-security patch OCCURRENCE_ID+npx @openai/codex-security patch --scan SCAN_ID --severity high --json+npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr```-Once the approved image has been published, prepare private results and-authentication directories, sign in, and run the Docker Compose configuration-from the root of the Codex Security repository:+`--scan latest` selects the current repository's latest scan. Saved-finding+patch commands support `--json`; literal-text and file inputs don't. Change+the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.+Each finding gets its own saved Codex desktop task.++`scan --patch` patches after a complete scan. `--patch-severity` defaults to+`low`; `high` selects high and critical findings. Use the interactive browser+to select findings and add patch instructions. Results include a `patches`+entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.+Verified and already-fixed findings no longer fail `--fail-on-severity`.++`--create-pr` commits verified patch files and opens a draft PR with `gh`.+If publication fails, run the printed `patch --resume-pr BRANCH` command in+the same repository. It reuses the saved commit without rerunning Codex,+but refuses to publish if the branch changed.++To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use+`--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.+Completed and canceled issues are excluded unless the filter sets `state`.+Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or+`LINEAR_ACCESS_TOKEN` for OAuth. `--linear-api-key KEY` overrides these; prefer+environment variables to keep keys out of shell history. Intake is read-only,+includes comments, and keeps Linear credentials out of the patch subprocess.+Issue URLs must match the selected workspace.++### Verify fixes++`verify-fix` checks fixes in a read-only sandbox. Pass a description, saved+finding ID, `--scan SCAN_ID`, `--linear-issue ISSUE`, or `--linear-project "PROJECT"`.+Linear credentials and filters work as for `patch`. To check a finished backlog,+explicitly filter for completed issues.++Results include evidence and a status: `fixed`, `still_vulnerable`, or+`inconclusive`. Use `--json` for structured output. Exit codes are `0` if all+findings are fixed, `1` if any remain vulnerable, and `2` if verification is+inconclusive or couldn't finish.++### Command discovery and integrations++The CLI uses [Incur](https://github.com/wevm/incur). Use `--llms` for the+command manifest, `scan --schema --format json` for a command schema, and+`completions bash|zsh|fish` for shell completions. Scan output supports+`--format toon|json|yaml|jsonl` and `--full-output`.++`skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.+MCP exposes only the read-only `info` command because the transport cannot+cancel active scans.++## Containerized bulk scans++Create `repositories.csv` as described under [Bulk scans](#bulk-scans).+With a published image, run from the Codex Security repository root:```bashmkdir -p results state@@ -1320,17 +906,17 @@ docker compose run --rm codex-security login --device-authdocker compose run --rm codex-security```-Reports and resumable scan results are written to `results/`; the reusable-device login remains in `state/`. For unattended scans, set `OPENAI_API_KEY`-or `CODEX_API_KEY` instead. Set `GH_TOKEN` or `GITHUB_TOKEN` for private-GitHub repositories.+Results go to `results/`; device login stays in `state/`. For unattended scans,+set `OPENAI_API_KEY` or `CODEX_API_KEY`. Private GitHub checkouts use `GH_TOKEN`+or `GITHUB_TOKEN`; GitHub Enterprise uses `CODEX_SECURITY_GIT_HOST`. The container+requires CSV input, without interactive discovery.-The container accepts the repository CSV before or after bulk-scan options.-Interactive repository discovery remains disabled, including when global CLI-options appear before `bulk-scan`.+Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,+`CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and+`CODEX_SECURITY_STATE` for the image, user, seccomp profile, and mounts.On Ubuntu hosts that restrict unprivileged user namespaces, an administrator-can install the optional, narrowly scoped AppArmor profile once:+can install the optional AppArmor profile:```bashsudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container@@ -1338,37 +924,29 @@ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-containerdocker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security```-The override preserves the nonroot user, dropped capabilities,-no-new-privileges, and hardened seccomp policy. Other Docker hosts do not need-the profile or override.+The override keeps the nonroot user, dropped capabilities, no-new-privileges,+and seccomp policy. Other Docker hosts don't need it.## Local security model-Codex Security runs with your local operating-system permissions. Scan only-repositories you trust and either own or are authorized to assess. Your-repository, Git installation, configured tools, and other scans under the-same account are not separate security principals.--Every scan uses the `codex_security_scan` filesystem profile and-automatically reviewed execution approvals. Its baseline profile allows reads-of the local filesystem and writes to workspace roots and the selected scan-state directory. Approval requests are reviewed without an interactive prompt;-approved requests can grant additional permissions for a specific operation.-Use `--codex 'approval_policy="never"'` or a selected profile with that policy-to deny all requests instead. Other `approval_policy`, `approvals_reviewer`,-`sandbox_mode`, or permission overrides cannot replace the reviewer or baseline-filesystem profile. Saved scans retain their effective approval policy; older-saved scans remain deny-all when rerun. Independently enforced host and network-restrictions still apply.--Scan and workbench subprocesses can inherit your environment, including-unrelated API tokens and cloud credentials. Start a scan with only the-credentials it needs.--The scanner must stay within the target and output paths you authorize and-must not disclose private data beyond the operation you requested. Its results-must accurately report the scan mode, reviewed files, and exclusions. Consult-the security policy for the full threat model and private reporting process.+Codex Security runs with your operating-system permissions. Only scan+repositories you trust and are authorized to assess. Local tools and scans+under the same account aren't separate security principals.++The `codex_security_scan` profile allows reads across the local filesystem and+writes to workspace roots and the scan state directory. Execution approvals+are reviewed automatically and may grant extra permissions for one operation. Set+`--codex 'approval_policy="never"'`, directly or in a selected profile, to deny+requests. Other overrides can't replace the reviewer or filesystem profile.+Saved scans keep their approval policy; older scans stay deny-all on rerun.+Host and network restrictions still apply.++Start scans with only the credentials they need. Scan and workbench subprocesses+can inherit your environment, including unrelated API tokens and cloud credentials.++Repository contents, model output, and imported artifacts do not authorize+access to other targets, disclosure of credentials, or writes outside approved+paths. See the security policy below for the full threat model.## Documentation and security