Documentation 2026-08-13 22:59 UTC to 2026-08-14 22:00 UTC

83 href: "/codex/enterprise/roles-and-workspace-permissions",83 href: "/codex/enterprise/roles-and-workspace-permissions",

84 icon: "userLock",84 icon: "userLock",

85 },85 },

86 {

87 title: "GPTs and Sharing",

88 description:

89 "Manage GPT sharing, ownership, connected apps, and third-party actions across your workspace.",

90 href: "/codex/enterprise/gpts-and-sharing",

91 icon: "userLock",

92 },

86 {93 {

87 title: "Managed configuration",94 title: "Managed configuration",

88 description:95 description:

1# GPTs and Sharing

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.

4 

5## Sharing

6 

7Control who can create GPTs and whether they can be shared with specific people, groups, or the entire workspace.

8 

9GPT builders can use either connected apps or custom actions, but not both in

10 the same GPT.

11 

12## Connected apps and actions

13 

14Allow 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.

15 

16## Domains

17 

18Restrict 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.

19 

20<WarningTip>

21 Domain approval does not replace API authentication or user authorization.

22</WarningTip>

23 

24## Managing GPTs

25 

26Review GPTs created in your workspace, manage sharing and ownership,

27and delete GPTs when appropriate. The management view organizes GPTs

28by assigned and unassigned ownership and includes the following

29information:

30 

31- Name

32- Builder

33- Custom actions

34- Who can access

35- Chats

36- Created

37- Updated

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 

5Record & Replay is available on macOS. Initial availability excludes the5Record & Replay is available on macOS. Computer Use must also be available and

6 European Economic Area, the United Kingdom, and Switzerland. Computer Use must6 enabled.

7 also be available and enabled.

8 7 

9Record & Replay lets you demonstrate a workflow on your8Record & Replay lets you demonstrate a workflow on your

10Mac and turn it into a reusable skill. Use it when the workflow is repetitive,9Mac and turn it into a reusable skill. Use it when the workflow is repetitive,

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: