2 2
3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4 4
5Use this reference to check the supported `codex-security` commands, flags,5Look up `codex-security` commands, flags, output formats, and exit behavior.
6output formats, and exit behavior. For a guided first scan, start with the6For a first scan, follow the
7[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).7[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).
8 8
9The `@openai/codex-security` package is public. Scans using OpenAI inference9The `@openai/codex-security` package is public. Scans using OpenAI inference
11 pause for approval. Before you start, review [Local scan11 pause for approval. Before you start, review [Local scan
12 permissions](#local-scan-permissions).12 permissions](#local-scan-permissions).
13 13
14Run the CLI with `npx @openai/codex-security`.14Run the CLI with `npx @openai/codex-security`. For older installations, check
15`--version` and command-specific `--help`. The installed package also provides
16the `cs` alias.
15 17
16## Command overview18## Command overview
17 19
22The CLI provides these commands:24The CLI provides these commands:
23 25
24| Command | Purpose |26| Command | Purpose |
25| ----------------------------- | ----------------------------------------------------- |27| ---------------------------------- | ------------------------------------------------------------------- |
26| `codex-security scan` | Run a Codex Security scan. |28| `codex-security scan` | Run a Codex Security scan. |
29| `codex-security scan import` | [Save CSV or JSON findings as a scan](#codex-security-scan-import). |
30| `codex-security import github` | [Read GitHub code scanning alerts](#codex-security-import-github). |
31| `codex-security policy` | Draft or update a repository security policy. |
32| `codex-security init` | Create a YAML or JSON project configuration. |
27| `codex-security install-hook` | Install a Git pre-commit security scan. |33| `codex-security install-hook` | Install a Git pre-commit security scan. |
28| `codex-security bulk-scan` | Discover repositories and run resumable bulk scans. |34| `codex-security bulk-scan` | Discover repositories and run resumable bulk scans. |
35| `codex-security scan-components` | Run separate scans for project components. |
29| `codex-security scans` | List, inspect, compare, and retrieve saved scan logs. |36| `codex-security scans` | List, inspect, compare, and retrieve saved scan logs. |
30| `codex-security findings` | Review and update saved security findings. |37| `codex-security findings` | Review and update saved security findings. |
31| `codex-security export` | Export completed findings as CSV, JSON, or SARIF. |38| `codex-security export` | Export findings or a retained threat model. |
32| `codex-security publish` | Publish completed scan findings to Linear. |39| `codex-security publish` | Publish findings to Linear or a custom findings service. |
40| `codex-security classify-severity` | Apply a severity rubric to saved findings. |
41| `codex-security suggest-owners` | Suggest finding owners using CODEOWNERS and Git history. |
42| `codex-security dedupe` | Deduplicate saved findings. |
33| `codex-security validate` | Check one or more candidate security findings. |43| `codex-security validate` | Check one or more candidate security findings. |
34| `codex-security patch` | Patch one or more security issues. |44| `codex-security patch` | Patch one or more security issues. |
45| `codex-security verify-fix` | Check whether reported issues are fixed. |
46| `codex-security feedback` | Send feedback to OpenAI and return a feedback ID. |
35| `codex-security login` | Sign in, store credentials, or check sign-in status. |47| `codex-security login` | Sign in, store credentials, or check sign-in status. |
36| `codex-security logout` | Remove the stored sign-in. |48| `codex-security logout` | Remove the stored sign-in. |
37| `codex-security info` | Show read-only SDK and bundled-plugin metadata. |49| `codex-security info` | Show read-only SDK and bundled-plugin metadata. |
59`codex-security --version` prints the installed version and exits.71`codex-security --version` prints the installed version and exits.
60`codex-security info --json` reports the SDK and bundled-plugin versions.72`codex-security info --json` reports the SDK and bundled-plugin versions.
61Neither command requires Python.73Neither command requires Python.
74Use `codex-security --update` to update the installed CLI.
62 75
63### Discover commands and connect agents76### Discover commands and connect agents
64 77
82 95
83Replace `bash` with `zsh` or `fish` for those shells.96Replace `bash` with `zsh` or `fish` for those shells.
84 97
85Scan results support `--format toon|json|yaml|jsonl` and `--full-output`. This98Scan results support `--format toon|json|yaml|jsonl` and `--full-output`.
86framework-level `--format` is separate from `--export-format`, which selects99`--export-format` instead selects the format of an artifact exported from a
87the format of an artifact exported from a completed scan. Global command help100completed scan. Global command help also lists `md`, but scan results don't
88also lists `md`, but scan results don't support Markdown output.101support Markdown output.
89 102
90Register the CLI as an MCP server:103Register the CLI as an MCP server:
91 104
99npx @openai/codex-security skills add112npx @openai/codex-security skills add
100```113```
101 114
102MCP exposes only the read-only `info` metadata command. Scans, exports,115The CLI exposes only the read-only `info` metadata command through its MCP
103authentication, validation, and patching remain CLI-only.116server. Scans, exports, publication, authentication, validation, and patching
117remain CLI-only.
104 118
105## `codex-security scan`119## `codex-security scan`
106 120
109 123
110```text124```text
111usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]125usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
126 [--config FILE]
127 [--cyber-access-program PROGRAM]
112 [--provider {openai,openrouter,fireworks,amazon-bedrock}]128 [--provider {openai,openrouter,fireworks,amazon-bedrock}]
113 [--path PATH | --diff BASE | --working-tree]129 [--path PATH | --diff BASE | --working-tree]
114 [--head HEAD] [--base BASE]130 [--head HEAD] [--base BASE]
115 [--knowledge-base PATH] [--scan-prompt-file FILE]131 [--knowledge-base PATH] [--scan-prompt-file FILE]
132 [--validation-prompt-file FILE]
116 [--post-scan-prompt-file FILE]133 [--post-scan-prompt-file FILE]
117 [--mode {standard,deep}] [--workers N]134 [--mode {standard,deep}] [--workers N]
118 [--subagents N] [--stop-after-no-new N]135 [--subagents N] [--stop-after-no-new N]
119 [--max-discovery-runs N] [--max-time-hours HOURS]136 [--max-discovery-runs N] [--max-time-hours HOURS]
120 [--model MODEL]137 [--model MODEL]
121 [--effort {minimal,low,medium,high,xhigh,max}]138 [--effort EFFORT]
122 [--output-dir DIR]139 [--output-dir DIR]
123 [--archive-existing]140 [--archive-existing]
124 [--plugin-path PATH] [--python PATH]141 [--plugin-path PATH] [--python PATH]
125 [--codex KEY=VALUE] [--fail-on-severity LEVEL]142 [--codex KEY=VALUE] [--fail-on-severity LEVEL]
126 [--patch] [--patch-severity {critical,high,medium,low}]143 [--patch] [--patch-severity {critical,high,medium,low}]
127 [--create-pr]144 [--create-pr]
128 [--max-cost USD] [--dry-run] [--headless] [--verbose]145 [--max-cost USD] [--show-cost] [--dry-run] [--mock]
146 [--workflow-id ID] [--safety-identifier ID]
147 [--headless] [--verbose]
129 [--json] [--format {toon,json,yaml,jsonl}]148 [--json] [--format {toon,json,yaml,jsonl}]
130 [--full-output] [repository]149 [--full-output] [repository]
131```150```
132 151
133`repository` defaults to the current directory.152`repository` defaults to the current directory.
134 153
154### Load project configuration
155
156Create a starter configuration and select it explicitly:
157
158```bash
159npx @openai/codex-security init codex-security.yaml
160npx @openai/codex-security scan . --config codex-security.yaml
161```
162
163`init` doesn't overwrite an existing file. Use `-c FILE` as a shorter form of
164`--config FILE`, or set `CODEX_SECURITY_PROJECT_CONFIG`. An explicit flag takes
165precedence over the environment variable. The CLI doesn't discover a project
166file automatically.
167
168Select only configuration you control. It has the same authority as CLI
169options: native Codex settings can start MCP server processes and choose model
170service destinations. Don't select a file controlled by an untrusted repository
171or pull request. In CI, keep scanner configuration outside the checkout being
172assessed. See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md) for settings and precedence.
173
135### Select scan authentication174### Select scan authentication
136 175
137Use `--auth auto`, the default, to select credentials automatically. When both176Use `--auth auto`, the default, to select credentials automatically. When both
155To make stored credentials the automatic default, run194To make stored credentials the automatic default, run
156`unset OPENAI_API_KEY CODEX_API_KEY`.195`unset OPENAI_API_KEY CODEX_API_KEY`.
157 196
197Use `--auth api-key` with
198`--cyber-access-program standard|daybreak_blue|daybreak_red` to select a
199Cyber access program for OpenAI model requests. Omission preserves Codex
200defaults; `standard` explicitly selects the standard program.
201Selecting a program doesn't grant access; your API project must be approved
202for the selected program. See the [access-program guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#select-a-cyber-access-program) for credential requirements.
203
204### Attribute scans to end users
205
206When scanning on behalf of users, `--safety-identifier ID` accepts a stable,
207hashed identifier with API-key authentication. Use 1–64 characters without NUL
208or personal data such as email addresses.
209
210The bundled runtime doesn't yet support this option. It requires a compatible
211Codex build selected with `CODEX_CLI_PATH` and a plugin that forwards the
212identifier to workers. The SDK validates the identifier format, not runtime
213or plugin compatibility; older versions may omit it.
214
158### Use OpenRouter or Fireworks215### Use OpenRouter or Fireworks
159 216
160Select OpenRouter with its API key and an explicit model:217Select OpenRouter with its API key and an explicit model:
231#### Local results and access checks288#### Local results and access checks
232 289
233Saved local reports, `scans show`, and `export` work without cloud credentials.290Saved local reports, `scans show`, and `export` work without cloud credentials.
234Uploading findings to Codex Security Cloud requires a separate ChatGPT
235sign-in and access to the destination.
236 291
237`info` and `scan --dry-run` don't test AWS credentials or model access. Run a292`info` and `scan --dry-run` don't test AWS credentials or model access. Run a
238scan to check access. For AWS authentication or access-denied errors, check293scan to check access. For AWS authentication or access-denied errors, check
240 295
241#### Bedrock release status296#### Bedrock release status
242 297
243`@openai/codex-security@0.1.31` supports Amazon Bedrock scans. This version298Starting in 0.2.0, `@openai/codex-security` supports cost estimates and `--max-cost` for
244doesn't provide cost estimates or support `--max-cost` for the Daybreak Blue299the Daybreak Blue and Daybreak Red model IDs above. Estimates use AWS Standard
245and Daybreak Red model IDs above.300commercial in-region prices, including the AWS fee. The cost limit uses
301`estimatedUsd`, the short-context baseline. Requests already in progress can
302put this estimate above the limit. Long-context pricing can raise the reported
303`estimatedUsdRange` above it. This limit is not a billing cap.
246 304
247Check your installed package and bundled Codex versions:305Check your installed package and bundled Codex versions:
248 306
334```392```
335 393
336When the time limit expires, the scan stops unfinished workers, keeps completed394When the time limit expires, the scan stops unfinished workers, keeps completed
337scan results, and aggregates them into the final report. Check the report for395scan results, and aggregates them into the final report. Reaching a configured
338reviewed areas and deferred work. The deadline alone doesn't determine the exit396limit with a valid finalized report isn't an execution failure. Review its
339code; execution status and the severity policy do.397follow-up work and coverage notes; see [Exit codes and signals](#exit-codes-and-signals).
340 398
341Set persistent defaults in `~/.codex/codex-security/config.toml`, or in399Set persistent defaults in `~/.codex/codex-security/config.toml`, or in
342`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:400`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:
352 410
353Command-line options override these defaults. `scan --workers` controls411Command-line options override these defaults. `scan --workers` controls
354independent standard-scan workers within one deep scan; `bulk-scan --workers`412independent standard-scan workers within one deep scan; `bulk-scan --workers`
355controls concurrent repository scans. Set `stop_after_consecutive_errors` only413controls concurrent repository scans. Set `stop_after_consecutive_errors` in
356in the TOML file; its default is `3`.414the legacy TOML file or `scan.deep.stop_after_consecutive_errors` in a project
415file; its default is `3`.
357 416
358### Add security context417### Add security context
359 418
366 --knowledge-base /path/to/security-policies425 --knowledge-base /path/to/security-policies
367```426```
368 427
369Supported documents include `.md`, `.markdown`, `.txt`, `.pdf`, and `.docx`428Supported documents include UTF-8 text files (including JSON and SARIF), PDF,
370files. The CLI searches directories recursively, rejects linked input paths,429and DOCX files. The CLI searches directories recursively, rejects linked input
371skips linked directory entries, and keeps extracted document content430paths, and skips linked directory entries. It saves extracted documents in the
372outside the saved scan results.431private `.scan-knowledge.json` continuation file beside the scan artifacts to
432support resuming the scan. Preserve this file with the scan directory.
433Canonical reports don't include the document text.
373 434
374### Add scan instructions435### Add scan instructions
375 436
376To add scan instructions, provide a text or Markdown file with437To add scan instructions, provide a text or Markdown file with
377`--scan-prompt-file`. Use `--post-scan-prompt-file` to run follow-up438`--scan-prompt-file`. Use `--post-scan-prompt-file` to run follow-up
378instructions in the same authenticated session after successful scans and439instructions in the same authenticated session after scans that succeed or
379scan errors:440return errors:
380 441
381```bash442```bash
382npx @openai/codex-security scan . \443npx @openai/codex-security scan . \
388the follow-up to write a new `post-scan-summary.md` in the scan directory.449the follow-up to write a new `post-scan-summary.md` in the scan directory.
389If the follow-up fails, the CLI reports a warning and keeps the completed scan.450If the follow-up fails, the CLI reports a warning and keeps the completed scan.
390The follow-up doesn't run after cancellation or when the scan reaches its cost451The follow-up doesn't run after cancellation or when the scan reaches its cost
391limit.452limit. When it runs, the follow-up is outside scan cost tracking and `--max-cost`.
453
454Use `--validation-prompt-file FILE` to replace final validation with your own
455workflow in Standard and diff scans. Source review still runs. Include setup,
456authorized targets, required evidence, and cleanup. Deep scans reject custom
457validation; scans with no candidates skip it.
392 458
393### Set output and policy options459### Set output and policy options
394 460
402| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |468| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |
403| `--patch` | Fix and verify selected findings after a complete scan. |469| `--patch` | Fix and verify selected findings after a complete scan. |
404| `--patch-severity LEVEL` | Patch findings at or above `critical`, `high`, `medium`, or `low`. Defaults to `low`. |470| `--patch-severity LEVEL` | Patch findings at or above `critical`, `high`, `medium`, or `low`. Defaults to `low`. |
405| `--create-pr` | Commit verified patch files and open a GitHub pull request. Requires `--patch`. |471| `--create-pr` | Commit verified patch files and open a draft GitHub pull request or GitLab merge request. Requires `--patch`. |
406| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |472| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |
473| `--show-cost` | Show estimated cost in progress and completion output. |
474| `--mock` | Save synthetic Standard scan findings without calling a model. |
475| `--workflow-id ID` | Reuse completed work in the named local findings workflow. |
407| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |476| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |
408| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |477| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |
409| `--verbose` | Print redacted lifecycle, authentication, progress, and cost diagnostics to stderr. |478| `--verbose` | Print additional lifecycle, authentication, progress, and cost diagnostics to stderr. |
410| `--json` | Print manifest, findings, coverage, paths, and turn metadata as one JSON document. |479| `--json` | Print manifest, findings, coverage, paths, and turn metadata as one JSON document. |
411| `--format FORMAT` | Print the complete scan result as `toon`, `json`, `yaml`, or `jsonl`. |480| `--format FORMAT` | Print the complete scan result as `toon`, `json`, `yaml`, or `jsonl`. |
412| `--full-output` | Print the complete result using the default structured output format. |481| `--full-output` | Print the complete result using the default structured output format. |
413 482
414The cost limit is an estimate, not a hard spending cap. Requests already in483Mock mode supports Standard repository, path, and diff scans. You can't combine
415progress can finish slightly above the limit. If a deep scan reaches the limit484it with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan prompts.
485Scan prompts and knowledge bases don't change its synthetic findings. Use a
486separate `CODEX_SECURITY_STATE_DIR` to keep mock results out of your scan history.
487
488The cost limit uses `estimatedUsd`, the short-context baseline. Requests already
489in progress can put this estimate above the limit. Long-context pricing can
490raise `estimatedUsdRange` above it. This limit is not a billing cap.
491
492If a deep scan reaches the limit
416after Codex Security aggregates completed worker results, the CLI can seal a493after Codex Security aggregates completed worker results, the CLI can seal a
417completed result and report the budget warning. It returns `0`, or `1` if494completed result and report the budget warning. It returns `0`, or `1` if
418findings meet the configured severity threshold. If it can't produce a valid495findings meet the configured severity threshold. If it can't produce a valid
430`CODEX_SECURITY_STATE_DIR` also moves the workbench database.507`CODEX_SECURITY_STATE_DIR` also moves the workbench database.
431 508
432The output directory must be outside the scanned directory and any enclosing509The output directory must be outside the scanned directory and any enclosing
433Git worktree. A scan can replace an existing result directory with510Git worktree. Use `--archive-existing` to preserve earlier results before reusing
434`--archive-existing`.511an output directory:
435
436To preserve earlier results before reusing an output directory:
437 512
438```bash513```bash
439npx @openai/codex-security scan . \514npx @openai/codex-security scan . \
465 540
466### Configure the runtime541### Configure the runtime
467 542
468Use runtime options when you need an explicit model, interpreter, plugin, or543Use runtime options to select a model, interpreter, plugin, or Codex
469Codex configuration value.544configuration value.
470 545
471| Argument | Description |546| Argument | Description |
472| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |547| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
473| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |548| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |
474| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |549| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |
475| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |550| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |
476| `--effort {minimal,low,medium,high,xhigh,max}` | Select the model's reasoning effort. The default is `xhigh`. |551| `--effort EFFORT` | Select the model's reasoning effort. The default is `xhigh`; supported values depend on the model and provider. |
477| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |552| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |
478| `--python PATH` | Select the Python interpreter for the plugin runtime. |553| `--python PATH` | Select the Python interpreter for the plugin runtime. |
479| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |554| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |
480 555
556Codex Security accepts model IDs and reasoning-effort values as strings.
557Supported combinations depend on the model, provider, Codex version, and your
558credentials.
559
560If the scan's isolated Codex configuration selects a profile, that profile's
561`model` and `model_reasoning_effort` values take precedence over `--model` and
562`--effort`. Your normal Codex configuration isn't loaded.
563Add `--dry-run --verbose` to your scan command to inspect the resolved model
564and effort before starting a scan.
565
481To select a different model and reasoning effort without writing TOML, choose a566To select a different model and reasoning effort without writing TOML, choose a
482model your credentials can access. If you use ChatGPT sign-in, check [GPT-6.1567model your credentials can access. If you use ChatGPT sign-in, check [GPT-6.1
483Sol availability](https://learn.chatgpt.com/docs/models#gpt-6.1-sol) before using these examples:568Sol availability](https://learn.chatgpt.com/docs/models#gpt-6.1-sol) before using these examples:
495```580```
496 581
497 582
583Model and effort values pass through to Codex unchanged. Unsupported
584combinations return Codex or provider errors without substituting another
585model or effort.
586
587## `codex-security scan import`
588
589Save existing findings as a completed scan in local history without running
590security analysis or making model calls. Import doesn't require model
591authentication.
592
593```text
594usage: codex-security scan import (--csv FILE | --json FILE)
595 [--output-dir DIR] [--archive-existing]
596 [--dry-run] [--format json]
597```
598
599Supply exactly one input. CSV uses the Codex Security export columns. JSON
600accepts a complete `codex-security.findings` document or an object containing
601a `findings` array that matches the findings schema. Arbitrary scanner JSON
602and raw GitHub alert arrays aren't accepted as saved findings.
603
604Save this synthetic example as `findings.csv`:
605
606```csv
607occurrence_id,finding_id,title,summary,severity,confidence,status,close_reason,note,remediation,path,start_line,end_line
608occ_000000000000000000000001,csf_000000000000000000000001,Missing authorization check,The route reads a record without checking ownership,high,high,open,,,Check record ownership before returning data,src/routes.ts,18,18
609```
610
611Validate the file, then import it:
612
613```bash
614npx @openai/codex-security scan import --csv findings.csv --dry-run --format json
615npx @openai/codex-security scan import --csv findings.csv --format json
616```
617
618The dry run reports `dryRun: true` and `findingCount: 1` without saving a scan.
619The import returns the saved scan ID and result paths. To import JSON instead:
620
621```bash
622npx @openai/codex-security scan import --json findings.json --format json
623```
624
625For this command, `--json FILE` selects the input file. Use `--format json` for
626JSON output.
627
628| Option | Behavior |
629| -------------------- | ------------------------------------------------------------------------------- |
630| `--csv FILE` | Read findings in the Codex Security CSV export format. |
631| `--json FILE` | Read a findings document or an object with a `findings` array. |
632| `--dry-run` | Validate the input without saving a scan. |
633| `--output-dir DIR` | Choose the artifact directory. The default is persistent Codex Security state. |
634| `--archive-existing` | Archive existing results before importing. This option requires `--output-dir`. |
635
636Use a regular input file with no symbolic links or directory junctions in its
637path. Each import preserves finding occurrences, including duplicates, and
638retains the input under `artifacts/import/`. Original identifiers are stored in
639`extensions.import`. Completion means the import finished; it doesn't mean the
640source was reviewed. `scans rerun SCAN_ID` imports the retained input again.
641
642To scan a repository named `import`, use `scan ./import`.
643
644## `codex-security import github`
645
646Read GitHub code scanning alerts without changing GitHub or checking out code:
647
648```bash
649npx @openai/codex-security import github example/repository --format json > /path/outside/repository/alerts.json
650npx @openai/codex-security import github example/repository \
651 --github-alert 12 --github-alert 18 --format json
652```
653
654Replace `example/repository` with your repository. Authenticate with GitHub
655CLI credentials that have code-scanning read access. By default, import reads
656open alerts from the default branch, including third-party SARIF uploads.
657
658| Option | Behavior |
659| ----------------------- | --------------------------------------------------------------------------------- |
660| `--github-alert NUMBER` | Select an exact alert regardless of state; repeat for multiple alerts. |
661| `--github-ref REF` | Select a Git reference instead of the default branch. |
662| `--github-state STATE` | List `open`, `closed`, `dismissed`, `fixed`, or `all` alerts; defaults to `open`. |
663
664Don't combine exact alert numbers with a state other than `open`. The command returns
665an array of upstream alerts, not a saved scan. From the corresponding local
666repository, run
667`codex-security validate /path/outside/repository/alerts.json` to assess them.
668Keep the full JSON without output filters or token limits when saving
669validation inputs. Use [`scan import`](#codex-security-scan-import) for
670findings already in the Codex Security schema.
671
498## `codex-security install-hook`672## `codex-security install-hook`
499 673
500Install a Git pre-commit security check for the current repository:674Install the CLI outside the repository, inspect the repository's existing
675pre-commit hook, and run the installed CLI from outside the checkout:
501 676
502```bash677```bash
503npx @openai/codex-security install-hook678git -C /path/to/repository rev-parse --git-path hooks/pre-commit
679codex-security install-hook /path/to/repository
504```680```
505 681
506The check scans staged and unstaged changes before each commit and blocks682The check scans staged and unstaged changes before each commit and blocks
507high-severity findings or scan errors. It respects `core.hooksPath` and does683commits on high or critical findings or scan errors. Local hooks are optional;
508not replace an existing pre-commit script. Set a different severity threshold684use a required CI check for enforcement. Leave custom, linked, or shared hooks
509when needed:685and hook directories to their owner. The installer doesn't replace an unrelated
686pre-commit script. Set a different severity threshold when needed:
687
688```bash
689codex-security install-hook /path/to/repository --fail-on-severity medium
690```
691
692## `codex-security policy`
693
694Draft a `SECURITY.md` policy that describes project security boundaries and
695what should count as a finding:
696
697```bash
698npx @openai/codex-security policy .
699npx @openai/codex-security policy . --headless --json
700```
701
702The command saves a draft outside the repository and leaves existing files
703unchanged. Review the draft, diff, and review notes, then copy only the reviewed
704`SECURITY.md` to the displayed policy target. In headless mode, unanswered
705questions remain in the review notes. Policy generation is optional; scans
706can use an existing policy or run without one. See the [policy guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#generate-a-security-policy) for path scopes and options.
707
708## `codex-security scan-components`
709
710Run a separate scan for each component of one repository:
711
712```bash
713npx @openai/codex-security scan-components . \
714 --component apps/api --component apps/web \
715 --workers 4 --output-dir /path/outside/repository/components
716```
717
718Unlike `scan --path`, this command produces a scan per component, then combines
719and matches the findings. Use `--components-file FILE` for a saved plan. To
720propose a split for review before scanning:
510 721
511```bash722```bash
512npx @openai/codex-security install-hook . --fail-on-severity medium723npx @openai/codex-security scan-components . --auto --plan-only \
724 --output-dir /path/outside/repository/component-plan
513```725```
514 726
727Component scans require `--output-dir` or `output.directory` in the project
728configuration, including plan-only runs. Failed scans or matching failures
729return `2`; severity-policy violations return `1`. See the [component scan guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#scan-project-components) for plan syntax and retries.
730
515## `codex-security bulk-scan`731## `codex-security bulk-scan`
516 732
517Discover and scan GitHub repositories, or run a resumable scan from a733Discover and scan GitHub repositories, or run a resumable scan from a
518repository CSV.734repository CSV.
519 735
520For a complete guide to GitHub discovery, CSV inventories, campaign results,736For GitHub discovery, CSV inventories, campaign results, and containerized
521and containerized scans, see [Run bulk security737scans, see [Run bulk security
522scans](https://learn.chatgpt.com/docs/security/cli/bulk-scans).738scans](https://learn.chatgpt.com/docs/security/cli/bulk-scans).
523 739
524```text740```text
526 [--workers N] [--mode {standard,deep}]742 [--workers N] [--mode {standard,deep}]
527 [--provider {openai,openrouter,fireworks,amazon-bedrock}]743 [--provider {openai,openrouter,fireworks,amazon-bedrock}]
528 [--model MODEL]744 [--model MODEL]
529 [--effort {minimal,low,medium,high,xhigh,max}]745 [--effort EFFORT]
530 [--knowledge-base PATH]746 [--knowledge-base PATH]
531 [--scan-prompt-file FILE]747 [--scan-prompt-file FILE]
532 [--post-scan-prompt-file FILE]748 [--post-scan-prompt-file FILE]
567repository. Use `--scan-prompt-file FILE` to add shared scan instructions; the783repository. Use `--scan-prompt-file FILE` to add shared scan instructions; the
568CSV `prompt` column adds repository-specific instructions after that shared784CSV `prompt` column adds repository-specific instructions after that shared
569prompt. `--post-scan-prompt-file FILE` runs follow-up instructions after each785prompt. `--post-scan-prompt-file FILE` runs follow-up instructions after each
570scan, including scan errors. It doesn't run after786scan, including scans that return errors. It doesn't run after
571cancellation or when a scan reaches its cost limit.787cancellation or when a scan reaches its cost limit.
572 788
573`--workers` limits simultaneous repository scans and defaults to `4`. `--mode`789`--workers` limits simultaneous repository scans and defaults to `4`. `--mode`
574defaults to `standard`, and `--max-attempts` defaults to `1`. Set790defaults to `standard`, and `--max-attempts` defaults to `1`. Set
575`--max-attempts` to retry repository or scan errors. Completed scans aren't791`--max-attempts` to retry repository or scan errors. Exclusions and follow-up
576retried because of coverage gaps or severity-policy violations. Their results792notes don't trigger retries of completed scans. Remaining execution failures
577remain available.793return `2`; completed severity-policy violations return `1`.
578 794
579Run the same command again to resume from an existing output directory. The CLI795Run the same command again to resume from an existing output directory. The CLI
580skips completed scans, including scans with coverage gaps.796skips completed scans. Use `--recover` to retry failed or interrupted attempts
797in a matching campaign.
581 798
582For containerized campaigns, see [Run bulk scans in799For containerized campaigns, see [Run bulk scans in
583Docker](https://learn.chatgpt.com/docs/security/cli/bulk-scans#run-bulk-scans-in-docker).800Docker](https://learn.chatgpt.com/docs/security/cli/bulk-scans#run-bulk-scans-in-docker).
614 831
615Add `--show-linked-findings` to include finding links from earlier scans.832Add `--show-linked-findings` to include finding links from earlier scans.
616 833
617Rerun the scan against the current checkout using its original configuration:834Rerun a saved scan:
618 835
619```bash836```bash
620npx @openai/codex-security scans rerun SCAN_ID837npx @openai/codex-security scans rerun SCAN_ID
621```838```
622 839
623The rerun requires the plugin version recorded by the original scan. If the840A rerun creates a new scan using saved settings and authentication choice,
624installed version differs, the command stops instead of running with a841the current checkout, and current context files. It doesn't reload project
625different plugin.842configuration files or reuse saved credentials. If the original used scan or
843custom-validation prompts, supply those files again with `--scan-prompt-file`
844and `--validation-prompt-file`.
845
846Reruns require the original scan's recorded plugin version and stop if the
847installed version differs.
626 848
627### Inspect saved scan logs849### Inspect saved scan logs
628 850
716 938
717## `codex-security export`939## `codex-security export`
718 940
719Export CSV, JSON, or SARIF from a completed, sealed scan. Export validates the941Export saved findings or a threat model without starting Codex or loading
720scan artifacts before writing output and leaves the Codex runtime and942credentials. You can export findings as CSV, JSON, or SARIF only from a
721credentials untouched.943completed, sealed scan. Threat models use Markdown.
722 944
723```text945```text
724usage: codex-security export [--export-format {csv,json,sarif}]946usage: codex-security export [scan_dir | --scan SCAN_ID]
947 [--artifact {findings,threat-model}]
948 [--export-format {csv,json,sarif,md}]
725 [--output FILE|-] [--source-root PATH]949 [--output FILE|-] [--source-root PATH]
726 [--python PATH] scan_dir950 [--python PATH]
727```951```
728 952
729`scan_dir` is the completed scan directory.953Omit `scan_dir` and `--scan` to use the current repository's latest completed
954scan. Otherwise, provide a saved result directory or select a scan by ID or
955unique prefix of at least eight characters with `--scan`. You can't combine
956these selectors.
730 957
731| Argument | Description |958| Argument | Description |
732| ---------------------------------- | ------------------------------------------------------------------------------------------- |959| ------------------------------------- | ------------------------------------------------------------------------------------------- |
733| `--export-format {csv,json,sarif}` | Select the export format. The default is `sarif`. |960| `--artifact {findings,threat-model}` | Select the saved artifact. The default is `findings`. |
961| `--scan SCAN_ID` | Select a saved scan by ID or unique prefix of at least eight characters. |
962| `--export-format {csv,json,sarif,md}` | Select the format. Findings default to `sarif`; threat models support only `md`. |
734| `--output FILE\|-` | Write the selected format to a file or stdout. Defaults to a file in the current directory. |963| `--output FILE\|-` | Write the selected format to a file or stdout. Defaults to a file in the current directory. |
735| `--source-root PATH` | Add source-line fingerprints to SARIF using a repository checkout. |964| `--source-root PATH` | Add source-line fingerprints to SARIF using a repository checkout. |
736| `--python PATH` | Select the Python interpreter for the bundled exporter. |965| `--python PATH` | Select the Python interpreter for the bundled exporter. |
737 966
738`--source-root` works only with `--export-format sarif`. JSON preserves967`--source-root` works only with SARIF findings exports. JSON preserves
739the sealed findings document. CSV contains portable finding columns and does968the sealed findings document. CSV contains portable finding columns and does
740not include local workbench triage state.969not include local workbench triage state.
741 970
742Without `--output`, the CLI writes SARIF to `results.sarif`, JSON to971Without `--output`, the CLI writes SARIF to `results.sarif`, JSON to
743`findings.json`, and CSV to `findings.csv` in the current working directory.972`findings.json`, CSV to `findings.csv`, and Markdown to `threatmodel.md` in the
744Exports can contain source excerpts and vulnerability details. Run the command973current working directory.
745outside the repository or pass `--output` with a private path outside the974Exports can contain source excerpts and vulnerability details. Pass `--output`
746scanned checkout.975with a private path outside the checkout. When running outside the repository,
976also specify a result directory or `--scan`.
977
978### Export findings
747 979
748Write SARIF to a file:980Write SARIF to a file:
749 981
779 --output /path/outside/repository/exports/findings.csv1011 --output /path/outside/repository/exports/findings.csv
780```1012```
781 1013
1014### Export a saved threat model
1015
1016Starting in version 0.2.0, scans save their threat models for reuse without
1017another model call. Export the latest completed scan's model to stdout:
1018
1019```bash
1020npx @openai/codex-security export --artifact threat-model --output -
1021```
1022
1023Or select a scan and save its model to a file:
1024
1025```bash
1026npx @openai/codex-security export --scan SCAN_ID \
1027 --artifact threat-model \
1028 --output /path/outside/repository/exports/threatmodel.md
1029```
1030
1031If you select a scan by ID or directory, you can also export a saved model
1032from an unfinished or failed scan. If no model was saved, the command returns
1033an error. Review any provisional or recovered content identified in the
1034document before reusing it.
1035
1036To provide the exported model as context for another scan, pass its path to
1037[`--knowledge-base`](#add-security-context).
1038
782## `codex-security publish scan`1039## `codex-security publish scan`
783 1040
784Publish every finding from a completed scan to Linear:1041Publish selected findings from a completed scan to Linear or a custom findings
1042service. The following options describe Linear publication:
785 1043
786```text1044```text
787usage: codex-security publish scan [SCAN_DIR] --to linear1045usage: codex-security publish scan [SCAN_DIR] --to linear
797also requires the scan and its findings to exist in local scan history. A dry1055also requires the scan and its findings to exist in local scan history. A dry
798run validates the sealed artifacts without this persistence check.1056run validates the sealed artifacts without this persistence check.
799 1057
1058Use `--scan SCAN_ID` or `--scan latest` instead of a directory to select a
1059saved scan. Repeat `--finding-id ID` to select a subset for Linear. Use
1060`publish check SCAN_DIR` with the Linear destination options to verify artifacts
1061and recorded publications. With an API key, it also checks authentication and
1062destination access; connected-app access is reported as `not-checked`.
1063
800| Argument | Description |1064| Argument | Description |
801| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |1065| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
802| `--to linear` | Publish to Linear. This argument is required. |1066| `--to linear` | Publish to Linear. This argument is required. |
805| `--linear-api-key KEY` | Use a Linear personal API key for direct publication. Uses `CODEX_SECURITY_LINEAR_API_KEY` when omitted. |1069| `--linear-api-key KEY` | Use a Linear personal API key for direct publication. Uses `CODEX_SECURITY_LINEAR_API_KEY` when omitted. |
806| `--linear-assignee EMAIL_OR_USER_ID` | Assign created issues by email address or Linear user ID. Requires `--linear-api-key` or `CODEX_SECURITY_LINEAR_API_KEY`. Issues remain unassigned when omitted. |1070| `--linear-assignee EMAIL_OR_USER_ID` | Assign created issues by email address or Linear user ID. Requires `--linear-api-key` or `CODEX_SECURITY_LINEAR_API_KEY`. Issues remain unassigned when omitted. |
807| `--dry-run` | Prepare issue payloads without starting Codex, contacting Linear, creating issues, or writing publication state. |1071| `--dry-run` | Prepare issue payloads without starting Codex, contacting Linear, creating issues, or writing publication state. |
1072| `--skip-existing` | Skip findings with a recorded successful publication for the same occurrence, Linear team, and project. Requires local history. |
808| `--json` | Write structured publication results to stdout. Progress remains on stderr. |1073| `--json` | Write structured publication results to stdout. Progress remains on stderr. |
809 1074
810Linear issue descriptions and dry-run output can include source code snippets1075Linear issue descriptions and dry-run output can include source code snippets
811 and vulnerability details. Check who can view the destination team or project1076 and vulnerability details. Check who can view the destination team or project
812 before publishing.1077 before publishing.
813 1078
814Each non-dry-run invocation attempts to create a new issue for every finding.1079Each non-dry-run invocation attempts to create a new issue for every selected
815Publishing the same scan again doesn't match, update, or reuse existing issues.1080finding unless `--skip-existing` finds a recorded success for that occurrence,
1081team, and project. This option doesn't inspect remote issues or cover
1082unrecorded or concurrent publication.
816If some findings fail, the command preserves successfully created issues and1083If some findings fail, the command preserves successfully created issues and
817returns exit code `2`.1084returns exit code `2`.
818With `--json`, review the `created` and `failed` results before retrying to1085With `--json`, review the `created` and `failed` results before retrying to
860keys, prefer `CODEX_SECURITY_LINEAR_API_KEY` over `--linear-api-key` because1127keys, prefer `CODEX_SECURITY_LINEAR_API_KEY` over `--linear-api-key` because
861command-line arguments can appear in shell history and process listings.1128command-line arguments can appear in shell history and process listings.
862 1129
1130### Publish to a custom findings service
1131
1132For an existing findings service, select its URL explicitly:
1133
1134```bash
1135npx @openai/codex-security publish scan --scan latest \
1136 --to custom --findings-url http://localhost:3000
1137```
1138
1139Publication sends the complete sealed findings and the repository target ID.
1140Findings can include source excerpts, evidence, and vulnerability details. Use
1141HTTPS for services outside your local machine, and add `--dry-run --json` to
1142inspect the payload before sending it.
1143
1144The CLI doesn't send model credentials to a custom service. Handle any required
1145authentication outside the CLI. See the [findings service guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/findings-service.md) for deployment and protocol details.
1146
1147## Finding review commands
1148
1149These commands work with existing findings:
1150
1151| Command | Example | Behavior |
1152| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1153| `classify-severity` | `codex-security classify-severity --scan latest --rubric policy.md --json` | Apply a rubric without repeating discovery or rewriting original findings. Omit `--rubric` to inherit an existing severity without model calls. Findings without severity require a rubric. |
1154| `suggest-owners` | `codex-security suggest-owners findings.json --source-root /path/to/repository --json` | Read committed source, CODEOWNERS, blame, and Git history to suggest owners. Doesn't assign tickets. |
1155| `dedupe` | `codex-security dedupe --scan SCAN_ID --json` | Identify duplicate findings in local SQLite. Missing or stale embeddings require an embedding API key; fresh reviews require model access. |
1156| `verify-fix` | `codex-security verify-fix --scan SCAN_ID --json` | Check existing fixes in a read-only sandbox. Accepts finding IDs, descriptions, and Linear selectors. |
1157
1158`verify-fix` returns `2` if any check is inconclusive or fails. Otherwise, it
1159returns `1` if any finding remains vulnerable, or `0` if all findings are fixed.
1160Use each command's `--help` for selectors, model settings, and output options.
1161
1162## `codex-security feedback`
1163
1164Send a problem description to OpenAI and receive an ID to share with support:
1165
1166```bash
1167npx @openai/codex-security feedback SCAN_ID \
1168 --reason "The scan stopped before it finished" --json
1169```
1170
1171Without a scan ID, the command selects the most recently started scan in the
1172current repository, including active or failed scans, or sends a general
1173report if none exists. Reports include the description, versions, and selected
1174scan/session IDs. Logs are excluded by default. Add `--include-logs` only when
1175you can share the included source, prompts, findings, and tool output with
1176OpenAI.
1177
863## `codex-security validate` and `codex-security patch`1178## `codex-security validate` and `codex-security patch`
864 1179
865Check whether a candidate finding is valid:1180Assess candidate findings against the current repository's source code:
866 1181
867```bash1182```bash
868npx @openai/codex-security validate findings.json \1183npx @openai/codex-security validate findings.json \
877```1192```
878 1193
879Each positional argument accepts literal text or a file path. These inputs use1194Each positional argument accepts literal text or a file path. These inputs use
880the current directory. Use `validate` to recheck a finding after a fix or when a1195the current directory. `validate` uses a read-only sandbox to assess source
881later scan no longer reports it. Comparing scans alone doesn't prove that a fix1196evidence. It doesn't build the target, execute application code, run tests or
882worked.1197proofs of concept, or contact services. Standard, Deep, and diff scans retain
1198their own validation workflows; `patch` still fixes and verifies findings.
1199
1200Use `validate` to reassess a finding after a fix or when a later scan no longer
1201reports it. Comparing scans alone doesn't prove that a fix worked. For runtime
1202evidence, run a separate reproduction step.
1203
1204The command prints its assessment to stdout without saving a report. Redirect
1205stdout to retain it:
1206
1207```bash
1208npx @openai/codex-security validate findings.json > /path/outside/repository/assessment.md
1209```
1210
1211Add `--context TEXT`, `--context-file FILE`, or repeated `--knowledge-base PATH`
1212options to supply security context. For structured output, use
1213`--output-schema FILE` with a self-contained JSON Schema supported by your model
1214and provider. The CLI checks the generated JSON against the schema before
1215writing stdout. If the output is invalid, the CLI exits with `2` and writes no
1216assessment. `validate` doesn't accept `--json`.
883 1217
884Use `--effort` to select reasoning effort for either command:1218Use `--effort` to select reasoning effort for either command:
885 1219
911```1245```
912 1246
913`--scan latest` selects the latest completed scan for the current repository.1247`--scan latest` selects the latest completed scan for the current repository.
914Saved-finding commands support `--json`; literal-text and file inputs don't.1248`patch` supports `--json` for saved findings, literal text, and file inputs.
915 1249
916Add `--create-pr` to commit only verified patch files and open a pull request1250Add `--create-pr` to commit only verified patch files and open a draft GitHub
917with the GitHub CLI:1251pull request or GitLab merge request with the corresponding CLI:
918 1252
919```bash1253```bash
920npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr1254npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
991npx @openai/codex-security info --json1325npx @openai/codex-security info --json
992```1326```
993 1327
994When you expose the CLI as an MCP server, `info` is the only available command.
995Scans, exports, publication, sign-in, validation, and patching remain CLI-only.
996
997## Read scan output1328## Read scan output
998 1329
999By default, scans send progress, completion summaries, and errors to stderr1330By default, scans send progress, completion summaries, and errors to stderr
1014 1345
1015### Verbose diagnostics1346### Verbose diagnostics
1016 1347
1017Add `--verbose` to print redacted lifecycle, authentication, progress, and cost1348Add `--verbose` to print lifecycle, authentication, progress, and cost
1018diagnostics to stderr:1349diagnostics to stderr:
1019 1350
1020```bash1351```bash
1023 1354
1024Set `CODEX_SECURITY_LOG_LEVEL=debug` to enable the same diagnostics without the1355Set `CODEX_SECURITY_LOG_LEVEL=debug` to enable the same diagnostics without the
1025flag. `LOG_LEVEL=debug` also enables diagnostics when1356flag. `LOG_LEVEL=debug` also enables diagnostics when
1026`CODEX_SECURITY_LOG_LEVEL` is unset.1357`CODEX_SECURITY_LOG_LEVEL` is unset or blank.
1358
1359Codex Security preserves diagnostic text. Diagnostics can contain source code
1360or credentials, so review them before sharing.
1027 1361
1028### Completion summary1362### Completion summary
1029 1363
1030A completed scan writes its open repository finding count, severity breakdown,1364A completed scan writes its open repository finding count, severity breakdown,
1031elapsed time, report path, and result directory to stderr. It1365elapsed time, report path, and result directory to stderr. It includes token
1032includes token usage and estimated cost when available. For example:1366usage when available and estimated cost when you set `--show-cost` or
1367`--max-cost`:
1033 1368
1034```text1369```text
1035 REPORT /path/to/scan/report.md1370 REPORT /path/to/scan/report.md
1054repositoryFindings1389repositoryFindings
1055findings1390findings
1056coverage1391coverage
1392threatModel
1393threatModelPath
1057scanDir1394scanDir
1058threadId1395threadId
1059reportPath1396reportPath
1068 usage1405 usage
1069```1406```
1070 1407
1408`threatModel` contains the saved model as structured data or Markdown.
1409`threatModelPath` points to its saved document. Either can be `null`; the model
1410can still be exported if writing the document failed.
1411
1071When [patching](#patch-findings-after-a-scan), JSON output also includes patch1412When [patching](#patch-findings-after-a-scan), JSON output also includes patch
1072results and any created pull request.1413results and any created pull request.
1073 1414
1074Progress, completion summaries, archive notices, and errors remain on stderr.1415Progress, completion summaries, archive notices, and diagnostics remain on
1075A completed scan still prints the full JSON result when a severity policy1416stderr. A completed scan still prints the JSON result when a severity policy
1076returns exit `1`.1417returns exit `1`.
1077 1418
1419Always check the process exit code, even when JSON parses successfully.
1420Execution failures without returned scan results produce a structured error
1421with `status`, `code`, and `message` when using `--json`, `--format json`, or
1422`--format jsonl`. When valid scan results are retained, output can instead
1423contain the normal scan result and `warnings`, such as after a target change.
1424With `--json`, `--format json`, or `--format jsonl`, add `--full-output` to
1425receive an `ok: false` envelope with the error under `error` and any valid
1426retained sealed results under `data`. Other formats report failures only on
1427stderr, even with `--full-output`. These rules also apply to `scans rerun` and
1428`scans resume`.
1429
1078`codex-security scan --json` emits one JSON document. `codex exec --json`1430`codex-security scan --json` emits one JSON document. `codex exec --json`
1079 emits a JSON Lines event stream. Use the output format that matches the1431 emits a JSON Lines event stream.
1080 command you run.
1081 1432
1082## Scan artifacts1433## Scan artifacts
1083 1434
1091├── findings.json1442├── findings.json
1092├── coverage.json1443├── coverage.json
1093├── report.md1444├── report.md
1445├── threatmodel.md # when available
1094├── artifacts/1446├── artifacts/
1095└── exports/1447└── exports/
1096 └── results.sarif # when produced1448 └── results.sarif # when produced
1102| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |1454| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
1103| `scan-manifest.json` | Scan identity, status, target, scope, producer, and sealed artifact records. |1455| `scan-manifest.json` | Scan identity, status, target, scope, producer, and sealed artifact records. |
1104| `findings.json` | Finding identifiers, severity, confidence, taxonomy, locations, evidence, validation, data flow, reachability, and remediation. |1456| `findings.json` | Finding identifiers, severity, confidence, taxonomy, locations, evidence, validation, data flow, reachability, and remediation. |
1105| `coverage.json` | Reviewed surfaces, exclusions, deferred work, and open questions. |1457| `coverage.json` | Recorded review scope, exclusions, deferred work, and open questions. |
1106| `report.md` | Readable scan report. |1458| `report.md` | Readable scan report. |
1459| `threatmodel.md` | Saved threat model, when available. |
1107| `artifacts/` | Supporting scan artifacts. |1460| `artifacts/` | Supporting scan artifacts. |
1108| `exports/results.sarif` | SARIF generated during the scan, when present. |1461| `exports/results.sarif` | SARIF generated during the scan, when present. |
1109 1462
1110Read `scan.status` in `scan-manifest.json` for execution status: `completed`,1463### Completion and review coverage
1111`failed`, `canceled`, or `interrupted`. New results don't include1464
1112`coverage.completeness`. Review deferred surfaces, explicit exclusions, and1465A completed scan means the requested workflow finished normally. It doesn't prove that
1113open questions in `coverage.json` to understand what the scan reviewed.1466every file or attack path was reviewed. Read `coverage.json`, `report.md`, and
1467the recorded scope in `scan-manifest.json` for exclusions, deferred work, and
1468open questions. Retained input inventories describe scan inputs but don't prove
1469that every listed file was reviewed.
1470
1471Current reports omit `coverage.completeness`. Older reports may contain
1472`complete`, `partial`, or `unknown`; those legacy values no longer determine
1473the command's status or exit code. Use `manifest.scan.status` and the
1474[exit code](#exit-codes-and-signals) to distinguish execution failures from
1475findings-policy violations.
1476
1477For unresolved work, inspect the available evidence with `scans show SCAN_ID`
1478and `scans logs SCAN_ID`. An eligible interrupted Deep Scan can continue with
1479`scans resume SCAN_ID`. To start a new review with saved settings, use
1480`scans rerun SCAN_ID` when a launch recipe is available. Plugin scans may lack
1481a replayable recipe; start a new scan with the intended paths and context in
1482that case.
1114 1483
1115## Exit codes and signals1484## Exit codes and signals
1116 1485
1117The CLI uses these exit codes:1486The CLI uses these exit codes:
1118 1487
1119| Exit | Condition |1488| Exit | Condition |
1120| ----- | ----------------------------------------------------------------------------------------------------------------------------------------- |1489| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1121| `0` | A scan or bulk campaign completed and passed its severity policy, a publication completed without failures, or another command succeeded. |1490| `0` | A scan or bulk campaign completed and passed its severity policy, a publication completed without failures, or another command succeeded. |
1122| `1` | A completed scan or bulk campaign reports a finding at or above the configured severity. |1491| `1` | A completed scan or bulk campaign reports a finding at or above the configured severity, or `verify-fix` reports a finding as still vulnerable with no inconclusive results. |
1123| `2` | An input, execution, result-integrity, required-output, or export failure occurred, or a publication has one or more failed findings. |1492| `2` | An input, execution, result-integrity, required-output, or export failure occurred, a publication has one or more failed findings, or `verify-fix` reports an inconclusive result. |
1124| `130` | Ctrl-C interrupted a scan or publication. |1493| `130` | Ctrl-C interrupted a scan or publication. |
1125| `143` | SIGTERM terminated a scan or publication. |1494| `143` | SIGTERM terminated a scan or publication. |
1126 1495
1133 1502
1134## Local scan permissions1503## Local scan permissions
1135 1504
1136CLI and SDK scans run with your local operating-system permissions. Every scan1505CLI and SDK scans run with your local operating-system permissions. The scan
1137uses the `codex_security_scan` filesystem profile and sets `approvalPolicy` to1506profile permits reading the local filesystem and writing to workspace roots.
1138`"never"`. The profile permits reading the local filesystem and writing to1507Execution approvals are reviewed automatically and may grant extra permissions
1139workspace roots and the selected scan state directory. Scans don't stop to1508for an operation. Use `--codex 'approval_policy="never"'`, or set
1140request interactive approval.1509`codexOverrides.approval_policy: "never"` in the SDK, to deny permission requests. Host
1141 1510and network restrictions still apply.
1142Settings supplied through CLI `--codex` or SDK `codexOverrides`, including
1143`approval_policy`, `sandbox_mode`, and filesystem permissions, can't replace
1144or restrict these scan controls. Host and network restrictions still apply.
1145 1511
1146Scan and workbench processes can inherit your environment, including unrelated1512Scan and workbench processes can inherit your environment, including unrelated
1147API tokens and cloud credentials. Remove unrelated credentials before1513API tokens and cloud credentials. Remove unrelated credentials before
1166Python 3.10 also requires `tomli`. Use `--python` with `scan`, `bulk-scan`, or1532Python 3.10 also requires `tomli`. Use `--python` with `scan`, `bulk-scan`, or
1167`export`, or set `PYTHON` for any Python-backed command.1533`export`, or set `PYTHON` for any Python-backed command.
1168 1534
1535To read or resume compressed Codex sessions (`.jsonl.zst`), use Node.js
153622.15.0 or later within 22.x, or Node.js 24 or 26. Plain `.jsonl` sessions work
1537on all supported Node.js versions.
1538
1169Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan1539Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan
1170guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI1540guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI
1171guide](https://learn.chatgpt.com/docs/security/cli/ci), or [TypeScript SDK guide](https://learn.chatgpt.com/docs/security/sdk).1541guide](https://learn.chatgpt.com/docs/security/cli/ci), or [TypeScript SDK guide](https://learn.chatgpt.com/docs/security/sdk).
