@openai/codex-security 0.1.20 → 0.1.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +578 -871
  2. package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
  3. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +243 -0
  6. package/_bundled_plugin/scripts/finalize_scan_contract.py +92 -11
  7. package/_bundled_plugin/scripts/launch_codex_security_mcp +0 -0
  8. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +88 -0
  9. package/_bundled_plugin/skills/assess-patch-risk/agents/openai.yaml +4 -0
  10. package/_bundled_plugin/skills/assess-patch-risk/references/risk-rubric.md +76 -0
  11. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +163 -0
  12. package/_bundled_plugin/skills/fix-finding/SKILL.md +16 -48
  13. package/dist/api.d.ts +1 -1
  14. package/dist/api.d.ts.map +1 -1
  15. package/dist/api.js +14 -18
  16. package/dist/api.js.map +1 -1
  17. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  18. package/dist/bulk-scan-discovery.js +6 -24
  19. package/dist/bulk-scan-discovery.js.map +1 -1
  20. package/dist/cli.d.ts +24 -2
  21. package/dist/cli.d.ts.map +1 -1
  22. package/dist/cli.js +401 -38
  23. package/dist/cli.js.map +1 -1
  24. package/dist/cloud-publish.d.ts +5 -1
  25. package/dist/cloud-publish.d.ts.map +1 -1
  26. package/dist/cloud-publish.js +307 -9
  27. package/dist/cloud-publish.js.map +1 -1
  28. package/dist/component-plan.d.ts.map +1 -1
  29. package/dist/component-plan.js +5 -1
  30. package/dist/component-plan.js.map +1 -1
  31. package/dist/github.d.ts +161 -0
  32. package/dist/github.d.ts.map +1 -0
  33. package/dist/github.js +158 -0
  34. package/dist/github.js.map +1 -0
  35. package/dist/index.d.ts +2 -0
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +1 -0
  38. package/dist/index.js.map +1 -1
  39. package/dist/publish.d.ts +10 -0
  40. package/dist/publish.d.ts.map +1 -1
  41. package/dist/publish.js +29 -5
  42. package/dist/publish.js.map +1 -1
  43. package/dist/runtime.d.ts +0 -3
  44. package/dist/runtime.d.ts.map +1 -1
  45. package/dist/runtime.js +258 -185
  46. package/dist/runtime.js.map +1 -1
  47. package/dist/scan-comparison.d.ts +3 -0
  48. package/dist/scan-comparison.d.ts.map +1 -1
  49. package/dist/scan-comparison.js +6 -1
  50. package/dist/scan-comparison.js.map +1 -1
  51. package/dist/targets.d.ts.map +1 -1
  52. package/dist/targets.js +1 -0
  53. package/dist/targets.js.map +1 -1
  54. package/dist/thread-source.d.ts +8 -0
  55. package/dist/thread-source.d.ts.map +1 -0
  56. package/dist/thread-source.js +7 -0
  57. package/dist/thread-source.js.map +1 -0
  58. package/dist/version.d.ts +1 -1
  59. package/dist/version.js +1 -1
  60. package/dist/version.js.map +1 -1
  61. package/package.json +8 -5
package/README.md CHANGED
@@ -1,12 +1,9 @@
1
1
  # `@openai/codex-security`
2
2
 
3
- Open-source TypeScript SDK and CLI for running Codex Security scans. The
4
- ESM-only package includes TypeScript declarations, the `codex-security`
5
- executable, and the matching Codex runtime.
3
+ Run Codex Security scans from TypeScript or the command line. This ESM-only
4
+ package includes TypeScript declarations and the Codex runtime.
6
5
 
7
- > [!NOTE]
8
- > This package follows semantic versioning. Its public API may change between
9
- > minor versions before `1.0.0`.
6
+ Before version `1.0.0`, minor releases may change the public API.
10
7
 
11
8
  ## Install
12
9
 
@@ -15,22 +12,14 @@ npm install @openai/codex-security
15
12
  npx @openai/codex-security --version
16
13
  ```
17
14
 
18
- The package supports macOS, Linux, and Windows and requires Node.js 22.13.0 or
19
- later in the 22.x release line, Node.js 24.x, or Node.js 26.x. Scans, bulk
20
- scans, exports, scan history, and saved findings also require Python 3.10 or
21
- later. Python 3.10 also requires `tomli`. Use `--python` with `scan`,
22
- `bulk-scan`, or `export`; use `pythonPath` with the SDK. Set `PYTHON` to select
23
- an interpreter for any Python-backed command.
24
-
25
- When a newer version is available, the CLI shows the update command for your
26
- installation method. Set `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to hide the
27
- notice. Notices are also disabled in CI and when stderr is not a terminal.
15
+ Use Node.js 22.13.0+ (22.x), 24.x, or 26.x on macOS, Linux, or Windows.
16
+ Scans, exports, scan history, and saved findings also need Python 3.10+
17
+ (plus `tomli` on Python 3.10).
28
18
 
29
19
  ## Run a scan from TypeScript
30
20
 
31
21
  Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or
32
- `CODEX_API_KEY`. Then create a client and scan a repository you own or have
33
- permission to assess:
22
+ `CODEX_API_KEY`, then scan a repository you own or have permission to assess:
34
23
 
35
24
  ```ts
36
25
  import { CodexSecurity } from "@openai/codex-security";
@@ -49,29 +38,15 @@ try {
49
38
  }
50
39
  ```
51
40
 
52
- The SDK supports repository, path, committed-diff, and working-tree targets.
53
- Use `security.preflight()` to validate local inputs, `onWorkerStatus` and
54
- `onReconnect` to observe long-running scans, and an `AbortSignal` to cancel a
55
- scan.
56
-
57
- For separate standard scans under one project, the SDK also exports
58
- `runComponentScans({ repository, outputDir, components })`. Each component has
59
- a `name` and `paths` array. Use `auto: true` instead of `components` for
60
- model-assisted planning, and `planOnly: true` to save the plan without scanning.
61
-
62
- Successful results include open repository findings in `repositoryFindings`,
63
- when available; `findings` remains the current scan. Matching earlier findings
64
- can make one additional model call, including with a scan cost limit.
41
+ `result.findings` contains this scan's findings; `repositoryFindings` also
42
+ includes earlier open findings when available. Matching earlier findings can
43
+ make one extra model call, even with a cost limit.
65
44
 
66
- Results can contain source excerpts, vulnerability details, and reproduction
67
- steps. Keep result directories and saved reports outside the repository and
68
- limit access to authorized reviewers.
45
+ Keep results outside the repository and restrict access: reports can contain
46
+ source code, vulnerability details, and reproduction steps.
69
47
 
70
48
  ### Validate an existing finding
71
49
 
72
- Use `security.validate()` to assess one finding without running a repository
73
- scan or invoking the Codex Security CLI:
74
-
75
50
  ```ts
76
51
  const security = new CodexSecurity();
77
52
  try {
@@ -90,89 +65,125 @@ try {
90
65
  }
91
66
  ```
92
67
 
93
- `finding` accepts literal text or a JSON-serializable object, never a file
94
- path. Read files explicitly. Validation uses the CLI's validation skill and
95
- the client's settings and authentication. It leaves repository files unchanged
96
- and does not add a scan to scan history.
68
+ Pass literal text or a JSON-serializable object as `finding`, not a file path.
69
+ Validation uses the client's settings and credentials without changing
70
+ repository files or adding a scan to history.
71
+
72
+ Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
73
+ or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
74
+ `reportable` may rely on static analysis; `deferred` means insufficient evidence.
75
+ Failed, incomplete, or malformed responses reject the promise.
76
+
77
+ `outputDir` must be empty and outside the Git worktree; it defaults to
78
+ `validations/` under the state directory. Pass `auth` to select credentials
79
+ or `signal` to cancel.
80
+
81
+ ### Import GitHub code scanning alerts
82
+
83
+ Import alerts, including third-party SARIF uploads, and validate them against
84
+ the matching local checkout:
85
+
86
+ ```ts
87
+ import {
88
+ CodexSecurity,
89
+ importGitHubCodeScanningAlerts,
90
+ } from "@openai/codex-security";
91
+
92
+ const findings = await importGitHubCodeScanningAlerts({
93
+ repository: "example/repository",
94
+ alertNumbers: [12, 18], // Omit to list all open alerts on the default branch.
95
+ githubToken: process.env["GH_TOKEN"],
96
+ });
97
+
98
+ const security = new CodexSecurity();
99
+ try {
100
+ for (const finding of findings) {
101
+ const result = await security.validate({
102
+ repositoryPath: "/path/to/repository",
103
+ finding,
104
+ });
105
+ console.log(finding.url, result.disposition, result.outputDir);
106
+ }
107
+ } finally {
108
+ await security.close();
109
+ }
110
+ ```
111
+
112
+ Each result contains `source`, `repository`, `number`, `url`, and the full
113
+ upstream `alert`. Import is read-only and does not start Codex or check out code.
97
114
 
98
- The result contains `disposition` (`reportable`, `suppressed`, `not_applicable`,
99
- or `deferred`), a Markdown `report`, `threadId`, and `outputDir` for evidence.
100
- The report explains root cause, exploitability, evidence, and proof gaps.
101
- `reportable` can rely on static analysis; `deferred` means insufficient evidence.
115
+ Without `alertNumbers`, `state` filters alerts and defaults to `"open"`.
116
+ It also accepts `"closed"`, `"dismissed"`, `"fixed"`, and `"all"`. Exact alert
117
+ numbers ignore state and reject a nondefault `state`. Use `ref` for another
118
+ branch or pull-request reference.
102
119
 
103
- `outputDir` must be empty and outside the enclosing Git worktree. It defaults
104
- to the Codex Security state directory's `validations/` folder. Pass `auth` to
105
- select authentication or `signal` to cancel. Failed, incomplete, or malformed
106
- responses reject the promise.
120
+ Supply `githubToken` or use your `gh auth token` credentials, including GitHub
121
+ CLI token environment variables. `githubHost` defaults to `GH_HOST` or
122
+ `github.com`. The token needs read access to code scanning alerts; access
123
+ failures reject the import. Pass `signal` to cancel.
107
124
 
108
125
  ### SDK configuration and scan options
109
126
 
110
- Pass runtime configuration to the `CodexSecurity` constructor:
127
+ Constructor options:
111
128
 
112
- | Option | Description |
113
- | ---------------- | --------------------------------------------------------------------------- |
114
- | `pluginPath` | Use a Codex Security plugin directory or ZIP instead of the bundled plugin. |
115
- | `pythonPath` | Select the Python interpreter before consulting `PYTHON`. |
116
- | `codexOverrides` | Deep-merge supported settings into the isolated Codex configuration. |
129
+ | Option | Description |
130
+ | ---------------- | ----------------------------------------------------------------------- |
131
+ | `pluginPath` | Plugin directory or ZIP; defaults to the bundled plugin. |
132
+ | `pythonPath` | Python interpreter; overrides `PYTHON`. |
133
+ | `codexOverrides` | Supported settings to deep-merge into the isolated Codex configuration. |
117
134
 
118
- Pass scan configuration to `security.run(repository, options)` or
135
+ Options for `security.run(repository, options)` and
119
136
  `security.preflight(repository, options)`:
120
137
 
