@openai/codex-security 0.1.19 → 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.
- package/README.md +585 -833
- package/_bundled_plugin/.codex-plugin/plugin.json +1 -1
- package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
- package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
- package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +243 -0
- package/_bundled_plugin/scripts/finalize_scan_contract.py +92 -11
- package/_bundled_plugin/scripts/launch_codex_security_mcp +0 -0
- package/_bundled_plugin/scripts/workbench_cli.py +5 -1
- package/_bundled_plugin/scripts/workbench_db.py +53 -0
- package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +88 -0
- package/_bundled_plugin/skills/assess-patch-risk/agents/openai.yaml +4 -0
- package/_bundled_plugin/skills/assess-patch-risk/references/risk-rubric.md +76 -0
- package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +163 -0
- package/_bundled_plugin/skills/fix-finding/SKILL.md +16 -48
- package/dist/api.d.ts +1 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +14 -18
- package/dist/api.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts +8 -0
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +21 -25
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/cli.d.ts +27 -4
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +561 -114
- package/dist/cli.js.map +1 -1
- package/dist/cloud-publish.d.ts +5 -1
- package/dist/cloud-publish.d.ts.map +1 -1
- package/dist/cloud-publish.js +323 -21
- package/dist/cloud-publish.js.map +1 -1
- package/dist/component-plan.d.ts.map +1 -1
- package/dist/component-plan.js +5 -1
- package/dist/component-plan.js.map +1 -1
- package/dist/github.d.ts +161 -0
- package/dist/github.d.ts.map +1 -0
- package/dist/github.js +158 -0
- package/dist/github.js.map +1 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/linear.d.ts +5 -0
- package/dist/linear.d.ts.map +1 -1
- package/dist/linear.js +8 -3
- package/dist/linear.js.map +1 -1
- package/dist/publication-events.d.ts +40 -13
- package/dist/publication-events.d.ts.map +1 -1
- package/dist/publication-events.js +218 -104
- package/dist/publication-events.js.map +1 -1
- package/dist/publication-store.d.ts +1 -0
- package/dist/publication-store.d.ts.map +1 -1
- package/dist/publication-store.js +73 -26
- package/dist/publication-store.js.map +1 -1
- package/dist/publication.d.ts +5 -0
- package/dist/publication.d.ts.map +1 -1
- package/dist/publication.js +12 -0
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +50 -1
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +640 -256
- package/dist/publish.js.map +1 -1
- package/dist/runtime.d.ts +0 -3
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +258 -185
- package/dist/runtime.js.map +1 -1
- package/dist/scan-comparison.d.ts +3 -0
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +6 -1
- package/dist/scan-comparison.js.map +1 -1
- package/dist/targets.d.ts.map +1 -1
- package/dist/targets.js +1 -0
- package/dist/targets.js.map +1 -1
- package/dist/thread-source.d.ts +8 -0
- package/dist/thread-source.d.ts.map +1 -0
- package/dist/thread-source.js +7 -0
- package/dist/thread-source.js.map +1 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +8 -5
package/README.md
CHANGED
|
@@ -1,12 +1,9 @@
|
|
|
1
1
|
# `@openai/codex-security`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
-
|
|
67
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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.
|
|
97
80
|
|
|
98
|
-
|
|
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.
|
|
81
|
+
### Import GitHub code scanning alerts
|
|
102
82
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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.
|
|
114
|
+
|
|
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.
|
|
119
|
+
|
|
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
|
-
|
|
127
|
+
Constructor options:
|
|
111
128
|
|
|
112
|
-
| Option | Description
|
|
113
|
-
| ---------------- |
|
|
114
|
-
| `pluginPath` |
|
|
115
|
-
| `pythonPath` |
|
|
116
|
-
| `codexOverrides` |
|
|
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
|
-
|
|
135
|
+
Options for `security.run(repository, options)` and
|
|
119
136
|
`security.preflight(repository, options)`:
|
|
120
137
|
|
|
121
|
-
| Option | Description
|
|
122
|
-
| ----------------------- |
|
|
123
|
-
| `auth` |
|
|
124
|
-
| `safetyIdentifier` | Stable hashed end-user ID for
|
|
125
|
-
| `target` |
|
|
126
|
-
| `mode` |
|
|
127
|
-
| `knowledgeBasePaths` |
|
|
128
|
-
| `outputDir` |
|
|
129
|
-
| `archiveExisting` | Archive results
|
|
130
|
-
| `maxCostUsd` | Stop
|
|
131
|
-
| `maxTimeHours` |
|
|
132
|
-
| `failureSeverity` |
|
|
133
|
-
| `parentScanId` |
|
|
134
|
-
| `expectedPluginVersion` |
|
|
135
|
-
| `signal` |
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
`
|
|
141
|
-
|
|
142
|
-
the
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
168
|
-
|
|
169
|
-
|
|
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
|
-
|
|
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
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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.
|
|
223
|
+
|
|
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.
|
|
221
228
|
|
|
222
|
-
|
|
223
|
-
|
|
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" })`.
|
|
229
|
+
If ChatGPT credentials cannot be refreshed, run `login status`. Retry if the
|
|
230
|
+
sign-in recently changed; otherwise run `logout`, then `login`.
|
|
228
231
|
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
237
|
+
npx @openai/codex-security scan . --auth chatgpt
|
|
238
|
+
npx @openai/codex-security scan . --auth api-key
|
|
234
239
|
```
|
|
235
240
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
`
|
|
240
|
-
|
|
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.
|
|
241
246
|
|
|
242
|
-
Some cybersecurity requests and protected findings require
|
|
243
|
-
|
|
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
|
-
|
|
315
|
-
`
|
|
316
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
336
|
-
|
|
337
|
-
|
|
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
|
-
|
|
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
|
-
|
|
356
|
-
|
|
357
|
-
|
|
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
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
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
|
|
371
|
-
|
|
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 `--
|
|
380
|
-
|
|
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
|
-
|
|
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
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
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`
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
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
|
|
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 =
|
|
462
|
-
subagents =
|
|
463
|
-
stop_after_no_new =
|
|
464
|
-
|
|
465
|
-
|
|
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
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
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
|
-
|
|
521
|
-
configuration
|
|
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`
|
|
546
|
-
`--codex KEY=VALUE`
|
|
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
|
|
557
|
-
|
|
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,253 +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
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
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
|
-
|
|
577
|
-
|
|
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
|
-
|
|
464
|
+
See [Local security model](#local-security-model) for approval and filesystem
|
|
465
|
+
restrictions.
|
|
582
466
|
|
|
583
|
-
|
|
584
|
-
`~/.codex/codex-security/config.toml`:
|
|
467
|
+
### Environment variables
|
|
585
468
|
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
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
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
615
|
-
|
|
616
|
-
|
|
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
|
-
```bash
|
|
738
|
-
npx @openai/codex-security publish scan --to cloud --dry-run --json
|
|
739
|
-
```
|
|
740
|
-
|
|
741
|
-
The picker shows each scan's repository, finding count, age, and scan ID.
|
|
742
|
-
Choose scans, then select **Done**. No scans are selected automatically.
|
|
743
|
-
|
|
744
|
-
For scripts, repeat `--scan` with saved scan IDs or unique ID prefixes (at
|
|
745
|
-
least eight characters):
|
|
746
|
-
|
|
747
530
|
```bash
|
|
748
|
-
npx @openai/codex-security
|
|
749
|
-
--
|
|
750
|
-
--to cloud --dry-run --json
|
|
531
|
+
npx @openai/codex-security bulk-scan repositories.csv \
|
|
532
|
+
--output-dir /path/outside/repositories/security-scans --workers 4
|
|
751
533
|
```
|
|
752
534
|
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
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.
|
|
757
540
|
|
|
758
|
-
`--
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
then sign in with ChatGPT again:
|
|
762
|
-
|
|
763
|
-
```toml
|
|
764
|
-
cli_auth_credentials_store = "file"
|
|
765
|
-
```
|
|
766
|
-
|
|
767
|
-
Automatic and keyring credential storage are not accepted for Cloud
|
|
768
|
-
publication, even when an `auth.json` file exists, because that file may be
|
|
769
|
-
stale and belong to a different account. The CLI sends one scan at a time,
|
|
770
|
-
with each scan's findings and metadata in a separate request.
|
|
771
|
-
|
|
772
|
-
For artifacts outside local history, use repeated `--scan-dir PATH` instead.
|
|
773
|
-
A single positional directory is still accepted and can be combined with
|
|
774
|
-
`--scan-dir`. Do not combine directory inputs with `--scan`. Each directory
|
|
775
|
-
must contain one completed, sealed scan; bulk-run directories and
|
|
776
|
-
`results.jsonl` files are not accepted. Relative paths start at the current
|
|
777
|
-
directory, and `~/...` starts at your home directory. Each resolved directory
|
|
778
|
-
is processed once.
|
|
779
|
-
|
|
780
|
-
For multiple distinct scans, output contains:
|
|
781
|
-
|
|
782
|
-
- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
|
|
783
|
-
- `failed`: errors with `scanDir` and, for saved selections, `scanId`.
|
|
784
|
-
- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
|
|
785
|
-
did not reach before cancellation.
|
|
786
|
-
|
|
787
|
-
For one distinct scan, the CLI returns the scan result directly,
|
|
788
|
-
without the batch fields above.
|
|
789
|
-
|
|
790
|
-
The CLI continues after a failed scan and exits with code `2` if any scan
|
|
791
|
-
fails. Ctrl-C or SIGTERM stops new requests and returns the results collected
|
|
792
|
-
so far. When cancellation stops work before every requested publication is
|
|
793
|
-
confirmed, the exit code is `130` for Ctrl-C and `143` for SIGTERM. If the
|
|
794
|
-
single response or final batch response has already confirmed the complete
|
|
795
|
-
publication, the command exits with code `0`. Cloud publication receipts
|
|
796
|
-
appear in command output; the CLI does not save them to scan history.
|
|
797
|
-
|
|
798
|
-
A successful receipt contains one opaque Cloud finding ID for each submitted
|
|
799
|
-
finding, in request order. These are not local finding IDs. The CLI verifies
|
|
800
|
-
the authenticated response status, count, and ID uniqueness, but cannot map
|
|
801
|
-
opaque server IDs back to individual local findings independently.
|
|
802
|
-
|
|
803
|
-
The CLI never retries an upload automatically. An upload with a missing or
|
|
804
|
-
invalid receipt may already have been accepted. Check whether Cloud accepted
|
|
805
|
-
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.
|
|
806
544
|
|
|
807
545
|
### Custom validation
|
|
808
546
|
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
into a separate validation turn and is not sent to discovery workers.
|
|
812
|
-
The SDK adapts the bundled discovery workflow without changing the plugin.
|
|
813
|
-
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.
|
|
814
549
|
|
|
815
550
|
```bash
|
|
816
551
|
npx @openai/codex-security scan . --validation-prompt-file validation.md
|
|
@@ -825,10 +560,10 @@ const result = await security.run(repository, {
|
|
|
825
560
|
});
|
|
826
561
|
```
|
|
827
562
|
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
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.
|
|
832
567
|
|
|
833
568
|
The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
|
|
834
569
|
|
|
@@ -857,63 +592,106 @@ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
|
|
|
857
592
|
}
|
|
858
593
|
```
|
|
859
594
|
|
|
860
|
-
|
|
861
|
-
`
|
|
862
|
-
`{ "level": "medium", "rationale": "..." }`
|
|
863
|
-
|
|
864
|
-
do not change. Deferred candidates make coverage partial. Suppressed and
|
|
865
|
-
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.
|
|
866
599
|
|
|
867
|
-
The scan
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
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.
|
|
872
605
|
|
|
873
|
-
### Publish
|
|
606
|
+
### Publish findings to Cloud
|
|
874
607
|
|
|
875
|
-
|
|
876
|
-
Linear team:
|
|
608
|
+
Choose completed scans from local history:
|
|
877
609
|
|
|
878
610
|
```bash
|
|
879
|
-
npx @openai/codex-security publish scan --
|
|
880
|
-
--to linear \
|
|
881
|
-
--linear-team TEAM_ID
|
|
611
|
+
npx @openai/codex-security publish scan --to cloud --dry-run --json
|
|
882
612
|
```
|
|
883
613
|
|
|
884
|
-
|
|
885
|
-
For external artifacts, a positional directory or `--scan-dir PATH` is also
|
|
886
|
-
accepted.
|
|
887
|
-
|
|
888
|
-
Add `--linear-project PROJECT_ID` to place the issues in a Linear project.
|
|
889
|
-
The existing `--project` flag remains an alias. Without a project, issues are
|
|
890
|
-
created directly in the selected team.
|
|
614
|
+
Press Space to select scans, then Enter to submit. Nothing is preselected.
|
|
891
615
|
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
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:
|
|
895
618
|
|
|
896
619
|
```bash
|
|
897
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 \
|
|
898
678
|
--to linear \
|
|
899
679
|
--linear-team TEAM_ID
|
|
900
680
|
```
|
|
901
681
|
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
Interactive publication shows a full-screen activity view with live Codex
|
|
907
|
-
output and issue-creation progress. Other terminals receive plain progress on
|
|
908
|
-
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.
|
|
909
686
|
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
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.
|
|
914
691
|
|
|
915
|
-
|
|
916
|
-
|
|
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:
|
|
917
695
|
|
|
918
696
|
```bash
|
|
919
697
|
export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
|
|
@@ -922,35 +700,36 @@ npx @openai/codex-security publish scan /path/to/completed-scan \
|
|
|
922
700
|
--linear-team TEAM_ID
|
|
923
701
|
```
|
|
924
702
|
|
|
925
|
-
Direct API publication leaves issues unassigned
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
to
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
creates
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
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.
|
|
707
|
+
|
|
708
|
+
Check scan integrity and recorded publications before publishing:
|
|
709
|
+
|
|
710
|
+
```bash
|
|
711
|
+
npx @openai/codex-security publish check /path/to/completed-scan \
|
|
712
|
+
--to linear --linear-team TEAM_ID --json
|
|
713
|
+
```
|
|
714
|
+
|
|
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.
|
|
954
733
|
|
|
955
734
|
```ts
|
|
956
735
|
import { publishScan } from "@openai/codex-security";
|
|
@@ -958,101 +737,65 @@ import { publishScan } from "@openai/codex-security";
|
|
|
958
737
|
const publication = await publishScan("/path/to/completed-scan", {
|
|
959
738
|
destination: "linear",
|
|
960
739
|
teamId: "TEAM_ID",
|
|
961
|
-
onProgress: (progress) => {
|
|
962
|
-
if (progress.type === "issue_completed") {
|
|
963
|
-
console.error(
|
|
964
|
-
`Processed ${progress.completed} of ${progress.total} findings.`,
|
|
965
|
-
);
|
|
966
|
-
}
|
|
967
|
-
},
|
|
968
740
|
});
|
|
969
741
|
|
|
970
742
|
console.log(publication.scanId);
|
|
971
743
|
console.log(publication.created.length);
|
|
972
744
|
```
|
|
973
745
|
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
Pass `linearApiKey` to publish directly through the Linear API. Omit
|
|
978
|
-
`assigneeId` to leave issues unassigned, or supply a Linear user ID or email
|
|
979
|
-
address to select an assignee:
|
|
980
|
-
|
|
981
|
-
```ts
|
|
982
|
-
const directPublication = await publishScan("/path/to/completed-scan", {
|
|
983
|
-
destination: "linear",
|
|
984
|
-
teamId: "TEAM_ID",
|
|
985
|
-
linearApiKey: process.env["CODEX_SECURITY_LINEAR_API_KEY"],
|
|
986
|
-
assigneeId: "teammate@example.com",
|
|
987
|
-
});
|
|
988
|
-
```
|
|
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.
|
|
989
749
|
|
|
990
750
|
### Scan history and reruns
|
|
991
751
|
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
`scans logs`
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
maintain
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
`
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
treated as resolved when the later scan is incomplete or does not cover their
|
|
1040
|
-
original scope.
|
|
1041
|
-
|
|
1042
|
-
The CLI uses [Incur](https://github.com/wevm/incur) for agent-friendly discovery
|
|
1043
|
-
and structured output. Inspect the command manifest with `--llms`, inspect a
|
|
1044
|
-
command schema with `scan --schema --format json`, register the CLI as an MCP
|
|
1045
|
-
server with `mcp add`, sync agent skills with `skills add`, or generate shell
|
|
1046
|
-
completions with `completions bash|zsh|fish`. Scan results support
|
|
1047
|
-
`--format toon|json|yaml|jsonl` and `--full-output`.
|
|
1048
|
-
Use `info --json` for SDK and bundled-plugin metadata. MCP exposes only this
|
|
1049
|
-
read-only metadata command; scans, bulk repository scans,
|
|
1050
|
-
authentication, exports, validation, and patching remain CLI-only because the
|
|
1051
|
-
MCP transport cannot cancel active scans.
|
|
1052
|
-
|
|
1053
|
-
For CI, save machine-readable output outside the checked-out repository and
|
|
1054
|
-
apply a severity policy. Incomplete coverage and runtime errors still exit
|
|
1055
|
-
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:
|
|
1056
799
|
|
|
1057
800
|
```bash
|
|
1058
801
|
SCAN_ROOT="$(mktemp -d)"
|
|
@@ -1063,97 +806,114 @@ npx @openai/codex-security scan . \
|
|
|
1063
806
|
--fail-on-severity high > "$SCAN_ROOT/findings.json"
|
|
1064
807
|
```
|
|
1065
808
|
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
Use `export` to create CSV, JSON, or SARIF from a completed, sealed scan without
|
|
1073
|
-
starting Codex or loading credentials. Without a scan directory, it exports the
|
|
1074
|
-
latest completed scan for the current repository. JSON preserves the sealed findings
|
|
1075
|
-
document. CSV uses the portable findings columns, marks findings as open, and
|
|
1076
|
-
does not include local workbench triage state. The exporter validates the seal
|
|
1077
|
-
before writing, accepts `--output -` for stdout, and can use
|
|
1078
|
-
`--source-root /path/to/repository` with SARIF to add source-line fingerprints.
|
|
1079
|
-
Run `npx @openai/codex-security export --help` for all export options.
|
|
1080
|
-
|
|
1081
|
-
Use `validate` to run the bundled validation skill on candidate findings and
|
|
1082
|
-
`patch` to run the bundled fix-finding skill on security issues. Each positional
|
|
1083
|
-
input can be either a file, whose contents are read into the request, or literal
|
|
1084
|
-
text. These inputs operate on the current directory. Pass a saved finding or
|
|
1085
|
-
occurrence ID instead to patch its original repository, or use
|
|
1086
|
-
`patch --scan SCAN_ID --severity high` for high and critical findings from one
|
|
1087
|
-
scan. `--scan latest` selects the most recent scan of the current repository.
|
|
1088
|
-
Saved-finding patch commands accept `--json` and return a verified, already
|
|
1089
|
-
fixed, blocked, or failed result for each finding. Both commands use the scan
|
|
1090
|
-
model and reasoning defaults and disable plugins. Patching starts a separate
|
|
1091
|
-
saved task in the Codex desktop app for each finding. Override the model with
|
|
1092
|
-
`--codex 'model="gpt-5.6-sol"'` and the
|
|
1093
|
-
reasoning effort with `--effort high` or
|
|
1094
|
-
`--codex 'model_reasoning_effort="high"'`.
|
|
1095
|
-
|
|
1096
|
-
Use `patch --linear-issue ISSUE` to import a Linear issue by identifier or URL.
|
|
1097
|
-
Repeat `--linear-issue` to include more issues. Use
|
|
1098
|
-
`patch --linear-project "PROJECT"` to patch every open issue in a project. Add
|
|
1099
|
-
`--linear-filter '{"labels":{"name":{"eq":"security"}}}'` to apply a native
|
|
1100
|
-
Linear issue filter on the server. Completed and canceled issues are excluded
|
|
1101
|
-
unless the filter explicitly sets `state`. Set `CODEX_SECURITY_LINEAR_API_KEY`
|
|
1102
|
-
for a personal API key, or `LINEAR_ACCESS_TOKEN` for an OAuth access token.
|
|
1103
|
-
`LINEAR_API_KEY` is also accepted. `--linear-api-key KEY` overrides these
|
|
1104
|
-
environment settings; prefer the environment variable to keep keys out of shell
|
|
1105
|
-
history. Imported content is always literal, and issue URLs must match the
|
|
1106
|
-
selected workspace. Each imported issue includes its title, description, and
|
|
1107
|
-
all comments with their source links. Linear access is read-only, and its
|
|
1108
|
-
credentials are not passed to the patch subprocess.
|
|
1109
|
-
|
|
1110
|
-
Use `verify-fix` to check whether an existing security fix actually closes its
|
|
1111
|
-
original vulnerability without modifying the repository. Pass a finding
|
|
1112
|
-
description, a saved finding identifier, `--scan SCAN_ID`, `--linear-issue ISSUE`,
|
|
1113
|
-
or `--linear-project "PROJECT"`. Linear intake uses the same credentials and
|
|
1114
|
-
`--linear-filter` options as `patch`; explicitly filter for completed issues when
|
|
1115
|
-
verifying a finished backlog. Verification runs the bundled `verify-fix` skill
|
|
1116
|
-
in a read-only Codex sandbox and reports `fixed`, `still_vulnerable`, or
|
|
1117
|
-
`inconclusive` with supporting evidence for every finding. Use `--json` for
|
|
1118
|
-
structured output. Exit code `0` means every finding is fixed, `1` means at
|
|
1119
|
-
least one finding remains vulnerable, and `2` means a result is inconclusive or
|
|
1120
|
-
verification could not complete.
|
|
1121
|
-
|
|
1122
|
-
Interactive verification shows the same live agent-activity dashboard used by
|
|
1123
|
-
scans and Linear publication. Reasoning, repository commands, and progress are
|
|
1124
|
-
written to stderr; redirected output and CI receive plain progress lines, and
|
|
1125
|
-
JSON results on stdout remain machine-readable.
|
|
1126
|
-
|
|
1127
|
-
Exit codes are `0` for a completed report-only scan or a passing policy, `1`
|
|
1128
|
-
for a completed policy violation, `2` for invalid input, incomplete coverage, or
|
|
1129
|
-
a runtime/export error, `130` for interruption, and `143` for termination.
|
|
1130
|
-
|
|
1131
|
-
Use `--dry-run` or `await security.preflight(...)` to validate the repository,
|
|
1132
|
-
target, mode, output location, and Codex overrides without initializing the
|
|
1133
|
-
runtime or loading credentials. Dry runs do not inspect the plugin or probe its
|
|
1134
|
-
Python interpreter. The preflight result includes the selected authentication
|
|
1135
|
-
method and, for an environment API key, its variable name. Authentication and
|
|
1136
|
-
model access remain unverified until a real scan starts.
|
|
1137
|
-
|
|
1138
|
-
Scan progress identifies the selected credential source before Codex starts.
|
|
1139
|
-
Terminals and noninteractive CI logs also show how to retry with
|
|
1140
|
-
`--auth chatgpt` when an environment API key overrides the stored sign-in.
|
|
1141
|
-
Progress remains on stderr so JSON output stays machine readable. Network
|
|
1142
|
-
failures and rate limits remain retryable; definitive authentication and model
|
|
1143
|
-
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`.
|
|
1144
814
|
|
|
1145
|
-
|
|
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`.
|
|
1146
818
|
|
|
1147
|
-
|
|
819
|
+
### Import alerts from the CLI
|
|
1148
820
|
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
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
|
|
1152
835
|
```
|
|
1153
836
|
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
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:
|
|
1157
917
|
|
|
1158
918
|
```bash
|
|
1159
919
|
mkdir -p results state
|
|
@@ -1165,17 +925,17 @@ docker compose run --rm codex-security login --device-auth
|
|
|
1165
925
|
docker compose run --rm codex-security
|
|
1166
926
|
```
|
|
1167
927
|
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
or `
|
|
1171
|
-
|
|
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.
|
|
1172
932
|
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
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.
|
|
1176
936
|
|
|
1177
937
|
On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
|
|
1178
|
-
can install the optional
|
|
938
|
+
can install the optional AppArmor profile:
|
|
1179
939
|
|
|
1180
940
|
```bash
|
|
1181
941
|
sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
|
|
@@ -1183,37 +943,29 @@ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
|
|
|
1183
943
|
docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
|
|
1184
944
|
```
|
|
1185
945
|
|
|
1186
|
-
The override
|
|
1187
|
-
|
|
1188
|
-
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.
|
|
1189
948
|
|
|
1190
949
|
## Local security model
|
|
1191
950
|
|
|
1192
|
-
Codex Security runs with your
|
|
1193
|
-
repositories you trust and
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
unrelated API tokens and cloud credentials. Start a scan with only the
|
|
1211
|
-
credentials it needs.
|
|
1212
|
-
|
|
1213
|
-
The scanner must stay within the target and output paths you authorize and
|
|
1214
|
-
must not disclose private data beyond the operation you requested. Its results
|
|
1215
|
-
must accurately report the scan mode, reviewed files, and exclusions. Consult
|
|
1216
|
-
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.
|
|
1217
969
|
|
|
1218
970
|
## Documentation and security
|
|
1219
971
|
|