@openai/codex-security 0.1.20 → 0.1.23
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 +1101 -865
- 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/references/config-preflight.md +2 -30
- package/_bundled_plugin/references/core-scan.md +1 -1
- package/_bundled_plugin/references/final-report.md +1 -1
- package/_bundled_plugin/references/finding-detail-fields.md +5 -10
- package/_bundled_plugin/references/sarif-adapter.md +1 -1
- package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +243 -0
- package/_bundled_plugin/scripts/config_preflight.py +2 -8
- package/_bundled_plugin/scripts/finalize_scan_contract.py +206 -35
- package/_bundled_plugin/scripts/finding_preview.py +22 -4
- package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -1
- package/_bundled_plugin/scripts/launch_codex_security_mcp +0 -0
- package/_bundled_plugin/scripts/windows_scan_local_files.py +101 -7
- package/_bundled_plugin/scripts/workbench_cli.py +21 -1
- package/_bundled_plugin/scripts/workbench_dashboard.py +115 -0
- package/_bundled_plugin/scripts/workbench_db.py +29 -2
- package/_bundled_plugin/scripts/workbench_finding_index.py +42 -24
- package/_bundled_plugin/scripts/workbench_finding_workflows.py +190 -0
- package/_bundled_plugin/scripts/workbench_findings.py +216 -0
- package/_bundled_plugin/scripts/workbench_saved_results.py +30 -5
- package/_bundled_plugin/scripts/workbench_schema.py +263 -58
- package/_bundled_plugin/scripts/workbench_target.py +22 -3
- 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/_bundled_plugin/skills/track-findings/SKILL.md +2 -0
- package/dist/api.d.ts +3 -1
- package/dist/api.d.ts.map +1 -1
- package/dist/api.js +129 -45
- package/dist/api.js.map +1 -1
- package/dist/bulk-scan-discovery.d.ts.map +1 -1
- package/dist/bulk-scan-discovery.js +6 -24
- package/dist/bulk-scan-discovery.js.map +1 -1
- package/dist/cli.d.ts +28 -2
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +525 -96
- 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 +312 -10
- 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/contract.d.ts +1 -0
- package/dist/contract.d.ts.map +1 -1
- package/dist/contract.js +9 -0
- package/dist/contract.js.map +1 -1
- package/dist/custom-publish.d.ts +22 -0
- package/dist/custom-publish.d.ts.map +1 -0
- package/dist/custom-publish.js +47 -0
- package/dist/custom-publish.js.map +1 -0
- package/dist/custom-validation-prompt.js +1 -1
- package/dist/custom-validation-prompt.js.map +1 -1
- package/dist/deduplication/checkpointed-review.d.ts +16 -0
- package/dist/deduplication/checkpointed-review.d.ts.map +1 -0
- package/dist/deduplication/checkpointed-review.js +76 -0
- package/dist/deduplication/checkpointed-review.js.map +1 -0
- package/dist/deduplication/codex-review.d.ts +21 -0
- package/dist/deduplication/codex-review.d.ts.map +1 -0
- package/dist/deduplication/codex-review.js +252 -0
- package/dist/deduplication/codex-review.js.map +1 -0
- package/dist/deduplication/deduplication-prompts.d.ts +8 -0
- package/dist/deduplication/deduplication-prompts.d.ts.map +1 -0
- package/dist/deduplication/deduplication-prompts.js +35 -0
- package/dist/deduplication/deduplication-prompts.js.map +1 -0
- package/dist/deduplication/deduplication-reviewer.d.ts +46 -0
- package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -0
- package/dist/deduplication/deduplication-reviewer.js +105 -0
- package/dist/deduplication/deduplication-reviewer.js.map +1 -0
- package/dist/deduplication/deduplication.d.ts +6 -0
- package/dist/deduplication/deduplication.d.ts.map +1 -0
- package/dist/deduplication/deduplication.js +85 -0
- package/dist/deduplication/deduplication.js.map +1 -0
- package/dist/deduplication/scan.d.ts +16 -0
- package/dist/deduplication/scan.d.ts.map +1 -0
- package/dist/deduplication/scan.js +101 -0
- package/dist/deduplication/scan.js.map +1 -0
- package/dist/finding-dedupe-groups.d.ts +7 -0
- package/dist/finding-dedupe-groups.d.ts.map +1 -0
- package/dist/finding-dedupe-groups.js +2 -0
- package/dist/finding-dedupe-groups.js.map +1 -0
- package/dist/finding-retrieval.d.ts +13 -0
- package/dist/finding-retrieval.d.ts.map +1 -0
- package/dist/finding-retrieval.js +2 -0
- package/dist/finding-retrieval.js.map +1 -0
- package/dist/finding-workflow.d.ts +53 -0
- package/dist/finding-workflow.d.ts.map +1 -0
- package/dist/finding-workflow.js +117 -0
- package/dist/finding-workflow.js.map +1 -0
- package/dist/findings-client.d.ts +15 -0
- package/dist/findings-client.d.ts.map +1 -0
- package/dist/findings-client.js +60 -0
- package/dist/findings-client.js.map +1 -0
- 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 +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/publication.js +28 -40
- package/dist/publication.js.map +1 -1
- package/dist/publish.d.ts +10 -0
- package/dist/publish.d.ts.map +1 -1
- package/dist/publish.js +29 -5
- package/dist/publish.js.map +1 -1
- package/dist/runtime.d.ts +5 -4
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +371 -197
- package/dist/runtime.js.map +1 -1
- package/dist/saved-scan.d.ts +15 -0
- package/dist/saved-scan.d.ts.map +1 -0
- package/dist/saved-scan.js +68 -0
- package/dist/saved-scan.js.map +1 -0
- package/dist/scan-comparison.d.ts +6 -2
- package/dist/scan-comparison.d.ts.map +1 -1
- package/dist/scan-comparison.js +7 -2
- package/dist/scan-comparison.js.map +1 -1
- package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +276 -0
- package/dist/server/dashboard/app.css +2 -0
- package/dist/server/dashboard/app.js +66 -0
- package/dist/server/dashboard/index.html +18 -0
- package/dist/server/dashboard-types.d.ts +45 -0
- package/dist/server/dashboard-types.d.ts.map +1 -0
- package/dist/server/dashboard-types.js +2 -0
- package/dist/server/dashboard-types.js.map +1 -0
- package/dist/server/dashboard.d.ts +6 -0
- package/dist/server/dashboard.d.ts.map +1 -0
- package/dist/server/dashboard.js +45 -0
- package/dist/server/dashboard.js.map +1 -0
- package/dist/server/embeddings.d.ts +16 -0
- package/dist/server/embeddings.d.ts.map +1 -0
- package/dist/server/embeddings.js +114 -0
- package/dist/server/embeddings.js.map +1 -0
- package/dist/server/errors.d.ts +5 -0
- package/dist/server/errors.d.ts.map +1 -0
- package/dist/server/errors.js +8 -0
- package/dist/server/errors.js.map +1 -0
- package/dist/server/findings-service.d.ts +20 -0
- package/dist/server/findings-service.d.ts.map +1 -0
- package/dist/server/findings-service.js +31 -0
- package/dist/server/findings-service.js.map +1 -0
- package/dist/server/index.d.ts +2 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/index.js +32 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/routes.d.ts +6 -0
- package/dist/server/routes.d.ts.map +1 -0
- package/dist/server/routes.js +86 -0
- package/dist/server/routes.js.map +1 -0
- package/dist/server/server.d.ts +10 -0
- package/dist/server/server.d.ts.map +1 -0
- package/dist/server/server.js +17 -0
- package/dist/server/server.js.map +1 -0
- package/dist/server/sqlite-store.d.ts +22 -0
- package/dist/server/sqlite-store.d.ts.map +1 -0
- package/dist/server/sqlite-store.js +82 -0
- package/dist/server/sqlite-store.js.map +1 -0
- package/dist/server/storage.d.ts +32 -0
- package/dist/server/storage.d.ts.map +1 -0
- package/dist/server/storage.js +2 -0
- package/dist/server/storage.js.map +1 -0
- package/dist/server/validation.d.ts +17 -0
- package/dist/server/validation.d.ts.map +1 -0
- package/dist/server/validation.js +53 -0
- package/dist/server/validation.js.map +1 -0
- 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/trusted-executable.d.ts.map +1 -1
- package/dist/trusted-executable.js +2 -1
- package/dist/trusted-executable.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +23 -8
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.
|
|
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.
|
|
61
44
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
can make one additional model call, including with a scan cost limit.
|
|
65
|
-
|
|
66
|
-
Results can contain source excerpts, vulnerability details, and reproduction
|
|
67
|
-
steps. Keep result directories and saved reports outside the repository and
|
|
68
|
-
limit access to authorized reviewers.
|
|
45
|
+
Keep results outside the repository and restrict access: reports can contain
|
|
46
|
+
source code, vulnerability details, and reproduction steps.
|
|
69
47
|
|
|
70
48
|
### Validate an existing finding
|
|
71
49
|
|
|
72
|
-
Use `security.validate()` to assess one finding without running a repository
|
|
73
|
-
scan or invoking the Codex Security CLI:
|
|
74
|
-
|
|
75
50
|
```ts
|
|
76
51
|
const security = new CodexSecurity();
|
|
77
52
|
try {
|
|
@@ -90,89 +65,125 @@ try {
|
|
|
90
65
|
}
|
|
91
66
|
```
|
|
92
67
|
|
|
93
|
-
|
|
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.
|
|
80
|
+
|
|
81
|
+
### Import GitHub code scanning alerts
|
|
82
|
+
|
|
83
|
+
Import alerts, including third-party SARIF uploads, and validate them against
|
|
84
|
+
the matching local checkout:
|
|
97
85
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
+
});
|
|
102
97
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
241
|
+
`--auth chatgpt` ignores environment API keys. `--auth api-key` requires
|
|
242
|
+
`OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; unset both
|
|
243
|
+
variables to default to ChatGPT. The SDK uses the same `auth` option on `run`
|
|
244
|
+
and `preflight`. Codex may still need ChatGPT credentials to load
|
|
245
|
+
workspace-managed policies when using an API key.
|
|
237
246
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
without printing its value, including when no stored sign-in exists.
|
|
241
|
-
|
|
242
|
-
Some cybersecurity requests and protected findings require approval through
|
|
243
|
-
Trusted Access for Cyber. To apply or check your access, visit
|
|
247
|
+
Some cybersecurity requests and protected findings require Trusted Access for
|
|
248
|
+
Cyber approval. Apply or check your access at
|
|
244
249
|
[chatgpt.com/cyber](https://chatgpt.com/cyber).
|
|
245
250
|
|
|
246
251
|
## CLI
|
|
247
252
|
|
|
248
253
|
```bash
|
|
249
|
-
npx @openai/codex-security scan
|
|
250
|
-
npx @openai/codex-security scan /path/to/repository
|
|
251
|
-
npx @openai/codex-security scan /path/to/repository --headless
|
|
252
|
-
npx @openai/codex-security scan /path/to/repository --patch
|
|
253
|
-
npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --json
|
|
254
|
-
npx @openai/codex-security scan /path/to/repository --patch --patch-severity high --create-pr
|
|
255
|
-
npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra
|
|
256
|
-
npx @openai/codex-security scan /path/to/repository --model gpt-5.6-terra --effort high
|
|
254
|
+
npx @openai/codex-security scan .
|
|
257
255
|
npx @openai/codex-security scan /path/to/repository --path src --path tests
|
|
258
|
-
npx @openai/codex-security scan-components /path/to/repository --component apps/api --component apps/web --output-dir /path/outside/repository/results
|
|
259
|
-
npx @openai/codex-security scan-components /path/to/repository --auto --output-dir /path/outside/repository/results
|
|
260
|
-
npx @openai/codex-security scan /path/to/repository --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
|
|
261
|
-
npx @openai/codex-security scan /path/to/repository --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
|
|
262
256
|
npx @openai/codex-security scan /path/to/repository --diff origin/main --json
|
|
263
257
|
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
|
|
264
|
-
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
|
|
265
|
-
npx @openai/codex-security scan /path/to/repository --verbose
|
|
266
258
|
npx @openai/codex-security scan /path/to/repository --dry-run
|
|
267
|
-
npx @openai/codex-security scan /path/to/repository --fail-on-severity high
|
|
268
|
-
npx @openai/codex-security scan /path/to/repository --max-cost 5
|
|
269
|
-
npx @openai/codex-security scan /path/to/repository --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5
|
|
270
|
-
npx @openai/codex-security install-hook
|
|
271
|
-
npx @openai/codex-security bulk-scan
|
|
272
|
-
npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high
|
|
273
|
-
npx @openai/codex-security bulk-scan --workers 4 --mode deep --max-attempts 3 --max-cost 25
|
|
274
|
-
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4 --knowledge-base /path/to/threat-models --knowledge-base /path/to/architecture.pdf
|
|
275
|
-
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --scan-prompt-file scan.md --post-scan-prompt-file follow-up.md
|
|
276
|
-
npx @openai/codex-security scans list /path/to/repository
|
|
277
|
-
npx @openai/codex-security scans list --scan-root /path/outside/repository/results
|
|
278
|
-
npx @openai/codex-security scans show
|
|
279
|
-
npx @openai/codex-security scans show SCAN_ID
|
|
280
|
-
npx @openai/codex-security scans logs
|
|
281
|
-
npx @openai/codex-security scans logs SCAN_ID
|
|
282
|
-
npx @openai/codex-security scans rerun
|
|
283
|
-
npx @openai/codex-security scans rerun SCAN_ID
|
|
284
|
-
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
|
|
285
|
-
npx @openai/codex-security scans match --all
|
|
286
|
-
npx @openai/codex-security scans compare
|
|
287
|
-
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID
|
|
288
|
-
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
|
|
289
|
-
npx @openai/codex-security findings
|
|
290
|
-
npx @openai/codex-security findings list /path/to/repository
|
|
291
|
-
npx @openai/codex-security findings false-positive OCCURRENCE_ID --reason "The route already checks permissions"
|
|
292
|
-
npx @openai/codex-security export
|
|
293
|
-
npx @openai/codex-security export /path/outside/repository/results --export-format sarif --output /path/outside/repository/results.sarif
|
|
294
|
-
npx @openai/codex-security export /path/outside/repository/results --export-format csv --output /path/outside/repository/findings.csv
|
|
295
|
-
npx @openai/codex-security export /path/outside/repository/results --export-format json --output /path/outside/repository/findings.json
|
|
296
|
-
npx @openai/codex-security publish scan /path/outside/repository/results --to linear --linear-team TEAM_ID
|
|
297
|
-
npx @openai/codex-security publish scan --to linear --linear-team TEAM_ID
|
|
298
|
-
npx @openai/codex-security validate /path/outside/repository/findings.json "Possible SQL injection in src/query.ts:42"
|
|
299
|
-
npx @openai/codex-security validate "Possible SQL injection" --effort high
|
|
300
|
-
npx @openai/codex-security verify-fix --linear-issue SEC-123 --json
|
|
301
|
-
npx @openai/codex-security verify-fix --linear-project "Security backlog" --linear-filter '{"state":{"type":{"eq":"completed"}}}' --json
|
|
302
|
-
npx @openai/codex-security verify-fix --scan SCAN_ID --severity high --json
|
|
303
|
-
npx @openai/codex-security patch /path/outside/repository/findings.json "Missing authorization check in src/routes.ts:18"
|
|
304
|
-
npx @openai/codex-security patch "Missing authorization check" --effort high
|
|
305
|
-
npx @openai/codex-security patch OCCURRENCE_ID
|
|
306
|
-
npx @openai/codex-security patch --scan SCAN_ID --severity high --json
|
|
307
|
-
npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
|
|
308
|
-
npx @openai/codex-security patch --resume-pr codex-security/patch-SCAN_ID
|
|
309
|
-
npx @openai/codex-security patch --scan latest --severity medium
|
|
310
|
-
npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124
|
|
311
|
-
npx @openai/codex-security patch --linear-project "Security backlog" --linear-filter '{"labels":{"name":{"eq":"security"}}}'
|
|
312
259
|
```
|
|
313
260
|
|
|
314
|
-
|
|
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,256 +453,99 @@ Quote string values as TOML, for example
|
|
|
564
453
|
`--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
|
|
565
454
|
rejected.
|
|
566
455
|
|
|
567
|
-
|
|
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
|
-
Press <kbd>Space</kbd> to select or deselect scans, then press
|
|
743
|
-
<kbd>Enter</kbd> to submit. At least one scan is required, and no scans are
|
|
744
|
-
selected automatically.
|
|
745
|
-
|
|
746
|
-
For scripts, repeat `--scan` with saved scan IDs or unique ID prefixes (at
|
|
747
|
-
least eight characters):
|
|
748
|
-
|
|
749
530
|
```bash
|
|
750
|
-
npx @openai/codex-security
|
|
751
|
-
--
|
|
752
|
-
--to cloud --dry-run --json
|
|
531
|
+
npx @openai/codex-security bulk-scan repositories.csv \
|
|
532
|
+
--output-dir /path/outside/repositories/security-scans --workers 4
|
|
753
533
|
```
|
|
754
534
|
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
`--dry-run` validates the scans and prints their findings without uploading or
|
|
762
|
-
requiring a login. Remove `--dry-run` to upload. Live uploads require ChatGPT
|
|
763
|
-
credentials explicitly stored in a file. Set this in your Codex `config.toml`,
|
|
764
|
-
then sign in with ChatGPT again:
|
|
765
|
-
|
|
766
|
-
```toml
|
|
767
|
-
cli_auth_credentials_store = "file"
|
|
768
|
-
```
|
|
769
|
-
|
|
770
|
-
Automatic and keyring credential storage are not accepted for Cloud
|
|
771
|
-
publication, even when an `auth.json` file exists, because that file may be
|
|
772
|
-
stale and belong to a different account. The CLI sends one scan at a time,
|
|
773
|
-
with each scan's findings and metadata in a separate request.
|
|
774
|
-
|
|
775
|
-
For artifacts outside local history, use repeated `--scan-dir PATH` instead.
|
|
776
|
-
A single positional directory is still accepted and can be combined with
|
|
777
|
-
`--scan-dir`. Do not combine directory inputs with `--scan`. Each directory
|
|
778
|
-
must contain one completed, sealed scan; bulk-run directories and
|
|
779
|
-
`results.jsonl` files are not accepted. Relative paths start at the current
|
|
780
|
-
directory, and `~/...` starts at your home directory. Each resolved directory
|
|
781
|
-
is processed once.
|
|
782
|
-
|
|
783
|
-
For multiple distinct scans, output contains:
|
|
784
|
-
|
|
785
|
-
- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
|
|
786
|
-
- `failed`: errors with `scanDir` and, for saved selections, `scanId`.
|
|
787
|
-
- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
|
|
788
|
-
did not reach before cancellation.
|
|
789
|
-
|
|
790
|
-
For one distinct scan, the CLI returns the scan result directly,
|
|
791
|
-
without the batch fields above.
|
|
792
|
-
|
|
793
|
-
The CLI continues after a failed scan and exits with code `2` if any scan
|
|
794
|
-
fails. Ctrl-C or SIGTERM stops new requests and returns the results collected
|
|
795
|
-
so far. When cancellation stops work before every requested publication is
|
|
796
|
-
confirmed, the exit code is `130` for Ctrl-C and `143` for SIGTERM. If the
|
|
797
|
-
single response or final batch response has already confirmed the complete
|
|
798
|
-
publication, the command exits with code `0`. Cloud publication receipts
|
|
799
|
-
appear in command output; the CLI does not save them to scan history.
|
|
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.
|
|
800
540
|
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
opaque server IDs back to individual local findings independently.
|
|
805
|
-
|
|
806
|
-
The CLI never retries an upload automatically. An upload with a missing or
|
|
807
|
-
invalid receipt may already have been accepted. Check whether Cloud accepted
|
|
808
|
-
that scan before retrying it. Do not resend scans with confirmed receipts.
|
|
541
|
+
`--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending
|
|
542
|
+
repository per invocation. Rerun the command to resume; `bulk-scan --help`
|
|
543
|
+
lists all options.
|
|
809
544
|
|
|
810
545
|
### Custom validation
|
|
811
546
|
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
into a separate validation turn and is not sent to discovery workers.
|
|
815
|
-
The SDK adapts the bundled discovery workflow without changing the plugin.
|
|
816
|
-
An incompatible plugin workflow stops the scan instead of using default validation.
|
|
547
|
+
Replace the final validation step of a standard or diff scan with a prompt
|
|
548
|
+
file. Source review still runs; discovery workers do not receive this prompt.
|
|
817
549
|
|
|
818
550
|
```bash
|
|
819
551
|
npx @openai/codex-security scan . --validation-prompt-file validation.md
|
|
@@ -828,10 +560,10 @@ const result = await security.run(repository, {
|
|
|
828
560
|
});
|
|
829
561
|
```
|
|
830
562
|
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
563
|
+
Put setup, allowed targets, required evidence, and cleanup in the prompt.
|
|
564
|
+
There are no separate setup or teardown hooks. Use environment variables for
|
|
565
|
+
credentials; keep secrets out of prompts and validation output. Deep scans
|
|
566
|
+
reject this option; scans without candidates skip it.
|
|
835
567
|
|
|
836
568
|
The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
|
|
837
569
|
|
|
@@ -860,63 +592,106 @@ The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
|
|
|
860
592
|
}
|
|
861
593
|
```
|
|
862
594
|
|
|
863
|
-
|
|
864
|
-
`
|
|
865
|
-
`{ "level": "medium", "rationale": "..." }`
|
|
866
|
-
|
|
867
|
-
do not change. Deferred candidates make coverage partial. Suppressed and
|
|
868
|
-
deferred candidates remain in the saved validation artifacts.
|
|
595
|
+
Return one result per candidate with disposition `reportable`, `suppressed`,
|
|
596
|
+
`not_applicable`, or `deferred`. Set `severity` or `impact` to
|
|
597
|
+
`{ "level": "medium", "rationale": "..." }` to revise an assessment, or `null`
|
|
598
|
+
to retain it. Identity and source locations stay unchanged.
|
|
869
599
|
|
|
870
|
-
The scan
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
600
|
+
The scan saves candidates and results, including suppressed and deferred
|
|
601
|
+
cases, under `artifacts/custom-validation/`. Coverage is incomplete if setup
|
|
602
|
+
fails, output is incomplete or invalid, or any candidate is deferred. An
|
|
603
|
+
incompatible plugin stops the scan; validation never falls back to the default.
|
|
604
|
+
Repeat `--validation-prompt-file` on reruns.
|
|
875
605
|
|
|
876
|
-
### Publish
|
|
606
|
+
### Publish findings to Cloud
|
|
877
607
|
|
|
878
|
-
|
|
879
|
-
Linear team:
|
|
608
|
+
Choose completed scans from local history:
|
|
880
609
|
|
|
881
610
|
```bash
|
|
882
|
-
npx @openai/codex-security publish scan --
|
|
883
|
-
--to linear \
|
|
884
|
-
--linear-team TEAM_ID
|
|
611
|
+
npx @openai/codex-security publish scan --to cloud --dry-run --json
|
|
885
612
|
```
|
|
886
613
|
|
|
887
|
-
|
|
888
|
-
For external artifacts, a positional directory or `--scan-dir PATH` is also
|
|
889
|
-
accepted.
|
|
614
|
+
Press Space to select scans, then Enter to submit. Nothing is preselected.
|
|
890
615
|
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
created directly in the selected team.
|
|
894
|
-
|
|
895
|
-
To choose from all completed scans saved in your local scan history, omit the
|
|
896
|
-
scan selector. The selector highlights each repository and shows its finding
|
|
897
|
-
count, relative run time, and abbreviated scan ID:
|
|
616
|
+
For scripts, repeat `--scan` with saved IDs or unique prefixes of at least
|
|
617
|
+
eight characters:
|
|
898
618
|
|
|
899
619
|
```bash
|
|
900
620
|
npx @openai/codex-security publish scan \
|
|
621
|
+
--scan SCAN_ID_A --scan SCAN_ID_B \
|
|
622
|
+
--to cloud --dry-run --json
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
Find IDs with `scans list --json`, or use `--scan latest` for the current
|
|
626
|
+
repository's latest completed scan. You still need the local sealed artifacts.
|
|
627
|
+
|
|
628
|
+
`--dry-run` checks inputs and prints findings without logging in or uploading.
|
|
629
|
+
Uploads need ChatGPT credentials saved to a file. Set this in Codex
|
|
630
|
+
`config.toml`, then sign in with ChatGPT again:
|
|
631
|
+
|
|
632
|
+
```toml
|
|
633
|
+
cli_auth_credentials_store = "file"
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
Cloud publication rejects automatic and keyring storage, even if an
|
|
637
|
+
`auth.json` file exists: the file may be stale or belong to another account.
|
|
638
|
+
|
|
639
|
+
For CSV input, use an export from `codex-security export --export-format csv`:
|
|
640
|
+
|
|
641
|
+
```bash
|
|
642
|
+
npx @openai/codex-security publish scan --to cloud \
|
|
643
|
+
--csv /path/outside/repository/findings.csv
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
The [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)
|
|
647
|
+
has the required columns; deep-scan exports may add `candidate_id`. `--csv`
|
|
648
|
+
only supports Cloud and cannot be combined with scan IDs or directories.
|
|
649
|
+
|
|
650
|
+
For artifacts outside local history, pass a directory or repeat `--scan-dir PATH`.
|
|
651
|
+
Each directory must contain one completed, sealed scan. Bulk-run directories
|
|
652
|
+
and `results.jsonl` files aren't accepted. Don't mix directories with `--scan`.
|
|
653
|
+
|
|
654
|
+
Multiple scans return:
|
|
655
|
+
|
|
656
|
+
- `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
|
|
657
|
+
- `failed`: errors with `scanDir` and, for saved selections, `scanId`.
|
|
658
|
+
- `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
|
|
659
|
+
did not reach before cancellation.
|
|
660
|
+
|
|
661
|
+
One scan returns its result directly. Uploads run sequentially. A failed upload
|
|
662
|
+
doesn't stop the rest, but the command exits with `2` if any failed. Cancellation
|
|
663
|
+
stops new requests and returns results so far with `130` (Ctrl-C) or `143`
|
|
664
|
+
(SIGTERM), unless all publications were already confirmed.
|
|
665
|
+
|
|
666
|
+
Save the output: Cloud receipts aren't stored in scan history. They contain
|
|
667
|
+
Cloud finding IDs in request order, not local IDs. Uploads aren't retried
|
|
668
|
+
automatically. Cloud may have accepted an upload even if its receipt is missing
|
|
669
|
+
or invalid. Check Cloud before retrying; never resend a scan with a confirmed
|
|
670
|
+
receipt.
|
|
671
|
+
|
|
672
|
+
### Publish completed scans to Linear
|
|
673
|
+
|
|
674
|
+
Linear publication accepts one completed scan:
|
|
675
|
+
|
|
676
|
+
```bash
|
|
677
|
+
npx @openai/codex-security publish scan --scan SCAN_ID \
|
|
901
678
|
--to linear \
|
|
902
679
|
--linear-team TEAM_ID
|
|
903
680
|
```
|
|
904
681
|
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
Interactive publication shows a full-screen activity view with live Codex
|
|
910
|
-
output and issue-creation progress. Other terminals receive plain progress on
|
|
911
|
-
stderr, so `--json` output remains machine-readable.
|
|
682
|
+
Choose a scan by ID, unique prefix, `latest`, or directory (positional or
|
|
683
|
+
`--scan-dir PATH`). Omit the selector for an interactive picker. Live publication
|
|
684
|
+
and `--skip-existing` require the scan in local history; a directory-based
|
|
685
|
+
`--dry-run` alone does not.
|
|
912
686
|
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
687
|
+
Add `--linear-project PROJECT_ID` (`--project` is an alias) to place issues in
|
|
688
|
+
a project. Destination flags override `CODEX_SECURITY_LINEAR_TEAM` and
|
|
689
|
+
`CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run` previews issue titles without
|
|
690
|
+
contacting Linear; `--json` returns structured results.
|
|
917
691
|
|
|
918
|
-
|
|
919
|
-
|
|
692
|
+
Sign in to Codex and connect Linear to publish with your existing Codex
|
|
693
|
+
configuration; publication doesn't use the isolated scan home. To use the
|
|
694
|
+
Linear API directly, set a personal API key:
|
|
920
695
|
|
|
921
696
|
```bash
|
|
922
697
|
export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
|
|
@@ -925,73 +700,36 @@ npx @openai/codex-security publish scan /path/to/completed-scan \
|
|
|
925
700
|
--linear-team TEAM_ID
|
|
926
701
|
```
|
|
927
702
|
|
|
928
|
-
Direct API publication leaves issues unassigned
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
You can also pass `--linear-api-key KEY`, which takes precedence over
|
|
934
|
-
`CODEX_SECURITY_LINEAR_API_KEY`. Prefer the environment variable to avoid
|
|
935
|
-
exposing your API key in shell history and process listings. API keys are not
|
|
936
|
-
added to successful publication results, scan history, or sealed scan artifacts.
|
|
937
|
-
Error messages are preserved as returned. `--dry-run` never contacts Linear in
|
|
938
|
-
either mode.
|
|
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.
|
|
939
707
|
|
|
940
|
-
|
|
941
|
-
local history, and to see which findings already have recorded Linear issues:
|
|
708
|
+
Check scan integrity and recorded publications before publishing:
|
|
942
709
|
|
|
943
710
|
```bash
|
|
944
711
|
npx @openai/codex-security publish check /path/to/completed-scan \
|
|
945
712
|
--to linear --linear-team TEAM_ID --json
|
|
946
713
|
```
|
|
947
714
|
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
to
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
only the remaining findings. Results distinguish newly `created` issues from
|
|
967
|
-
previously recorded `skipped` issues.
|
|
968
|
-
|
|
969
|
-
This option uses local publication history; it does not search, update, or
|
|
970
|
-
verify the continued existence of remote issues. Recover any retained handoff
|
|
971
|
-
from an interrupted or uncertain publication before retrying. Concurrent
|
|
972
|
-
publishers and remote creations that were never recorded can still create
|
|
973
|
-
duplicates.
|
|
974
|
-
|
|
975
|
-
Issue descriptions contain source code and vulnerability details. Select a
|
|
976
|
-
Linear destination authorized to receive that information. Publication receipts
|
|
977
|
-
are stored separately from the sealed scan artifacts.
|
|
978
|
-
|
|
979
|
-
Before recording a connected-app publication, Codex Security verifies the exact
|
|
980
|
-
mutation arguments and reconciles every recognized issue identifier and
|
|
981
|
-
non-empty URL in the connector result with its durable handoff. If those claims
|
|
982
|
-
conflict, or a completed mutation cannot be verified, publication exits with an
|
|
983
|
-
indeterminate recovery error. The private handoff, connector-event evidence,
|
|
984
|
-
and partial receipts remain in local state; independently verified sibling
|
|
985
|
-
issues may already be recorded in scan history.
|
|
986
|
-
|
|
987
|
-
Do not immediately rerun an indeterminate publication. Inspect the retained
|
|
988
|
-
evidence and the selected Linear destination, reconcile every issue that may
|
|
989
|
-
already have been created, and retry only after confirming that no unrecorded
|
|
990
|
-
issue would be duplicated. Publication does not perform a fresh remote readback
|
|
991
|
-
or recover unrecorded remote creations. The opt-in `--skip-existing` behavior
|
|
992
|
-
only skips issues already recorded in local history.
|
|
993
|
-
|
|
994
|
-
You can also publish a scan from TypeScript:
|
|
715
|
+
`publish check` is read-only. With an API key it also checks authentication,
|
|
716
|
+
team, project, and assignee access; connected-app access is `not-checked`.
|
|
717
|
+
Issue-creation permission is always `not-tested`.
|
|
718
|
+
|
|
719
|
+
Each finding becomes an issue titled `[Codex Security][HIGH] Finding title`
|
|
720
|
+
with source locations, code, evidence, and remediation. Choose a destination
|
|
721
|
+
authorized to receive these details. Local history stores successful issue IDs
|
|
722
|
+
separately from sealed scan artifacts.
|
|
723
|
+
|
|
724
|
+
Republishing creates duplicates by default. `--skip-existing` skips recorded
|
|
725
|
+
successes for the same occurrence, team, and project, without checking remote
|
|
726
|
+
issues. Results distinguish `created` and `skipped` issues. Add `--dry-run`
|
|
727
|
+
to preview the remaining findings.
|
|
728
|
+
|
|
729
|
+
After an interrupted or indeterminate publication, check the retained handoff,
|
|
730
|
+
evidence, and Linear destination before retrying. Issues may exist without a
|
|
731
|
+
local record. The CLI can't recover those issues, and `--skip-existing` can't
|
|
732
|
+
prevent duplicates from them or concurrent publications.
|
|
995
733
|
|
|
996
734
|
```ts
|
|
997
735
|
import { publishScan } from "@openai/codex-security";
|
|
@@ -999,206 +737,712 @@ import { publishScan } from "@openai/codex-security";
|
|
|
999
737
|
const publication = await publishScan("/path/to/completed-scan", {
|
|
1000
738
|
destination: "linear",
|
|
1001
739
|
teamId: "TEAM_ID",
|
|
1002
|
-
onProgress: (progress) => {
|
|
1003
|
-
if (progress.type === "handoff_recorded") {
|
|
1004
|
-
console.error("Saved mutation result", progress.recorded);
|
|
1005
|
-
} else if (progress.type === "issue_completed") {
|
|
1006
|
-
console.error(
|
|
1007
|
-
`Processed ${progress.completed} of ${progress.total} findings.`,
|
|
1008
|
-
);
|
|
1009
|
-
}
|
|
1010
|
-
},
|
|
1011
740
|
});
|
|
1012
741
|
|
|
1013
742
|
console.log(publication.scanId);
|
|
1014
743
|
console.log(publication.created.length);
|
|
1015
744
|
```
|
|
1016
745
|
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
destination options for a read-only preflight.
|
|
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.
|
|
1021
749
|
|
|
1022
|
-
|
|
1023
|
-
`assigneeId` to leave issues unassigned, or supply a Linear user ID or email
|
|
1024
|
-
address to select an assignee:
|
|
750
|
+
### Scan history and reruns
|
|
1025
751
|
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
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:
|
|
799
|
+
|
|
800
|
+
```bash
|
|
801
|
+
SCAN_ROOT="$(mktemp -d)"
|
|
802
|
+
npx @openai/codex-security scan . \
|
|
803
|
+
--diff origin/main \
|
|
804
|
+
--output-dir "$SCAN_ROOT/results" \
|
|
805
|
+
--json \
|
|
806
|
+
--fail-on-severity high > "$SCAN_ROOT/findings.json"
|
|
1033
807
|
```
|
|
1034
808
|
|
|
1035
|
-
|
|
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`.
|
|
814
|
+
|
|
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`.
|
|
818
|
+
|
|
819
|
+
### Import alerts from the CLI
|
|
1036
820
|
|
|
1037
|
-
`
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
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
|
|
835
|
+
```
|
|
1043
836
|
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
Logs and live details can contain source code and credentials.
|
|
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.
|
|
1048
840
|
|
|
1049
|
-
|
|
1050
|
-
least eight characters.
|
|
841
|
+
### Validate and patch findings
|
|
1051
842
|
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
defaults to `~/.codex`. Scan credentials are never stored in the scan
|
|
1056
|
-
configuration. Recorded failure summaries and bulk-scan receipts omit messages
|
|
1057
|
-
that contain recognizable credentials.
|
|
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.
|
|
1058
846
|
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
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.
|
|
1062
854
|
|
|
1063
855
|
```bash
|
|
1064
|
-
|
|
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
|
|
1065
862
|
```
|
|
1066
863
|
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
`
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
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
|
|
1092
907
|
`--format toon|json|yaml|jsonl` and `--full-output`.
|
|
1093
|
-
Use `info --json` for SDK and bundled-plugin metadata. MCP exposes only this
|
|
1094
|
-
read-only metadata command; scans, bulk repository scans,
|
|
1095
|
-
authentication, exports, validation, and patching remain CLI-only because the
|
|
1096
|
-
MCP transport cannot cancel active scans.
|
|
1097
908
|
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
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
|
+
## Findings service (preview)
|
|
914
|
+
|
|
915
|
+
The findings API uses the same `ghcr.io/openai/codex-security` image as the
|
|
916
|
+
scanner, for Linux `amd64` and `arm64`. `compose.findings.yaml` starts the API
|
|
917
|
+
in a separate container with its own state volume and server configuration.
|
|
918
|
+
Once a release is published, it can be pulled without a GitHub login. See
|
|
919
|
+
[container release setup](../../docker/README.md) for the required maintainer
|
|
920
|
+
setup and publication process.
|
|
921
|
+
|
|
922
|
+
From the repository root, copy the example if you do not already have a `.env`:
|
|
1101
923
|
|
|
1102
924
|
```bash
|
|
1103
|
-
|
|
1104
|
-
npx @openai/codex-security scan . \
|
|
1105
|
-
--diff origin/main \
|
|
1106
|
-
--output-dir "$SCAN_ROOT/results" \
|
|
1107
|
-
--json \
|
|
1108
|
-
--fail-on-severity high > "$SCAN_ROOT/findings.json"
|
|
925
|
+
cp .env.example .env
|
|
1109
926
|
```
|
|
1110
927
|
|
|
1111
|
-
|
|
1112
|
-
Saved-finding patch commands support `--json`; literal issue and file patch
|
|
1113
|
-
commands do not. The `validate`, `login`, and `logout` commands reject `--json`.
|
|
1114
|
-
Sign-in commands remain interactive. CSV exports cannot be written to stdout
|
|
1115
|
-
while JSON output is requested.
|
|
1116
|
-
|
|
1117
|
-
Use `export` to create CSV, JSON, or SARIF from a completed, sealed scan without
|
|
1118
|
-
starting Codex or loading credentials. Without a scan directory, it exports the
|
|
1119
|
-
latest completed scan for the current repository. JSON preserves the sealed findings
|
|
1120
|
-
document. CSV uses the portable findings columns, marks findings as open, and
|
|
1121
|
-
does not include local workbench triage state. The exporter validates the seal
|
|
1122
|
-
before writing, accepts `--output -` for stdout, and can use
|
|
1123
|
-
`--source-root /path/to/repository` with SARIF to add source-line fingerprints.
|
|
1124
|
-
Run `npx @openai/codex-security export --help` for all export options.
|
|
1125
|
-
|
|
1126
|
-
Use `validate` to run the bundled validation skill on candidate findings and
|
|
1127
|
-
`patch` to run the bundled fix-finding skill on security issues. Each positional
|
|
1128
|
-
input can be either a file, whose contents are read into the request, or literal
|
|
1129
|
-
text. These inputs operate on the current directory. Pass a saved finding or
|
|
1130
|
-
occurrence ID instead to patch its original repository, or use
|
|
1131
|
-
`patch --scan SCAN_ID --severity high` for high and critical findings from one
|
|
1132
|
-
scan. `--scan latest` selects the most recent scan of the current repository.
|
|
1133
|
-
Saved-finding patch commands accept `--json` and return a verified, already
|
|
1134
|
-
fixed, blocked, or failed result for each finding. Both commands use the scan
|
|
1135
|
-
model and reasoning defaults and disable plugins. Patching starts a separate
|
|
1136
|
-
saved task in the Codex desktop app for each finding. Override the model with
|
|
1137
|
-
`--codex 'model="gpt-5.6-sol"'` and the
|
|
1138
|
-
reasoning effort with `--effort high` or
|
|
1139
|
-
`--codex 'model_reasoning_effort="high"'`.
|
|
1140
|
-
|
|
1141
|
-
Use `patch --linear-issue ISSUE` to import a Linear issue by identifier or URL.
|
|
1142
|
-
Repeat `--linear-issue` to include more issues. Use
|
|
1143
|
-
`patch --linear-project "PROJECT"` to patch every open issue in a project. Add
|
|
1144
|
-
`--linear-filter '{"labels":{"name":{"eq":"security"}}}'` to apply a native
|
|
1145
|
-
Linear issue filter on the server. Completed and canceled issues are excluded
|
|
1146
|
-
unless the filter explicitly sets `state`. Set `CODEX_SECURITY_LINEAR_API_KEY`
|
|
1147
|
-
for a personal API key, or `LINEAR_ACCESS_TOKEN` for an OAuth access token.
|
|
1148
|
-
`LINEAR_API_KEY` is also accepted. `--linear-api-key KEY` overrides these
|
|
1149
|
-
environment settings; prefer the environment variable to keep keys out of shell
|
|
1150
|
-
history. Imported content is always literal, and issue URLs must match the
|
|
1151
|
-
selected workspace. Each imported issue includes its title, description, and
|
|
1152
|
-
all comments with their source links. Linear access is read-only, and its
|
|
1153
|
-
credentials are not passed to the patch subprocess.
|
|
1154
|
-
|
|
1155
|
-
Use `verify-fix` to check whether an existing security fix actually closes its
|
|
1156
|
-
original vulnerability without modifying the repository. Pass a finding
|
|
1157
|
-
description, a saved finding identifier, `--scan SCAN_ID`, `--linear-issue ISSUE`,
|
|
1158
|
-
or `--linear-project "PROJECT"`. Linear intake uses the same credentials and
|
|
1159
|
-
`--linear-filter` options as `patch`; explicitly filter for completed issues when
|
|
1160
|
-
verifying a finished backlog. Verification runs the bundled `verify-fix` skill
|
|
1161
|
-
in a read-only Codex sandbox and reports `fixed`, `still_vulnerable`, or
|
|
1162
|
-
`inconclusive` with supporting evidence for every finding. Use `--json` for
|
|
1163
|
-
structured output. Exit code `0` means every finding is fixed, `1` means at
|
|
1164
|
-
least one finding remains vulnerable, and `2` means a result is inconclusive or
|
|
1165
|
-
verification could not complete.
|
|
1166
|
-
|
|
1167
|
-
Interactive verification shows the same live agent-activity dashboard used by
|
|
1168
|
-
scans and Linear publication. Reasoning, repository commands, and progress are
|
|
1169
|
-
written to stderr; redirected output and CI receive plain progress lines, and
|
|
1170
|
-
JSON results on stdout remain machine-readable.
|
|
1171
|
-
|
|
1172
|
-
Exit codes are `0` for a completed report-only scan or a passing policy, `1`
|
|
1173
|
-
for a completed policy violation, `2` for invalid input, incomplete coverage, or
|
|
1174
|
-
a runtime/export error, `130` for interruption, and `143` for termination.
|
|
1175
|
-
|
|
1176
|
-
Use `--dry-run` or `await security.preflight(...)` to validate the repository,
|
|
1177
|
-
target, mode, output location, and Codex overrides without initializing the
|
|
1178
|
-
runtime or loading credentials. Dry runs do not inspect the plugin or probe its
|
|
1179
|
-
Python interpreter. The preflight result includes the selected authentication
|
|
1180
|
-
method and, for an environment API key, its variable name. Authentication and
|
|
1181
|
-
model access remain unverified until a real scan starts.
|
|
1182
|
-
|
|
1183
|
-
Scan progress identifies the selected credential source before Codex starts.
|
|
1184
|
-
Terminals and noninteractive CI logs also show how to retry with
|
|
1185
|
-
`--auth chatgpt` when an environment API key overrides the stored sign-in.
|
|
1186
|
-
Progress remains on stderr so JSON output stays machine readable. Network
|
|
1187
|
-
failures and rate limits remain retryable; definitive authentication and model
|
|
1188
|
-
authorization failures stop immediately.
|
|
928
|
+
Set `OPENAI_API_KEY` in `.env`, then pull and start the findings API:
|
|
1189
929
|
|
|
1190
|
-
|
|
930
|
+
```bash
|
|
931
|
+
docker compose -f compose.findings.yaml pull
|
|
932
|
+
docker compose -f compose.findings.yaml up --no-build -d
|
|
933
|
+
curl -i http://127.0.0.1:3000/v1/findings
|
|
934
|
+
```
|
|
1191
935
|
|
|
1192
|
-
|
|
936
|
+
You can deploy with just `compose.findings.yaml` and a private `.env`; no source
|
|
937
|
+
checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
|
|
938
|
+
defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
|
|
939
|
+
version, `sha-<commit>` tag, or digest for repeatable deployments.
|
|
1193
940
|
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
941
|
+
To build from a source checkout instead:
|
|
942
|
+
|
|
943
|
+
```bash
|
|
944
|
+
docker build --target scanner -t codex-security:local .
|
|
945
|
+
export CODEX_SECURITY_FINDINGS_IMAGE=codex-security:local
|
|
946
|
+
docker compose -f compose.findings.yaml up --no-build -d
|
|
947
|
+
```
|
|
948
|
+
|
|
949
|
+
For an existing deployment using the separate findings image or
|
|
950
|
+
`--target findings-service`, follow the [single-image migration guide](../../docker/README.md#migrating-the-findings-service).
|
|
951
|
+
|
|
952
|
+
### Read-only dashboard
|
|
953
|
+
|
|
954
|
+
Open `http://localhost:3000/dashboard` on the running findings service. The UI
|
|
955
|
+
uses the public OpenAI Apps SDK UI design system, follows the browser's light
|
|
956
|
+
or dark preference, and polls the service every five seconds. It never starts,
|
|
957
|
+
cancels, resumes, publishes, edits, or deduplicates anything.
|
|
958
|
+
|
|
959
|
+
The dashboard opens on Findings, followed by Duplicate groups. Both views
|
|
960
|
+
support search, repository filtering, sorting, pagination, and record details.
|
|
961
|
+
Findings show stored content and links to their duplicate groups. Groups link
|
|
962
|
+
back to their member findings, preserving separate overlapping groups and the
|
|
963
|
+
original finding records.
|
|
964
|
+
|
|
965
|
+
The dashboard reads only findings, repository associations, and duplicate groups
|
|
966
|
+
stored in the service's configured database. It does not display scans or
|
|
967
|
+
workflows: publication sends findings, not remote scan or workflow history. It
|
|
968
|
+
does not read report or source paths from stored records. The UI retains the last
|
|
969
|
+
successful data on a refresh failure and shows a connection warning until polling
|
|
970
|
+
succeeds.
|
|
971
|
+
|
|
972
|
+
`GET /v1/dashboard` returns a consistent read snapshot with overview counts,
|
|
973
|
+
repository choices, a page of records, and optional selected-record details:
|
|
974
|
+
|
|
975
|
+
- `view`: `findings` (default) or `groups`.
|
|
976
|
+
- `query`, `repository`: optional search text and exact repository ID.
|
|
977
|
+
- `sort`: `activity` (default; most recently updated first) or `newest`.
|
|
978
|
+
- `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
|
|
979
|
+
- `id`: optional exact record ID to include in `detail`; unknown IDs return
|
|
980
|
+
`detail: null` without hiding the list.
|
|
981
|
+
|
|
982
|
+
Overview counts are service-wide, not filtered page totals. Responses and UI
|
|
983
|
+
assets are served by the same Node process; no separate frontend server, CDN,
|
|
984
|
+
model credentials, or new CLI flags are needed to view the dashboard. Compiled
|
|
985
|
+
HTML, JavaScript, and CSS are included in the npm package and container. Frontend
|
|
986
|
+
source, build tools, and tests are not shipped as runtime dependencies.
|
|
987
|
+
|
|
988
|
+
The existing preview access boundary is unchanged. The dashboard contains
|
|
989
|
+
sensitive finding content: keep the service on a trusted local endpoint or behind
|
|
990
|
+
an authenticated proxy. It does not add authentication or broaden the default
|
|
991
|
+
network binding.
|
|
992
|
+
|
|
993
|
+
### API
|
|
994
|
+
|
|
995
|
+
`POST /v1/bulk/findings` accepts `{"findings": [...]}`, using the existing SDK
|
|
996
|
+
`Finding` model, including `findingId`, `occurrenceId`, and `fingerprints`.
|
|
997
|
+
A complete exported `findings.json` document is also accepted; only its
|
|
998
|
+
`findings` array is imported. No files or source paths referenced by the
|
|
999
|
+
findings are opened. Only the supplied JSON is processed.
|
|
1000
|
+
|
|
1001
|
+
Include `repositoryId` alongside `findings` to associate every imported finding
|
|
1002
|
+
with a repository. For SDK/CLI scans, use `scan.target.targetId` from the sealed
|
|
1003
|
+
`scan-manifest.json`. IDs are matched exactly; the service does not infer a
|
|
1004
|
+
repository from titles, paths, or URLs. Reimports add associations without
|
|
1005
|
+
removing earlier ones, so a finding can belong to more than one repository.
|
|
1006
|
+
Imports without this metadata remain accepted, but unassociated findings are
|
|
1007
|
+
only available to explicit all-repository retrieval until imported with an ID.
|
|
1008
|
+
|
|
1009
|
+
| Method | Path | Response |
|
|
1010
|
+
| ------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
1011
|
+
| `POST` | `/v1/bulk/findings` | HTTP 201 with an array of stored finding IDs, in request order |
|
|
1012
|
+
| `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200 with a page of complete findings |
|
|
1013
|
+
| `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200 with the stored finding and up to 50 potential duplicates, without vectors |
|
|
1014
|
+
| `POST` | `/v1/dedupe-groups` | HTTP 201 with the persisted duplicate groups |
|
|
1015
|
+
| `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200 with every stored group containing this finding |
|
|
1016
|
+
|
|
1017
|
+
Bulk insertion generates embeddings and then writes the findings and vectors
|
|
1018
|
+
in one SQLite transaction. If embedding generation fails or a finding identity
|
|
1019
|
+
conflicts with another stored identity, no part of the batch is written.
|
|
1020
|
+
Reusing a `findingId` updates that finding and replaces its embedding; retries
|
|
1021
|
+
do not create extra rows. An existing ID's fingerprint, rule, and identity
|
|
1022
|
+
anchor/instance cannot be replaced. Repeated IDs in one request are applied in order,
|
|
1023
|
+
with the last supplied record retained. Stored scan occurrences are unchanged.
|
|
1024
|
+
|
|
1025
|
+
For example, add `repositoryId` to a copy of an exported findings document
|
|
1026
|
+
saved as `findings-import.json` (leave the sealed scan artifacts unchanged),
|
|
1027
|
+
then import it with the API key configured before starting Compose:
|
|
1028
|
+
|
|
1029
|
+
```bash
|
|
1030
|
+
curl http://127.0.0.1:3000/v1/bulk/findings \
|
|
1031
|
+
-H 'Content-Type: application/json' \
|
|
1032
|
+
--data-binary @findings-import.json
|
|
1033
|
+
```
|
|
1034
|
+
|
|
1035
|
+
```json
|
|
1036
|
+
["csf_852f90d6e1177502ff113d4a"]
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
The potential-duplicates response contains `finding` (the complete stored
|
|
1040
|
+
anchor) and `potentialDuplicates` (an array of complete `Finding` records).
|
|
1041
|
+
Neither includes embedding vectors. The anchor is not repeated in the array.
|
|
1042
|
+
Specify one scope explicitly on the request:
|
|
1043
|
+
|
|
1044
|
+
```text
|
|
1045
|
+
GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example
|
|
1046
|
+
GET /v1/finding/{id}/potential-duplicates?allRepositories=true
|
|
1047
|
+
```
|
|
1048
|
+
|
|
1049
|
+
Repository scope requires the anchor and each candidate to be associated with
|
|
1050
|
+
that repository. All-repository scope includes tagged and untagged findings.
|
|
1051
|
+
Omitting scope or combining a repository with `allRepositories=true` returns
|
|
1052
|
+
HTTP 400. Scope selects candidates; it is not an authorization boundary.
|
|
1053
|
+
|
|
1054
|
+
Candidates have cosine similarity at least 0.55 and the same embedding model
|
|
1055
|
+
and dimensions as the anchor. They are ordered by descending similarity, with
|
|
1056
|
+
ties resolved by insertion time and finding ID, and limited to 50. Each request
|
|
1057
|
+
reads a current snapshot; separate requests do not share a database snapshot.
|
|
1058
|
+
SQLite first filters repository associations, reads only IDs and embedding
|
|
1059
|
+
vectors (plus the anchor's model), and performs exact cosine ranking. It then
|
|
1060
|
+
loads complete documents only for the anchor and the selected top 50 candidates,
|
|
1061
|
+
all within the same read transaction.
|
|
1062
|
+
The API does not run Codex or decide whether candidates are duplicates.
|
|
1063
|
+
|
|
1064
|
+
### Publishing to a custom findings service
|
|
1065
|
+
|
|
1066
|
+
Publish a completed scan directly from the local CLI to the Docker service:
|
|
1067
|
+
|
|
1068
|
+
```bash
|
|
1069
|
+
codex-security publish scan --scan SCAN_ID --to custom \
|
|
1070
|
+
--findings-url http://localhost:3000 --json
|
|
1071
|
+
```
|
|
1072
|
+
|
|
1073
|
+
`--findings-url` is required for `--to custom`, with no default. It is the
|
|
1074
|
+
service base URL, including `http://` or `https://`; the client appends
|
|
1075
|
+
`/v1/bulk/findings`, preserving any base path. A different endpoint must
|
|
1076
|
+
implement that API and return the stored finding IDs. The command sends the
|
|
1077
|
+
complete sealed findings and their manifest's `scan.target.targetId` as
|
|
1078
|
+
`repositoryId`, without changing scan artifacts or forwarding model credentials.
|
|
1079
|
+
The service creates embeddings and commits the batch before acknowledging it.
|
|
1080
|
+
|
|
1081
|
+
The existing saved-scan selector, external `--scan-dir`, and interactive picker
|
|
1082
|
+
work with custom publication. Custom publication accepts one scan, not CSV
|
|
1083
|
+
input or Linear options. Add `--dry-run` to validate and preview the payload
|
|
1084
|
+
without making an HTTP request. Existing Linear and Cloud destinations are
|
|
1085
|
+
unchanged. Upload failures and incomplete receipts fail the command; uploads
|
|
1086
|
+
are not automatically retried because a lost response may have been committed.
|
|
1087
|
+
|
|
1088
|
+
```typescript
|
|
1089
|
+
import { publishScanToCustom } from "@openai/codex-security";
|
|
1090
|
+
|
|
1091
|
+
const receipt = await publishScanToCustom("/path/to/completed-scan", {
|
|
1092
|
+
findingsUrl: "http://localhost:3000",
|
|
1093
|
+
// dryRun: true,
|
|
1094
|
+
// signal: controller.signal,
|
|
1095
|
+
});
|
|
1096
|
+
console.log(receipt.repositoryId, receipt.findingIds);
|
|
1197
1097
|
```
|
|
1198
1098
|
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1099
|
+
### Deduplication from the SDK and CLI
|
|
1100
|
+
|
|
1101
|
+
Publish the scan with `--to custom` (or import it through the bulk API with its
|
|
1102
|
+
`repositoryId`) before deduplicating. The
|
|
1103
|
+
workflow reads a completed saved scan, queries candidates by finding ID, and
|
|
1104
|
+
runs Luna and Sol in the calling SDK/CLI process. Once all reviews succeed,
|
|
1105
|
+
it posts accepted groups to the service. It does not re-upload findings or
|
|
1106
|
+
change scan artifacts.
|
|
1107
|
+
|
|
1108
|
+
```bash
|
|
1109
|
+
codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
|
|
1110
|
+
```
|
|
1111
|
+
|
|
1112
|
+
The default scope is the saved scan's repository, identified by
|
|
1113
|
+
`scan.target.targetId` in its manifest. Add `--all-repositories` to search the
|
|
1114
|
+
entire stored corpus explicitly; the flag defaults to false. The SDK has the
|
|
1115
|
+
equivalent optional `allRepositories: true` setting. This narrows the previous
|
|
1116
|
+
preview's implicit all-repository behavior.
|
|
1117
|
+
|
|
1118
|
+
Both `--scan` and `--findings-url` are required, with no implicit scan or service
|
|
1119
|
+
URL. As with `publish scan --scan`, the selector accepts a full ID, unique
|
|
1120
|
+
prefix, or `latest` for the current repository. The saved scan must be complete
|
|
1121
|
+
and its sealed artifacts must be available.
|
|
1122
|
+
|
|
1123
|
+
```typescript
|
|
1124
|
+
import { deduplicateScan } from "@openai/codex-security";
|
|
1125
|
+
|
|
1126
|
+
const result = await deduplicateScan("scan_example_001", {
|
|
1127
|
+
findingsUrl: "http://127.0.0.1:3000",
|
|
1128
|
+
// allRepositories: true, // Omit to search only this scan's repository.
|
|
1129
|
+
// signal: controller.signal,
|
|
1130
|
+
});
|
|
1131
|
+
console.log(result.duplicateGroups);
|
|
1132
|
+
```
|
|
1133
|
+
|
|
1134
|
+
The CLI and SDK return the same result:
|
|
1135
|
+
|
|
1136
|
+
```json
|
|
1137
|
+
{
|
|
1138
|
+
"scanId": "scan_example_001",
|
|
1139
|
+
"uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
|
|
1140
|
+
"duplicateGroups": [],
|
|
1141
|
+
"deduplicationStatus": "completed"
|
|
1142
|
+
}
|
|
1143
|
+
```
|
|
1144
|
+
|
|
1145
|
+
`uniqueFindingIds` contains one representative for each selected finding after
|
|
1146
|
+
accepted duplicate groups are collapsed. A representative can be an existing
|
|
1147
|
+
stored finding outside the scan. Each `duplicateGroups` entry contains all
|
|
1148
|
+
members of an accepted group, with its canonical finding first. The canonical
|
|
1149
|
+
has the highest reported severity; ties use finding ID. Results do not delete,
|
|
1150
|
+
merge, or change stored finding documents. Accepted groups are saved as durable
|
|
1151
|
+
associations in the service before `deduplicationStatus` becomes `completed`.
|
|
1152
|
+
|
|
1153
|
+
### Stored duplicate groups
|
|
1154
|
+
|
|
1155
|
+
`POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
|
|
1156
|
+
|
|
1157
|
+
```json
|
|
1158
|
+
{
|
|
1159
|
+
"groups": [
|
|
1160
|
+
["csf_000000000000000000000001", "csf_000000000000000000000002"],
|
|
1161
|
+
["csf_000000000000000000000002", "csf_000000000000000000000003"]
|
|
1162
|
+
]
|
|
1163
|
+
}
|
|
1164
|
+
```
|
|
1165
|
+
|
|
1166
|
+
Each group must contain at least two distinct, existing finding IDs. The entire
|
|
1167
|
+
batch is committed in one transaction; a missing finding returns HTTP 409 and
|
|
1168
|
+
writes none of the batch. A response contains `groupId`, `findingIds`, and
|
|
1169
|
+
`createdAt` for each group. Group identity depends on membership, not member
|
|
1170
|
+
order, so submitting the same set again returns its original ID and timestamp.
|
|
1171
|
+
|
|
1172
|
+
SQLite stores groups in `finding_dedupe_groups` and memberships in
|
|
1173
|
+
`finding_dedupe_group_members`. A finding may belong to multiple groups:
|
|
1174
|
+
`[A, B]`, `[B, C]`, and `[C, A]` are three separate reviewed sets. Overlapping
|
|
1175
|
+
groups are not automatically united or promoted into an unreviewed larger
|
|
1176
|
+
group. Stored members are sorted by ID; their order does not designate a
|
|
1177
|
+
canonical. The CLI result retains its existing canonical-first ordering.
|
|
1178
|
+
|
|
1179
|
+
`GET /v1/finding/{id}/dedupe-groups` returns every group containing that finding,
|
|
1180
|
+
including each group's full membership, or `[]` if it has no groups. These
|
|
1181
|
+
associations do not rewrite original findings, fingerprints, scan artifacts,
|
|
1182
|
+
embeddings, or external tickets. They do not require an embedding API key or
|
|
1183
|
+
trigger model calls. Review-generated merged findings remain review outputs;
|
|
1184
|
+
they do not replace stored documents.
|
|
1185
|
+
|
|
1186
|
+
### Resuming a local findings workflow
|
|
1187
|
+
|
|
1188
|
+
Add `--workflow-id` to opt into durable state shared by `scan`, `publish scan
|
|
1189
|
+
--to custom`, and `dedupe`. The SDK equivalents are the optional `workflowId`
|
|
1190
|
+
fields on `ScanOptions`, `PublishScanToCustomOptions`, and `DeduplicateScanOptions`.
|
|
1191
|
+
Without a workflow ID, existing command behavior and output shapes are unchanged.
|
|
1192
|
+
|
|
1193
|
+
```bash
|
|
1194
|
+
codex-security scan /path/to/repository --workflow-id run-001
|
|
1195
|
+
codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000
|
|
1196
|
+
codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json
|
|
1197
|
+
```
|
|
1198
|
+
|
|
1199
|
+
Repeat this sequence with the same ID after a process stops. Completed scans and
|
|
1200
|
+
acknowledged publications are reused; unfinished stages run again. If the scan
|
|
1201
|
+
completed before the workflow recorded its receipt, recovery verifies the saved
|
|
1202
|
+
scan and its sealed artifacts instead of scanning again. Scan IDs and artifact
|
|
1203
|
+
locations are recorded in the scan-registration transaction. This resumes between
|
|
1204
|
+
completed steps; it does not resume individual model turns inside an unfinished
|
|
1205
|
+
scan. Existing output-directory and archive safeguards still apply to scan retries.
|
|
1206
|
+
|
|
1207
|
+
Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
|
|
1208
|
+
scan selector must identify that same scan. A workflow can also begin at custom
|
|
1209
|
+
publication of a completed scan. Dedupe still requires local scan history to locate
|
|
1210
|
+
the approved source checkout. For a workflow, dedupe first completes publication
|
|
1211
|
+
if its receipt is missing. `--all-repositories` retains its existing default of
|
|
1212
|
+
false. Changing a workflow's scan, destination, or bound scope is an error: choose
|
|
1213
|
+
a different workflow ID. Use one coordinating process per workflow.
|
|
1214
|
+
|
|
1215
|
+
Workflow metadata, stage statuses, errors, publication receipts, and results live
|
|
1216
|
+
in the local workbench SQLite database under `CODEX_SECURITY_STATE_DIR`, outside
|
|
1217
|
+
the sealed scan artifacts. Identity, scan/artifact references, destination, scope,
|
|
1218
|
+
hashes, stage statuses, and errors use explicit columns; only receipts and result
|
|
1219
|
+
payloads use JSON. Review source, scope, model settings, and contract/hash bindings
|
|
1220
|
+
also use columns; review results remain JSON. Existing workflows and checkpoints
|
|
1221
|
+
are migrated atomically in place without changing their review keys.
|
|
1222
|
+
Successful empty results are stored as completed
|
|
1223
|
+
results, not treated as missing work. An empty scan can complete workflow
|
|
1224
|
+
publication with an empty receipt. Dry-run never advances a workflow stage.
|
|
1225
|
+
|
|
1226
|
+
A completed `dedupe --workflow-id` returns its saved result without repeating
|
|
1227
|
+
reviews or group writes. A publication whose acknowledgement was lost is retried
|
|
1228
|
+
using the service's existing idempotent upsert.
|
|
1229
|
+
|
|
1230
|
+
Each validated screening and pair review is checkpointed locally,
|
|
1231
|
+
including DISTINCT decisions. Every SAME checkpoint retains its required
|
|
1232
|
+
`canonicalFindingId` and generated `mergedFinding`. The merged record must satisfy
|
|
1233
|
+
the Finding schema and preserve the canonical finding ID. Validation still happens
|
|
1234
|
+
through `review_validator.submit_decisions`; invalid submissions are corrected in
|
|
1235
|
+
the same review conversation, and invalid or unfinished reviews are not cached.
|
|
1236
|
+
|
|
1237
|
+
Checkpoints bind to the exact original records and ordering, approved source path,
|
|
1238
|
+
Git revision and current file contents (including ignored files), repository scope,
|
|
1239
|
+
model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
|
|
1240
|
+
inputs cause a new review rather than reusing a decision. Source changes during
|
|
1241
|
+
review stop that attempt before group writes; restart with the same ID to review
|
|
1242
|
+
the changed source. Original findings, never prior rationales or merged findings,
|
|
1243
|
+
are supplied to later independent reviews. Source snapshots do not follow directory
|
|
1244
|
+
links outside the approved checkout.
|
|
1245
|
+
|
|
1246
|
+
Before posting groups, the workflow saves the exact final result and write payload.
|
|
1247
|
+
If posting fails or its acknowledgement is lost, rerunning dedupe replays that
|
|
1248
|
+
payload without looking up candidates or running models. Group persistence reuses
|
|
1249
|
+
the existing membership identity, so replay does not create another group. The
|
|
1250
|
+
dedupe stage completes only after acknowledgement. Empty results are also retained.
|
|
1251
|
+
A completed workflow or pending write represents its already reviewed snapshot;
|
|
1252
|
+
use another workflow ID for a fresh review rather than changing that saved result.
|
|
1253
|
+
|
|
1254
|
+
### Deduplication workflow
|
|
1255
|
+
|
|
1256
|
+
1. For each distinct finding ID in the scan, request
|
|
1257
|
+
`/v1/finding/{id}/potential-duplicates` with the selected repository or
|
|
1258
|
+
explicit all-repository scope. Use the complete stored anchor and
|
|
1259
|
+
candidates returned by that request.
|
|
1260
|
+
2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
|
|
1261
|
+
effort. The review covers every anchor-neighbor pair; nominations between
|
|
1262
|
+
neighbors are rejected.
|
|
1263
|
+
3. Independently review each nominated pair once with `gpt-5.6-sol` at `xhigh`
|
|
1264
|
+
reasoning effort. Only accepted pairs contribute to duplicate groups.
|
|
1265
|
+
4. Group connected findings deterministically, treating accepted duplicate
|
|
1266
|
+
pairs as transitive: if A matches B and B matches C, all three belong to one
|
|
1267
|
+
group. There is no additional whole-group review. A mistaken accepted pair
|
|
1268
|
+
can therefore join otherwise distinct findings.
|
|
1269
|
+
5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
|
|
1270
|
+
only after the service accepts the write. An empty result requires no write.
|
|
1271
|
+
|
|
1272
|
+
Each review uses a fresh, ephemeral Codex app-server thread with the complete
|
|
1273
|
+
original finding records, not earlier model rationales, vector scores, or
|
|
1274
|
+
summaries. Reviews can inspect source in the saved scan's local checkout,
|
|
1275
|
+
starting with cited paths and revisions. Source inspection establishes duplicate
|
|
1276
|
+
identity and shared remediation. Reviews preserve the originals' severity and
|
|
1277
|
+
priority metadata without reassessment or normalization. The baseline
|
|
1278
|
+
filesystem profile is read-only and excludes credentials
|
|
1279
|
+
and Codex state. Screening denies approval requests; final reviews use Codex's
|
|
1280
|
+
automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
|
|
1281
|
+
Finding content never authorizes access to another target.
|
|
1282
|
+
|
|
1283
|
+
Decisions must arrive through the direct `review_validator.submit_decisions`
|
|
1284
|
+
tool; invalid submissions can be corrected in the same session. A final text
|
|
1285
|
+
answer alone is insufficient. Every `SAME` decision, including screening
|
|
1286
|
+
nominations, requires an assigned `canonicalFindingId` and a generated,
|
|
1287
|
+
inclusive `mergedFinding`; missing or null values are rejected. Screening
|
|
1288
|
+
canonicals must belong to the nominated pair. Sol reviews use only the complete
|
|
1289
|
+
originals, never earlier merged findings. These review fields do not change
|
|
1290
|
+
the command's ID-only result or stored findings.
|
|
1291
|
+
|
|
1292
|
+
Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
|
|
1293
|
+
`OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
|
|
1294
|
+
credentials are not sent to the findings API. Larger scans can take time and
|
|
1295
|
+
incur multiple model calls per finding. Empty scans and findings without
|
|
1296
|
+
eligible neighbors do not invoke review models. `completed` means this
|
|
1297
|
+
retrieval, review, and group persistence completed, not that every possible pair in the
|
|
1298
|
+
database was compared or that model decisions are infallible. An API, review, or write-back
|
|
1299
|
+
failure fails the command without claiming a completed result. Retry after
|
|
1300
|
+
fixing the failure; stored findings remain unchanged. A lost write-back response
|
|
1301
|
+
may have committed groups; retrying the same memberships does not duplicate
|
|
1302
|
+
them. Failed or interrupted reviews write no groups. The CLI supports Ctrl-C
|
|
1303
|
+
and SIGTERM, and the SDK accepts an `AbortSignal`.
|
|
1304
|
+
|
|
1305
|
+
### Listing and errors
|
|
1306
|
+
|
|
1307
|
+
Listing defaults to `limit=50` and `offset=0`; `limit` must be a positive
|
|
1308
|
+
integer and `offset` a non-negative integer. Records are ordered by their first
|
|
1309
|
+
insertion time, then finding ID. Follow `nextOffset` until it is `null`:
|
|
1310
|
+
|
|
1311
|
+
```json
|
|
1312
|
+
{
|
|
1313
|
+
"findings": [],
|
|
1314
|
+
"limit": 50,
|
|
1315
|
+
"offset": 0,
|
|
1316
|
+
"total": 0,
|
|
1317
|
+
"nextOffset": null
|
|
1318
|
+
}
|
|
1319
|
+
```
|
|
1320
|
+
|
|
1321
|
+
The list includes API imports and complete finding documents from existing CLI
|
|
1322
|
+
scan history. It returns the latest stored document for each finding ID,
|
|
1323
|
+
without embedding vectors. Legacy identities without a complete document are
|
|
1324
|
+
not included. Pagination reflects current database contents, not a snapshot
|
|
1325
|
+
held between HTTP requests.
|
|
1326
|
+
|
|
1327
|
+
Malformed JSON, invalid finding objects, repository metadata, groups, scopes, and pagination return HTTP
|
|
1328
|
+
400 (`invalid_request`). Identity conflicts or missing dedupe group members return 409 (`finding_conflict`),
|
|
1329
|
+
embedding provider failures or unusable vectors return 502 (`embedding_failed`),
|
|
1330
|
+
and missing embedding credentials return 503 (`embedding_unavailable`). A
|
|
1331
|
+
potential-duplicates query without a current embedding returns 404
|
|
1332
|
+
(`finding_not_indexed`), including findings outside the requested repository or
|
|
1333
|
+
whose embedding was invalidated by an update; import the finding with the
|
|
1334
|
+
matching `repositoryId` before retrying. This is an error, not an
|
|
1335
|
+
empty candidate list. Unknown routes return 404 (`not_found`); unexpected
|
|
1336
|
+
server failures return 500 (`internal_error`). Errors have an `error` code and,
|
|
1337
|
+
for expected failures, a `message`. Request bodies and provider error bodies
|
|
1338
|
+
are not logged.
|
|
1339
|
+
|
|
1340
|
+
### Embeddings and storage
|
|
1341
|
+
|
|
1342
|
+
Set `OPENAI_API_KEY` in the repository-root `.env`, using `.env.example` as a
|
|
1343
|
+
template, or export `OPENAI_API_KEY` or `CODEX_API_KEY` in the host environment.
|
|
1344
|
+
Compose passes the key to the service; exported values override `.env` values.
|
|
1345
|
+
The `.env` file is excluded from Git and Docker builds. `OPENAI_API_KEY` takes
|
|
1346
|
+
precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
|
|
1347
|
+
`CODEX_API_KEY` instead. Listing and empty imports do not require a key.
|
|
1348
|
+
A Codex ChatGPT login is not an embedding API credential.
|
|
1349
|
+
|
|
1350
|
+
The service calls the OpenAI embeddings API with `text-embedding-3-large` and
|
|
1351
|
+
1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
|
|
1352
|
+
bundled `cl100k_base` encoding. Long inputs are split without truncation;
|
|
1353
|
+
their vectors are combined by token weight and normalized. Requests respect
|
|
1354
|
+
the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.
|
|
1355
|
+
See the [embedding API contract](https://developers.openai.com/api/reference/resources/embeddings/methods/create).
|
|
1356
|
+
|
|
1357
|
+
Storage initializes before the server listens. The SQLite adapter reuses the
|
|
1358
|
+
bundled workbench's schema and migrations at
|
|
1359
|
+
`$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. An append-only migration adds
|
|
1360
|
+
complete finding documents and an embedding table, while retaining the existing
|
|
1361
|
+
finding identity table and scan history. Both the API and current CLI indexing
|
|
1362
|
+
use the same finding upsert operation. Changing a stored document invalidates
|
|
1363
|
+
its old embedding so later matching cannot use a stale vector. Historical
|
|
1364
|
+
findings are not automatically embedded; submit them to a bulk endpoint first.
|
|
1365
|
+
|
|
1366
|
+
The `findings-state` named volume persists `/state`, including the database,
|
|
1367
|
+
across container replacements. Keep the same Compose project name to reuse it.
|
|
1368
|
+
The image runs as UID/GID `10001:10001`; a bind mount must be writable by that
|
|
1369
|
+
UID/GID if used instead of the named volume.
|
|
1370
|
+
|
|
1371
|
+
Stop the service with
|
|
1372
|
+
`docker compose -f compose.findings.yaml down`; add `--volumes` only when you
|
|
1373
|
+
intend to delete the stored data.
|
|
1374
|
+
|
|
1375
|
+
The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
|
|
1376
|
+
`CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
|
|
1377
|
+
changing these settings. Compose binds only to host loopback; the API has no
|
|
1378
|
+
authentication. Use an authenticated TLS proxy before sharing access. Finding
|
|
1379
|
+
JSON is sent to `api.openai.com` over HTTPS for embeddings; the database and
|
|
1380
|
+
generated embeddings stay in the local volume.
|
|
1381
|
+
|
|
1382
|
+
### Upgrades and backups
|
|
1383
|
+
|
|
1384
|
+
Read the release notes and stop the service before backing up the entire
|
|
1385
|
+
`/state` directory. For the published-image Compose configuration:
|
|
1386
|
+
|
|
1387
|
+
```bash
|
|
1388
|
+
docker compose -f compose.findings.yaml stop findings
|
|
1389
|
+
mkdir -p backups
|
|
1390
|
+
chmod 700 backups
|
|
1391
|
+
docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \
|
|
1392
|
+
--entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz
|
|
1393
|
+
chmod 600 backups/findings-state.tgz
|
|
1394
|
+
```
|
|
1395
|
+
|
|
1396
|
+
Keep backups separately; this command overwrites an existing backup of the same
|
|
1397
|
+
name. Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest and repeat
|
|
1398
|
+
the pull/start commands above, retaining the volume. Startup applies SQLite
|
|
1399
|
+
migrations automatically. To roll back, stop the service, restore the pre-upgrade
|
|
1400
|
+
backup, and select the previous image digest; an older image may not support the
|
|
1401
|
+
migrated database.
|
|
1402
|
+
|
|
1403
|
+
### Running without Docker
|
|
1404
|
+
|
|
1405
|
+
To run locally, use Node.js and Python 3 as described in the prerequisites.
|
|
1406
|
+
Export the API key in your shell; the server does not load `.env` automatically.
|
|
1407
|
+
From `sdk/typescript`, install dependencies, build, and start:
|
|
1408
|
+
|
|
1409
|
+
```bash
|
|
1410
|
+
pnpm install --frozen-lockfile
|
|
1411
|
+
pnpm run build
|
|
1412
|
+
pnpm run start:server
|
|
1413
|
+
```
|
|
1414
|
+
|
|
1415
|
+
Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
|
|
1416
|
+
`CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
|
|
1417
|
+
without a state override, the service uses the same default state directory as
|
|
1418
|
+
the CLI. These settings also work on Windows.
|
|
1419
|
+
|
|
1420
|
+
HTTP routing, orchestration, embedding generation, and the SQLite adapter live
|
|
1421
|
+
separately under `src/server/`. `FindingsService` receives a `FindingEmbedder`
|
|
1422
|
+
whose `embed(findings)` method returns one `{ model, vector }` per finding in
|
|
1423
|
+
input order. `OpenAiFindingEmbedder` handles tokenization, batching, API calls,
|
|
1424
|
+
and vector normalization; it does not access storage. The `FindingsStore`
|
|
1425
|
+
interface stores findings and vectors and exposes
|
|
1426
|
+
`findPotentialDuplicates(findingId, scope)`. Repository filtering, vector ranking,
|
|
1427
|
+
and fetching selected documents stay inside the store implementation; replacing
|
|
1428
|
+
SQLite with an indexed store does not change the service or SDK/CLI. Repository
|
|
1429
|
+
associations are stored separately from finding documents, with an append-only
|
|
1430
|
+
migration that also imports known associations from stored scan occurrences.
|
|
1431
|
+
New scan findings retain their target associations when indexed locally.
|
|
1432
|
+
The server entrypoint selects the concrete
|
|
1433
|
+
embedder and store, so either can be replaced independently.
|
|
1434
|
+
The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
|
|
1435
|
+
receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
|
|
1436
|
+
separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
|
|
1437
|
+
and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
|
|
1438
|
+
`deduplicateScan` validates saved scan artifacts before running the workflow.
|
|
1439
|
+
The SDK reuses the existing Codex runtime and credentials without additional
|
|
1440
|
+
runtime dependencies.
|
|
1441
|
+
|
|
1442
|
+
## Containerized bulk scans
|
|
1443
|
+
|
|
1444
|
+
Create `repositories.csv` as described under [Bulk scans](#bulk-scans).
|
|
1445
|
+
With a published image, run from the Codex Security repository root:
|
|
1202
1446
|
|
|
1203
1447
|
```bash
|
|
1204
1448
|
mkdir -p results state
|
|
@@ -1210,17 +1454,17 @@ docker compose run --rm codex-security login --device-auth
|
|
|
1210
1454
|
docker compose run --rm codex-security
|
|
1211
1455
|
```
|
|
1212
1456
|
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
or `
|
|
1216
|
-
|
|
1457
|
+
Results go to `results/`; device login stays in `state/`. For unattended scans,
|
|
1458
|
+
set `OPENAI_API_KEY` or `CODEX_API_KEY`. Private GitHub checkouts use `GH_TOKEN`
|
|
1459
|
+
or `GITHUB_TOKEN`; GitHub Enterprise uses `CODEX_SECURITY_GIT_HOST`. The container
|
|
1460
|
+
requires CSV input, without interactive discovery.
|
|
1217
1461
|
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1462
|
+
Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,
|
|
1463
|
+
`CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and
|
|
1464
|
+
`CODEX_SECURITY_STATE` for the image, user, seccomp profile, and mounts.
|
|
1221
1465
|
|
|
1222
1466
|
On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
|
|
1223
|
-
can install the optional
|
|
1467
|
+
can install the optional AppArmor profile:
|
|
1224
1468
|
|
|
1225
1469
|
```bash
|
|
1226
1470
|
sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
|
|
@@ -1228,37 +1472,29 @@ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
|
|
|
1228
1472
|
docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
|
|
1229
1473
|
```
|
|
1230
1474
|
|
|
1231
|
-
The override
|
|
1232
|
-
|
|
1233
|
-
the profile or override.
|
|
1475
|
+
The override keeps the nonroot user, dropped capabilities, no-new-privileges,
|
|
1476
|
+
and seccomp policy. Other Docker hosts don't need it.
|
|
1234
1477
|
|
|
1235
1478
|
## Local security model
|
|
1236
1479
|
|
|
1237
|
-
Codex Security runs with your
|
|
1238
|
-
repositories you trust and
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
unrelated API tokens and cloud credentials. Start a scan with only the
|
|
1256
|
-
credentials it needs.
|
|
1257
|
-
|
|
1258
|
-
The scanner must stay within the target and output paths you authorize and
|
|
1259
|
-
must not disclose private data beyond the operation you requested. Its results
|
|
1260
|
-
must accurately report the scan mode, reviewed files, and exclusions. Consult
|
|
1261
|
-
the security policy for the full threat model and private reporting process.
|
|
1480
|
+
Codex Security runs with your operating-system permissions. Only scan
|
|
1481
|
+
repositories you trust and are authorized to assess. Local tools and scans
|
|
1482
|
+
under the same account aren't separate security principals.
|
|
1483
|
+
|
|
1484
|
+
The `codex_security_scan` profile allows reads across the local filesystem and
|
|
1485
|
+
writes to workspace roots. Execution approvals are reviewed automatically and
|
|
1486
|
+
may grant extra permissions for one operation. Set
|
|
1487
|
+
`--codex 'approval_policy="never"'`, directly or in a selected profile, to deny
|
|
1488
|
+
requests. Other overrides can't replace the reviewer or filesystem profile.
|
|
1489
|
+
Saved scans keep their approval policy; older scans stay deny-all on rerun.
|
|
1490
|
+
Host and network restrictions still apply.
|
|
1491
|
+
|
|
1492
|
+
Start scans with only the credentials they need. Scan and workbench subprocesses
|
|
1493
|
+
can inherit your environment, including unrelated API tokens and cloud credentials.
|
|
1494
|
+
|
|
1495
|
+
Repository contents, model output, and imported artifacts do not authorize
|
|
1496
|
+
access to other targets, disclosure of credentials, or writes outside approved
|
|
1497
|
+
paths. See the security policy below for the full threat model.
|
|
1262
1498
|
|
|
1263
1499
|
## Documentation and security
|
|
1264
1500
|
|