121
- | Option | Description |
122
- | ----------------------- | ------------------------------------------------------------------------------------------ |
123
- | `auth` | Select `"auto"`, `"chatgpt"`, or `"api-key"`. |
124
- | `safetyIdentifier` | Stable hashed end-user ID for this scan's model requests; requires API-key authentication. |
125
- | `target` | Select a repository, repository-relative paths, committed diff, or working-tree diff. |
126
- | `mode` | Select `"standard"` or `"deep"`; deep mode supports repositories and paths. |
127
- | `knowledgeBasePaths` | Add architecture documents, security policies, threat models, or directories. |
128
- | `outputDir` | Choose an artifact directory outside the enclosing Git worktree. |
129
- | `archiveExisting` | Archive results already in `outputDir` before starting a scan. |
130
- | `maxCostUsd` | Stop after the estimated model cost exceeds a positive USD amount. |
131
- | `maxTimeHours` | Limit deep-scan discovery to a positive number of hours, up to 96. |
132
- | `failureSeverity` | Record a finding-severity policy in the saved scan recipe. |
133
- | `parentScanId` | Link a rerun to an existing parent scan. |
134
- | `expectedPluginVersion` | Require the original plugin version when replaying a scan. |
135
- | `signal` | Cancel a scan with an `AbortSignal`. |
136
-
137
- Progress and lifecycle callbacks are `onAuthentication`, `onCost`,
138
- `onOutputArchived`, `onOutputDirReady`, `onScanStarted`,
139
- `onTrustedAccessStatus`, `onReconnect`, `onSessionEvent`, `onWorkerStatus`,
140
- `onWarning`, and `onObserverError`. `onSessionEvent` receives saved scan and
141
- worker events with their thread IDs and worker numbers. Preflight does not start
142
- the runtime, authenticate, resolve Python, inspect the plugin, or run those
143
- scan-lifecycle callbacks.
138
+ | Option | Description |
139
+ | ----------------------- | ------------------------------------------------------------------------------ |
140
+ | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
141
+ | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
142
+ | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
143
+ | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
144
+ | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
145
+ | `outputDir` | Artifact directory outside the enclosing Git worktree. |
146
+ | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
147
+ | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
148
+ | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
149
+ | `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |
150
+ | `parentScanId` | Parent scan ID for a rerun. |
151
+ | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
152
+ | `signal` | `AbortSignal` to cancel a scan. |
153
+
154
+ Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
155
+ saved events with thread IDs and worker numbers; `ScanOptions` lists all callbacks.
156
+
157
+ `preflight` and CLI `--dry-run` check local inputs without starting Codex or
158
+ using the network. They don't authenticate, verify model access, resolve Python,
159
+ inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
144
160
 
145
161
  ## Authentication
146
162
 
147
- For local use, sign in with ChatGPT:
163
+ Sign in with ChatGPT:
148
164
 
149
165
  ```bash
150
166
  npx @openai/codex-security login
151
167
  npx @openai/codex-security scan .
152
168
  ```
153
169
 
154
- On a remote or headless machine, use device authentication:
170
+ Use device authentication on remote or headless machines:
155
171
 
156
172
  ```bash
157
173
  npx @openai/codex-security login --device-auth
158
174
  ```
159
175
 
160
- For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To store an API key instead,
161
- pass it on stdin:
176
+ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin:
162
177
 
163
178
  ```bash
164
179
  printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
165
180
  ```
166
181
 
167
- Environment API keys are supplied directly to the current scan and are never
168
- saved to the Codex credential home or system keyring. Only an explicit
169
- `login --with-api-key` stores an API key.
170
-
171
- To pass a Codex access token explicitly, use
172
- `login --with-access-token` and provide the token on stdin. An access token
173
- environment variable is not automatically used as a scan API key.
182
+ Environment API keys apply to the current scan; only `login --with-api-key`
183
+ saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
184
+ Access-token environment variables are not scan API keys.
174
185
 
175
- To use another inference provider, set its API key and select its provider:
186
+ For other inference providers:
176
187
 
177
188
  ```bash
178
189
  export OPENROUTER_API_KEY="<your-openrouter-api-key>"
@@ -186,6 +197,11 @@ export AWS_REGION="us-east-2"
186
197
  npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna
187
198
  ```
188
199
 
200
+ Bedrock also accepts AWS access keys, profiles, web identity, container
201
+ credentials, and the default AWS credential chain. Set `AWS_REGION` and choose
202
+ a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`
203
+ support `--max-cost`.
204
+
189
205
  On Windows, set the API key in PowerShell:
190
206
 
191
207
  ```powershell
@@ -193,153 +209,86 @@ $env:OPENAI_API_KEY = "<your-api-key>"
193
209
  npx @openai/codex-security scan C:\code\repository
194
210
  ```
195
211
 
196
- Check or remove the stored sign-in with `npx @openai/codex-security login status`
197
- and `npx @openai/codex-security logout`. Codex Security keeps its sign-in in a
198
- private, stable Codex home at `$CODEX_SECURITY_STATE_DIR/codex-home`, or at
199
- `$CODEX_HOME/state/plugins/codex-security/codex-home` when no state directory is
200
- configured. On managed Windows devices, inherited access for `SYSTEM` and local
201
- `Administrators` is preserved while protecting the home against future changes
202
- to its parents. Other users and broad groups are rejected, and PowerShell
203
- Constrained Language Mode is supported. Login,
204
- status, logout, and scans use the same home. Codex manages
205
- credentials using its configured file or system-keyring backend and honors
206
- managed-device policies. An existing file-based Codex sign-in is imported only
207
- when the dedicated home does not already contain stored credentials. Logging
208
- out prevents later scans from automatically reimporting that ambient sign-in
209
- until you explicitly log in again.
210
-
211
- An environment API key takes precedence over a stored sign-in by default.
212
- When both a stored ChatGPT sign-in and an environment API key are available, an
213
- interactive scan asks which credential to use. JSON output, dry runs, CI, and
214
- other noninteractive scans never prompt and retain automatic API-key
215
- precedence. Select the credential source explicitly with `--auth`:
212
+ Login, logout, and scans share a private credential home:
213
+ `$CODEX_SECURITY_STATE_DIR/codex-home`, or
214
+ `$CODEX_HOME/state/plugins/codex-security/codex-home`. Codex uses the configured
215
+ file or keyring storage and managed-device policies. If this home has no
216
+ credentials, it imports an existing file-based Codex sign-in. Logout disables
217
+ imports until you log in again.
216
218
 
217
- ```bash
218
- npx @openai/codex-security scan . --auth chatgpt
219
- npx @openai/codex-security scan . --auth api-key
220
- ```
219
+ Finish operations using older versions before upgrading. Runtime preparation
220
+ holds the credential-home lock through pauses; exit or crash releases it.
221
+ Compatibility heartbeats protect active locks from older heartbeat-only
222
+ clients, but those clients can replace a paused client's lock.
221
223
 
222
- `--auth chatgpt` uses the stored sign-in and ignores `OPENAI_API_KEY` and
223
- `CODEX_API_KEY`. `--auth api-key` requires one of those environment variables.
224
- Omit `--auth`, or pass `--auth auto`, to preserve automatic API-key precedence
225
- for existing CI and unattended scans. The SDK accepts the same selection as
226
- `security.run(repository, { auth: "chatgpt" })` and
227
- `security.preflight(repository, { auth: "chatgpt" })`.
224
+ Keep `.codex-security-scan.sqlite3` between operations; never remove it during
225
+ an operation. PID reuse can make old PID-only locks appear active and block
226
+ recovery. Stop all operations using this home before removing an old
227
+ `.codex-security-scan.lock` directory manually.
228
228
 
229
- To make the stored ChatGPT sign-in the automatic default instead, unset any
230
- configured API-key variables:
229
+ If ChatGPT credentials cannot be refreshed, run `login status`. Retry if the
230
+ sign-in recently changed; otherwise run `logout`, then `login`.
231
+
232
+ Interactive scans ask whether to use ChatGPT or an environment API key when
233
+ both are available. The choice applies to that scan. Noninteractive scans,
234
+ including CI, JSON output, and dry runs, prefer the API key. Choose with `--auth`:
231
235
 
232
236
  ```bash
233
- unset OPENAI_API_KEY CODEX_API_KEY
237
+ npx @openai/codex-security scan . --auth chatgpt
238
+ npx @openai/codex-security scan . --auth api-key
234
239
  ```
235
240
 
236
- The interactive choice applies only to the current scan and is not persisted.
241
+ `--auth chatgpt` ignores environment API keys. `--auth api-key` requires
242
+ `OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; unset both
243
+ variables to default to ChatGPT. The SDK uses the same `auth` option on `run`
244
+ and `preflight`. Codex may still need ChatGPT credentials to load
245
+ workspace-managed policies when using an API key.
237
246
 
238
- When an environment key is configured, ChatGPT login and
239
- `codex-security login status` identify the effective scan credential source
240
- without printing its value, including when no stored sign-in exists.
241
-
242
- Some cybersecurity requests and protected findings require approval through
243
- Trusted Access for Cyber. To apply or check your access, visit
247
+ Some cybersecurity requests and protected findings require Trusted Access for
248
+ Cyber approval. Apply or check your access at
244
249
  [chatgpt.com/cyber](https://chatgpt.com/cyber).
245
250
 
246
251
  ## CLI
247
252
 
248
253
  ```bash
249
- npx @openai/codex-security scan
250
- npx @openai/codex-security scan /path/to/repository
251
- npx @openai/codex-security scan /path/to/repository --headless
252
- npx @openai/codex-security scan /path/to/repository --patch
253
- npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --json
254
- npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --create-pr
255
- npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
256
- npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
254
+ npx @openai/codex-security scan .
257
255
  npx @openai/codex-security scan /path/to/repository --path src --path tests
258
- npx @openai/codex-security scan-components /path/to/repository --component apps/api --component apps/web --output-dir /path/outside/repository/results
259
- npx @openai/codex-security scan-components /path/to/repository --auto --output-dir /path/outside/repository/results
260
- npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
261
- npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
262
256
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
263
257
  npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
264
- npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
265
- npx @openai/codex-security scan /path/to/repository --verbose
266
258
  npx @openai/codex-security scan /path/to/repository --dry-run
267
- npx @openai/codex-security scan /path/to/repository --fail-on-severity high
268
- npx @openai/codex-security scan /path/to/repository --max-cost 5
269
- npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5
270
- npx @openai/codex-security install-hook
271
- npx @openai/codex-security bulk-scan
272
- npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
273
- npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3 --max-cost 25
274
- npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
275
- npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
276
- npx @openai/codex-security scans list /path/to/repository
277
- npx @openai/codex-security scans list --scan-root /path/outside/repository/results
278
- npx @openai/codex-security scans show
279
- npx @openai/codex-security scans show SCAN_ID
280
- npx @openai/codex-security scans logs
281
- npx @openai/codex-security scans logs SCAN_ID
282
- npx @openai/codex-security scans rerun
283
- npx @openai/codex-security scans rerun SCAN_ID
284
- npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
285
- npx @openai/codex-security scans match --all
286
- npx @openai/codex-security scans compare
287
- npx @openai/codex-security scans compare PREVIOUS_SCAN_ID
288
- npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
289
- npx @openai/codex-security findings
290
- npx @openai/codex-security findings list /path/to/repository
291
- npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
292
- npx @openai/codex-security export
293
- npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
294
- npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
295
- npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
296
- npx @openai/codex-security publish scan /path/outside/repository/results --to linear --linear-team TEAM_ID
297
- npx @openai/codex-security publish scan --to linear --linear-team TEAM_ID
298
- npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
299
- npx @openai/codex-security validate "Possible SQL injection" --effort high
300
- npx @openai/codex-security verify-fix --linear-issue SEC-123 --json
301
- npx @openai/codex-security verify-fix --linear-project "Security backlog" --linear-filter '{"state":{"type":{"eq":"completed"}}}' --json
302
- npx @openai/codex-security verify-fix --scan SCAN_ID --severity high --json
303
- npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
304
- npx @openai/codex-security patch "Missing authorization check" --effort high
305
- npx @openai/codex-security patch OCCURRENCE_ID
306
- npx @openai/codex-security patch --scan SCAN_ID --severity high --json
307
- npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
308
- npx @openai/codex-security patch --resume-pr codex-security/patch-SCAN_ID
309
- npx @openai/codex-security patch --scan latest --severity medium
310
- npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124
311
- npx @openai/codex-security patch --linear-project "Security backlog" --linear-filter '{"labels":{"name":{"eq":"security"}}}'
312
259
  ```
313
260
 
314
- Run `npx @openai/codex-security --version` for the installed CLI version or
315
- `npx @openai/codex-security info --json` for the package, bundled plugin, Codex runtime,
316
- default model, reasoning effort, and first-scan command. A scan with `--dry-run`
317
- also reports its effective model and reasoning effort, including `--codex`
318
- overrides, without starting Codex or contacting the network.
261
+ Use `scan --help` for options, `--version` for the installed version, and
262
+ `info --json` for package, plugin, runtime, and model details. `--dry-run`
263
+ runs local preflight checks.
319
264
 
320
- `install-hook` scans staged and unstaged changes before each commit. It respects
321
- `core.hooksPath`, does not replace an existing hook, and blocks high-severity
322
- findings or failed scans. Set `--fail-on-severity` to change the threshold.
265
+ ### Scan options and output
323
266
 
324
267
  `--path` scopes a scan to one or more paths, `--diff` scans committed changes,
325
268
  and `--working-tree` scans staged and unstaged changes. Deep scans support
326
- repository and path targets. The output directory must be outside the scanned
327
- directory and any enclosing Git worktree. When SARIF is produced, it is written
328
- to
329
- `<scan-dir>/exports/results.sarif`.
269
+ repository and path targets.
330
270
 
331
271
  Working-tree snapshots include files from untracked nested Git repositories.
332
272
  Initialized submodules must be clean and checked out at the commit recorded by
333
273
  the parent repository.
334
274
 
335
- Repeat `--knowledge-base PATH` for multiple files or directories; `bulk-scan`
336
- shares them with every repository. Directories are searched recursively for
337
- Markdown, text, PDF, and Word (`.docx`) files.
275
+ Repeat `--knowledge-base PATH` for Markdown, text, PDF, or Word (`.docx`) files.
276
+ Directories are searched recursively. Bulk scans share these documents with
277
+ every repository.
278
+
279
+ Use an empty output directory outside the scanned directory and enclosing Git
280
+ worktree. On macOS/Linux, existing directories must be private to you
281
+ (`chmod 700`). `--archive-existing` moves previous results to
282
+ `<output-dir>.previous-<timestamp>-<id>`; add `--dry-run` to preview the move.
283
+ SARIF output, when produced, is at `<scan-dir>/exports/results.sarif`.
284
+
285
+ Scans are report-only by default. Set `--fail-on-severity high` to exit with
286
+ `1` if a completed scan finds high or critical issues. Incomplete scans exit
287
+ with `2`, writing available results to stdout and a coverage warning to stderr.
338
288
 
339
289
  ### Attribute scans to end users
340
290
 
341
- For an application that serves multiple users, pass the originating user's
342
- stable hashed ID on each scan:
291
+ When scanning on behalf of users, pass each user's stable hashed ID:
343
292
 
344
293
  ```ts
