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
5575
5576- Set `[deep_scan].max_time_hours` to a positive duration of up to 96 hours.
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
5488 5583
5489These versions apply to the Codex Security plugin. The Codex app, Codex CLI,5584- Keep completed discovery work when a worker stops or a reducer retries.
5490TypeScript SDK, and plugin app have separate version numbers.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
26346 26510
26347Source: [Record & Replay](https://learn.chatgpt.com/docs/extend/record-and-replay.md)26511Source: [Record & Replay](https://learn.chatgpt.com/docs/extend/record-and-replay.md)
26348 26512
26349Record & Replay is available on macOS. Initial availability excludes the26513Record & Replay is available on macOS. Computer Use must also be available and
26350European Economic Area, the United Kingdom, and Switzerland. Computer Use must26514enabled.
26351also be available and enabled.
26352 26515
26353Record & Replay lets you demonstrate a workflow on your26516Record & Replay lets you demonstrate a workflow on your
26354Mac and turn it into a reusable skill. Use it when the workflow is repetitive,26517Mac and turn it into a reusable skill. Use it when the workflow is repetitive,
33209- [Analytics API](https://learn.chatgpt.com/docs/enterprise/analytics-api)33372- [Analytics API](https://learn.chatgpt.com/docs/enterprise/analytics-api)
33210- [Compliance API](https://learn.chatgpt.com/docs/enterprise/compliance-api)33373- [Compliance API](https://learn.chatgpt.com/docs/enterprise/compliance-api)
33211 33374
33375### GPTs and Sharing
33376
33377Source: [GPTs and Sharing](https://learn.chatgpt.com/docs/enterprise/gpts-and-sharing.md)
33378
33379#### Sharing
33380
33381Control who can create GPTs and whether they can be shared with specific people, groups, or the entire workspace.
33382
33383GPT builders can use either connected apps or custom actions, but not both in
33384the same GPT.
33385
33386#### Connected apps and actions
33387
33388Allow GPT builders to use approved workspace apps or configure actions that interact with permitted third-party APIs. Access remains subject to workspace policies, user permissions, and approved domains.
33389
33390#### Domains
33391
33392Restrict GPT actions to approved external domains to control which third-party APIs GPTs created in your workspace can access. If no domains are allowed, custom GPT actions cannot execute.
33393
33394Domain approval does not replace API authentication or user authorization.
33395
33396#### Managing GPTs
33397
33398Review GPTs created in your workspace, manage sharing and ownership,
33399and delete GPTs when appropriate. The management view organizes GPTs
33400by assigned and unassigned ownership and includes the following
33401information:
33402
33403- Name
33404- Builder
33405- Custom actions
33406- Who can access
33407- Chats
33408- Created
33409- Updated
33410
33212### Groups and provisioning33411### Groups and provisioning
33213 33412
33214Source: [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning.md)33413Source: [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning.md)
34793 34992
34794- [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions): Use the canonical map of workspace, runtime, API, plugin, and source-system controls.34993- [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions): Use the canonical map of workspace, runtime, API, plugin, and source-system controls.
34795 34994
34995- [GPTs and Sharing](https://learn.chatgpt.com/docs/enterprise/gpts-and-sharing): Manage GPT sharing, ownership, connected apps, and third-party actions across your workspace.
34996
34796- [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration): Distribute managed settings where supported and enforce runtime requirements for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension.34997- [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration): Distribute managed settings where supported and enforce runtime requirements for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension.
34797 34998
34798- [Prisma AIRS](https://learn.chatgpt.com/docs/enterprise/prisma-airs): Apply workspace-wide security policies to Codex prompts.34999- [Prisma AIRS](https://learn.chatgpt.com/docs/enterprise/prisma-airs): Apply workspace-wide security policies to Codex prompts.
