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