345
294
  await security.run("/path/to/repository", {
@@ -352,23 +301,19 @@ await security.run("/path/to/repository", {
352
301
  codex-security scan /path/to/repository --auth api-key --safety-identifier hashed-user-id
353
302
  ```
354
303
 
355
- The ID must contain 1–64 characters and cannot be blank or contain NUL.
356
- Do not use an email address or other personal data. The ID is passed to Codex
357
- for the scan, nested workers, retries, and follow-up work. It is not saved in
358
- shared configuration or the scan recipe. Supply it again for a later rerun.
359
- Concurrent SDK clients can use different IDs without changing `process.env`.
304
+ Use a nonblank ID of 1 to 64 characters without NUL or personal data such as
305
+ email addresses. It applies to the scan, workers, retries, and follow-up work
306
+ without changing shared configuration. Supply it again for reruns.
360
307
 
361
- This requires a Codex runtime with native `--safety-identifier` support and a
362
- plugin that forwards it to workers. The current bundled runtime does not yet
363
- support this option. Use `CODEX_CLI_PATH` to select a compatible build.
364
- The SDK does not check runtime or plugin compatibility; older versions may
365
- omit the identifier. Omitting the option leaves ordinary scans unchanged.
366
- Preflight checks the ID's format; authentication is checked when the scan starts.
308
+ The runtime needs native `--safety-identifier` support, and the plugin must
309
+ forward it to workers. The bundled runtime doesn't support it yet; choose a
310
+ compatible build with `CODEX_CLI_PATH`. The SDK checks the ID's format, not
311
+ runtime or plugin compatibility. Older versions may omit the ID.
367
312
 
368
313
  ### Scan project components
369
314
 
370
- `scan --path` runs one scan across the selected paths. Use `scan-components`
371
- to run a separate standard scan for each component of one local project:
315
+ `scan --path` runs one scan across selected paths. To scan each local project
316
+ component separately in standard mode, use `scan-components`:
372
317
 
373
318
  ```bash
374
319
  npx @openai/codex-security scan-components /path/to/project \
@@ -376,12 +321,8 @@ npx @openai/codex-security scan-components /path/to/project \
376
321
  --workers 4 --output-dir /path/outside/project/results
377
322
  ```
378
323
 
379
- Use `--auth chatgpt` or `--auth api-key` to select credentials for planning,
380
- component scans, and matching. The default is `--auth auto`, as with `scan`.
381
- The SDK accepts the same choice through `scanOptions.auth`.
382
-
383
- Use `--auto` instead of `--component` to let Codex propose the split. To review
384
- or edit it first, save a plan, then run that plan into a new output directory:
324
+ Use `--auto` instead of `--component` for a proposed split. Save a plan to
325
+ review or edit, then run it with a new output directory:
385
326
 
386
327
  ```bash
387
328
  npx @openai/codex-security scan-components /path/to/project \
@@ -391,7 +332,7 @@ npx @openai/codex-security scan-components /path/to/project \
391
332
  --output-dir /path/outside/project/results
392
333
  ```
393
334
 
394
- A component can contain several repository-relative paths:
335
+ Components use repository-relative paths:
395
336
 
396
337
  ```json
397
338
  {
@@ -402,45 +343,36 @@ A component can contain several repository-relative paths:
402
343
  }
403
344
  ```
404
345
 
405
- Automatic planning uses a local file inventory. In Git repositories it follows
406
- Git's ignore rules. Each automatic path must cover at least one inventoried file.
407
- Explicit `--component` and `--components-file` selections keep their existing behavior.
408
- Inventoried files omitted by the model are added to an
409
- `Other files` component. No source files are changed during planning.
410
-
411
- In an interactive terminal, one dashboard shows all components and their scan
412
- progress. Use the arrow keys to select a component, Enter to view its activity,
413
- and Esc to return. Other scans continue while you inspect one. Finding counts
414
- are preliminary until cross-component matching finishes. Use `--headless` for
415
- plain status lines; CI and redirected output use those automatically.
416
- Failed or incomplete components are also saved in `retry-components.json`.
417
- Pass that file to `--components-file` with a new output directory to retry them.
418
-
419
- Each component keeps its normal scan artifacts under `component-N/`.
420
- The combined `findings.json` uses the same root-cause matcher as `scans match`.
421
- It merges high-confidence matches even when their titles, locations, or
422
- fingerprints differ. Each group keeps its highest-severity finding and all
423
- original scan and occurrence IDs. Match reasons and uncertain pairs are saved;
424
- uncertain findings stay separate. `summary.json` records scan coverage and
425
- whether matching finished. `report.md` links to the component reports.
426
- These combined files are a project summary, not a new sealed scan. Use the
427
- individual scan folders with `export` and `publish`.
428
-
429
- The output directory must be empty and outside the project. Failed components
430
- do not stop the others. The command saves the available results and exits with
431
- code `2` if a component fails, coverage is incomplete, or cross-component
432
- matching fails. `--max-cost` applies to each component scan, not planning,
433
- cross-component matching, or the whole project. `--model` and `--effort` also
434
- apply to matching. `--knowledge-base`,
435
- `--scan-prompt-file`, and `--post-scan-prompt-file` work as they do for bulk scans.
346
+ Automatic planning respects Git ignore rules and groups omitted files under
347
+ `Other files`. Each proposed path must contain an inventoried file. Planning
348
+ leaves source files unchanged.
349
+
350
+ Each component saves artifacts under `component-N/`. Combined `findings.json`
351
+ merges high-confidence root-cause matches, keeping the highest severity and
352
+ original IDs. Uncertain matches stay separate. `summary.json` records coverage
353
+ and matching status; `report.md` links to component reports. Export and publish
354
+ from the individual scan folders, not the combined summary.
355
+
356
+ Use an empty output directory outside the project. Failed components don't
357
+ stop others, but failures, incomplete coverage, or failed matching exit with
358
+ `2`. Retry failed or incomplete components with
359
+ `--components-file retry-components.json` and a new output directory.
360
+
361
+ `--max-cost` applies per component, excluding planning and matching.
362
+ `--model` and `--effort` also apply to matching; `--auth` applies throughout.
363
+ Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for
364
+ bulk scans.
365
+
366
+ From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
367
+ Use `auto: true` for planning, `planOnly: true` to save the plan without scans,
368
+ and `scanOptions.auth` to select credentials.
436
369
 
437
370
  ### Configure deep scans
438
371
 
439
- For `scan --mode deep`, `--workers` limits concurrent discovery workers,
440
- `--subagents` controls each worker's subagents, `--stop-after-no-new` stops after
441
- that many runs find no new issues, `--max-discovery-runs` limits total runs, and
442
- `--max-time-hours` limits discovery duration. These options are also available
443
- on SDK scans:
372
+ For `scan --mode deep`, `--workers` sets discovery concurrency and `--subagents`
373
+ sets subagents per worker. `--stop-after-no-new` stops after that many runs
374
+ without new issues. `--max-discovery-runs` and `--max-time-hours` cap discovery
375
+ runs and duration. SDK equivalents:
444
376
 
445
377
  ```ts
446
378
  await security.run("/path/to/repository", {
@@ -453,73 +385,33 @@ await security.run("/path/to/repository", {
453
385
  });
454
386
  ```
455
387
 
456
- Set defaults in `~/.codex/codex-security/config.toml`, or under `$CODEX_HOME`
457
- when it is configured. Explicit CLI and SDK settings override these defaults:
388
+ Set defaults in `$CODEX_HOME/codex-security/config.toml`:
458
389
 
459
390
  ```toml
460
391
  [deep_scan]
461
- workers = 2
462
- subagents = 0
463
- stop_after_no_new = 3
464
- max_discovery_runs = 10
465
- max_time_hours = 1.5
392
+ workers = 4
393
+ subagents = 3
394
+ stop_after_no_new = 4
395
+ stop_after_consecutive_errors = 3
396
+ max_discovery_runs = 40
397
+ max_time_hours = 96
466
398
  ```
467
399
 
468
- The discovery deadline defaults to 96 hours. The configured value may be any
469
- positive number, including fractional hours, up to 96. At the deadline,
470
- in-flight discovery stops and completed findings are reduced and returned.
471
- The 97-hour outer tool-call timeout reserves approximately one hour for final
472
- reduction and result delivery, including at the 96-hour maximum.
400
+ CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`
401
+ in the file; `--codex` cannot configure this section. Worker and run counts must
402
+ be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
403
+ four workers. Unknown keys are rejected.
404
+
405
+ `max_time_hours` accepts positive values up to 96, including fractional hours.
406
+ At the deadline, discovery stops; the scan combines and returns completed findings.
473
407
 
474
408
  `scan --workers` controls discovery workers within one deep scan;
475
409
  `bulk-scan --workers` controls how many repositories are scanned concurrently.
476
410
 
477
- On macOS/Linux, an existing output directory must be private to the current
478
- user (`chmod 700`).
479
-
480
- If the output directory already contains results, add `--archive-existing`.
481
- The CLI moves them to `<output-dir>.previous-<timestamp>-<id>` and starts the
482
- scan in a new, empty directory at the original path. Add `--dry-run` to see
483
- the destination without moving files.
484
-
485
- Scans are report-only by default. Use `--fail-on-severity` in CI to exit 1 when
486
- a completed scan contains a finding at or above the selected severity.
487
- Incomplete coverage and CLI/runtime errors exit 2 so they cannot be mistaken
488
- for a passing policy. Incomplete scans still write the available human or JSON
489
- result to stdout and a coverage warning to stderr, including in report-only
490
- mode.
491
-
492
- Use `--patch` to fix and verify confirmed findings after a complete scan.
493
- `--patch-severity high` selects high and critical findings; the default is low
494
- and above. After showing the findings summary, interactive scans with findings
495
- ask whether to open a color-coded finding browser with complete finding details
496
- and a separate patch-instructions panel. Use the arrow keys to
497
- browse, `Tab` to inspect details, `Space` to select individual findings, `i` to
498
- edit instructions for the focused finding, `1`–`4` to select by severity, and
499
- `r` to optionally create a draft GitHub pull request after patching. Press
500
- `Enter` to patch or `q` to keep the checkout unchanged. Each selected finding
501
- runs in its own saved Codex desktop task. Add `--create-pr` to `scan --patch` or a
502
- saved-finding `patch` command to commit only verified patch files and open a
503
- draft pull request with `gh`. If the push or pull request fails, run the printed
504
- `patch --resume-pr BRANCH` command from the same repository. It uses the saved
505
- commit without running Codex again and refuses to publish if the branch changed.
506
- JSON scan results include `patchSeverity`. Scan and
507
- saved-finding results include one `patches` entry per selected finding with
508
- status `verified`, `no_change`, `blocked`, or `failed`, plus `pullRequest` when
509
- one is created. When `--fail-on-severity` is also set, verified and already-fixed
510
- findings no longer fail the policy.
511
-
512
- Scans use `gpt-5.6-sol` with extra-high reasoning effort by default. OpenAI is
513
- the implied provider. Use `--model gpt-5.6-terra` to switch models and
514
- `--effort minimal|low|medium|high|xhigh|max` to set reasoning effort. Repeat
515
- `--codex KEY=VALUE` for other Codex settings; existing
516
- `--codex 'model_reasoning_effort="high"'` overrides remain supported.
517
-
518
411
  ### Runtime configuration and worker limits
519
412
 
520
- The standalone CLI and SDK do not load an unrelated user or repository Codex
521
- configuration. Each scan starts with a private runtime and these Codex
522
- defaults:
413
+ Scans use these isolated Codex defaults instead of your user or repository
414
+ configuration:
523
415
 
524
416
  ```toml
525
417
  approval_policy = "on-request"
@@ -542,9 +434,8 @@ max_concurrent_threads_per_session = 9
542
434
  sandbox = "unelevated"
543
435
  ```
544
436
 
545
- Use `--model` and `--effort` for model selection. Repeat
546
- `--codex KEY=VALUE` to deep-merge other TOML values into this isolated
547
- configuration:
437
+ Use `--model` to choose a model and `--effort minimal|low|medium|high|xhigh|max`
438
+ for reasoning effort. Repeat `--codex KEY=VALUE` for other TOML settings:
548
439
 
549
440
  ```bash
550
441
  npx @openai/codex-security scan . \
@@ -553,10 +444,8 @@ npx @openai/codex-security scan . \
553
444
  --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
554
445
  ```
555
446
 
556
- The session thread limit includes the parent agent: the default of `9`
557
- provides up to eight delegated worker slots. This limit is separate from
558
- `bulk-scan --workers`, which controls how many repositories run concurrently.
559
- A configured limit is a maximum, not evidence that every worker started.
447
+ The thread limit of `9` includes the parent and up to eight delegated workers.
448
+ It is separate from deep-scan and bulk-scan worker counts.
560
449
 
561
450
  Quote string values as TOML, for example
562
451
  `--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
@@ -564,256 +453,99 @@ Quote string values as TOML, for example
564
453
  `--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
565
454
  rejected.
566
455
 
567
- Plugin and marketplace loading belong to Codex Security. Overrides of
568
- `plugins`, `marketplaces`, or `features.plugins`, including profile-specific
569
- plugin overrides, are rejected; choose `--plugin-path` instead. Native
570
- multi-agent v2 must remain enabled. The legacy `agents.max_threads` setting
571
- and `features.multi_agent_v2.enabled=false` are incompatible and rejected.
572
- `validate` and `patch` accept `--effort` and only the `model` and
573
- `model_reasoning_effort` `--codex` keys; they do not accept general scan
574
- runtime overrides.
456
+ Choose plugins with `--plugin-path`. Overrides of `plugins`, `marketplaces`,
457
+ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
458
+ stay enabled: `agents.max_threads` and
459
+ `features.multi_agent_v2.enabled=false` are rejected.
575
460
 
576
- These overrides cannot replace the scanner-owned approval reviewer or
577
- filesystem profile. Use `--codex 'approval_policy="never"'` to deny approval
578
- requests instead of reviewing them automatically. See
579
- [Local security model](#local-security-model).
461
+ `validate` and `patch` accept `--effort` and the `model` and
462
+ `model_reasoning_effort` keys in `--codex`, but no other runtime overrides.
580
463
 
581
- ### Deep-scan engine configuration
464
+ See [Local security model](#local-security-model) for approval and filesystem
465
+ restrictions.
582
466
 
583
- Deep scans read `$CODEX_HOME/codex-security/config.toml`, defaulting to
584
- `~/.codex/codex-security/config.toml`:
467
+ ### Environment variables
585
468
 
586
- ```toml
587
- [deep_scan]
588
- workers = 4
589
- subagents = 3
590
- stop_after_no_new = 4
591
- stop_after_consecutive_errors = 3
592
- max_discovery_runs = 40
593
- max_time_hours = 96
594
- ```
469
+ | Variable | Effect |
470
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
471
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
472
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
473
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
474
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
475
+ | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
476
+ | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
477
+ | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
478
+ | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
479
+ | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
480
+ | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
481
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
482
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
483
+ | `CI` | Disables interactive update notices. |
484
+ | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
485
+
486
+ Custom Codex executables need thread source attribution for `exec` and
487
+ `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
488
+ command shims such as `codex.cmd` fall back to the bundled executable.
489
+
490
+ Python lookup order: `--python` (on `scan`, `bulk-scan`, or `export`) or SDK
491
+ `pythonPath`, then `PYTHON`, the managed Codex runtime, and `python3` or `python`
492
+ on `PATH` (`py` also works on Windows). `CODEX_SECURITY_STATE_DIR` overrides
493
+ `CODEX_HOME` for state storage. Keep state and results outside the repository.
494
+
495
+ ### Progress and cost
496
+
497
+ Interactive scans show full-screen progress; CI, redirected output, and
498
+ `--headless` use plain status lines. Results go to stdout, progress and
499
+ diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for
500
+ sensitive information before sharing them.
501
+
502
+ JSON results, scan history, and bulk-scan receipts record the model, tokens,
503
+ and estimated cost. Estimates use
504
+ [standard API token prices](https://developers.openai.com/api/docs/models/compare),
505
+ including cached input and cache writes, but exclude fees and surcharges.
595
506
 
596
- The default is four discovery workers; the legacy `workers = "auto"` setting
597
- also resolves to four. Set `workers` to a positive integer to choose an explicit
598
- count. `subagents` must be a nonnegative integer;
599
- `stop_after_no_new`, `stop_after_consecutive_errors`, and `max_discovery_runs`
600
- must be positive integers. `max_time_hours` must be a positive finite number no
601
- greater than 96; fractional hours are supported. Unknown `[deep_scan]` keys are
602
- rejected.
507
+ `--max-cost USD` stops the scan and its workers when estimated cost exceeds
508
+ the limit, though in-flight requests can finish above it. If deep-scan
509
+ discovery has finished, the scan returns a sealed partial report without more
510
+ model calls and lists unvalidated candidates as follow-up work. Bulk scans
511
+ apply the limit per repository attempt.
603
512
 
604
- These settings are separate from Codex's
605
- `features.multi_agent_v2.max_concurrent_threads_per_session` and
606
- `bulk-scan --workers`. Standalone CLI and SDK scans create an isolated
607
- `CODEX_HOME`, import the ambient `[deep_scan]` configuration, and apply explicit
608
- CLI or SDK options on top. Set `stop_after_consecutive_errors` in the
609
- configuration file. Use `--codex` to adjust the Codex session thread limit, not
610
- to set `[deep_scan]` values.
513
+ ### Bulk scans
611
514
 
612
- ### Environment variables
515
+ Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select
516
+ GitHub repositories pushed in the last 90 days. Forks and archived repositories
517
+ are excluded; private checkouts use your GitHub CLI sign-in. The command asks
518
+ for an output directory and saves your selection there as `repositories.csv`.
519
+ `--output-dir` requires CSV input.
613
520
 
614
- The CLI and SDK recognize the following user-configurable environment:
615
-
616
- | Variable | Effect |
617
- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
618
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan authentication; `OPENAI_API_KEY` wins when both are present. |
619
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default Linear team and project for completed-scan publication. |
620
- | `CODEX_SECURITY_LINEAR_API_KEY` | Patch Linear issues or publish directly with a personal API key. |
621
- | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; set to `debug` for verbose diagnostics. |
622
- | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
623
- | `CODEX_SECURITY_STATE_DIR` | Override the private scan-history, workbench, and default artifact directory. |
624
- | `CODEX_HOME` | Set the ambient Codex home for file-backed sign-in and default state; defaults to `~/.codex`. |
625
- | `CODEX_CLI_PATH` | Use another Codex executable for authentication, plugin setup, scans, and nested workers. |
626
- | `PYTHON` | Select a Python interpreter when `--python` or SDK `pythonPath` is not set. |
627
- | `GH_HOST` | Select a GitHub Enterprise host during interactive `bulk-scan` discovery. |
628
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices when either variable is defined. |
629
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Select the update-check registry, in the listed precedence order. |
630
- | `CI` | Disable interactive update notices in automated environments. |
631
- | `NO_COLOR`, `TERM` | Disable colored scan-history output when `NO_COLOR` is defined or `TERM=dumb`. |
632
-
633
- On Windows, `CODEX_CLI_PATH` must name a native `.exe` or `.com`. Command
634
- shims such as `codex.cmd` automatically use the bundled Codex executable
635
- instead.
636
-
637
- Interpreter discovery uses `--python` or `pythonPath` first, then `PYTHON`,
638
- the managed Codex runtime, and finally `python3` or `python` from `PATH` (`py`
639
- is also supported on Windows).
640
- `CODEX_SECURITY_STATE_DIR` takes precedence over `CODEX_HOME`; keep both
641
- state and result paths outside the scanned repository.
642
-
643
- The repository's Docker Compose workflow additionally recognizes
644
- `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`, `CODEX_SECURITY_SECCOMP`,
645
- `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and `CODEX_SECURITY_STATE` for
646
- its image, runtime user, seccomp profile, input, results, and state mounts.
647
- Provide `GH_TOKEN` or `GITHUB_TOKEN` for private GitHub checkouts and
648
- `CODEX_SECURITY_GIT_HOST` for a GitHub Enterprise host in the container.
649
- These container settings are distinct from standalone CLI flags and
650
- interactive discovery's `GH_HOST`.
651
-
652
- Variables such as `CODEX_SECURITY_SCAN_ID`, `CODEX_SECURITY_SCAN_DIR`,
653
- `CODEX_SECURITY_PLUGIN_ROOT`, `CODEX_SECURITY_CONFIG_PATH`, and
654
- `CODEX_SECURITY_TARGET_PATHS_FILE` are generated by an active scan. They are
655
- internal runtime data, not supported user configuration.
656
-
657
- Use `--provider openrouter` to send inference through OpenRouter. Set
658
- `OPENROUTER_API_KEY` and specify a supported model with `--model`.
659
-
660
- Use `--provider fireworks` to send inference through Fireworks AI. Set
661
- `FIREWORKS_API_KEY` and specify a supported model with `--model`.
662
-
663
- Use `--provider amazon-bedrock` to send inference through Amazon Bedrock. Set
664
- `AWS_REGION` and authenticate with `AWS_BEARER_TOKEN_BEDROCK`, standard AWS
665
- access keys, an AWS profile, web identity, container credentials, or the
666
- default AWS credential chain. Specify a supported Bedrock model with `--model`;
667
- OpenAI Bedrock models such as `openai.gpt-5.6-luna` support `--max-cost`.
668
-
669
- Scan progress identifies the requested paths and reports actual ranking,
670
- file-review, validation, and attack-path phases as they become available.
671
- Interactive terminals show a full-screen view; CI, redirected output, and
672
- `--headless` use plain timestamped progress lines.
673
- Completion summarizes findings, severity, coverage, elapsed time, available
674
- token and worker counts, estimated cost, the results directory, and the next
675
- useful command.
676
- Progress and summaries use stderr; structured scan results remain on stdout.
677
-
678
- Add `--verbose` or set `CODEX_SECURITY_LOG_LEVEL=debug` to print
679
- lifecycle, authentication, progress, and cost diagnostics to stderr.
680
- `LOG_LEVEL=debug` is used only when `CODEX_SECURITY_LOG_LEVEL` is unset.
681
- Structured JSON results remain on stdout. Review sensitive verbose logs before
682
- sharing them. The normal activity feed hides credentials.
683
-
684
- Each scan records its model, tokens, and estimated cost in its JSON result,
685
- scan history, and bulk-scan receipt. Estimates use
686
- [standard API token prices](https://developers.openai.com/api/docs/models/compare),
687
- including cached input and cache writes; fees and surcharges are not included.
688
-
689
- Use `--max-cost USD` to stop a scan, including its delegated workers, when its
690
- running cost exceeds the limit. If a Deep Scan has already finished discovery,
691
- it returns a sealed partial report with any completed findings and lists
692
- unvalidated candidates as follow-up work. Requests already in progress can
693
- finish above the limit; preparing the partial report makes no additional model
694
- requests. Incomplete coverage retains its existing exit code.
695
- For `bulk-scan`, the limit applies separately to each repository attempt.
696
-
697
- Run `npx @openai/codex-security scan --help` or `npx @openai/codex-security bulk-scan --help`
698
- for the complete CLI references.
699
-
700
- Sign in with `gh auth login`, then run `npx @openai/codex-security bulk-scan` to discover
701
- GitHub repositories pushed in the last 90 days. Archived
702
- repositories and forks are excluded. Search the repository list, select the
703
- repositories to scan, and confirm before scanning.
704
- Private checkouts reuse your GitHub CLI sign-in without changing your global Git
705
- configuration. The selected repositories are saved to
706
- `<output-dir>/repositories.csv` for review or resumption.
707
-
708
- Interactive discovery accepts the same `--workers`, `--mode`, `--max-attempts`,
709
- `--model`, `--effort`, `--plugin-path`, `--python`, and `--codex` settings as
710
- CSV-driven scans. It prompts for the output directory; `--output-dir` is only
711
- valid when a repository CSV is supplied.
712
-
713
- To use an existing repository list or run in CI, pass a CSV with required `id`,
714
- `repository`, and `revision` columns. Revisions must be full commit hashes;
715
- optional `scope`, `mode`, and `prompt` columns customize individual scans:
521
+ For CI or an existing repository list, pass a CSV with `id`, `repository`, and
522
+ `revision` (full commit hash). Optional `scope`, `mode`, and `prompt` columns
523
+ customize each scan:
716
524
 
717
525
  ```csv
718
526
  id,repository,revision,scope,mode,prompt
719
527
  service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Focus on authentication and authorization.
720
528
  ```
721
529
 
722
- Use `--scan-prompt-file PATH` to add instructions to a scan or every bulk scan.
723
- Bulk scans append each repository's CSV `prompt` after the shared instructions.
724
- Use `--post-scan-prompt-file PATH` to run a follow-up in the same authenticated
725
- session after each scan, including incomplete or failed scans. Canceled scans
726
- and scans stopped at their configured cost limit do not start another turn.
727
-
728
- `--workers` sets the number of concurrent repository scans and defaults to
729
- `4`. `--max-attempts` sets how many times each pending repository can run per
730
- invocation and defaults to `1`. Results remain under `--output-dir`; rerun the
731
- same command to resume.
732
-
733
- ### Publish multiple completed scans to Cloud
734
-
735
- Choose completed scans from your local history:
736
-
737
530
  ```bash
738
- npx @openai/codex-security publish scan --to cloud --dry-run --json
531
+ npx @openai/codex-security bulk-scan repositories.csv \
532
+ --output-dir /path/outside/repositories/security-scans --workers 4
739
533
  ```
740
534
 
741
- The picker shows each scan's repository, finding count, age, and scan ID.
742
- Press <kbd>Space</kbd> to select or deselect scans, then press
743
- <kbd>Enter</kbd> to submit. At least one scan is required, and no scans are
744
- selected automatically.
745
-
746
- For scripts, repeat `--scan` with saved scan IDs or unique ID prefixes (at
747
- least eight characters):
748
-
749
- ```bash
750
- npx @openai/codex-security publish scan \
751
- --scan SCAN_ID_A --scan SCAN_ID_B \
752
- --to cloud --dry-run --json
753
- ```
535
+ `--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
536
+ repository's CSV `prompt` follows the shared instructions.
537
+ `--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
538
+ even after a failed or incomplete scan, but not after cancellation or a
539
+ cost-limit stop.
754
540
 
755
- Use `scans list --json` to find IDs for the current repository. `--scan latest`
756
- selects its latest completed scan. The CLI resolves IDs through saved history,
757
- processes each selected scan once, and checks that its sealed artifacts match
758
- the selected ID. Picker selections use the order shown; repeated `--scan`
759
- selections use argument order. The artifacts must still be available locally.
760
-
761
- `--dry-run` validates the scans and prints their findings without uploading or
762
- requiring a login. Remove `--dry-run` to upload. Live uploads require ChatGPT
763
- credentials explicitly stored in a file. Set this in your Codex `config.toml`,
764
- then sign in with ChatGPT again:
765
-
766
- ```toml
767
- cli_auth_credentials_store = "file"
768
- ```
769
-
770
- Automatic and keyring credential storage are not accepted for Cloud
771
- publication, even when an `auth.json` file exists, because that file may be
772
- stale and belong to a different account. The CLI sends one scan at a time,
773
- with each scan's findings and metadata in a separate request.
774
-
775
- For artifacts outside local history, use repeated `--scan-dir PATH` instead.
776
- A single positional directory is still accepted and can be combined with
777
- `--scan-dir`. Do not combine directory inputs with `--scan`. Each directory
778
- must contain one completed, sealed scan; bulk-run directories and
779
- `results.jsonl` files are not accepted. Relative paths start at the current
780
- directory, and `~/...` starts at your home directory. Each resolved directory
781
- is processed once.
782
-
783
- For multiple distinct scans, output contains:
784
-
785
- - `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
786
- - `failed`: errors with `scanDir` and, for saved selections, `scanId`.
787
- - `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
788
- did not reach before cancellation.
789
-
790
- For one distinct scan, the CLI returns the scan result directly,
791
- without the batch fields above.
792
-
793
- The CLI continues after a failed scan and exits with code `2` if any scan
794
- fails. Ctrl-C or SIGTERM stops new requests and returns the results collected
795
- so far. When cancellation stops work before every requested publication is
796
- confirmed, the exit code is `130` for Ctrl-C and `143` for SIGTERM. If the
797
- single response or final batch response has already confirmed the complete
798
- publication, the command exits with code `0`. Cloud publication receipts
799
- appear in command output; the CLI does not save them to scan history.
800
-
801
- A successful receipt contains one opaque Cloud finding ID for each submitted
802
- finding, in request order. These are not local finding IDs. The CLI verifies
803
- the authenticated response status, count, and ID uniqueness, but cannot map
804
- opaque server IDs back to individual local findings independently.
805
-
806
- The CLI never retries an upload automatically. An upload with a missing or
807
- invalid receipt may already have been accepted. Check whether Cloud accepted
808
- that scan before retrying it. Do not resend scans with confirmed receipts.
541
+ `--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending
542
+ repository per invocation. Rerun the command to resume; `bulk-scan --help`
543
+ lists all options.
809
544
 
810
545
  ### Custom validation
811
546
 
812
- Use a prompt file to replace the final validation step in a standard or diff
813
- scan. The ordinary source review still runs. The supplied text goes directly
814
- into a separate validation turn and is not sent to discovery workers.
815
- The SDK adapts the bundled discovery workflow without changing the plugin.
816
- An incompatible plugin workflow stops the scan instead of using default validation.
547
+ Replace the final validation step of a standard or diff scan with a prompt
548
+ file. Source review still runs; discovery workers do not receive this prompt.
817
549
 
818
550
  ```bash
819
551
  npx @openai/codex-security scan . --validation-prompt-file validation.md
@@ -828,10 +560,10 @@ const result = await security.run(repository, {
828
560
  });
829
561
  ```
830
562
 
831
- Describe setup, allowed test targets, expected evidence, and cleanup in the
832
- prompt. Refer to credentials through environment variables; do not put secrets
833
- in the prompt or validation output. There are no separate setup or teardown
834
- hooks. Deep scans reject this option. Empty candidate sets skip the custom turn.
563
+ Put setup, allowed targets, required evidence, and cleanup in the prompt.
564
+ There are no separate setup or teardown hooks. Use environment variables for
565
+ credentials; keep secrets out of prompts and validation output. Deep scans
566
+ reject this option; scans without candidates skip it.
835
567
 
836
568
  The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
837
569
 
@@ -860,63 +592,106 @@ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
860
592
  }
861
593
  ```
862
594
 
863
- Each candidate needs exactly one result. The disposition is `reportable`,
864
- `suppressed`, `not_applicable`, or `deferred`. Optional assessment changes use
865
- `{ "level": "medium", "rationale": "..." }` in `severity` or `impact`; use
866
- `null` to retain the original assessment. Finding identity and source locations
867
- do not change. Deferred candidates make coverage partial. Suppressed and
868
- deferred candidates remain in the saved validation artifacts.
595
+ Return one result per candidate with disposition `reportable`, `suppressed`,
596
+ `not_applicable`, or `deferred`. Set `severity` or `impact` to
597
+ `{ "level": "medium", "rationale": "..." }` to revise an assessment, or `null`
598
+ to retain it. Identity and source locations stay unchanged.
869
599
 
870
- The scan directory contains `artifacts/custom-validation/candidates.json` and
871
- `results.json`. Setup failure, incomplete output, or invalid output leaves the
872
- scan incomplete. There is no automatic fallback to default validation. When
873
- rerunning a saved custom-validation scan, supply
874
- `scans rerun SCAN_ID --validation-prompt-file validation.md` again.
600
+ The scan saves candidates and results, including suppressed and deferred
601
+ cases, under `artifacts/custom-validation/`. Coverage is incomplete if setup
602
+ fails, output is incomplete or invalid, or any candidate is deferred. An
603
+ incompatible plugin stops the scan; validation never falls back to the default.
604
+ Repeat `--validation-prompt-file` on reruns.
875
605
 
876
- ### Publish completed scans to Linear
606
+ ### Publish findings to Cloud
877
607
 
878
- Publish every finding from a completed standard, deep, or scoped scan to one
879
- Linear team:
608
+ Choose completed scans from local history:
880
609
 
881
610
  ```bash
882
- npx @openai/codex-security publish scan --scan SCAN_ID \
883
- --to linear \
884
- --linear-team TEAM_ID
611
+ npx @openai/codex-security publish scan --to cloud --dry-run --json
885
612
  ```
886
613
 
887
- Linear accepts one scan. Use a saved scan ID, a unique ID prefix, or `latest`.
888
- For external artifacts, a positional directory or `--scan-dir PATH` is also
889
- accepted.
890
-
891
- Add `--linear-project PROJECT_ID` to place the issues in a Linear project.
892
- The existing `--project` flag remains an alias. Without a project, issues are
893
- created directly in the selected team.
614
+ Press Space to select scans, then Enter to submit. Nothing is preselected.
894
615
 
895
- To choose from all completed scans saved in your local scan history, omit the
896
- scan selector. The selector highlights each repository and shows its finding
897
- count, relative run time, and abbreviated scan ID:
616
+ For scripts, repeat `--scan` with saved IDs or unique prefixes of at least
617
+ eight characters:
898
618
 
899
619
  ```bash
900
620
  npx @openai/codex-security publish scan \
621
+ --scan SCAN_ID_A --scan SCAN_ID_B \
622
+ --to cloud --dry-run --json
623
+ ```
624
+
625
+ Find IDs with `scans list --json`, or use `--scan latest` for the current
626
+ repository's latest completed scan. You still need the local sealed artifacts.
627
+
628
+ `--dry-run` checks inputs and prints findings without logging in or uploading.
629
+ Uploads need ChatGPT credentials saved to a file. Set this in Codex
630
+ `config.toml`, then sign in with ChatGPT again:
631
+
632
+ ```toml
633
+ cli_auth_credentials_store = "file"
634
+ ```
635
+
636
+ Cloud publication rejects automatic and keyring storage, even if an
637
+ `auth.json` file exists: the file may be stale or belong to another account.
638
+
639
+ For CSV input, use an export from `codex-security export --export-format csv`:
640
+
641
+ ```bash
642
+ npx @openai/codex-security publish scan --to cloud \
643
+ --csv /path/outside/repository/findings.csv
644
+ ```
645
+
646
+ The [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)
647
+ has the required columns; deep-scan exports may add `candidate_id`. `--csv`
648
+ only supports Cloud and cannot be combined with scan IDs or directories.
649
+
650
+ For artifacts outside local history, pass a directory or repeat `--scan-dir PATH`.
651
+ Each directory must contain one completed, sealed scan. Bulk-run directories
652
+ and `results.jsonl` files aren't accepted. Don't mix directories with `--scan`.
653
+
654
+ Multiple scans return:
655
+
656
+ - `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
657
+ - `failed`: errors with `scanDir` and, for saved selections, `scanId`.
658
+ - `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
659
+ did not reach before cancellation.
660
+
661
+ One scan returns its result directly. Uploads run sequentially. A failed upload
662
+ doesn't stop the rest, but the command exits with `2` if any failed. Cancellation
663
+ stops new requests and returns results so far with `130` (Ctrl-C) or `143`
664
+ (SIGTERM), unless all publications were already confirmed.
665
+
666
+ Save the output: Cloud receipts aren't stored in scan history. They contain
667
+ Cloud finding IDs in request order, not local IDs. Uploads aren't retried
668
+ automatically. Cloud may have accepted an upload even if its receipt is missing
669
+ or invalid. Check Cloud before retrying; never resend a scan with a confirmed
670
+ receipt.
671
+
672
+ ### Publish completed scans to Linear
673
+
674
+ Linear publication accepts one completed scan:
675
+
676
+ ```bash
677
+ npx @openai/codex-security publish scan --scan SCAN_ID \
901
678
  --to linear \
902
679
  --linear-team TEAM_ID
903
680
  ```
904
681
 
905
- Destination flags take precedence over `CODEX_SECURITY_LINEAR_TEAM` and the
906
- optional `CODEX_SECURITY_LINEAR_PROJECT`. Use `--dry-run` to preview the issue
907
- titles without creating them, or `--json` to return structured publication
908
- results.
909
- Interactive publication shows a full-screen activity view with live Codex
910
- output and issue-creation progress. Other terminals receive plain progress on
911
- stderr, so `--json` output remains machine-readable.
682
+ Choose a scan by ID, unique prefix, `latest`, or directory (positional or
683
+ `--scan-dir PATH`). Omit the selector for an interactive picker. Live publication
684
+ and `--skip-existing` require the scan in local history; a directory-based
685
+ `--dry-run` alone does not.
912
686
 
913
- By default, publishing starts Codex with your existing Codex configuration and
914
- connected Linear app. Sign in to Codex and connect Linear before publishing in
915
- this mode. No separate Linear API token is required, and publication does not
916
- use the isolated Codex home created for security scans.
687
+ Add `--linear-project PROJECT_ID` (`--project` is an alias) to place issues in
688
+ a project. Destination flags override `CODEX_SECURITY_LINEAR_TEAM` and
689
+ `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run` previews issue titles without
690
+ contacting Linear; `--json` returns structured results.
917
691
 
918
- To publish directly through the Linear API without starting Codex, configure a
919
- Linear personal API key:
692
+ Sign in to Codex and connect Linear to publish with your existing Codex
693
+ configuration; publication doesn't use the isolated scan home. To use the
694
+ Linear API directly, set a personal API key:
920
695
 
921
696
  ```bash
922
697
  export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
@@ -925,73 +700,36 @@ npx @openai/codex-security publish scan /path/to/completed-scan \
925
700
  --linear-team TEAM_ID
926
701
  ```
927
702
 
928
- Direct API publication leaves issues unassigned by default. Pass
929
- `--linear-assignee teammate@example.com` or `--linear-assignee USER_ID` to
930
- assign the issues to a Linear user by email address or user ID.
931
- `--linear-assignee` requires direct API publication.
703
+ Direct API publication leaves issues unassigned unless `--linear-assignee`
704
+ specifies a user ID or email. `--linear-api-key KEY` overrides the environment
705
+ variable, but exposes the key in shell history and process listings. Keys are
706
+ omitted from saved results and artifacts; error messages are returned unchanged.
932
707
 
933
- You can also pass `--linear-api-key KEY`, which takes precedence over
934
- `CODEX_SECURITY_LINEAR_API_KEY`. Prefer the environment variable to avoid
935
- exposing your API key in shell history and process listings. API keys are not
936
- added to successful publication results, scan history, or sealed scan artifacts.
937
- Error messages are preserved as returned. `--dry-run` never contacts Linear in
938
- either mode.
939
-
940
- Use `publish check` to verify that the completed scan and its findings match
941
- local history, and to see which findings already have recorded Linear issues:
708
+ Check scan integrity and recorded publications before publishing:
942
709
 
943
710
  ```bash
944
711
  npx @openai/codex-security publish check /path/to/completed-scan \
945
712
  --to linear --linear-team TEAM_ID --json
946
713
  ```
947
714
 
948
- The check does not create issues, migrate scan history, or change sealed scan
949
- artifacts. With a Linear API key, it also makes read-only authentication, team,
950
- optional project, and assignee checks. Without a key, connected-app access is
951
- reported as `not-checked`. Issue-creation permission is always `not-tested`;
952
- successful read access does not prove write permission.
953
-
954
- Each finding creates a separate new issue titled
955
- `[Codex Security][HIGH] Finding title`. The issue includes the scan ID,
956
- repository, scanned scope, source locations and code snippets, severity,
957
- confidence, vulnerability classification, summary, and remediation guidance.
958
- Verified immutable Git revisions include source links. Findings are published
959
- concurrently in batches of up to 20. Successful issue identifiers are linked
960
- to their findings in the local scan-history database, and structured results
961
- are read back from that database rather than generated by Codex. The completed
962
- scan must already exist in the local scan history. By default, running
963
- publication again creates another set of issues for the same scan. Add
964
- `--skip-existing` to skip findings with a recorded issue for the exact scan
965
- occurrence, team, and optional project. Combine it with `--dry-run` to preview
966
- only the remaining findings. Results distinguish newly `created` issues from
967
- previously recorded `skipped` issues.
968
-
969
- This option uses local publication history; it does not search, update, or
970
- verify the continued existence of remote issues. Recover any retained handoff
971
- from an interrupted or uncertain publication before retrying. Concurrent
972
- publishers and remote creations that were never recorded can still create
973
- duplicates.
974
-
975
- Issue descriptions contain source code and vulnerability details. Select a
976
- Linear destination authorized to receive that information. Publication receipts
977
- are stored separately from the sealed scan artifacts.
978
-
979
- Before recording a connected-app publication, Codex Security verifies the exact
980
- mutation arguments and reconciles every recognized issue identifier and
981
- non-empty URL in the connector result with its durable handoff. If those claims
982
- conflict, or a completed mutation cannot be verified, publication exits with an
983
- indeterminate recovery error. The private handoff, connector-event evidence,
984
- and partial receipts remain in local state; independently verified sibling
985
- issues may already be recorded in scan history.
986
-
987
- Do not immediately rerun an indeterminate publication. Inspect the retained
988
- evidence and the selected Linear destination, reconcile every issue that may
989
- already have been created, and retry only after confirming that no unrecorded
990
- issue would be duplicated. Publication does not perform a fresh remote readback
991
- or recover unrecorded remote creations. The opt-in `--skip-existing` behavior
992
- only skips issues already recorded in local history.
993
-
994
- You can also publish a scan from TypeScript:
715
+ `publish check` is read-only. With an API key it also checks authentication,
716
+ team, project, and assignee access; connected-app access is `not-checked`.
717
+ Issue-creation permission is always `not-tested`.
718
+
719
+ Each finding becomes an issue titled `[Codex Security][HIGH] Finding title`
720
+ with source locations, code, evidence, and remediation. Choose a destination
721
+ authorized to receive these details. Local history stores successful issue IDs
722
+ separately from sealed scan artifacts.
723
+
724
+ Republishing creates duplicates by default. `--skip-existing` skips recorded
725
+ successes for the same occurrence, team, and project, without checking remote
726
+ issues. Results distinguish `created` and `skipped` issues. Add `--dry-run`
727
+ to preview the remaining findings.
728
+
729
+ After an interrupted or indeterminate publication, check the retained handoff,
730
+ evidence, and Linear destination before retrying. Issues may exist without a
731
+ local record. The CLI can't recover those issues, and `--skip-existing` can't
732
+ prevent duplicates from them or concurrent publications.
995
733
 
996
734
  ```ts
997
735
  import { publishScan } from "@openai/codex-security";
@@ -999,105 +737,65 @@ import { publishScan } from "@openai/codex-security";
999
737
  const publication = await publishScan("/path/to/completed-scan", {
1000
738
  destination: "linear",
1001
739
  teamId: "TEAM_ID",
1002
- onProgress: (progress) => {
1003
- if (progress.type === "handoff_recorded") {
1004
- console.error("Saved mutation result", progress.recorded);
1005
- } else if (progress.type === "issue_completed") {
1006
- console.error(
1007
- `Processed ${progress.completed} of ${progress.total} findings.`,
1008
- );
1009
- }
1010
- },
1011
740
  });
1012
741
 
1013
742
  console.log(publication.scanId);
1014
743
  console.log(publication.created.length);
1015
744
  ```
1016
745
 
1017
- Add `projectId: "PROJECT_ID"` to the options to publish into a specific Linear
1018
- project instead of directly to the team. Pass `skipExisting: true` to skip
1019
- recorded successes, or import `checkScanPublication` and call it with the same
1020
- destination options for a read-only preflight.
1021
-
1022
- Pass `linearApiKey` to publish directly through the Linear API. Omit
1023
- `assigneeId` to leave issues unassigned, or supply a Linear user ID or email
1024
- address to select an assignee:
1025
-
1026
- ```ts
1027
- const directPublication = await publishScan("/path/to/completed-scan", {
1028
- destination: "linear",
1029
- teamId: "TEAM_ID",
1030
- linearApiKey: process.env["CODEX_SECURITY_LINEAR_API_KEY"],
1031
- assigneeId: "teammate@example.com",
1032
- });
1033
- ```
746
+ Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
747
+ publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
748
+ the same destination options for a read-only check.
1034
749
 
1035
750
  ### Scan history and reruns
1036
751
 
1037
- `scans` or `scans list` lists scans for the current repository. Pass a repository
1038
- path to inspect another checkout, or `--scan-root DIR` to list scans whose
1039
- artifacts are under a particular root. `scans show` opens the latest completed
1040
- scan for the current repository. Pass `SCAN_ID` to inspect another scan. Scan
1041
- details include the configuration, results, coverage, and artifact locations. Add
1042
- `--show-linked-findings` to include finding links from previous scans.
1043
-
1044
- `scans logs` shows session events from the latest scan, including an active scan.
1045
- Pass `SCAN_ID` to select another scan. During a scan, press `d` for live details.
1046
- Filter with `a` for all sources, `m` for the main scan, or `1`–`9` for a worker.
1047
- Logs and live details can contain source code and credentials.
1048
-
1049
- Every scan history command accepts a full scan ID or a unique prefix of at
1050
- least eight characters.
1051
-
1052
- Scan history uses `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3` when
1053
- `CODEX_SECURITY_STATE_DIR` is set. Otherwise, it uses
1054
- `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`; `CODEX_HOME`
1055
- defaults to `~/.codex`. Scan credentials are never stored in the scan
1056
- configuration. Recorded failure summaries and bulk-scan receipts omit messages
1057
- that contain recognizable credentials.
1058
-
1059
- The scan sandbox permits writes to the selected state directory so SQLite can
1060
- maintain its database and journal files. If the host itself cannot write to the
1061
- default directory, select a writable directory outside the scanned repository:
1062
-
1063
- ```bash
1064
- export CODEX_SECURITY_STATE_DIR=/path/to/writable/codex-security-state
1065
- ```
1066
-
1067
- `findings` or `findings list` lists open findings for the current repository.
1068
- Use `findings false-positive OCCURRENCE_ID --reason TEXT` to mark a finding as a
1069
- false positive and explain why. Later scans dismiss a matching finding only when
1070
- the same reason still applies.
1071
-
1072
- `scans rerun` repeats the latest completed scan against the current checkout.
1073
- Pass `SCAN_ID` to rerun another scan.
1074
-
1075
- `scans match BEFORE_SCAN_ID AFTER_SCAN_ID` links findings with the same root
1076
- cause; `scans match --all` matches all completed scans of the current repository,
1077
- including other worktrees and clones. Saved matches appear in `scans show` and
1078
- are reused unless `--force` is passed. Scans without sealed artifacts are skipped.
1079
-
1080
- `scans compare` compares the two latest completed scans. Pass one scan ID to
1081
- compare it with the latest completed scan, or two IDs to select both scans. It
1082
- matches findings by root cause, reuses saved matches, and reports findings as
1083
- new, persisting, reopened, resolved, or unknown. Missing findings are not
1084
- treated as resolved when the later scan is incomplete or does not cover their
1085
- original scope.
1086
-
1087
- The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery
1088
- and structured output. Inspect the command manifest with `--llms`, inspect a
1089
- command schema with `scan --schema --format json`, register the CLI as an MCP
1090
- server with `mcp add`, sync agent skills with `skills add`, or generate shell
1091
- completions with `completions bash|zsh|fish`. Scan results support
1092
- `--format toon|json|yaml|jsonl` and `--full-output`.
1093
- Use `info --json` for SDK and bundled-plugin metadata. MCP exposes only this
1094
- read-only metadata command; scans, bulk repository scans,
1095
- authentication, exports, validation, and patching remain CLI-only because the
1096
- MCP transport cannot cancel active scans.
1097
-
1098
- For CI, save machine-readable output outside the checked-out repository and
1099
- apply a severity policy. Incomplete coverage and runtime errors still exit
1100
- nonzero:
752
+ Commands default to the current repository. Select scans by full ID or a
753
+ unique prefix of at least eight characters.
754
+
755
+ | Command | Purpose |
756
+ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
757
+ | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
758
+ | `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |
759
+ | `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |
760
+ | `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |
761
+ | `scans match BEFORE AFTER` | Link findings with the same root cause. |
762
+ | `scans match --all` | Match completed scans across the repository's worktrees and clones. |
763
+ | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to the latest two completed scans. |
764
+ | `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |
765
+ | `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |
766
+
767
+ Matching requires sealed artifacts and reuses saved matches unless you pass
768
+ `--force`. Comparisons classify findings as new, persisting, reopened, resolved,
769
+ or unknown. Missing findings aren't resolved if the later scan is incomplete
770
+ or excludes their original scope. With one ID, `scans compare` compares it
771
+ to the latest completed scan.
772
+
773
+ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
774
+ `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
775
+ workbench maintain the database and its journal files as the current user.
776
+ Keep state private, writable, and outside the scanned repository.
777
+
778
+ On Windows, an older sandboxed run can leave an invalid credential-home ancestor
779
+ ACL. Preserve that state and its reports, and select a **new**, private
780
+ `CODEX_SECURITY_STATE_DIR` outside both the old state and the repository.
781
+ Sign in again if needed and keep using the new setting; it starts separate scan
782
+ history. Existing ancestor ACLs are not rewritten.
783
+
784
+ Scan configurations don't store credentials; session logs and live details can
785
+ contain them. Press `d` during a scan for details, then `a` for all sources,
786
+ `m` for the main scan, or `1` through `9` for a worker.
787
+
788
+ ### Exports and CI
789
+
790
+ `export` writes CSV, JSON, or SARIF from a completed, sealed scan, defaulting to
791
+ the current repository's latest completed scan. It doesn't start Codex or load
792
+ credentials. Use `--output -` for stdout and `--source-root PATH` to add SARIF
793
+ source-line fingerprints. `export --help` lists all options.
794
+
795
+ JSON preserves the sealed findings document. CSV marks findings as open,
796
+ omits local triage state, and cannot go to stdout when JSON output is requested.
797
+
798
+ For CI, save output outside the checkout and set a severity threshold:
1101
799
 
1102
800
  ```bash
1103
801
  SCAN_ROOT="$(mktemp -d)"
@@ -1108,97 +806,114 @@ npx @openai/codex-security scan . \
1108
806
  --fail-on-severity high > "$SCAN_ROOT/findings.json"
1109
807
  ```
1110
808
 
1111
- JSON scans never use interactive terminal controls, even when stderr is a TTY.
1112
- Saved-finding patch commands support `--json`; literal issue and file patch
1113
- commands do not. The `validate`, `login`, and `logout` commands reject `--json`.
1114
- Sign-in commands remain interactive. CSV exports cannot be written to stdout
1115
- while JSON output is requested.
1116
-
1117
- Use `export` to create CSV, JSON, or SARIF from a completed, sealed scan without
1118
- starting Codex or loading credentials. Without a scan directory, it exports the
1119
- latest completed scan for the current repository. JSON preserves the sealed findings
1120
- document. CSV uses the portable findings columns, marks findings as open, and
1121
- does not include local workbench triage state. The exporter validates the seal
1122
- before writing, accepts `--output -` for stdout, and can use
1123
- `--source-root /path/to/repository` with SARIF to add source-line fingerprints.
1124
- Run `npx @openai/codex-security export --help` for all export options.
1125
-
1126
- Use `validate` to run the bundled validation skill on candidate findings and
1127
- `patch` to run the bundled fix-finding skill on security issues. Each positional
1128
- input can be either a file, whose contents are read into the request, or literal
1129
- text. These inputs operate on the current directory. Pass a saved finding or
1130
- occurrence ID instead to patch its original repository, or use
1131
- `patch --scan SCAN_ID --severity high` for high and critical findings from one
1132
- scan. `--scan latest` selects the most recent scan of the current repository.
1133
- Saved-finding patch commands accept `--json` and return a verified, already
1134
- fixed, blocked, or failed result for each finding. Both commands use the scan
1135
- model and reasoning defaults and disable plugins. Patching starts a separate
1136
- saved task in the Codex desktop app for each finding. Override the model with
1137
- `--codex 'model="gpt-5.6-sol"'` and the
1138
- reasoning effort with `--effort high` or
1139
- `--codex 'model_reasoning_effort="high"'`.
1140
-
1141
- Use `patch --linear-issue ISSUE` to import a Linear issue by identifier or URL.
1142
- Repeat `--linear-issue` to include more issues. Use
1143
- `patch --linear-project "PROJECT"` to patch every open issue in a project. Add
1144
- `--linear-filter '{"labels":{"name":{"eq":"security"}}}'` to apply a native
1145
- Linear issue filter on the server. Completed and canceled issues are excluded
1146
- unless the filter explicitly sets `state`. Set `CODEX_SECURITY_LINEAR_API_KEY`
1147
- for a personal API key, or `LINEAR_ACCESS_TOKEN` for an OAuth access token.
1148
- `LINEAR_API_KEY` is also accepted. `--linear-api-key KEY` overrides these
1149
- environment settings; prefer the environment variable to keep keys out of shell
1150
- history. Imported content is always literal, and issue URLs must match the
1151
- selected workspace. Each imported issue includes its title, description, and
1152
- all comments with their source links. Linear access is read-only, and its
1153
- credentials are not passed to the patch subprocess.
1154
-
1155
- Use `verify-fix` to check whether an existing security fix actually closes its
1156
- original vulnerability without modifying the repository. Pass a finding
1157
- description, a saved finding identifier, `--scan SCAN_ID`, `--linear-issue ISSUE`,
1158
- or `--linear-project "PROJECT"`. Linear intake uses the same credentials and
1159
- `--linear-filter` options as `patch`; explicitly filter for completed issues when
1160
- verifying a finished backlog. Verification runs the bundled `verify-fix` skill
1161
- in a read-only Codex sandbox and reports `fixed`, `still_vulnerable`, or
1162
- `inconclusive` with supporting evidence for every finding. Use `--json` for
1163
- structured output. Exit code `0` means every finding is fixed, `1` means at
1164
- least one finding remains vulnerable, and `2` means a result is inconclusive or
1165
- verification could not complete.
1166
-
1167
- Interactive verification shows the same live agent-activity dashboard used by
1168
- scans and Linear publication. Reasoning, repository commands, and progress are
1169
- written to stderr; redirected output and CI receive plain progress lines, and
1170
- JSON results on stdout remain machine-readable.
1171
-
1172
- Exit codes are `0` for a completed report-only scan or a passing policy, `1`
1173
- for a completed policy violation, `2` for invalid input, incomplete coverage, or
1174
- a runtime/export error, `130` for interruption, and `143` for termination.
1175
-
1176
- Use `--dry-run` or `await security.preflight(...)` to validate the repository,
1177
- target, mode, output location, and Codex overrides without initializing the
1178
- runtime or loading credentials. Dry runs do not inspect the plugin or probe its
1179
- Python interpreter. The preflight result includes the selected authentication
1180
- method and, for an environment API key, its variable name. Authentication and
1181
- model access remain unverified until a real scan starts.
1182
-
1183
- Scan progress identifies the selected credential source before Codex starts.
1184
- Terminals and noninteractive CI logs also show how to retry with
1185
- `--auth chatgpt` when an environment API key overrides the stored sign-in.
1186
- Progress remains on stderr so JSON output stays machine readable. Network
1187
- failures and rate limits remain retryable; definitive authentication and model
1188
- authorization failures stop immediately.
809
+ Scan exit codes are `0` for a completed report-only scan or passing policy,
810
+ `1` for a policy violation, `2` for invalid input, incomplete coverage, or a
811
+ runtime/export error, `130` for interruption, and `143` for termination.
812
+ JSON scans do not use interactive controls. `validate`, `login`, and `logout`
813
+ reject `--json`.
1189
814
 
1190
- ## Containerized bulk scans
815
+ `install-hook` scans staged and unstaged changes before each commit. It blocks
816
+ on high-severity findings or failed scans, respects `core.hooksPath`, and leaves
817
+ existing hooks alone. Change the threshold with `--fail-on-severity`.
1191
818
 
1192
- Create `repositories.csv` with one full, immutable Git commit per repository:
819
+ ### Import alerts from the CLI
1193
820
 
1194
- ```csv
1195
- id,repository,revision
1196
- payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567
821
+ `import github OWNER/REPO` reads open code scanning alerts from the default
822
+ branch. Repeat `--github-alert NUMBER` for exact alerts. Filter with
823
+ `--github-state open|closed|dismissed|fixed|all` or select a reference with
824
+ `--github-ref REF`. Authentication follows the
825
+ [SDK import options](#import-github-code-scanning-alerts).
826
+
827
+ ```bash
828
+ # Import all open alerts, or a selected subset, as complete JSON.
829
+ npx @openai/codex-security import github example/repository --format json \
830
+ > /path/outside/repository/github-alerts.json
831
+ npx @openai/codex-security import github example/repository \
832
+ --github-alert 12 --github-alert 18 --format json
833
+ # Run from the corresponding local repository; imported contents are data.
834
+ npx @openai/codex-security validate /path/outside/repository/github-alerts.json
1197
835
  ```
1198
836
 
1199
- Once the approved image has been published, prepare private results and
1200
- authentication directories, sign in, and run the Docker Compose configuration
1201
- from the root of the Codex Security repository:
837
+ Import is read-only and returns an array (`[]` when empty). `--json` aliases
838
+ `--format json`. Save validation inputs without output filters or token limits.
839
+ Use the SDK loop for a disposition per alert.
840
+
841
+ ### Validate and patch findings
842
+
843
+ `validate` assesses candidates; `patch` fixes and verifies them. Both accept
844
+ files or literal text and work in the current directory. Pass a saved finding
845
+ or occurrence ID to `patch` to use its original repository.
846
+
847
+ Add `--assess-patch-risk` to a `patch` command to run the bundled patch-risk
848
+ assessment skill once on the completed patch. The assessment is advisory and
849
+ does not change the patch or its merge state. Human-readable commands print the
850
+ report after the patch results; saved-finding JSON output returns it as
851
+ `patchRisk.report` in the same result object. When combined with `--create-pr`,
852
+ the draft pull request body includes only the concise Markdown summary from the
853
+ assessment; the validated JSON remains in the command result.
854
+
855
+ ```bash
856
+ npx @openai/codex-security validate "Possible SQL injection" --effort high
857
+ npx @openai/codex-security patch OCCURRENCE_ID
858
+ npx @openai/codex-security patch --scan SCAN_ID --severity high --json
859
+ npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
860
+ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
861
+ npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
862
+ ```
863
+
864
+ `--scan latest` selects the current repository's latest scan. Saved-finding
865
+ patch commands support `--json`; literal-text and file inputs don't. Change
866
+ the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
867
+ Each finding gets its own saved Codex desktop task.
868
+
869
+ `scan --patch` patches after a complete scan. `--patch-severity` defaults to
870
+ `low`; `high` selects high and critical findings. Use the interactive browser
871
+ to select findings and add patch instructions. Results include a `patches`
872
+ entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
873
+ Verified and already-fixed findings no longer fail `--fail-on-severity`.
874
+
875
+ `--create-pr` commits generated patch files and opens a draft PR with `gh`.
876
+ Supplied-issue pull requests require a clean working tree before patching so
877
+ existing work is never included. If publication fails, run the printed
878
+ `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
879
+ commit without rerunning Codex, but refuses to publish if the branch changed.
880
+
881
+ To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
882
+ `--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
883
+ Completed and canceled issues are excluded unless the filter sets `state`.
884
+ Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or
885
+ `LINEAR_ACCESS_TOKEN` for OAuth. `--linear-api-key KEY` overrides these; prefer
886
+ environment variables to keep keys out of shell history. Intake is read-only,
887
+ includes comments, and keeps Linear credentials out of the patch subprocess.
888
+ Issue URLs must match the selected workspace.
889
+
890
+ ### Verify fixes
891
+
892
+ `verify-fix` checks fixes in a read-only sandbox. Pass a description, saved
893
+ finding ID, `--scan SCAN_ID`, `--linear-issue ISSUE`, or `--linear-project "PROJECT"`.
894
+ Linear credentials and filters work as for `patch`. To check a finished backlog,
895
+ explicitly filter for completed issues.
896
+
897
+ Results include evidence and a status: `fixed`, `still_vulnerable`, or
898
+ `inconclusive`. Use `--json` for structured output. Exit codes are `0` if all
899
+ findings are fixed, `1` if any remain vulnerable, and `2` if verification is
900
+ inconclusive or couldn't finish.
901
+
902
+ ### Command discovery and integrations
903
+
904
+ The CLI uses [Incur](https://github.com/wevm/incur). Use `--llms` for the
905
+ command manifest, `scan --schema --format json` for a command schema, and
906
+ `completions bash|zsh|fish` for shell completions. Scan output supports
907
+ `--format toon|json|yaml|jsonl` and `--full-output`.
908
+
909
+ `skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
910
+ MCP exposes only the read-only `info` command because the transport cannot
911
+ cancel active scans.
912
+
913
+ ## Containerized bulk scans
914
+
915
+ Create `repositories.csv` as described under [Bulk scans](#bulk-scans).
916
+ With a published image, run from the Codex Security repository root:
1202
917
 
1203
918
  ```bash
1204
919
  mkdir -p results state
@@ -1210,17 +925,17 @@ docker compose run --rm codex-security login --device-auth
1210
925
  docker compose run --rm codex-security
1211
926
  ```
1212
927
 
1213
- Reports and resumable scan results are written to `results/`; the reusable
1214
- device login remains in `state/`. For unattended scans, set `OPENAI_API_KEY`
1215
- or `CODEX_API_KEY` instead. Set `GH_TOKEN` or `GITHUB_TOKEN` for private
1216
- GitHub repositories.
928
+ Results go to `results/`; device login stays in `state/`. For unattended scans,
929
+ set `OPENAI_API_KEY` or `CODEX_API_KEY`. Private GitHub checkouts use `GH_TOKEN`
930
+ or `GITHUB_TOKEN`; GitHub Enterprise uses `CODEX_SECURITY_GIT_HOST`. The container
931
+ requires CSV input, without interactive discovery.
1217
932
 
1218
- The container accepts the repository CSV before or after bulk-scan options.
1219
- Interactive repository discovery remains disabled, including when global CLI
1220
- options appear before `bulk-scan`.
933
+ Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,
934
+ `CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and
935
+ `CODEX_SECURITY_STATE` for the image, user, seccomp profile, and mounts.
1221
936
 
1222
937
  On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
1223
- can install the optional, narrowly scoped AppArmor profile once:
938
+ can install the optional AppArmor profile:
1224
939
 
1225
940
  ```bash
1226
941
  sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
@@ -1228,37 +943,29 @@ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
1228
943
  docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
1229
944
  ```
1230
945
 
1231
- The override preserves the nonroot user, dropped capabilities,
1232
- no-new-privileges, and hardened seccomp policy. Other Docker hosts do not need
1233
- the profile or override.
946
+ The override keeps the nonroot user, dropped capabilities, no-new-privileges,
947
+ and seccomp policy. Other Docker hosts don't need it.
1234
948
 
1235
949
  ## Local security model
1236
950
 
1237
- Codex Security runs with your local operating-system permissions. Scan only
1238
- repositories you trust and either own or are authorized to assess. Your
1239
- repository, Git installation, configured tools, and other scans under the
1240
- same account are not separate security principals.
1241
-
1242
- Every scan uses the `codex_security_scan` filesystem profile and
1243
- automatically reviewed execution approvals. Its baseline profile allows reads
1244
- of the local filesystem and writes to workspace roots and the selected scan
1245
- state directory. Approval requests are reviewed without an interactive prompt;
1246
- approved requests can grant additional permissions for a specific operation.
1247
- Use `--codex 'approval_policy="never"'` or a selected profile with that policy
1248
- to deny all requests instead. Other `approval_policy`, `approvals_reviewer`,
1249
- `sandbox_mode`, or permission overrides cannot replace the reviewer or baseline
1250
- filesystem profile. Saved scans retain their effective approval policy; older
1251
- saved scans remain deny-all when rerun. Independently enforced host and network
1252
- restrictions still apply.
1253
-
1254
- Scan and workbench subprocesses can inherit your environment, including
1255
- unrelated API tokens and cloud credentials. Start a scan with only the
1256
- credentials it needs.
1257
-
1258
- The scanner must stay within the target and output paths you authorize and
1259
- must not disclose private data beyond the operation you requested. Its results
1260
- must accurately report the scan mode, reviewed files, and exclusions. Consult
1261
- the security policy for the full threat model and private reporting process.
951
+ Codex Security runs with your operating-system permissions. Only scan
952
+ repositories you trust and are authorized to assess. Local tools and scans
953
+ under the same account aren't separate security principals.
954
+
955
+ The `codex_security_scan` profile allows reads across the local filesystem and
956
+ writes to workspace roots. Execution approvals are reviewed automatically and
957
+ may grant extra permissions for one operation. Set
958
+ `--codex 'approval_policy="never"'`, directly or in a selected profile, to deny
959
+ requests. Other overrides can't replace the reviewer or filesystem profile.
960
+ Saved scans keep their approval policy; older scans stay deny-all on rerun.
961
+ Host and network restrictions still apply.
962
+
963
+ Start scans with only the credentials they need. Scan and workbench subprocesses
964
+ can inherit your environment, including unrelated API tokens and cloud credentials.
965
+
966
+ Repository contents, model output, and imported artifacts do not authorize
967
+ access to other targets, disclosure of credentials, or writes outside approved
968
+ paths. See the security policy below for the full threat model.
1262
969
 
1263
970
  ## Documentation and security
1264
971