Documentation 2026-08-13 22:59 UTC to 2026-08-14 20:01 UTC

3855npx @openai/codex-security scans rerun BASELINE_SCAN_ID3855npx @openai/codex-security scans rerun BASELINE_SCAN_ID

3856```3856```

3857 3857 

3858The rerun keeps the original scan configuration and requires the same plugin

3859version. If the installed plugin has changed, the command stops.

3860 

3858Compare the baseline with the new scan:3861Compare the baseline with the new scan:

3859 3862 

3860```bash3863```bash

3904 3907 

3905#### Automation and cost3908#### Automation and cost

3906 3909 

3910#### How do deep-scan time limits work

3911 

3912Set a discovery deadline when starting a deep scan:

3913 

3914```bash

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

3916```

3917 

3918The default is `96` hours. Use any positive value up to `96`, including

3919fractions. The limit applies only to discovery, so validation and reporting

3920can continue after the deadline. If no source review finishes, the report

3921records partial coverage and the CLI returns exit code `2`.

3922 

3923For persistent settings or bulk campaigns, set `max_time_hours` under

3924`[deep_scan]` in the [deep-scan

3925configuration](https://learn.chatgpt.com/docs/security/cli/reference#configure-deep-scans).

3926 

3907#### How do scan cost limits work3927#### How do scan cost limits work

3908 3928 

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

3913```3933```

3914 3934 

3915The limit is an estimate, not a hard spending cap. Requests already in3935The limit is an estimate, not a hard spending cap. Requests already in

3916progress can finish above the limit. Codex Security keeps available results3936progress can finish above it. If a deep scan reaches the limit after discovery

3917when the scan stops.3937finishes, the CLI saves the completed report with partial coverage and exits

3938with code `2`. Otherwise, it preserves any available partial output.

3918 3939 

3919#### Can scans check commits and pull requests3940#### Can scans check commits and pull requests

3920 3941 

3959 3980 

3960#### Check the prerequisites3981#### Check the prerequisites

3961 3982 

3962The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings3983The CLI requires Node.js 22 (22.13.0 or later), 24, or 26. Scans, bulk scans,

3963also requires Python 3.10 or later. For more detail, see [Authentication and3984exports, scan history, and saved findings also require Python 3.10 or later.

3985For more detail, see [Authentication and

3964prerequisites](https://learn.chatgpt.com/docs/security/cli/reference#authentication-and-prerequisites).3986prerequisites](https://learn.chatgpt.com/docs/security/cli/reference#authentication-and-prerequisites).

3965 3987 

3966#### Set up and verify the CLI3988#### Set up and verify the CLI

3971npx @openai/codex-security --version3993npx @openai/codex-security --version

3972```3994```

3973 3995 

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

3997 

3998```bash

3999npx @openai/codex-security info --json

4000```

4001 

3974List the available commands:4002List the available commands:

3975 4003 

3976```bash4004```bash

4021 4049 

4022#### Prepare a scan4050#### Prepare a scan

4023 4051 

4024Choose a repository to scan and a directory to write results.4052Choose a repository you trust and have permission to assess. Scans use your

4053local operating-system permissions and don't pause for approval. Scan

4054processes can inherit your environment, so remove unrelated credentials before

4055you start. See [Local scan

4056permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

4057 

4058Choose a directory outside the repository for the scan results:

4025 4059 

4026```bash4060```bash

4027REPOSITORY=/path/to/repository4061REPOSITORY=/path/to/repository

4165 --workers 2 \4199 --workers 2 \

4166 --subagents 0 \4200 --subagents 0 \

4167 --stop-after-no-new 3 \4201 --stop-after-no-new 3 \

4168 --max-discovery-runs 104202 --max-discovery-runs 10 \

4203 --max-time-hours 1.5

4169```4204```

4170 4205 

4171These options require deep mode, which supports repository and path targets,4206These options require deep mode, which supports repository and path targets,

4172not diff or working-tree scans. Here, `--workers` controls discovery workers4207not diff or working-tree scans. Here, `--workers` controls discovery workers

4173within one scan; `bulk-scan --workers` controls concurrent repository scans.4208within one scan; `bulk-scan --workers` controls concurrent repository scans.

4209`--max-time-hours` accepts a positive number up to `96`, including fractional

4210hours. When discovery reaches that limit, the scan preserves completed work

4211and continues with validation and reporting.

4174 4212 

4175#### Add architecture and security context4213#### Add architecture and security context

4176 4214 

4196```4234```

4197 4235 

4198The follow-up runs in the same authenticated session after successful scans4236The follow-up runs in the same authenticated session after successful scans

4199and scans with incomplete coverage or errors. It doesn't run after cancellation4237and scans with incomplete coverage or errors. If the follow-up fails, the CLI

4200or a scan that reaches its cost limit. Both options also work with4238reports a warning and keeps the completed scan. It doesn't run after

4201`bulk-scan`; a CSV `prompt` column adds repository-specific instructions.4239cancellation or a scan that reaches its cost limit. Both options also work

4240with `bulk-scan`; a CSV `prompt` column adds repository-specific instructions.

4202 4241 

4203#### Set a scan budget4242#### Set a scan budget

4204 4243 

4209npx @openai/codex-security scan "$REPOSITORY" --max-cost 54248npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

4210```4249```

4211 4250 

4212Requests already in progress can finish slightly above the limit. If a scan4251Requests already in progress can finish slightly above the limit. If a deep

4213aborts due to the cost limit, partial scan results remain available on disk.4252scan reaches the limit after discovery finishes, the CLI saves the completed

4253report, marks its coverage as `partial`, and returns exit code `2`. If the

4254scan can't produce a completed report, any available partial output stays on

4255disk.

4214 4256 

4215#### Scan changes before each commit4257#### Scan changes before each commit

4216 4258 

4359[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).4401[CLI quickstart](https://learn.chatgpt.com/docs/security/cli).

4360 4402 

4361The `@openai/codex-security` package is public. Running scans requires Codex4403The `@openai/codex-security` package is public. Running scans requires Codex

4362Security access.4404Security access. Scans use your local permissions and don't pause for

4405approval. Before you start, review [Local scan

4406permissions](#local-scan-permissions).

4363 4407 

4364Run the CLI with `npx @openai/codex-security`.4408Run the CLI with `npx @openai/codex-security`.

4365 4409 

4465 [--post-scan-prompt-file FILE]4509 [--post-scan-prompt-file FILE]

4466 [--mode {standard,deep}] [--workers N]4510 [--mode {standard,deep}] [--workers N]

4467 [--subagents N] [--stop-after-no-new N]4511 [--subagents N] [--stop-after-no-new N]

4468 [--max-discovery-runs N] [--model MODEL]4512 [--max-discovery-runs N] [--max-time-hours HOURS]

4513 [--model MODEL]

4469 [--effort {minimal,low,medium,high,xhigh}]4514 [--effort {minimal,low,medium,high,xhigh}]

4470 [--output-dir DIR]4515 [--output-dir DIR]

4471 [--archive-existing]4516 [--archive-existing]

4601| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |4646| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |

4602| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |4647| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |

4603| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |4648| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |

4649| `--max-time-hours HOURS` | Discovery time limit in hours. Defaults to `96`; accepts fractions. |

4604 4650 

4605`--subagents` accepts zero or a positive integer. The other options require a4651`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a

4606positive integer. These options aren't available for standard scans.4652positive number no greater than `96`. The remaining options require a positive

4653integer. These options aren't available for standard scans.

4607 4654 

4608For example, limit a deep scan to two discovery workers and ten total runs:4655For example, use two discovery workers, allow up to ten runs, and stop

4656discovery after 1.5 hours:

4609 4657 

4610```bash4658```bash

4611npx @openai/codex-security scan . \4659npx @openai/codex-security scan . \

4613 --workers 2 \4661 --workers 2 \

4614 --subagents 0 \4662 --subagents 0 \

4615 --stop-after-no-new 3 \4663 --stop-after-no-new 3 \

4616 --max-discovery-runs 104664 --max-discovery-runs 10 \

4665 --max-time-hours 1.5

4617```4666```

4618 4667 

4668The time limit applies only to discovery. When it expires, the scan stops

4669unfinished discovery, keeps completed discovery results, and continues with

4670validation and reporting. If no source review finishes, the scan records

4671partial coverage and returns exit code `2`.

4672 

4619Set persistent defaults in `~/.codex/codex-security/config.toml`, or in4673Set persistent defaults in `~/.codex/codex-security/config.toml`, or in

4620`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:4674`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:

4621 4675 

4625subagents = 04679subagents = 0

4626stop_after_no_new = 34680stop_after_no_new = 3

4627max_discovery_runs = 104681max_discovery_runs = 10

4682max_time_hours = 1.5

4628```4683```

4629 4684 

4630Command-line options override these defaults. `scan --workers` controls4685Command-line options override these defaults. `scan --workers` controls

4631discovery workers within one scan; `bulk-scan --workers` controls concurrent4686discovery workers within one scan; `bulk-scan --workers` controls concurrent

4632repository scans.4687repository scans. Set `stop_after_consecutive_errors` only in the TOML file;

4688its default is `3`.

4633 4689 

4634#### Add security context4690#### Add security context

4635 4691 

4662 4718 

4663For example, use the scan prompt to focus on authorization boundaries and ask4719For example, use the scan prompt to focus on authorization boundaries and ask

4664the follow-up to write a new `post-scan-summary.md` in the scan directory.4720the follow-up to write a new `post-scan-summary.md` in the scan directory.

4721If the follow-up fails, the CLI reports a warning and keeps the completed scan.

4665The follow-up doesn't run after cancellation or when the scan reaches its cost4722The follow-up doesn't run after cancellation or when the scan reaches its cost

4666limit.4723limit.

4667 4724 

4684| `--full-output` | Print the complete result using the default structured output format. |4741| `--full-output` | Print the complete result using the default structured output format. |

4685 4742 

4686The cost limit is an estimate, not a hard spending cap. Requests already in4743The cost limit is an estimate, not a hard spending cap. Requests already in

4687progress can finish slightly above the limit. If a scan aborts due to the cost4744progress can finish slightly above the limit. If a deep scan reaches the limit

4688limit, partial scan results remain available on disk.4745after discovery finishes, the CLI seals the available results, marks coverage

4746as `partial`, and returns exit code `2`. Otherwise, it returns `2` and leaves

4747any available partial output on disk.

4689 4748 

4690When you omit `--output-dir`, results persist under4749When you omit `--output-dir`, results persist under

4691`$CODEX_HOME/state/plugins/codex-security/scans/`. `CODEX_HOME`4750`$CODEX_HOME/state/plugins/codex-security/scans/`. `CODEX_HOME`

4882npx @openai/codex-security scans rerun SCAN_ID4941npx @openai/codex-security scans rerun SCAN_ID

4883```4942```

4884 4943 

4944The rerun requires the plugin version recorded by the original scan. If the

4945installed version differs, the command stops instead of running with a

4946different plugin.

4947 

4885#### Inspect saved scan logs4948#### Inspect saved scan logs

4886 4949 

4887Read the complete saved session events for a scan and its workers:4950Read the complete saved session events for a scan and its workers. These logs

4951aren't redacted and can contain source code or credentials, so review them

4952before sharing:

4888 4953 

4889```bash4954```bash

4890npx @openai/codex-security scans logs SCAN_ID4955npx @openai/codex-security scans logs SCAN_ID

5241write the available results to stdout. The CLI prints the location of any5306write the available results to stdout. The CLI prints the location of any

5242partial output after an interruption or runtime error.5307partial output after an interruption or runtime error.

5243 5308 

5309#### Local scan permissions

5310 

5311CLI and SDK scans run with your local operating-system permissions. Every scan

5312uses the `codex_security_scan` filesystem profile and sets `approvalPolicy` to

5313`"never"`. The profile permits reading the local filesystem and writing to

5314workspace roots and the selected scan state directory. Scans don't stop to

5315request interactive approval.

5316 

5317Settings supplied through CLI `--codex` or SDK `codexOverrides`, including

5318`approval_policy`, `sandbox_mode`, and filesystem permissions, can't replace

5319or restrict these scan controls. Host and network restrictions still apply.

5320 

5321Scan and workbench processes can inherit your environment, including unrelated

5322API tokens and cloud credentials. Scan only repositories you trust and have

5323permission to assess, and provide only the credentials the scan requires.

5324 

5244#### Authentication and prerequisites5325#### Authentication and prerequisites

5245 5326 

5246Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with5327Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with

5254 5335 

5255For CI, keep the API key scoped to the scan step and use a trusted workflow.5336For CI, keep the API key scoped to the scan step and use a trusted workflow.

5256 5337 

5257The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings5338The CLI requires Node.js 22 (22.13.0 or later), 24, or 26. Scans, bulk scans,

5258also requires Python 3.10 or later. Python 3.10 also requires `tomli`. Use5339exports, scan history, and saved findings also require Python 3.10 or later.

5259`--python` or `PYTHON` to select an interpreter when automatic discovery is5340Python 3.10 also requires `tomli`. Use `--python` with `scan`, `bulk-scan`, or

5260unsuitable.5341`export`, or set `PYTHON` for any Python-backed command.

5261 5342 

5262Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan5343Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan

5263guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI5344guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI

5477 5558 

5478Source: [Codex Security plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog.md)5559Source: [Codex Security plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog.md)

5479 5560 

5480Use this changelog to see what changed in Codex Security and which plugin5561Use this changelog to see what changed in the Codex Security plugin.

5481versions are available from each installation source.

5482 5562 

5483**Latest release in the hosted Codex Security catalog:** `0.1.18`.5563**Latest plugin version:** `0.1.19`.

5484 5564 

5485Check the plugin version in your current Codex environment before you use a5565Check the plugin version in your current Codex environment before you use a

5486feature from a newer release. Reopening or rerunning a saved scan doesn't pin5566feature from a newer release.

5487the installed plugin version.5567 

5568Changelog entries follow the plugin version, not the package version. CLI and

5569SDK users can run `npx @openai/codex-security info --json` to check the

5570package and bundled plugin versions together.

5571 

5572#### 0.1.19 (August 13, 2026)

5573 

5574#### Set a time limit for deep scans

5488 5575 

5489These versions apply to the Codex Security plugin. The Codex app, Codex CLI,5576- Set `[deep_scan].max_time_hours` to a positive duration of up to 96 hours.

5490TypeScript SDK, and plugin app have separate version numbers.5577 You can use fractional hours.

5578- Keep completed discovery results when the deadline expires, then continue

5579 with validation and reporting.

5580- Mark the report as partial if no source review finishes before the deadline.

5581 

5582#### Improve scan reliability

5583 

5584- Keep completed discovery work when a worker stops or a reducer retries.

5585- Read larger source files and generate reports without the previous fixed

5586 size limits.

5587- Read committed changes from the selected revision and preserve

5588 repository-relative paths on Windows.

5589- Pass OpenRouter and Fireworks credentials to deep-scan workers.

5491 5590 

5492#### 0.1.18 (August 7, 2026)5591#### 0.1.18 (August 7, 2026)

5493 5592 

5834To install Codex Security for a local repository, use the ChatGPT desktop app5933To install Codex Security for a local repository, use the ChatGPT desktop app

5835or Codex CLI.5934or Codex CLI.

5836 5935 

5837The hosted desktop-app catalog and public Codex CLI marketplace can offer5936Check the [plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you rely

5838different plugin versions. Check the [plugin5937on a feature or start a long-running scan. If **Security** doesn't appear in

5839changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you rely on a feature or5938the desktop-app sidebar, update the app and plugin and confirm that the plugin

5840start a long-running scan. If **Security** doesn't appear in the desktop-app5939is enabled.

5841sidebar, update the app and plugin and confirm that the plugin is enabled.

5842 5940 

5843#### Run your first scan5941#### Run your first scan

5844 5942 

5962findings, coverage details, and paths to scan artifacts. For longer scans, it6060findings, coverage details, and paths to scan artifacts. For longer scans, it

5963supports preflight checks, cost limits, progress callbacks, and cancellation.6061supports preflight checks, cost limits, progress callbacks, and cancellation.

5964 6062 

5965The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22.13.06063The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22

5966or later. Scanning also requires Python 3.10 or later.6064(22.13.0 or later), 24, or 26. Scanning also requires Python 3.10 or later.

6065Python 3.10 also requires the `tomli` package.

5967 6066 

5968The Codex Security SDK is [publicly available on6067The Codex Security SDK is [publicly available on

5969GitHub](https://github.com/openai/codex-security). Running scans requires6068GitHub](https://github.com/openai/codex-security). Running scans requires

5991 6090 

5992#### Run a scan6091#### Run a scan

5993 6092 

6093Scan only repositories you trust and have permission to assess. The SDK runs

6094with your local operating-system permissions and never pauses for approval.

6095Scan processes can inherit your environment, so remove unrelated credentials

6096before you start. See [Local scan

6097permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

6098 

5994Create one `CodexSecurity` client, run a standard repository scan, and close6099Create one `CodexSecurity` client, run a standard repository scan, and close

5995the client when the work completes. Pass `outputDir` to choose a private6100the client when the work completes. Pass `outputDir` to choose a private

5996results directory outside the enclosing Git worktree.6101results directory outside the enclosing Git worktree.

6134 subagents: 0,6239 subagents: 0,

6135 stopAfterNoNew: 3,6240 stopAfterNoNew: 3,

6136 maxDiscoveryRuns: 10,6241 maxDiscoveryRuns: 10,

6242 maxTimeHours: 1.5,

6137});6243});

6138```6244```

6139 6245 

6140Deep mode supports repository and path targets. Use standard mode for diff and6246Deep mode supports repository and path targets. Use standard mode for diff and

6141working-tree scans. The optional settings control concurrent discovery workers,6247working-tree scans. The optional settings control concurrent discovery workers,

6142subagents per worker, consecutive discovery runs without new findings, and the6248subagents per worker, consecutive discovery runs without new findings, and the

6143total number of discovery runs. They require `mode: "deep"`.6249total number and duration of discovery runs. They require `mode: "deep"`.

6250 

6251`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,

6252including fractional hours. At the deadline, Codex Security stops unfinished

6253discovery, keeps completed discovery results, and continues with validation

6254and reporting. Review `result.coverage.completeness` before treating a

6255time-limited scan as evidence of full coverage.

6144 6256 

6145#### Add a security knowledge base6257#### Add a security knowledge base

6146 6258 

6172});6284});

6173```6285```

6174 6286 

6287If the follow-up fails, the SDK keeps the completed scan and reports the

6288error through `onWarning`. It restores any completed scan artifacts that the

6289follow-up changed.

6290 

6175#### Set a scan budget6291#### Set a scan budget

6176 6292 

6177Set `maxCostUsd` to stop a scan when its estimated model cost exceeds a limit.6293Set `maxCostUsd` to stop a scan when its estimated model cost exceeds a limit.

6189```6305```

6190 6306 

6191The limit estimates spending but isn't a hard cap, so requests already in6307The limit estimates spending but isn't a hard cap, so requests already in

6192progress can finish slightly above it. If the scan exceeds the limit, the SDK6308progress can finish slightly above it. If a deep scan reaches the limit after

6193throws `ScanCostLimitExceededError` and preserves the available results.6309discovery finishes, `run` returns a result with `coverage.completeness` set to

6310`"partial"` and reports the budget warning through `onWarning`.

6311 

6312If the scan can't produce a completed partial result, `run` throws

6313`ScanCostLimitExceededError` and preserves any available output.

6194 6314 

6195#### Work with scan results6315#### Work with scan results

6196 6316 

6215| `sarifPath` | The generated SARIF path, or `null` when SARIF is absent. |6335| `sarifPath` | The generated SARIF path, or `null` when SARIF is absent. |

6216| `pluginVersion` | The version recorded by the scan producer. |6336| `pluginVersion` | The version recorded by the scan producer. |

6217 6337 

6338To require the same plugin for a later scan, pass

6339`expectedPluginVersion: result.pluginVersion`. The SDK rejects the scan if

6340the installed plugin version differs.

6341 

6218Use the structured findings and coverage directly:6342Use the structured findings and coverage directly:

6219 6343 

6220```ts6344```ts

6352Bedrock](https://learn.chatgpt.com/docs/security/cli/reference#use-amazon-bedrock), set6476Bedrock](https://learn.chatgpt.com/docs/security/cli/reference#use-amazon-bedrock), set

6353`model_provider` and `model` in `codexOverrides`.6477`model_provider` and `model` in `codexOverrides`.

6354 6478 

6479`codexOverrides` can't restrict the scan's filesystem access or change its

6480approval policy. See [Local scan

6481permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

6482 

6355For OpenRouter or Fireworks, also provide the matching API key and a complete6483For OpenRouter or Fireworks, also provide the matching API key and a complete

6356provider configuration in `codexOverrides`. For example, set6484provider configuration in `codexOverrides`. For example, set

6357`OPENROUTER_API_KEY` and configure OpenRouter:6485`OPENROUTER_API_KEY` and configure OpenRouter:

6891codex plugin add codex-security@openai-curated7019codex plugin add codex-security@openai-curated

6892```7020```

6893 7021 

6894The install command uses the public Codex CLI plugin marketplace, which can7022The install command uses the public Codex CLI plugin marketplace. Check the

6895offer a different version from the hosted desktop-app catalog. Check the

6896[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you depend on a7023[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you depend on a

6897specific plugin version or feature in CI.7024specific plugin version or feature in CI.

6898 7025 

7343subagents = 07470subagents = 0

7344stop_after_no_new = 37471stop_after_no_new = 3

7345max_discovery_runs = 107472max_discovery_runs = 10

7473max_time_hours = 1.5

7346```7474```

7347 7475 

7348| Setting | Default | Description |7476| Setting | Default | Description |

7349| -------------------- | ------- | ------------------------------------------------------------------------------------------------ |7477| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |

7350| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |7478| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |

7351| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |7479| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |

7352| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |7480| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |

7481| `stop_after_consecutive_errors` | `3` | Stop discovery after this many consecutive worker errors. |

7353| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |7482| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |

7483| `max_time_hours` | `96` | Limit discovery to a positive number of hours up to `96`; use fractions as needed. |

7354 7484 

7355Lower values can reduce scan time and token use but may miss findings.7485Lower values can reduce scan time and token use but may miss findings.

7356Configuration changes apply to new deep scans, not scans already in progress.7486Configuration changes apply to new deep scans, not scans already in progress.

7357 7487 

7488The time limit applies only to discovery. When it expires, Codex Security

7489stops unfinished discovery, keeps completed results, and continues with

7490validation and reporting. If no source review finishes before the deadline,

7491the report records partial coverage.

7492 

7493The `max_time_hours` setting requires plugin version `0.1.19` or later. See the

7494[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.

7495 

7358#### Start the deep scan7496#### Start the deep scan

7359 7497 

7360In the desktop app, open **Security**, select **Scans**, and select **+ Scan**.7498In the desktop app, open **Security**, select **Scans**, and select **+ Scan**.

7529Use `--mode deep` to select deep scanning for rows without their own `mode`.7667Use `--mode deep` to select deep scanning for rows without their own `mode`.

7530Each CSV row can still choose its own scan mode and repository scope.7668Each CSV row can still choose its own scan mode and repository scope.

7531 7669 

7670Set `[deep_scan].max_time_hours` to limit discovery for each deep scan in the

7671campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.

7672 

7532The CLI checks out each pinned revision, scans the selected target, records the7673The CLI checks out each pinned revision, scans the selected target, records the

7533result, and removes the temporary repository checkout. A repository counts as7674result, and removes the temporary repository checkout. A repository counts as

7534complete only when its scan has complete coverage and all required result7675complete only when its scan has complete coverage and all required result

7733variable. Keep the credential scoped to the scan process and use7874variable. Keep the credential scoped to the scan process and use

7734`--auth api-key` to select it explicitly.7875`--auth api-key` to select it explicitly.

7735 7876 

7877Run the workflow only for repositories and pull requests you trust. Scans use

7878the runner's local permissions and don't pause for approval. Scan processes

7879can inherit the job environment, so keep unrelated tokens and cloud

7880credentials out of it.

7881 

7736The runner needs:7882The runner needs:

7737 7883 

7738- Node.js 22.13.0 or later.7884- Node.js 22 (22.13.0 or later), 24, or 26.

7739- Python 3.10 or later.7885- Python 3.10 or later.

7740- The published `@openai/codex-security` package, installed outside the7886- The published `@openai/codex-security` package, installed outside the

7741 repository checkout.7887 repository checkout.

19737 19883 

19738If you support CIMD, set `client_id_metadata_document_supported: true` in your authorization server metadata. This lets ChatGPT use one stable client identity for connectors that choose CIMD, which your authorization server can use for redirect URI allowlists, rate limits, and other policies.19884If you support CIMD, set `client_id_metadata_document_supported: true` in your authorization server metadata. This lets ChatGPT use one stable client identity for connectors that choose CIMD, which your authorization server can use for redirect URI allowlists, rate limits, and other policies.

19739 19885 

19740ChatGPT's production CIMD document advertises both supported client authentication methods using the [OpenID Connect RP Metadata Choices](https://openid.net/specs/openid-connect-rp-metadata-choices-1_0-final.html) client metadata field:19886ChatGPT is adopting the CIMD transition proposed in

19887[MCP SEP-3149](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3149).

19888Its production CIMD document publishes

19889`token_endpoint_auth_methods_supported` as an array of methods that ChatGPT

19890can use, with no preference order. During the transition, it also publishes

19891the legacy singular `token_endpoint_auth_method` as a preference:

19741 19892 

19742```json19893```json

19743{19894{

19744 "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"]19895 "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],

19896 "token_endpoint_auth_method": "private_key_jwt"

19745}19897}

19746```19898```

19747 19899 

19748The same field name has different perspectives in the two documents: in authorization server metadata, it lists the methods your token endpoint accepts; in ChatGPT's CIMD document, it lists the methods ChatGPT can use. The `client_id` URL is stable and does not use query parameters to select a method-specific document. At runtime, ChatGPT compares both lists and prefers the stronger `private_key_jwt` method when your authorization server supports it; otherwise, it uses `none`.19900The plural field has different perspectives in the two documents:

19901authorization server metadata lists the methods your token endpoint accepts,

19902while ChatGPT's CIMD document lists the methods ChatGPT can use. ChatGPT

19903selects a method from the intersection of those sets. When the singular legacy

19904preference is in the intersection, ChatGPT uses it for compatibility with

19905authorization servers that still treat the singular field as binding.

19906Otherwise, ChatGPT can use another method in the intersection.

19907 

19908Authorization servers that read the plural CIMD field should accept any method

19909in the intersection unless local security policy disallows that method for the

19910client. They must reject methods outside the intersection. The `client_id` URL

19911stays stable and does not use query parameters to select a method-specific

19912document.

19749 19913 

19750The supported methods are:19914The supported methods are:

19751 19915 

14 14 

15## Check the prerequisites15## Check the prerequisites

16 16 

17The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings17The CLI requires Node.js 22 (22.13.0 or later), 24, or 26. Scans, bulk scans,

18also requires Python 3.10 or later. For more detail, see [Authentication and18exports, scan history, and saved findings also require Python 3.10 or later.

19For more detail, see [Authentication and

19prerequisites](https://learn.chatgpt.com/docs/security/cli/reference#authentication-and-prerequisites).20prerequisites](https://learn.chatgpt.com/docs/security/cli/reference#authentication-and-prerequisites).

20 21 

21## Set up and verify the CLI22## Set up and verify the CLI

26npx @openai/codex-security --version27npx @openai/codex-security --version

27```28```

28 29 

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

31 

32```bash

33npx @openai/codex-security info --json

34```

35 

29List the available commands:36List the available commands:

30 37 

31```bash38```bash

76 83 

77## Prepare a scan84## Prepare a scan

78 85 

79Choose a repository to scan and a directory to write results.86Choose a repository you trust and have permission to assess. Scans use your

87local operating-system permissions and don't pause for approval. Scan

88processes can inherit your environment, so remove unrelated credentials before

89you start. See [Local scan

90permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

91 

92Choose a directory outside the repository for the scan results:

80 93 

81```bash94```bash

82REPOSITORY=/path/to/repository95REPOSITORY=/path/to/repository

220 --workers 2 \233 --workers 2 \

221 --subagents 0 \234 --subagents 0 \

222 --stop-after-no-new 3 \235 --stop-after-no-new 3 \

223 --max-discovery-runs 10236 --max-discovery-runs 10 \

237 --max-time-hours 1.5

224```238```

225 239 

226These options require deep mode, which supports repository and path targets,240These options require deep mode, which supports repository and path targets,

227not diff or working-tree scans. Here, `--workers` controls discovery workers241not diff or working-tree scans. Here, `--workers` controls discovery workers

228within one scan; `bulk-scan --workers` controls concurrent repository scans.242within one scan; `bulk-scan --workers` controls concurrent repository scans.

243`--max-time-hours` accepts a positive number up to `96`, including fractional

244hours. When discovery reaches that limit, the scan preserves completed work

245and continues with validation and reporting.

229 246 

230## Add architecture and security context247## Add architecture and security context

231 248 

251```268```

252 269 

253The follow-up runs in the same authenticated session after successful scans270The follow-up runs in the same authenticated session after successful scans

254and scans with incomplete coverage or errors. It doesn't run after cancellation271and scans with incomplete coverage or errors. If the follow-up fails, the CLI

255or a scan that reaches its cost limit. Both options also work with272reports a warning and keeps the completed scan. It doesn't run after

256`bulk-scan`; a CSV `prompt` column adds repository-specific instructions.273cancellation or a scan that reaches its cost limit. Both options also work

274with `bulk-scan`; a CSV `prompt` column adds repository-specific instructions.

257 275 

258## Set a scan budget276## Set a scan budget

259 277 

264npx @openai/codex-security scan "$REPOSITORY" --max-cost 5282npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

265```283```

266 284 

267Requests already in progress can finish slightly above the limit. If a scan285Requests already in progress can finish slightly above the limit. If a deep

268aborts due to the cost limit, partial scan results remain available on disk.286scan reaches the limit after discovery finishes, the CLI saves the completed

287report, marks its coverage as `partial`, and returns exit code `2`. If the

288scan can't produce a completed report, any available partial output stays on

289disk.

269 290 

270## Scan changes before each commit291## Scan changes before each commit

271 292 

106Use `--mode deep` to select deep scanning for rows without their own `mode`.106Use `--mode deep` to select deep scanning for rows without their own `mode`.

107Each CSV row can still choose its own scan mode and repository scope.107Each CSV row can still choose its own scan mode and repository scope.

108 108 

109Set `[deep_scan].max_time_hours` to limit discovery for each deep scan in the

110campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.

111 

109The CLI checks out each pinned revision, scans the selected target, records the112The CLI checks out each pinned revision, scans the selected target, records the

110result, and removes the temporary repository checkout. A repository counts as113result, and removes the temporary repository checkout. A repository counts as

111complete only when its scan has complete coverage and all required result114complete only when its scan has complete coverage and all required result

22variable. Keep the credential scoped to the scan process and use22variable. Keep the credential scoped to the scan process and use

23`--auth api-key` to select it explicitly.23`--auth api-key` to select it explicitly.

24 24 

25Run the workflow only for repositories and pull requests you trust. Scans use

26the runner's local permissions and don't pause for approval. Scan processes

27can inherit the job environment, so keep unrelated tokens and cloud

28credentials out of it.

29 

25The runner needs:30The runner needs:

26 31 

27- Node.js 22.13.0 or later.32- Node.js 22 (22.13.0 or later), 24, or 26.

28- Python 3.10 or later.33- Python 3.10 or later.

29- The published `@openai/codex-security` package, installed outside the34- The published `@openai/codex-security` package, installed outside the

30 repository checkout.35 repository checkout.

183npx @openai/codex-security scans rerun BASELINE_SCAN_ID183npx @openai/codex-security scans rerun BASELINE_SCAN_ID

184```184```

185 185 

186The rerun keeps the original scan configuration and requires the same plugin

187version. If the installed plugin has changed, the command stops.

188 

186Compare the baseline with the new scan:189Compare the baseline with the new scan:

187 190 

188```bash191```bash

232 235 

233## Automation and cost236## Automation and cost

234 237 

238### How do deep-scan time limits work

239 

240Set a discovery deadline when starting a deep scan:

241 

242```bash

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

244```

245 

246The default is `96` hours. Use any positive value up to `96`, including

247fractions. The limit applies only to discovery, so validation and reporting

248can continue after the deadline. If no source review finishes, the report

249records partial coverage and the CLI returns exit code `2`.

250 

251For persistent settings or bulk campaigns, set `max_time_hours` under

252`[deep_scan]` in the [deep-scan

253configuration](https://learn.chatgpt.com/docs/security/cli/reference#configure-deep-scans).

254 

235### How do scan cost limits work255### How do scan cost limits work

236 256 

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

241```261```

242 262 

243The limit is an estimate, not a hard spending cap. Requests already in263The limit is an estimate, not a hard spending cap. Requests already in

244progress can finish above the limit. Codex Security keeps available results264progress can finish above it. If a deep scan reaches the limit after discovery

245when the scan stops.265finishes, the CLI saves the completed report with partial coverage and exits

266with code `2`. Otherwise, it preserves any available partial output.

246 267 

247### Can scans check commits and pull requests268### Can scans check commits and pull requests

248 269 

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. Running scans requires Codex9The `@openai/codex-security` package is public. Running scans requires Codex

10 Security access.10 Security access. Scans use your local permissions and don't pause for

11 approval. Before you start, review [Local scan

12 permissions](#local-scan-permissions).

11 13 

12Run the CLI with `npx @openai/codex-security`.14Run the CLI with `npx @openai/codex-security`.

13 15 

113 [--post-scan-prompt-file FILE]115 [--post-scan-prompt-file FILE]

114 [--mode {standard,deep}] [--workers N]116 [--mode {standard,deep}] [--workers N]

115 [--subagents N] [--stop-after-no-new N]117 [--subagents N] [--stop-after-no-new N]

116 [--max-discovery-runs N] [--model MODEL]118 [--max-discovery-runs N] [--max-time-hours HOURS]

119 [--model MODEL]

117 [--effort {minimal,low,medium,high,xhigh}]120 [--effort {minimal,low,medium,high,xhigh}]

118 [--output-dir DIR]121 [--output-dir DIR]

119 [--archive-existing]122 [--archive-existing]

249| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |252| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |

250| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |253| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |

251| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |254| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |

255| `--max-time-hours HOURS` | Discovery time limit in hours. Defaults to `96`; accepts fractions. |

252 256 

253`--subagents` accepts zero or a positive integer. The other options require a257`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a

254positive integer. These options aren't available for standard scans.258positive number no greater than `96`. The remaining options require a positive

259integer. These options aren't available for standard scans.

255 260 

256For example, limit a deep scan to two discovery workers and ten total runs:261For example, use two discovery workers, allow up to ten runs, and stop

262discovery after 1.5 hours:

257 263 

258```bash264```bash

259npx @openai/codex-security scan . \265npx @openai/codex-security scan . \

261 --workers 2 \267 --workers 2 \

262 --subagents 0 \268 --subagents 0 \

263 --stop-after-no-new 3 \269 --stop-after-no-new 3 \

264 --max-discovery-runs 10270 --max-discovery-runs 10 \

271 --max-time-hours 1.5

265```272```

266 273 

274The time limit applies only to discovery. When it expires, the scan stops

275unfinished discovery, keeps completed discovery results, and continues with

276validation and reporting. If no source review finishes, the scan records

277partial coverage and returns exit code `2`.

278 

267Set persistent defaults in `~/.codex/codex-security/config.toml`, or in279Set persistent defaults in `~/.codex/codex-security/config.toml`, or in

268`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:280`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:

269 281 

273subagents = 0285subagents = 0

274stop_after_no_new = 3286stop_after_no_new = 3

275max_discovery_runs = 10287max_discovery_runs = 10

288max_time_hours = 1.5

276```289```

277 290 

278Command-line options override these defaults. `scan --workers` controls291Command-line options override these defaults. `scan --workers` controls

279discovery workers within one scan; `bulk-scan --workers` controls concurrent292discovery workers within one scan; `bulk-scan --workers` controls concurrent

280repository scans.293repository scans. Set `stop_after_consecutive_errors` only in the TOML file;

294its default is `3`.

281 295 

282### Add security context296### Add security context

283 297 

310 324 

311For example, use the scan prompt to focus on authorization boundaries and ask325For example, use the scan prompt to focus on authorization boundaries and ask

312the follow-up to write a new `post-scan-summary.md` in the scan directory.326the follow-up to write a new `post-scan-summary.md` in the scan directory.

327If the follow-up fails, the CLI reports a warning and keeps the completed scan.

313The follow-up doesn't run after cancellation or when the scan reaches its cost328The follow-up doesn't run after cancellation or when the scan reaches its cost

314limit.329limit.

315 330 

332| `--full-output` | Print the complete result using the default structured output format. |347| `--full-output` | Print the complete result using the default structured output format. |

333 348 

334The cost limit is an estimate, not a hard spending cap. Requests already in349The cost limit is an estimate, not a hard spending cap. Requests already in

335progress can finish slightly above the limit. If a scan aborts due to the cost350progress can finish slightly above the limit. If a deep scan reaches the limit

336limit, partial scan results remain available on disk.351after discovery finishes, the CLI seals the available results, marks coverage

352as `partial`, and returns exit code `2`. Otherwise, it returns `2` and leaves

353any available partial output on disk.

337 354 

338When you omit `--output-dir`, results persist under355When you omit `--output-dir`, results persist under

339`$CODEX_HOME/state/plugins/codex-security/scans/<repository>`. `CODEX_HOME`356`$CODEX_HOME/state/plugins/codex-security/scans/<repository>`. `CODEX_HOME`

530npx @openai/codex-security scans rerun SCAN_ID547npx @openai/codex-security scans rerun SCAN_ID

531```548```

532 549 

550The rerun requires the plugin version recorded by the original scan. If the

551installed version differs, the command stops instead of running with a

552different plugin.

553 

533### Inspect saved scan logs554### Inspect saved scan logs

534 555 

535Read the complete saved session events for a scan and its workers:556Read the complete saved session events for a scan and its workers. These logs

557aren't redacted and can contain source code or credentials, so review them

558before sharing:

536 559 

537```bash560```bash

538npx @openai/codex-security scans logs SCAN_ID561npx @openai/codex-security scans logs SCAN_ID

889write the available results to stdout. The CLI prints the location of any912write the available results to stdout. The CLI prints the location of any

890partial output after an interruption or runtime error.913partial output after an interruption or runtime error.

891 914 

915## Local scan permissions

916 

917CLI and SDK scans run with your local operating-system permissions. Every scan

918uses the `codex_security_scan` filesystem profile and sets `approvalPolicy` to

919`"never"`. The profile permits reading the local filesystem and writing to

920workspace roots and the selected scan state directory. Scans don't stop to

921request interactive approval.

922 

923Settings supplied through CLI `--codex` or SDK `codexOverrides`, including

924`approval_policy`, `sandbox_mode`, and filesystem permissions, can't replace

925or restrict these scan controls. Host and network restrictions still apply.

926 

927Scan and workbench processes can inherit your environment, including unrelated

928API tokens and cloud credentials. Scan only repositories you trust and have

929permission to assess, and provide only the credentials the scan requires.

930 

892## Authentication and prerequisites931## Authentication and prerequisites

893 932 

894Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with933Set `OPENAI_API_KEY` or `CODEX_API_KEY`, sign in with

902 941 

903For CI, keep the API key scoped to the scan step and use a trusted workflow.942For CI, keep the API key scoped to the scan step and use a trusted workflow.

904 943 

905The CLI requires Node.js 22.13.0 or later. Running a scan or exporting findings944The CLI requires Node.js 22 (22.13.0 or later), 24, or 26. Scans, bulk scans,

906also requires Python 3.10 or later. Python 3.10 also requires `tomli`. Use945exports, scan history, and saved findings also require Python 3.10 or later.

907`--python` or `PYTHON` to select an interpreter when automatic discovery is946Python 3.10 also requires `tomli`. Use `--python` with `scan`, `bulk-scan`, or

908unsuitable.947`export`, or set `PYTHON` for any Python-backed command.

909 948 

910Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan949Continue with the [CLI quickstart](https://learn.chatgpt.com/docs/security/cli), [bulk-scan

911guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI950guide](https://learn.chatgpt.com/docs/security/cli/bulk-scans), [CLI FAQ](https://learn.chatgpt.com/docs/security/cli/faq), [CI

55 55 

56 56 

57 57 

58The hosted desktop-app catalog and public Codex CLI marketplace can offer58Check the [plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you rely

59 different plugin versions. Check the [plugin59 on a feature or start a long-running scan. If **Security** doesn't appear in

60 changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you rely on a feature or60 the desktop-app sidebar, update the app and plugin and confirm that the plugin

61 start a long-running scan. If **Security** doesn't appear in the desktop-app61 is enabled.

62 sidebar, update the app and plugin and confirm that the plugin is enabled.

63 62 

64## Run your first scan63## Run your first scan

65 64 

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 changelog to see what changed in Codex Security and which plugin5Use this changelog to see what changed in the Codex Security plugin.

6versions are available from each installation source.

7 6 

8**Latest release in the hosted Codex Security catalog:** `0.1.18`.7**Latest plugin version:** `0.1.19`.

9 8 

10Check the plugin version in your current Codex environment before you use a9Check the plugin version in your current Codex environment before you use a

11feature from a newer release. Reopening or rerunning a saved scan doesn't pin10feature from a newer release.

12the installed plugin version.

13 11 

14These versions apply to the Codex Security plugin. The Codex app, Codex CLI,12Changelog entries follow the plugin version, not the package version. CLI and

15TypeScript SDK, and plugin app have separate version numbers.13SDK users can run `npx @openai/codex-security info --json` to check the

14package and bundled plugin versions together.

15 

16## 0.1.19 (August 13, 2026)

17 

18### Set a time limit for deep scans

19 

20- Set `[deep_scan].max_time_hours` to a positive duration of up to 96 hours.

21 You can use fractional hours.

22- Keep completed discovery results when the deadline expires, then continue

23 with validation and reporting.

24- Mark the report as partial if no source review finishes before the deadline.

25 

26### Improve scan reliability

27 

28- Keep completed discovery work when a worker stops or a reducer retries.

29- Read larger source files and generate reports without the previous fixed

30 size limits.

31- Read committed changes from the selected revision and preserve

32 repository-relative paths on Windows.

33- Pass OpenRouter and Fireworks credentials to deep-scan workers.

16 34 

17## 0.1.18 (August 7, 2026)35## 0.1.18 (August 7, 2026)

18 36 

77codex plugin add codex-security@openai-curated77codex plugin add codex-security@openai-curated

78```78```

79 79 

80The install command uses the public Codex CLI plugin marketplace, which can80The install command uses the public Codex CLI plugin marketplace. Check the

81offer a different version from the hosted desktop-app catalog. Check the

82[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you depend on a81[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you depend on a

83specific plugin version or feature in CI.82specific plugin version or feature in CI.

84 83 

33subagents = 033subagents = 0

34stop_after_no_new = 334stop_after_no_new = 3

35max_discovery_runs = 1035max_discovery_runs = 10

36max_time_hours = 1.5

36```37```

37 38 

38| Setting | Default | Description |39| Setting | Default | Description |

39| -------------------- | ------- | ------------------------------------------------------------------------------------------------ |40| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |

40| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |41| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |

41| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |42| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |

42| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |43| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |

44| `stop_after_consecutive_errors` | `3` | Stop discovery after this many consecutive worker errors. |

43| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |45| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |

46| `max_time_hours` | `96` | Limit discovery to a positive number of hours up to `96`; use fractions as needed. |

44 47 

45Lower values can reduce scan time and token use but may miss findings.48Lower values can reduce scan time and token use but may miss findings.

46Configuration changes apply to new deep scans, not scans already in progress.49Configuration changes apply to new deep scans, not scans already in progress.

47 50 

51The time limit applies only to discovery. When it expires, Codex Security

52stops unfinished discovery, keeps completed results, and continues with

53validation and reporting. If no source review finishes before the deadline,

54the report records partial coverage.

55 

56The `max_time_hours` setting requires plugin version `0.1.19` or later. See the

57[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.

58 

48## Start the deep scan59## Start the deep scan

49 60 

50In the desktop app, open **Security**, select **Scans**, and select **+ Scan**.61In the desktop app, open **Security**, select **Scans**, and select **+ Scan**.

7findings, coverage details, and paths to scan artifacts. For longer scans, it7findings, coverage details, and paths to scan artifacts. For longer scans, it

8supports preflight checks, cost limits, progress callbacks, and cancellation.8supports preflight checks, cost limits, progress callbacks, and cancellation.

9 9 

10The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22.13.010The SDK uses ECMAScript modules (ESM) and runs server-side with Node.js 22

11or later. Scanning also requires Python 3.10 or later.11(22.13.0 or later), 24, or 26. Scanning also requires Python 3.10 or later.

12Python 3.10 also requires the `tomli` package.

12 13 

13The Codex Security SDK is [publicly available on14The Codex Security SDK is [publicly available on

14 GitHub](https://github.com/openai/codex-security). Running scans requires15 GitHub](https://github.com/openai/codex-security). Running scans requires

36 37 

37## Run a scan38## Run a scan

38 39 

40Scan only repositories you trust and have permission to assess. The SDK runs

41with your local operating-system permissions and never pauses for approval.

42Scan processes can inherit your environment, so remove unrelated credentials

43before you start. See [Local scan

44permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

45 

39Create one `CodexSecurity` client, run a standard repository scan, and close46Create one `CodexSecurity` client, run a standard repository scan, and close

40the client when the work completes. Pass `outputDir` to choose a private47the client when the work completes. Pass `outputDir` to choose a private

41results directory outside the enclosing Git worktree.48results directory outside the enclosing Git worktree.

179 subagents: 0,186 subagents: 0,

180 stopAfterNoNew: 3,187 stopAfterNoNew: 3,

181 maxDiscoveryRuns: 10,188 maxDiscoveryRuns: 10,

189 maxTimeHours: 1.5,

182});190});

183```191```

184 192 

185Deep mode supports repository and path targets. Use standard mode for diff and193Deep mode supports repository and path targets. Use standard mode for diff and

186working-tree scans. The optional settings control concurrent discovery workers,194working-tree scans. The optional settings control concurrent discovery workers,

187subagents per worker, consecutive discovery runs without new findings, and the195subagents per worker, consecutive discovery runs without new findings, and the

188total number of discovery runs. They require `mode: "deep"`.196total number and duration of discovery runs. They require `mode: "deep"`.

197 

198`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,

199including fractional hours. At the deadline, Codex Security stops unfinished

200discovery, keeps completed discovery results, and continues with validation

201and reporting. Review `result.coverage.completeness` before treating a

202time-limited scan as evidence of full coverage.

189 203 

190### Add a security knowledge base204### Add a security knowledge base

191 205 

217});231});

218```232```

219 233 

234If the follow-up fails, the SDK keeps the completed scan and reports the

235error through `onWarning`. It restores any completed scan artifacts that the

236follow-up changed.

237 

220### Set a scan budget238### Set a scan budget

221 239 

222Set `maxCostUsd` to stop a scan when its estimated model cost exceeds a limit.240Set `maxCostUsd` to stop a scan when its estimated model cost exceeds a limit.

234```252```

235 253 

236The limit estimates spending but isn't a hard cap, so requests already in254The limit estimates spending but isn't a hard cap, so requests already in

237progress can finish slightly above it. If the scan exceeds the limit, the SDK255progress can finish slightly above it. If a deep scan reaches the limit after

238throws `ScanCostLimitExceededError` and preserves the available results.256discovery finishes, `run` returns a result with `coverage.completeness` set to

257`"partial"` and reports the budget warning through `onWarning`.

258 

259If the scan can't produce a completed partial result, `run` throws

260`ScanCostLimitExceededError` and preserves any available output.

239 261 

240## Work with scan results262## Work with scan results

241 263 

260| `sarifPath` | The generated SARIF path, or `null` when SARIF is absent. |282| `sarifPath` | The generated SARIF path, or `null` when SARIF is absent. |

261| `pluginVersion` | The version recorded by the scan producer. |283| `pluginVersion` | The version recorded by the scan producer. |

262 284 

285To require the same plugin for a later scan, pass

286`expectedPluginVersion: result.pluginVersion`. The SDK rejects the scan if

287the installed plugin version differs.

288 

263Use the structured findings and coverage directly:289Use the structured findings and coverage directly:

264 290 

265```ts291```ts

397Bedrock](https://learn.chatgpt.com/docs/security/cli/reference#use-amazon-bedrock), set423Bedrock](https://learn.chatgpt.com/docs/security/cli/reference#use-amazon-bedrock), set

398`model_provider` and `model` in `codexOverrides`.424`model_provider` and `model` in `codexOverrides`.

399 425 

426`codexOverrides` can't restrict the scan's filesystem access or change its

427approval policy. See [Local scan

428permissions](https://learn.chatgpt.com/docs/security/cli/reference#local-scan-permissions).

429 

400For OpenRouter or Fireworks, also provide the matching API key and a complete430For OpenRouter or Fireworks, also provide the matching API key and a complete

401provider configuration in `codexOverrides`. For example, set431provider configuration in `codexOverrides`. For example, set

402`OPENROUTER_API_KEY` and configure OpenRouter:432`OPENROUTER_API_KEY` and configure OpenRouter: