@openai/codex-security 0.1.26 → 0.1.28

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 (253) hide show
  1. package/README.md +637 -74
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs +24 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/native/COPYRIGHT-library.html +5556 -0
  6. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +5989 -0
  7. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/licenses/Apache-2.0.txt +73 -0
  10. package/_bundled_plugin/mcp/native/licenses/BSD-2-Clause.txt +9 -0
  11. package/_bundled_plugin/mcp/native/licenses/MIT.txt +9 -0
  12. package/_bundled_plugin/mcp/native/licenses/Unicode-3.0.txt +39 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  21. package/_bundled_plugin/references/artifact-storage.md +56 -0
  22. package/_bundled_plugin/references/config-preflight.md +9 -1
  23. package/_bundled_plugin/references/core-scan.md +1 -1
  24. package/_bundled_plugin/references/final-report.md +2 -0
  25. package/_bundled_plugin/references/scan-artifacts.md +6 -14
  26. package/_bundled_plugin/references/scan-contract.md +35 -35
  27. package/_bundled_plugin/references/scan-prologue.md +2 -0
  28. package/_bundled_plugin/references/security-guidance.md +9 -1
  29. package/_bundled_plugin/scripts/deep_scan_config.py +10 -8
  30. package/_bundled_plugin/scripts/deep_scan_defaults.json +8 -0
  31. package/_bundled_plugin/scripts/generate_in_scope_files.py +2 -2
  32. package/_bundled_plugin/scripts/generate_rank_input.py +8 -1
  33. package/_bundled_plugin/scripts/launch_codex_security_mcp +6 -0
  34. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +43 -9
  35. package/_bundled_plugin/scripts/rank_preview.py +4 -1
  36. package/_bundled_plugin/scripts/reserved_artifact_paths.json +6 -0
  37. package/_bundled_plugin/scripts/windows_scan_local_files.py +1 -3
  38. package/_bundled_plugin/scripts/workbench/storage.py +18 -0
  39. package/_bundled_plugin/scripts/workbench_cli.py +17 -0
  40. package/_bundled_plugin/scripts/workbench_db.py +46 -42
  41. package/_bundled_plugin/scripts/workbench_saved_results.py +72 -1
  42. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -2
  43. package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -10
  44. package/_bundled_plugin/scripts/workbench_validation.py +4 -0
  45. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +2 -0
  46. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +2 -0
  47. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +5 -1
  48. package/_bundled_plugin/skills/define-security-policy/SKILL.md +3 -3
  49. package/_bundled_plugin/skills/finding-discovery/SKILL.md +2 -0
  50. package/_bundled_plugin/skills/fix-finding/SKILL.md +3 -1
  51. package/_bundled_plugin/skills/fix-finding/agents/openai.yaml +1 -1
  52. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +2 -0
  53. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +5 -1
  54. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -0
  55. package/_bundled_plugin/skills/validation/SKILL.md +2 -0
  56. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +2 -0
  57. package/dist/api.d.ts +14 -24
  58. package/dist/api.d.ts.map +1 -1
  59. package/dist/api.js +585 -168
  60. package/dist/api.js.map +1 -1
  61. package/dist/auth.d.ts.map +1 -1
  62. package/dist/auth.js +10 -0
  63. package/dist/auth.js.map +1 -1
  64. package/dist/bulk-scan-discovery.d.ts +1 -1
  65. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  66. package/dist/bulk-scan-discovery.js +2 -2
  67. package/dist/bulk-scan-discovery.js.map +1 -1
  68. package/dist/classify-scan-severity.js.map +1 -1
  69. package/dist/classify-severity.d.ts.map +1 -1
  70. package/dist/classify-severity.js.map +1 -1
  71. package/dist/cli.d.ts +24 -4
  72. package/dist/cli.d.ts.map +1 -1
  73. package/dist/cli.js +1577 -610
  74. package/dist/cli.js.map +1 -1
  75. package/dist/cloud-publish.d.ts.map +1 -1
  76. package/dist/cloud-publish.js +2 -207
  77. package/dist/cloud-publish.js.map +1 -1
  78. package/dist/component-plan.d.ts.map +1 -1
  79. package/dist/component-plan.js +116 -32
  80. package/dist/component-plan.js.map +1 -1
  81. package/dist/component-scan.d.ts +4 -2
  82. package/dist/component-scan.d.ts.map +1 -1
  83. package/dist/component-scan.js +7 -1
  84. package/dist/component-scan.js.map +1 -1
  85. package/dist/config-path.d.ts +6 -0
  86. package/dist/config-path.d.ts.map +1 -0
  87. package/dist/config-path.js +6 -0
  88. package/dist/config-path.js.map +1 -0
  89. package/dist/config.d.ts +3 -0
  90. package/dist/config.d.ts.map +1 -1
  91. package/dist/config.js +30 -5
  92. package/dist/config.js.map +1 -1
  93. package/dist/contract.d.ts +5 -10
  94. package/dist/contract.d.ts.map +1 -1
  95. package/dist/contract.js.map +1 -1
  96. package/dist/cost-model.d.ts +30 -0
  97. package/dist/cost-model.d.ts.map +1 -1
  98. package/dist/cost-model.js +123 -4
  99. package/dist/cost-model.js.map +1 -1
  100. package/dist/cost.d.ts.map +1 -1
  101. package/dist/cost.js +18 -3
  102. package/dist/cost.js.map +1 -1
  103. package/dist/custom-publish.js.map +1 -1
  104. package/dist/custom-validation-prompt.js +1 -1
  105. package/dist/custom-validation-prompt.js.map +1 -1
  106. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  107. package/dist/deduplication/checkpointed-review.js.map +1 -1
  108. package/dist/deduplication/codex-review.d.ts +6 -1
  109. package/dist/deduplication/codex-review.d.ts.map +1 -1
  110. package/dist/deduplication/codex-review.js +72 -17
  111. package/dist/deduplication/codex-review.js.map +1 -1
  112. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  113. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  114. package/dist/deduplication/deduplication.d.ts +2 -0
  115. package/dist/deduplication/deduplication.d.ts.map +1 -1
  116. package/dist/deduplication/deduplication.js +99 -26
  117. package/dist/deduplication/deduplication.js.map +1 -1
  118. package/dist/deduplication/retry.d.ts +3 -0
  119. package/dist/deduplication/retry.d.ts.map +1 -0
  120. package/dist/deduplication/retry.js +15 -0
  121. package/dist/deduplication/retry.js.map +1 -0
  122. package/dist/deduplication/scan.d.ts +2 -0
  123. package/dist/deduplication/scan.d.ts.map +1 -1
  124. package/dist/deduplication/scan.js +4 -2
  125. package/dist/deduplication/scan.js.map +1 -1
  126. package/dist/deep-config.d.ts +17 -0
  127. package/dist/deep-config.d.ts.map +1 -0
  128. package/dist/deep-config.js +145 -0
  129. package/dist/deep-config.js.map +1 -0
  130. package/dist/deep-progress.d.ts.map +1 -1
  131. package/dist/deep-scan-defaults.d.ts +9 -0
  132. package/dist/deep-scan-defaults.d.ts.map +1 -0
  133. package/dist/deep-scan-defaults.js +10 -0
  134. package/dist/deep-scan-defaults.js.map +1 -0
  135. package/dist/errors.d.ts.map +1 -1
  136. package/dist/errors.js +2 -2
  137. package/dist/errors.js.map +1 -1
  138. package/dist/feedback.d.ts +20 -0
  139. package/dist/feedback.d.ts.map +1 -0
  140. package/dist/feedback.js +135 -0
  141. package/dist/feedback.js.map +1 -0
  142. package/dist/finding-catalogue.js.map +1 -1
  143. package/dist/finding-workflow.d.ts.map +1 -1
  144. package/dist/finding-workflow.js.map +1 -1
  145. package/dist/findings-client.d.ts +7 -1
  146. package/dist/findings-client.d.ts.map +1 -1
  147. package/dist/findings-client.js +55 -10
  148. package/dist/findings-client.js.map +1 -1
  149. package/dist/findings-import.d.ts +44 -0
  150. package/dist/findings-import.d.ts.map +1 -0
  151. package/dist/findings-import.js +302 -0
  152. package/dist/findings-import.js.map +1 -0
  153. package/dist/github.d.ts +625 -7
  154. package/dist/github.d.ts.map +1 -1
  155. package/dist/github.js.map +1 -1
  156. package/dist/import-scan.d.ts +27 -0
  157. package/dist/import-scan.d.ts.map +1 -0
  158. package/dist/import-scan.js +236 -0
  159. package/dist/import-scan.js.map +1 -0
  160. package/dist/index.d.ts +7 -0
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +2 -0
  163. package/dist/index.js.map +1 -1
  164. package/dist/knowledge-base.d.ts +1 -1
  165. package/dist/knowledge-base.d.ts.map +1 -1
  166. package/dist/knowledge-base.js +19 -8
  167. package/dist/knowledge-base.js.map +1 -1
  168. package/dist/models.d.ts.map +1 -1
  169. package/dist/models.js.map +1 -1
  170. package/dist/multiscan.d.ts +7 -5
  171. package/dist/multiscan.d.ts.map +1 -1
  172. package/dist/multiscan.js +212 -55
  173. package/dist/multiscan.js.map +1 -1
  174. package/dist/patch-tui.d.ts.map +1 -1
  175. package/dist/patch-tui.js.map +1 -1
  176. package/dist/project-config-schema.d.ts +191 -0
  177. package/dist/project-config-schema.d.ts.map +1 -0
  178. package/dist/project-config-schema.js +85 -0
  179. package/dist/project-config-schema.js.map +1 -0
  180. package/dist/project-config.d.ts +50 -0
  181. package/dist/project-config.d.ts.map +1 -0
  182. package/dist/project-config.js +220 -0
  183. package/dist/project-config.js.map +1 -0
  184. package/dist/prompt-files.d.ts +13 -0
  185. package/dist/prompt-files.d.ts.map +1 -0
  186. package/dist/prompt-files.js +74 -0
  187. package/dist/prompt-files.js.map +1 -0
  188. package/dist/publication-events.d.ts.map +1 -1
  189. package/dist/publication-events.js +7 -2
  190. package/dist/publication-events.js.map +1 -1
  191. package/dist/publish.d.ts.map +1 -1
  192. package/dist/publish.js +1 -1
  193. package/dist/publish.js.map +1 -1
  194. package/dist/result.d.ts +2 -1
  195. package/dist/result.d.ts.map +1 -1
  196. package/dist/result.js +5 -0
  197. package/dist/result.js.map +1 -1
  198. package/dist/runtime.d.ts +5 -1
  199. package/dist/runtime.d.ts.map +1 -1
  200. package/dist/runtime.js +12 -6
  201. package/dist/runtime.js.map +1 -1
  202. package/dist/scan-comparison.d.ts.map +1 -1
  203. package/dist/scan-comparison.js.map +1 -1
  204. package/dist/scan-dashboard.d.ts +1 -0
  205. package/dist/scan-dashboard.d.ts.map +1 -1
  206. package/dist/scan-dashboard.js +45 -20
  207. package/dist/scan-dashboard.js.map +1 -1
  208. package/dist/scan-history-renderer.d.ts.map +1 -1
  209. package/dist/scan-history-renderer.js.map +1 -1
  210. package/dist/scan-logs.d.ts +39 -3
  211. package/dist/scan-logs.d.ts.map +1 -1
  212. package/dist/scan-logs.js +77 -15
  213. package/dist/scan-logs.js.map +1 -1
  214. package/dist/scan-modes.d.ts +3 -0
  215. package/dist/scan-modes.d.ts.map +1 -0
  216. package/dist/scan-modes.js +2 -0
  217. package/dist/scan-modes.js.map +1 -0
  218. package/dist/scan-settings.d.ts +81 -0
  219. package/dist/scan-settings.d.ts.map +1 -0
  220. package/dist/scan-settings.js +123 -0
  221. package/dist/scan-settings.js.map +1 -0
  222. package/dist/security-policy-cli.d.ts +39 -0
  223. package/dist/security-policy-cli.d.ts.map +1 -0
  224. package/dist/security-policy-cli.js +193 -0
  225. package/dist/security-policy-cli.js.map +1 -0
  226. package/dist/security-policy.d.ts +80 -0
  227. package/dist/security-policy.d.ts.map +1 -0
  228. package/dist/security-policy.js +672 -0
  229. package/dist/security-policy.js.map +1 -0
  230. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +2 -2
  231. package/dist/server/dashboard/app.js +2 -2
  232. package/dist/server/dashboard.js.map +1 -1
  233. package/dist/server/embeddings.d.ts.map +1 -1
  234. package/dist/server/embeddings.js.map +1 -1
  235. package/dist/server/errors.d.ts.map +1 -1
  236. package/dist/server/errors.js.map +1 -1
  237. package/dist/server/findings-service.d.ts.map +1 -1
  238. package/dist/server/findings-service.js.map +1 -1
  239. package/dist/server/serve.js.map +1 -1
  240. package/dist/server/sqlite-store.d.ts.map +1 -1
  241. package/dist/server/sqlite-store.js.map +1 -1
  242. package/dist/severity-store.js.map +1 -1
  243. package/dist/targets.d.ts +10 -2
  244. package/dist/targets.d.ts.map +1 -1
  245. package/dist/targets.js +243 -14
  246. package/dist/targets.js.map +1 -1
  247. package/dist/thread-source.d.ts.map +1 -1
  248. package/dist/version.js.map +1 -1
  249. package/dist/worker-progress.d.ts.map +1 -1
  250. package/dist/worker-progress.js.map +1 -1
  251. package/package.json +36 -29
  252. package/schemas/project-config.schema.json +211 -0
  253. package/_bundled_plugin/scripts/resolve_security_md.py +0 -158
package/README.md CHANGED
@@ -13,7 +13,7 @@ npx @openai/codex-security --version
13
13
  ```
14
14
 
15
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+
16
+ Policy drafting, scans, exports, scan history, and saved findings also need Python 3.10+
17
17
  (plus `tomli` on Python 3.10).
18
18
 
19
19
  ## Run a scan from TypeScript
@@ -139,21 +139,25 @@ Constructor options:
139
139
  Options for `security.run(repository, options)` and
140
140
  `security.preflight(repository, options)`:
141
141
 
142
- | Option | Description |
143
- | ----------------------- | ------------------------------------------------------------------------------ |
144
- | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
- | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
- | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
- | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
- | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
- | `outputDir` | Artifact directory outside the enclosing Git worktree. |
150
- | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
151
- | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
152
- | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
153
- | `failureSeverity` | Finding-severity policy to record in the saved scan recipe. |
154
- | `parentScanId` | Parent scan ID for a rerun. |
155
- | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
156
- | `signal` | `AbortSignal` to cancel a scan. |
142
+ | Option | Description |
143
+ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
144
+ | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
+ | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
+ | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
+ | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
+ | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
+ | `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |
150
+ | `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |
151
+ | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |
152
+ | `outputDir` | Artifact directory outside the enclosing Git worktree. |
153
+ | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
154
+ | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
155
+ | `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |
156
+ | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
157
+ | `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |
158
+ | `parentScanId` | Parent scan ID for a rerun. |
159
+ | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
160
+ | `signal` | `AbortSignal` to cancel a scan. |
157
161
 
158
162
  Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
159
163
  saved events with thread IDs and worker numbers. Deep scans can additionally use
@@ -164,6 +168,46 @@ and `maximum`. The maximum is a configured cap, not a percentage denominator.
164
168
  `preflight` and CLI `--dry-run` check local inputs without starting Codex or
165
169
  using the network. They don't authenticate, verify model access, resolve Python,
166
170
  inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
171
+ Deep preflight includes all six resolved deep settings and their origins in
172
+ `deepScanSources`. Applicable legacy deep configuration is validated during
173
+ preflight rather than after runtime startup.
174
+
175
+ `ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,
176
+ cancellation, workflow, and runtime controls. Load the same project file used by
177
+ `scan -c` through the SDK:
178
+
179
+ ```ts
180
+ import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
181
+
182
+ const { config, options } = await loadProjectConfig("codex-security.yaml");
183
+ await using security = new CodexSecurity(config);
184
+ const result = await security.run(repository, options);
185
+ if (
186
+ options.failureSeverity !== undefined &&
187
+ result.hasFindingsAtOrAbove(options.failureSeverity)
188
+ ) {
189
+ process.exitCode = 1;
190
+ }
191
+ ```
192
+
193
+ `resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`
194
+ object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,
195
+ options }` pair and an immutable `sources` map. Resolved context, prompt, and output
196
+ paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file
197
+ from `directory`, which defaults to the current directory; paths inside the file
198
+ are relative to that file. Object paths are relative to the supplied directory.
199
+ Scope paths remain relative to the selected repository. Neither helper starts a
200
+ scan, reads prompt contents, or discovers another configuration file. `preflight`
201
+ and `run` apply the existing local checks and remaining legacy deep defaults.
202
+ Project-file keys follow Codex's configuration convention; SDK options keep their
203
+ existing `camelCase` names, and CLI flags keep `kebab-case`.
204
+
205
+ Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add
206
+ callbacks there. Direct SDK prompt-file paths use the current directory; inline
207
+ text takes precedence over its matching file. Files use the same regular-file
208
+ protections as the CLI. The SDK records `failureSeverity` without throwing or
209
+ changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering
210
+ and leaves the findings unchanged.
167
211
 
168
212
  ## Authentication
169
213
 
@@ -186,7 +230,7 @@ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin
186
230
  printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
187
231
  ```
188
232
 
189
- Environment API keys apply to the current scan; only `login --with-api-key`
233
+ Environment API keys apply to the current command; only `login --with-api-key`
190
234
  saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
191
235
  Access-token environment variables are not scan API keys.
192
236
 
@@ -219,6 +263,15 @@ credentials, and the default AWS credential chain. Set `AWS_REGION` and choose
219
263
  a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`
220
264
  support `--max-cost`.
221
265
 
266
+ Bedrock scans, including Deep Scan workers, default to
267
+ `model_reasoning_summary = "none"` because some Bedrock models reject
268
+ `reasoning.summary`. This leaves reasoning effort unchanged. Explicit summary
269
+ settings in `--codex` overrides or the selected Codex profile take precedence.
270
+ For standard scans on older CLI versions, append
271
+ `--codex 'model_reasoning_summary="none"'` to your scan command if Bedrock
272
+ reports that `reasoning.summary` is unsupported. Deep scans require a CLI
273
+ version that forwards this setting to workers.
274
+
222
275
  On Windows, set the API key in PowerShell:
223
276
 
224
277
  ```powershell
@@ -226,11 +279,23 @@ $env:OPENAI_API_KEY = "<your-api-key>"
226
279
  npx @openai/codex-security scan C:\code\repository
227
280
  ```
228
281
 
229
- Login, logout, and scans share a private credential home:
282
+ Login, logout, scans, validation, patching, and fix verification share a private
283
+ credential home for stored OpenAI credentials, including custom providers with
284
+ `requires_openai_auth = true`:
230
285
  `$CODEX_SECURITY_STATE_DIR/codex-home`, or
231
- `$CODEX_HOME/state/plugins/codex-security/codex-home`. Codex uses the configured
232
- file or keyring storage and managed-device policies. If this home has no
233
- credentials, it imports an existing file-based Codex sign-in. Logout disables
286
+ `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this credential
287
+ home outside the target directory and every enclosing Git worktree, including
288
+ when running a command from a subdirectory. Codex carries
289
+ `cli_auth_credentials_store`, `forced_login_method`, and
290
+ `forced_chatgpt_workspace_id` from the ambient configuration into this home,
291
+ including removing settings that are no longer present in the ambient configuration.
292
+ Each command carries its selected provider into this home. Patching and fix
293
+ verification also synchronize the ambient home's project-trust decisions and
294
+ project-root markers, preserving which project configuration Codex loads.
295
+ They hold the credential-home lock until the app-server thread is ready,
296
+ then release it before model execution.
297
+ Managed-device policies still apply. If this home has no credentials, it imports
298
+ an existing file-based Codex sign-in. Logout disables
234
299
  imports until you log in again.
235
300
 
236
301
  Finish operations using older versions before upgrading. Runtime preparation
@@ -255,19 +320,167 @@ npx @openai/codex-security scan . --auth chatgpt
255
320
  npx @openai/codex-security scan . --auth api-key
256
321
  ```
257
322
 
323
+ `--auth` also works with `validate`, `patch`, and `verify-fix`. These commands
324
+ use the same stored login as `scan`, including a sign-in created with
325
+ `codex-security login --device-auth`:
326
+
327
+ ```bash
328
+ npx @openai/codex-security patch OCCURRENCE_ID --auth chatgpt
329
+ npx @openai/codex-security verify-fix OCCURRENCE_ID --auth api-key
330
+ ```
331
+
258
332
  `--auth chatgpt` ignores environment API keys. `--auth api-key` requires
259
- `OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; unset both
260
- variables to default to ChatGPT. The SDK uses the same `auth` option on `run`
261
- and `preflight`. Codex may still need ChatGPT credentials to load
262
- workspace-managed policies when using an API key.
333
+ `OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; noninteractive
334
+ commands prefer `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
335
+ Patch follow-up assessment uses the same selection, and `scan --patch` keeps
336
+ the scan's choice. Environment API keys do not replace the saved login.
337
+ The SDK uses the same `auth` option on `run`, `validate`, and `preflight`.
338
+ Codex may still need ChatGPT credentials to load workspace-managed policies
339
+ when using an API key.
263
340
 
264
341
  Some cybersecurity requests and protected findings require Trusted Access for
265
342
  Cyber approval. Apply or check your access at
266
343
  [chatgpt.com/cyber](https://chatgpt.com/cyber).
267
344
 
345
+ ## Generate a security policy
346
+
347
+ `policy` drafts `SECURITY.md` guidance for future scans. It does not run a
348
+ vulnerability scan, change application settings, or install the draft in the
349
+ checkout. It uses the scan runtime and authentication, requesting read-only
350
+ access to the selected repository or component and required tools. Network access,
351
+ web search, apps, and MCP servers are disabled. Drafts stay outside the checkout.
352
+ The host resolves inherited guidance once and includes each checked descendant
353
+ policy separately. Descendant policy links must stay within the selected component.
354
+ Inherited and reporting-policy links may also resolve to ancestor `SECURITY.md`
355
+ files or the checkout's `.github/SECURITY.md` and `docs/SECURITY.md`.
356
+ The model cannot read sibling components or Git metadata. Policy turns deny
357
+ access to the resolved Git metadata and markers, including those inside the
358
+ selected source tree, nested bare repositories, and associated alternate object
359
+ stores.
360
+ Policy shell tools inherit only Codex's core environment; custom shell environment
361
+ settings, login shells, and shell snapshots are disabled for these turns.
362
+ Knowledge-base text stays with the private review artifacts during generation
363
+ and is removed afterward.
364
+
365
+ Known limitation: policy preflight and generation currently fail on Unix
366
+ directories with non-UTF-8 names.
367
+
368
+ On macOS, the pinned Codex runtime does not fully enforce write restrictions
369
+ under `/tmp` (including `/private/tmp`). Keep the repository and artifacts outside
370
+ that tree when read-only enforcement is required. See the
371
+ [upstream sandbox limitation](https://github.com/openai/codex/issues/32395).
372
+
373
+ ```bash
374
+ npx @openai/codex-security policy .
375
+ npx @openai/codex-security policy . --path services/api
376
+ npx @openai/codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high
377
+ npx @openai/codex-security policy . --dry-run --json
378
+ ```
379
+
380
+ The repository defaults to the current directory. `--path` selects a component,
381
+ which inherits policies from its Git root, with the closest policy taking
382
+ precedence. Linked worktrees and initialized submodules use their own roots.
383
+ Targets and policy links must stay in the selected checkout, outside Git
384
+ metadata; ancestor links cannot widen a component policy's scope.
385
+
386
+ For an intentional separate Git directory, set `core.worktree` to the checkout's
387
+ absolute path. Use `git worktree repair` for moved linked worktrees.
388
+
389
+ Generation uses three Codex stages: describe the system, build a threat model,
390
+ then draft the policy. The first two documents support review; they are not
391
+ additional approval steps or policies to install.
392
+ In a terminal, it asks about facts the source cannot establish and shows the
393
+ exact diff. If both ChatGPT and API-key credentials are available, it asks which
394
+ to use; `--auth chatgpt` or `--auth api-key` selects one explicitly.
395
+
396
+ | Invocation | Calls Codex? | Result |
397
+ | ---------------------------- | ------------ | ----------------------------------------------------------------------- |
398
+ | `policy .` | Yes | Ask owner questions, save documents, and preview the draft. |
399
+ | `policy . --headless --json` | Yes | Save documents without prompts and return their paths and review notes. |
400
+ | `policy . --format md` | Yes | Generate a draft and write its Markdown to stdout. |
401
+ | `policy . --dry-run --json` | No | Check local inputs and show the resolved target and settings. |
402
+
403
+ None of these commands installs `SECURITY.md` in the repository. Output formats
404
+ change presentation; they do not turn generation into a saved-draft read.
405
+
406
+ ### Review the draft
407
+
408
+ Review the saved `SECURITY.md` before copying it to the reported target. Check
409
+ links from `.github/SECURITY.md` or `docs/SECURITY.md`: copying can change their
410
+ guidance too. Preserve reporting instructions and obtain owner approval for
411
+ exclusions, accepted risks, and severity decisions. Later scans read this policy.
412
+
413
+ Generation and preview check for changes to the selected or inherited policies.
414
+ If governing guidance changes during generation, completed documents remain for
415
+ inspection, but no completed-draft manifest is written. Other source files are not
416
+ frozen; regenerate if relevant source or neighboring policies change.
417
+ A failed terminal preview reports a warning and the saved draft paths. Explicit
418
+ output formats return the draft directly without running a diff preview.
419
+
420
+ Use `--headless` or an explicit output format to skip questions. Unanswered
421
+ questions remain in the review notes. Drafts default to the Codex Security state
422
+ directory; `--output-dir` selects an empty directory outside every enclosing
423
+ Git checkout and its Git metadata.
424
+
425
+ ```bash
426
+ npx @openai/codex-security policy . --path services/api \
427
+ --headless --output-dir /path/outside/repository/api-policy --json
428
+ ```
429
+
430
+ The artifact directory contains:
431
+
432
+ | File | Purpose |
433
+ | ---------------------- | --------------------------------------------------------- |
434
+ | `SECURITY.md` | Editable policy draft. |
435
+ | `THREAT_MODEL.md` | Detailed threat model with source references. |
436
+ | `project-spec.md` | System description and security boundaries. |
437
+ | `previous-SECURITY.md` | Original policy used for the diff. |
438
+ | `policy-draft.json` | Target, policy hashes, revision, model, and review notes. |
439
+
440
+ Keep supporting documents private until reviewed for disclosure. A generated
441
+ threat scenario is neither owner approval nor a confirmed vulnerability.
442
+
443
+ `--format md` writes the draft to stdout. `--json` returns paths, review notes,
444
+ status, and estimated cost. Global filters and token options work with these
445
+ formats. Progress goes to stderr. `--full-output` reports failures with
446
+ `ok: false`. `--max-cost` applies to the whole generation. If a stage cannot
447
+ inspect required source evidence, generation stops and preserves completed
448
+ documents. Fix the reported problem and use a new output directory to retry.
449
+
450
+ ### Generate a policy from TypeScript
451
+
452
+ ```ts
453
+ import { CodexSecurity } from "@openai/codex-security";
454
+
455
+ const security = new CodexSecurity();
456
+ try {
457
+ const draft = await security.generatePolicy("/path/to/repository", {
458
+ path: "services/api",
459
+ knowledgeBasePaths: ["/path/to/architecture.md"],
460
+ onStage: (stage) => console.error(stage),
461
+ });
462
+
463
+ console.log(await security.previewPolicy(draft));
464
+ // Open draft.draftPath in an editor to review the saved policy.
465
+ } finally {
466
+ await security.close();
467
+ }
468
+ ```
469
+
470
+ `preflightPolicy()` checks local inputs without starting Codex.
471
+ `previewPolicy()` previews the supplied in-memory draft, uses the client's Python
472
+ setting, and makes terminal control characters visible. Editing the saved file
473
+ does not change that object. The standalone `securityPolicyDiff()` returns a raw diff
474
+ for files or other non-terminal uses; pass an interpreter explicitly if needed.
475
+ `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
476
+ `maxCostUsd`, `signal`, and progress and cost callbacks. An optional
477
+ `answerQuestions` callback receives each group of up to three owner questions
478
+ and a cancellation signal. Without it, the questions remain unresolved.
479
+
268
480
  ## CLI
269
481
 
270
482
  ```bash
483
+ npx @openai/codex-security policy . --path services/api
271
484
  npx @openai/codex-security scan .
272
485
  npx @openai/codex-security scan /path/to/repository --path src --path tests
273
486
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
@@ -277,7 +490,73 @@ npx @openai/codex-security scan /path/to/repository --dry-run
277
490
 
278
491
  Use `scan --help` for options, `--version` for the installed version, and
279
492
  `info --json` for package, plugin, runtime, and model details. `--dry-run`
280
- runs local preflight checks.
493
+ runs local preflight checks. `info -c FILE --json` inspects resolved configuration
494
+ and its sources without a repository or runtime.
495
+
496
+ ### Project files
497
+
498
+ Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:
499
+
500
+ ```bash
501
+ codex-security scan . -c codex-security.yaml --dry-run --json
502
+ codex-security scan . -c codex-security.json --model gpt-5.6-terra
503
+ codex-security init
504
+ codex-security info -c codex-security.yaml --json
505
+ ```
506
+
507
+ Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,
508
+ and `info` accept `-c`. They also accept an operator-set
509
+ `CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is
510
+ loaded or discovered. The repository still comes from the command's target
511
+ selection. SDK `run()` and saved reruns do not load project files automatically.
512
+
513
+ The selected file is trusted like CLI options and SDK `codexOverrides`. Native
514
+ settings can start configured MCP server processes and select model-service destinations. Do not
515
+ select configuration controlled by an untrusted repository or pull request; keep
516
+ CI scanner configuration outside the checkout being assessed.
517
+
518
+ `init [file]` writes `codex-security.yaml` by default and never overwrites an
519
+ existing file. YAML starters show defaults as comments; JSON starters contain the
520
+ editor schema hint, relative to the chosen file and the invocation directory's
521
+ local package installation. `info` reports effective model details and native key sources
522
+ without dumping raw native values.
523
+
524
+ ```yaml
525
+ # yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
526
+ scan:
527
+ mode: standard
528
+ scope:
529
+ paths: [src]
530
+ codex:
531
+ model: gpt-5.6-sol
532
+ model_reasoning_effort: xhigh
533
+ policy:
534
+ fail_on_severity: high
535
+ ```
536
+
537
+ All settings are optional; `{}` uses the existing defaults. JSON files can use a
538
+ root `$schema` string pointing to the same packaged schema. Schema hints are for
539
+ editors; the CLI uses its bundled validator without fetching URLs, coercing values,
540
+ or dropping unknown keys. Native `codex` settings retain their existing checks and
541
+ profile semantics. CLI `scan --schema --json` describes command arguments.
542
+
543
+ Settings use built-in defaults, applicable legacy deep defaults, the file, then
544
+ explicit CLI values. Lists and scope variants are replaced. `--head` can refine
545
+ a file diff and `--base` a file working-tree scope. A selected native profile can
546
+ still override root model/effort values. Existing native alias-conflict checks
547
+ and the behavior of `--provider openai` are unchanged.
548
+
549
+ File context, instruction, validation, and output paths resolve from the file's
550
+ directory. CLI file paths resolve from the invocation directory; scope paths
551
+ resolve from the repository. The file cannot select a different repository or
552
+ enable automatic patching/publication. The loader does not evaluate code,
553
+ interpolate environment values, include remote files, or merge multiple files.
554
+
555
+ Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected
556
+ prompt paths, and the finding policy without dumping raw native configuration.
557
+ Missing or invalid selected files exit `2`. Help, version, and command schema
558
+ output do not load project files. Existing scan and finding-policy exit codes
559
+ remain unchanged.
281
560
 
282
561
  ### Scan options and output
283
562
 
@@ -285,13 +564,18 @@ runs local preflight checks.
285
564
  and `--working-tree` scans staged and unstaged changes. Deep scans support
286
565
  repository and path targets.
287
566
 
567
+ Bulk scans use clean, shallow checkouts and support repository or path scopes.
568
+ They reject configured diff or working-tree scopes before starting unless each
569
+ affected CSV row supplies its own path scope.
570
+
288
571
  Working-tree snapshots include files from untracked nested Git repositories.
289
572
  Initialized submodules must be clean and checked out at the commit recorded by
290
573
  the parent repository.
291
574
 
292
- Repeat `--knowledge-base PATH` for Markdown, text, PDF, or Word (`.docx`) files.
293
- Directories are searched recursively. Bulk scans share these documents with
294
- every repository.
575
+ Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including
576
+ JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,
577
+ skipping other binary files. Explicitly supplied unsupported binary files are rejected.
578
+ Bulk scans share these documents with every repository.
295
579
 
296
580
  Use an empty output directory outside the scanned directory and enclosing Git
297
581
  worktree. On macOS/Linux, existing directories must be private to you
@@ -303,6 +587,39 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
303
587
  `1` if a completed scan finds high or critical issues. Incomplete scans exit
304
588
  with `2`, writing available results to stdout and a coverage warning to stderr.
305
589
 
590
+ ### Import findings as a saved scan
591
+
592
+ Import an existing findings CSV or JSON file into local scan history and SQLite:
593
+
594
+ ```bash
595
+ codex-security scan import --csv /path/to/findings.csv
596
+ codex-security scan import --json /path/to/findings.json --format json
597
+ codex-security scan import --csv /path/to/findings.csv --dry-run
598
+ ```
599
+
600
+ Supply exactly one of `--csv PATH` or `--json PATH`. CSV uses the existing
601
+ [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv),
602
+ including the optional `candidate_id` column. JSON accepts a complete
603
+ `codex-security.findings` document or `{ "findings": [...] }`, with each finding
604
+ matching the existing findings schema. On `scan import`, `--json` selects the
605
+ input file; use `--format json` for JSON output. Other commands retain their
606
+ existing `--json` output flag. The selected input must be a regular file, and its
607
+ path must not traverse symbolic links or directory junctions. Use the direct
608
+ filesystem path when the file or a parent directory is linked.
609
+
610
+ Each import creates one completed scan using the configured
611
+ `CODEX_SECURITY_STATE_DIR`. The target is a retained copy of the input dataset,
612
+ independent of the current repository. Every source occurrence remains a separate
613
+ finding, including duplicate reports. Original identifiers are preserved in
614
+ `extensions.import`; the original file is sealed under `artifacts/import/`.
615
+ JSON writeup paths are retained as source metadata without reading external files.
616
+
617
+ Completion means the import finished. Coverage is unknown and the report states
618
+ that no security analysis was performed. Importing requires no model calls or
619
+ authentication. `--dry-run` validates without saving a scan. `--output-dir` and
620
+ `--archive-existing` control saved output, and `scans rerun SCAN_ID` reimports the
621
+ retained input.
622
+
306
623
  ### Generate mock scan results
307
624
 
308
625
  Use `--mock` to populate a Standard scan with synthetic test data in seconds,
@@ -365,7 +682,7 @@ runtime or plugin compatibility. Older versions may omit the ID.
365
682
  ### Scan project components
366
683
 
367
684
  `scan --path` runs one scan across selected paths. To scan each local project
368
- component separately in standard mode, use `scan-components`:
685
+ component separately (standard mode by default), use `scan-components`:
369
686
 
370
687
  ```bash
371
688
  npx @openai/codex-security scan-components /path/to/project \
@@ -373,6 +690,12 @@ npx @openai/codex-security scan-components /path/to/project \
373
690
  --workers 4 --output-dir /path/outside/project/results
374
691
  ```
375
692
 
693
+ Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
694
+ files, per-scan deep workers, cost limits, and severity policy. Component plans
695
+ override the file's scope. `output.directory` supplies the results directory when
696
+ `--output-dir` is omitted. A configured severity threshold returns exit `1` after
697
+ completed scans; failures or incomplete results return `2`.
698
+
376
699
  Use `--auto` instead of `--component` for a proposed split. Save a plan to
377
700
  review or edit, then run it with a new output directory:
378
701
 
@@ -384,6 +707,14 @@ npx @openai/codex-security scan-components /path/to/project \
384
707
  --output-dir /path/outside/project/results
385
708
  ```
386
709
 
710
+ For large repositories, automatic planning splits inventories into separate calls
711
+ that fit Codex's input character limit. It preserves directory boundaries where
712
+ possible and subdivides oversized packages and flat directories as needed. Each
713
+ call uses a fresh context and can select only paths within its batch. Omitted
714
+ files are retained in `Other files` components within those same boundaries.
715
+ Large repositories can therefore require more planning calls and produce more
716
+ components. Review or edit the saved plan before scanning with `--components-file`.
717
+
387
718
  Components use repository-relative paths:
388
719
 
389
720
  ```json
@@ -441,6 +772,7 @@ await security.run("/path/to/repository", {
441
772
  workers: 2,
442
773
  subagents: 0,
443
774
  stopAfterNoNew: 3,
775
+ stopAfterConsecutiveErrors: 2,
444
776
  maxDiscoveryRuns: 10,
445
777
  maxTimeHours: 1.5,
446
778
  });
@@ -458,8 +790,10 @@ max_discovery_runs = 40
458
790
  max_time_hours = 96
459
791
  ```
460
792
 
461
- CLI and SDK options override these defaults. Set `stop_after_consecutive_errors`
462
- in the file; `--codex` cannot configure this section. Worker and run counts must
793
+ CLI and SDK options override these defaults. Project files can use
794
+ `scan.deep.stop_after_consecutive_errors`, and SDK calls can use
795
+ `stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
796
+ configure this section. Worker and run counts must
463
797
  be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
464
798
  four workers. Unknown keys are rejected.
465
799
 
@@ -469,6 +803,12 @@ At the deadline, discovery stops; the scan combines and returns completed findin
469
803
  `scan --workers` controls discovery workers within one deep scan;
470
804
  `bulk-scan --workers` controls how many repositories are scanned concurrently.
471
805
 
806
+ The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
807
+ `subagents` setting. A valid deep block can remain inactive in standard mode;
808
+ explicit deep CLI options require deep mode. All six active values are resolved
809
+ before runtime preparation and saved in new recipes. Complete saved values are
810
+ independent of later changes to the legacy TOML file.
811
+
472
812
  ### Runtime configuration and worker limits
473
813
 
474
814
  Scans use these isolated Codex defaults instead of your user or repository
@@ -480,7 +820,7 @@ approvals_reviewer = "auto_review"
480
820
  cli_auth_credentials_store = "auto"
481
821
  model = "gpt-5.6-sol"
482
822
  model_reasoning_effort = "xhigh"
483
- model_reasoning_summary = "detailed"
823
+ model_reasoning_summary = "detailed" # "none" for amazon-bedrock
484
824
  show_raw_agent_reasoning = true
485
825
 
486
826
  [features]
@@ -519,7 +859,7 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
519
859
  stay enabled: `agents.max_threads` and
520
860
  `features.multi_agent_v2.enabled=false` are rejected.
521
861
 
522
- `validate`, `patch`, and `verify-fix` accept `--effort` and the `model`,
862
+ `validate`, `patch`, and `verify-fix` accept `--auth`, `--effort`, and the `model`,
523
863
  `model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
524
864
  other runtime overrides.
525
865
 
@@ -536,9 +876,12 @@ The same setting works for `scan` and `bulk-scan`. An explicit setting is
536
876
  preserved when `scan --patch` starts remediation and when
537
877
  `patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
538
878
  is also accepted; omitting the setting preserves the command's existing
539
- configuration and Codex defaults. Validation continues to ignore user
540
- configuration, while patching and verification retain their existing ambient
541
- configuration and project-trust behavior.
879
+ configuration and Codex defaults. Validation ignores user configuration.
880
+ For stored OpenAI credentials, patching and verification read configuration
881
+ from the shared credential home. API-key commands and custom providers that use their own credentials retain
882
+ their ambient Codex configuration. Patching and verification preserve project trust from the
883
+ ambient home; explicit `--codex` settings apply to the command and its
884
+ patch-risk assessment.
542
885
 
543
886
  This setting does not control explicitly configured OpenTelemetry log or trace
544
887
  exporters, authentication, integrations, or CLI update checks.
@@ -548,23 +891,24 @@ restrictions.
548
891
 
549
892
  ### Environment variables
550
893
 
551
- | Variable | Effect |
552
- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
553
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
554
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
555
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
556
- | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
557
- | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
558
- | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
559
- | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
560
- | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
561
- | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
562
- | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
563
- | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
564
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
565
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
566
- | `CI` | Disables interactive update notices. |
567
- | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
894
+ | Variable | Effect |
895
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
896
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
897
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
898
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
899
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
900
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
901
+ | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
902
+ | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
903
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
904
+ | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
905
+ | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
906
+ | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
907
+ | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
908
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
909
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
910
+ | `CI` | Disables interactive update notices. |
911
+ | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
568
912
 
569
913
  Custom Codex executables need thread source attribution for `exec` and
570
914
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -582,10 +926,40 @@ Interactive scans show full-screen progress; CI, redirected output, and
582
926
  diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for
583
927
  sensitive information before sharing them.
584
928
 
585
- JSON results, scan history, and bulk-scan receipts record the model, tokens,
586
- and estimated cost. Estimates use
587
- [standard API token prices](https://developers.openai.com/api/docs/models/compare),
588
- including cached input and cache writes, but exclude fees and surcharges.
929
+ The token summary shows uncached input, cache reads, cache writes, output,
930
+ and total tokens. Total tokens include all input plus output; cache reads and
931
+ writes are subsets of input, not extra tokens. When cache-write usage is missing,
932
+ the summary shows uncached input and cache writes as unavailable.
933
+ The final summary preserves missing-data information from a matching session log.
934
+ If the Codex runtime converts an omitted count to zero before recording it, the
935
+ CLI cannot distinguish that zero from reported usage.
936
+
937
+ Cost displays show a range using
938
+ [standard API prices](https://developers.openai.com/api/docs/pricing), because
939
+ runtime usage does not identify which requests received long-context pricing.
940
+ The minimum assumes short-context pricing; the maximum assumes long-context
941
+ pricing. These are token-cost estimates for the observed usage, excluding other
942
+ processing tiers, fees, surcharges, and account-specific pricing.
943
+
944
+ JSON results, scan history, and bulk-scan receipts preserve
945
+ `cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
946
+ means an upper estimate is unavailable, including models without verified
947
+ long-context rates. `cost.pricing` records the price source, verification date,
948
+ processing tier, short-context rates, and verified long-context rates when known.
949
+ Models without known short-context prices still have no cost estimate.
950
+
951
+ For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
952
+ `cacheWriteInputTokensReported: false` means at least one included usage record
953
+ did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
954
+ In that case, the range minimum prices unclassified input as ordinary input,
955
+ and the maximum allows it to be cache writes. Token counts remain unchanged.
956
+ Older saved records remain readable and display a labeled legacy estimate;
957
+ they are not repriced using current rates.
958
+
959
+ For compatibility, `cost.estimatedUsd` retains the short-context baseline used
960
+ by existing spending limits. `cost.pricing.context: "short"` describes that
961
+ baseline, not observed request contexts. Use `estimatedUsdRange` for cost
962
+ reporting. This change does not change when spending limits stop scans.
589
963
 
590
964
  `--max-cost USD` stops the scan and its workers when estimated cost exceeds
591
965
  the limit, though in-flight requests can finish above it. If deep-scan
@@ -642,13 +1016,55 @@ npx @openai/codex-security bulk-scan repositories.csv \
642
1016
 
643
1017
  `--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
644
1018
  repository's CSV `prompt` follows the shared instructions.
1019
+ `-c FILE` shares config with single scans: CSV mode/scope override file defaults,
1020
+ and deep settings apply only to deep rows. `output.directory` can supply the
1021
+ results directory. `fail_on_severity` returns exit `1` without retrying completed
1022
+ scans, including when resuming saved results. A changed project configuration
1023
+ requires a new campaign output directory.
645
1024
  `--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
646
1025
  even after a failed or incomplete scan, but not after cancellation or a
647
1026
  cost-limit stop.
648
1027
 
649
1028
  `--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending
650
- repository per invocation. Rerun the command to resume; `bulk-scan --help`
651
- lists all options.
1029
+ repository per invocation. Rerunning the command continues the campaign, skips
1030
+ completed results, and starts new attempts for pending repositories. If an
1031
+ attempt directory is occupied, that repository stops before replacing its
1032
+ checkout and the command recommends `--recover`.
1033
+
1034
+ #### Recovering failed or interrupted bulk scans
1035
+
1036
+ Use the original CSV, output directory, and campaign options with `--recover`:
1037
+
1038
+ ```bash
1039
+ npx @openai/codex-security bulk-scan repositories.csv \
1040
+ --output-dir /path/outside/repositories/security-scans --recover
1041
+ ```
1042
+
1043
+ Recovery requires an existing campaign with a matching manifest. It skips
1044
+ completed results, including partial coverage, and repositories never started.
1045
+ For each failed or interrupted repository, it checks the latest attempt:
1046
+
1047
+ - A sealed scan is recorded in `results.jsonl` without scanning again.
1048
+ - An eligible running Deep Scan resumes its original session, keeping its scan
1049
+ ID, completed workers, artifacts, saved settings, and accumulated cost.
1050
+ - A failed, canceled, or otherwise unavailable scan starts a new attempt at the
1051
+ CSV's pinned revision. Attempt numbers account for both receipts and existing
1052
+ directories. Old artifacts and checkouts are preserved; new attempts use
1053
+ `recovery-checkouts/<id>/attempt-<n>`.
1054
+
1055
+ `--workers` still defaults to `4`; `--max-attempts` defaults to one recovery or
1056
+ new attempt per repository. A resume connection failure stops that repository
1057
+ for this invocation instead of starting another scan. Other repositories
1058
+ continue. Failed and interrupted recovery checkouts remain available for a later
1059
+ `--recover`; fresh completed checkouts are removed after recording the result.
1060
+ If a reboot interrupted a receipt write, its unfinished tail is saved beside
1061
+ `results.jsonl` as `results.jsonl.interrupted-<id>` before appending valid records.
1062
+
1063
+ Same-scan resume requires the original checkout, session logs, and Codex Security
1064
+ state directory. Recovery does not reconstruct deleted checkpoints or fix the
1065
+ underlying cause of execution failures. New attempts incur new scan costs.
1066
+ Any remaining failures or partial coverage keep exit code `2`.
1067
+ `bulk-scan --help` lists all options.
652
1068
 
653
1069
  ### Custom validation
654
1070
 
@@ -659,7 +1075,8 @@ file. Source review still runs; discovery workers do not receive this prompt.
659
1075
  npx @openai/codex-security scan . --validation-prompt-file validation.md
660
1076
  ```
661
1077
 
662
- The SDK accepts the same text as `validationPrompt`:
1078
+ The SDK accepts the same file as `validationPromptFile`, or inline text as
1079
+ `validationPrompt`:
663
1080
 
664
1081
  ```ts
665
1082
  const result = await security.run(repository, {
@@ -873,7 +1290,7 @@ Omitting `--rubric` inherits each finding's existing severity without a model ca
873
1290
 
874
1291
  `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
875
1292
  to provide supporting architecture, deployment, or business context. Both accept
876
- the same Markdown, text, PDF, DOCX, and directory inputs as scan knowledge bases.
1293
+ the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
877
1294
  Rubric classification uses the full supplied report and context in a separate
878
1295
  read-only Codex turn per finding, without source inspection, tools, or new
879
1296
  validation. `--model` and `--effort` select the classification model and reasoning
@@ -988,16 +1405,60 @@ once before they can be reused.
988
1405
  Pass `signal` to cancel any classification operation. Keep human overrides in the
989
1406
  calling workflow or issue tracker; assessments remain separate recommendations.
990
1407
 
1408
+ ### Feedback
1409
+
1410
+ Send a problem report to OpenAI and share the returned feedback ID with support:
1411
+
1412
+ ```sh
1413
+ codex-security feedback --reason "The scan stopped before it finished"
1414
+ codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
1415
+ ```
1416
+
1417
+ Without an ID, `feedback` selects the most recently started scan in the current
1418
+ repository, including active or failed scans. If there are no saved scans, it sends
1419
+ a general report. The report includes your description, version details, and the selected
1420
+ scan and session IDs. Add `--json` for structured output.
1421
+
1422
+ Logs are off by default. `--include-logs` uploads Codex diagnostics and saved scan
1423
+ and worker activity. These can contain source code, prompts, findings, tool
1424
+ output, and other sensitive data. Only include logs you can share with OpenAI.
1425
+ The command uses Codex's feedback service and respects `feedback.enabled = false`.
1426
+
1427
+ For scans started through the Desktop plugin, run the command on the machine
1428
+ where the scan ran, using the same Codex home and Codex Security state directory.
1429
+ It searches active and archived sessions in both that Codex home and the CLI's
1430
+ managed home, and attaches available worker logs even if the parent log is missing.
1431
+ Earlier retries that started separate sessions may be missing when their session
1432
+ IDs are no longer recorded.
1433
+
1434
+ Standard scans run inside an existing Codex conversation attach only the owner's
1435
+ saved session; they do not record which subagents belong to the scan. Deep Scans
1436
+ and scans launched by `codex-security` also attach their recorded execution
1437
+ threads and descendants, without following unrelated children of the owner.
1438
+
991
1439
  ### Scan history and reruns
992
1440
 
993
1441
  Commands default to the current repository. Select scans by full ID or a
994
1442
  unique prefix of at least eight characters.
995
1443
 
1444
+ New recipes retain resolved settings and the authentication choice, not
1445
+ credentials. Reruns do not reload project files; complete saved deep settings do
1446
+ not use current legacy defaults. Older partial recipes retain their previous
1447
+ fallback behavior. Context paths and the current checkout are not immutable input
1448
+ snapshots.
1449
+
1450
+ Reruns require replacement scan instructions when the original scan used them.
1451
+ New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
1452
+ `scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
1453
+ Replacement files resolve from the invocation directory. Custom validation keeps its existing
1454
+ `scans rerun --validation-prompt-file` requirement.
1455
+
996
1456
  | Command | Purpose |
997
1457
  | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
998
1458
  | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
999
1459
  | `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |
1000
1460
  | `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |
1461
+ | `scans resume SCAN_ID` | Resume an interrupted Deep Scan in its original session and output directory. |
1001
1462
  | `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |
1002
1463
  | `scans match BEFORE AFTER` | Link findings with the same root cause. |
1003
1464
  | `scans match --all` | Match completed scans across the repository's worktrees and clones. |
@@ -1005,6 +1466,45 @@ unique prefix of at least eight characters.
1005
1466
  | `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |
1006
1467
  | `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |
1007
1468
 
1469
+ #### Resuming an interrupted Deep Scan
1470
+
1471
+ After the CLI process or host stops unexpectedly, find the scan and rejoin it:
1472
+
1473
+ ```bash
1474
+ npx @openai/codex-security scans list --scan-root /path/to/security-scans
1475
+ npx @openai/codex-security scans resume SCAN_ID
1476
+ ```
1477
+
1478
+ The scan must still be `running`, with its original checkout, output directory,
1479
+ and owning Codex session available in the same Codex Security state directory.
1480
+ The checkout's identity, revision, and contents must match the saved target.
1481
+ Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
1482
+
1483
+ Resume uses the saved configuration and instructions with the installed plugin.
1484
+ New scans save the selected authentication mode, explicit safety identifier, and
1485
+ post-scan prompt contents. Resume restores the authentication choice without
1486
+ saving credentials. Single-scan resume restores the prompt even if its original
1487
+ file changes or disappears.
1488
+ Older records that did not save these values cannot reconstruct them. Bulk
1489
+ recovery still requires matching campaign inputs and options; it uses the supplied
1490
+ post-scan prompt when the scan has no saved prompt.
1491
+ It keeps the scan ID, completed workers, artifacts, and accumulated session cost.
1492
+ The existing coordinator recovers interrupted workers after its lease expires.
1493
+ If discovery finished before the interruption, resume completes and seals the
1494
+ same scan. No archiving or new attempt directory is needed. A failed connection
1495
+ leaves the existing scan available for another resume attempt.
1496
+
1497
+ Compatible saved scans can resume after a plugin update. Already-sealed results
1498
+ keep their original producer version and contents when completion is recorded.
1499
+ Unsupported or invalid sealed artifacts are rejected before resuming, preserving
1500
+ the saved scan state and files.
1501
+
1502
+ For bulk campaigns, use [`bulk-scan --recover`](#recovering-failed-or-interrupted-bulk-scans)
1503
+ to recover eligible attempts and update `results.jsonl`. Individual `scans resume`
1504
+ does not update campaign receipts.
1505
+
1506
+ #### Matching saved scans
1507
+
1008
1508
  Matching requires sealed artifacts and reuses saved matches unless you pass
1009
1509
  `--force`. Comparisons classify findings as new, persisting, reopened, resolved,
1010
1510
  or unknown. Missing findings aren't resolved if the later scan is incomplete
@@ -1140,11 +1640,31 @@ npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
1140
1640
  npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
1141
1641
  ```
1142
1642
 
1143
- `--scan latest` selects the current repository's latest scan. Saved-finding
1144
- patch commands support `--json`; literal-text and file inputs don't. Change
1643
+ `--scan latest` selects the current repository's latest scan. Patch commands
1644
+ support `--json`, including literal-text and file inputs. Change
1145
1645
  the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
1146
1646
  Each finding gets its own saved Codex desktop task.
1147
1647
 
1648
+ Before patching, the CLI runs a command with the task's sandbox policy. If the
1649
+ sandbox cannot start, the command exits with a nonzero status and reports
1650
+ `SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
1651
+ with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
1652
+ `filesChanged`, and `files`; existing local changes do not count as patch changes.
1653
+ These fields report file changes, not proof that the security issue is fixed.
1654
+ Saved findings still require a verified result from the patch task.
1655
+
1656
+ For a controlled container that provides its own isolation, explicitly opt in:
1657
+
1658
+ ```bash
1659
+ npx @openai/codex-security patch "Security issue" --external-sandbox --json
1660
+ ```
1661
+
1662
+ `--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
1663
+ and prints a warning: Codex does not enforce filesystem or network isolation for
1664
+ the patch task. The container must enforce those boundaries. The CLI never
1665
+ falls back to this mode automatically. Optional patch-risk assessment still uses
1666
+ its read-only Codex sandbox.
1667
+
1148
1668
  `scan --patch` patches after a complete scan. `--patch-severity` defaults to
1149
1669
  `low`; `high` selects high and critical findings. Use the interactive browser
1150
1670
  to select findings and add patch instructions. Results include a `patches`
@@ -1231,7 +1751,9 @@ checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
1231
1751
  defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
1232
1752
  version, `sha-<commit>` tag, or digest for repeatable deployments.
1233
1753
 
1234
- To build from a source checkout instead:
1754
+ To build from a source checkout, first prepare the
1755
+ [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
1756
+ for that checkout. Then run from the repository root:
1235
1757
 
1236
1758
  ```bash
1237
1759
  docker build --target scanner -t codex-security:local .
@@ -1402,14 +1924,32 @@ change scan artifacts.
1402
1924
  codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
1403
1925
  ```
1404
1926
 
1927
+ Deduplication runs up to 8 jobs concurrently by default. Set `--concurrency N`
1928
+ to choose a positive integer, or `--concurrency 1` for serial execution. The SDK
1929
+ equivalent is `concurrency: N`. Candidate neighborhoods are fetched first, with
1930
+ the same concurrency limit. Luna screenings and ready Sol pair reviews then use
1931
+ two queues sharing one worker pool, with at most 8 jobs running in total by
1932
+ default. Each available worker takes a ready job as soon as its current job
1933
+ finishes; it does not wait for a batch to finish.
1934
+
1935
+ A Sol pair review becomes ready once every Luna screening covering that pair
1936
+ has finished and none voted `DISTINCT`. It can run while unrelated Luna
1937
+ screenings continue. Results are combined in input order so completion timing
1938
+ does not change the groups.
1939
+
1940
+ If a job fails after its retries, queued jobs stop and already running jobs
1941
+ finish before the command reports the failure. No groups are posted from an
1942
+ incomplete review. To retain completed reviews across runs, use a
1943
+ `--workflow-id` as described below.
1944
+
1405
1945
  The default scope is the saved scan's repository, identified by
1406
1946
  `scan.target.targetId` in its manifest. Add `--all-repositories` to search the
1407
1947
  entire stored corpus explicitly; the flag defaults to false. The SDK has the
1408
1948
  equivalent optional `allRepositories: true` setting. This narrows the previous
1409
1949
  preview's implicit all-repository behavior.
1410
1950
 
1411
- Both `--scan` and `--findings-url` are required, with no implicit scan or service
1412
- URL. As with `publish scan --scan`, the selector accepts a full ID, unique
1951
+ Provide `--findings-url` and either `--scan` or `--workflow-id`, with no implicit
1952
+ scan or service URL. As with `publish scan --scan`, the scan selector accepts a full ID, unique
1413
1953
  prefix, or `latest` for the current repository. The saved scan must be complete
1414
1954
  and its sealed artifacts must be available.
1415
1955
 
@@ -1418,6 +1958,7 @@ import { deduplicateScan } from "@openai/codex-security";
1418
1958
 
1419
1959
  const result = await deduplicateScan("scan_example_001", {
1420
1960
  findingsUrl: "http://127.0.0.1:3000",
1961
+ // concurrency: 8, // Shared worker limit for Luna and Sol; use 1 for serial.
1421
1962
  // allRepositories: true, // Omit to search only this scan's repository.
1422
1963
  // signal: controller.signal,
1423
1964
  });
@@ -1433,6 +1974,7 @@ import { deduplicateScanDirectory } from "@openai/codex-security";
1433
1974
  const result = await deduplicateScanDirectory("/path/to/completed-scan", {
1434
1975
  repository: "/path/to/repository",
1435
1976
  findingsUrl: "http://127.0.0.1:3000",
1977
+ // concurrency: 8,
1436
1978
  // expectedScanId: "scan_example_001",
1437
1979
  // allRepositories: true,
1438
1980
  // signal: controller.signal,
@@ -1515,8 +2057,9 @@ scan. Existing output-directory and archive safeguards still apply to scan retri
1515
2057
 
1516
2058
  Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
1517
2059
  scan selector must identify that same scan. A workflow can also begin at custom
1518
- publication of a completed scan. Dedupe still requires local scan history to locate
1519
- the approved source checkout. For a workflow, dedupe first completes publication
2060
+ publication of a completed scan. The CLI and `deduplicateScan` require local scan
2061
+ history to locate the approved source checkout; `deduplicateScanDirectory` uses
2062
+ the supplied repository. For a workflow, dedupe first completes publication
1520
2063
  if its receipt is missing. `--all-repositories` retains its existing default of
1521
2064
  false. Changing a workflow's scan, destination, or bound scope is an error: choose
1522
2065
  a different workflow ID. Use one coordinating process per workflow.
@@ -1536,6 +2079,12 @@ A completed `dedupe --workflow-id` returns its saved result without repeating
1536
2079
  reviews or group writes. A publication whose acknowledgement was lost is retried
1537
2080
  using the service's existing idempotent upsert.
1538
2081
 
2082
+ Concurrent jobs save their validated reviews independently. Resuming with the
2083
+ same workflow ID reuses completed reviews and retries unfinished jobs. The
2084
+ concurrency setting is not part of a review's checkpoint identity, so it is safe
2085
+ to change `--concurrency` when resuming. Cancellation stops active reviews and
2086
+ leaves their completed checkpoints available for the next run.
2087
+
1539
2088
  Each validated screening and pair review is checkpointed locally,
1540
2089
  including DISTINCT decisions. Screening checkpoints retain pair recommendations
1541
2090
  and rationales under host-assigned pair slots bound to the original records.
@@ -1545,8 +2094,17 @@ must satisfy the Finding schema and preserve the canonical finding ID. Validatio
1545
2094
  still happens through `review_validator.submit_decisions`; invalid submissions
1546
2095
  are corrected in the same review conversation. A completed turn without an
1547
2096
  accepted submission receives one corrective turn in that same conversation.
1548
- Transport, model, cancellation, and accepted `submit_error` failures are terminal.
1549
- Invalid or unfinished reviews are not cached.
2097
+ If formatting remains invalid, the job retries in a fresh review session.
2098
+ Explicit transient Codex failures and unexpected process exits also retry, with
2099
+ at most three fresh sessions per review. Transient findings-service failures, including
2100
+ rate limits and network errors, receive up to three request attempts. Retries use
2101
+ exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to retry
2102
+ occupies the job's concurrency slot.
2103
+
2104
+ Cancellation, authentication or configuration errors, permanent HTTP errors, and
2105
+ required-source-access blockers are not retried. Exhausted retries fail deduplication;
2106
+ invalid or unfinished reviews are not cached. Completed checkpoints remain
2107
+ available when the workflow resumes.
1550
2108
 
1551
2109
  Checkpoints bind to the exact original records and ordering, approved source path,
1552
2110
  Git revision and current file contents (including ignored files), repository scope,
@@ -1570,12 +2128,15 @@ use another workflow ID for a fresh review rather than changing that saved resul
1570
2128
  1. For each distinct finding ID in the scan, request
1571
2129
  `/v1/finding/{id}/potential-duplicates` with the selected repository or
1572
2130
  explicit all-repository scope. Use the complete stored anchor and
1573
- candidates returned by that request.
2131
+ candidates returned by that request. Fetch all neighborhoods before starting
2132
+ reviews so every pair's screening dependencies are known.
1574
2133
  2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1575
2134
  effort. The review covers every anchor-neighbor pair; nominations between
1576
2135
  neighbors are rejected.
1577
2136
  3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
1578
- reasoning effort. Only accepted pairs contribute to duplicate groups.
2137
+ reasoning effort after all Luna screenings covering that pair finish without
2138
+ a `DISTINCT` decision. Luna and ready Sol jobs share the configured worker
2139
+ pool and can run together. Only accepted pairs contribute to duplicate groups.
1579
2140
  4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
1580
2141
  decision contradicts the resulting component. Contradicted components are
1581
2142
  split deterministically, preferring legal subgroups that preserve more
@@ -1778,7 +2339,9 @@ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
1778
2339
  Startup and listing need no key. The service does not load `.env` or authenticate
1779
2340
  requests; keep it on loopback or behind an authenticated TLS proxy.
1780
2341
 
1781
- From a source checkout's `sdk/typescript` directory:
2342
+ For a source build, first prepare the
2343
+ [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
2344
+ for that checkout. Then run from its `sdk/typescript` directory:
1782
2345
 
1783
2346
  ```bash
1784
2347
  pnpm install --frozen-lockfile