@openai/codex-security 0.1.26 → 0.1.27

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 (138) hide show
  1. package/README.md +398 -30
  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/config-preflight.md +2 -0
  22. package/_bundled_plugin/references/core-scan.md +1 -1
  23. package/_bundled_plugin/references/scan-contract.md +35 -35
  24. package/_bundled_plugin/references/security-guidance.md +7 -1
  25. package/_bundled_plugin/scripts/generate_in_scope_files.py +2 -2
  26. package/_bundled_plugin/scripts/generate_rank_input.py +8 -1
  27. package/_bundled_plugin/scripts/launch_codex_security_mcp +6 -0
  28. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +43 -9
  29. package/_bundled_plugin/scripts/rank_preview.py +4 -1
  30. package/_bundled_plugin/scripts/workbench_cli.py +4 -0
  31. package/_bundled_plugin/scripts/workbench_db.py +33 -29
  32. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -2
  33. package/_bundled_plugin/scripts/workbench_validation.py +4 -0
  34. package/_bundled_plugin/skills/define-security-policy/SKILL.md +3 -3
  35. package/dist/api.d.ts +7 -1
  36. package/dist/api.d.ts.map +1 -1
  37. package/dist/api.js +481 -60
  38. package/dist/api.js.map +1 -1
  39. package/dist/auth.js +10 -0
  40. package/dist/auth.js.map +1 -1
  41. package/dist/cli.d.ts +18 -2
  42. package/dist/cli.d.ts.map +1 -1
  43. package/dist/cli.js +962 -276
  44. package/dist/cli.js.map +1 -1
  45. package/dist/cloud-publish.d.ts.map +1 -1
  46. package/dist/cloud-publish.js +2 -207
  47. package/dist/cloud-publish.js.map +1 -1
  48. package/dist/component-plan.d.ts.map +1 -1
  49. package/dist/component-plan.js +116 -32
  50. package/dist/component-plan.js.map +1 -1
  51. package/dist/config.d.ts +1 -0
  52. package/dist/config.d.ts.map +1 -1
  53. package/dist/config.js +17 -2
  54. package/dist/config.js.map +1 -1
  55. package/dist/contract.d.ts +5 -10
  56. package/dist/contract.d.ts.map +1 -1
  57. package/dist/contract.js.map +1 -1
  58. package/dist/cost-model.d.ts +16 -0
  59. package/dist/cost-model.d.ts.map +1 -1
  60. package/dist/cost-model.js +57 -3
  61. package/dist/cost-model.js.map +1 -1
  62. package/dist/cost.d.ts.map +1 -1
  63. package/dist/cost.js +18 -3
  64. package/dist/cost.js.map +1 -1
  65. package/dist/custom-validation-prompt.js +1 -1
  66. package/dist/custom-validation-prompt.js.map +1 -1
  67. package/dist/deduplication/codex-review.d.ts +6 -1
  68. package/dist/deduplication/codex-review.d.ts.map +1 -1
  69. package/dist/deduplication/codex-review.js +72 -17
  70. package/dist/deduplication/codex-review.js.map +1 -1
  71. package/dist/deduplication/deduplication.d.ts +2 -0
  72. package/dist/deduplication/deduplication.d.ts.map +1 -1
  73. package/dist/deduplication/deduplication.js +99 -26
  74. package/dist/deduplication/deduplication.js.map +1 -1
  75. package/dist/deduplication/retry.d.ts +3 -0
  76. package/dist/deduplication/retry.d.ts.map +1 -0
  77. package/dist/deduplication/retry.js +15 -0
  78. package/dist/deduplication/retry.js.map +1 -0
  79. package/dist/deduplication/scan.d.ts +2 -0
  80. package/dist/deduplication/scan.d.ts.map +1 -1
  81. package/dist/deduplication/scan.js +4 -2
  82. package/dist/deduplication/scan.js.map +1 -1
  83. package/dist/feedback.d.ts +20 -0
  84. package/dist/feedback.d.ts.map +1 -0
  85. package/dist/feedback.js +121 -0
  86. package/dist/feedback.js.map +1 -0
  87. package/dist/findings-client.d.ts +7 -1
  88. package/dist/findings-client.d.ts.map +1 -1
  89. package/dist/findings-client.js +55 -10
  90. package/dist/findings-client.js.map +1 -1
  91. package/dist/findings-import.d.ts +44 -0
  92. package/dist/findings-import.d.ts.map +1 -0
  93. package/dist/findings-import.js +302 -0
  94. package/dist/findings-import.js.map +1 -0
  95. package/dist/import-scan.d.ts +27 -0
  96. package/dist/import-scan.d.ts.map +1 -0
  97. package/dist/import-scan.js +236 -0
  98. package/dist/import-scan.js.map +1 -0
  99. package/dist/index.d.ts +2 -0
  100. package/dist/index.d.ts.map +1 -1
  101. package/dist/index.js +1 -0
  102. package/dist/index.js.map +1 -1
  103. package/dist/knowledge-base.d.ts +1 -1
  104. package/dist/knowledge-base.d.ts.map +1 -1
  105. package/dist/knowledge-base.js +2 -2
  106. package/dist/knowledge-base.js.map +1 -1
  107. package/dist/multiscan.d.ts +2 -0
  108. package/dist/multiscan.d.ts.map +1 -1
  109. package/dist/multiscan.js +144 -52
  110. package/dist/multiscan.js.map +1 -1
  111. package/dist/publication-events.d.ts.map +1 -1
  112. package/dist/publication-events.js +7 -2
  113. package/dist/publication-events.js.map +1 -1
  114. package/dist/runtime.d.ts +5 -1
  115. package/dist/runtime.d.ts.map +1 -1
  116. package/dist/runtime.js +8 -2
  117. package/dist/runtime.js.map +1 -1
  118. package/dist/scan-dashboard.d.ts.map +1 -1
  119. package/dist/scan-dashboard.js +19 -6
  120. package/dist/scan-dashboard.js.map +1 -1
  121. package/dist/scan-logs.d.ts +29 -0
  122. package/dist/scan-logs.d.ts.map +1 -1
  123. package/dist/scan-logs.js +36 -5
  124. package/dist/scan-logs.js.map +1 -1
  125. package/dist/security-policy-cli.d.ts +39 -0
  126. package/dist/security-policy-cli.d.ts.map +1 -0
  127. package/dist/security-policy-cli.js +193 -0
  128. package/dist/security-policy-cli.js.map +1 -0
  129. package/dist/security-policy.d.ts +80 -0
  130. package/dist/security-policy.d.ts.map +1 -0
  131. package/dist/security-policy.js +672 -0
  132. package/dist/security-policy.js.map +1 -0
  133. package/dist/targets.d.ts +8 -1
  134. package/dist/targets.d.ts.map +1 -1
  135. package/dist/targets.js +243 -14
  136. package/dist/targets.js.map +1 -1
  137. package/package.json +8 -4
  138. 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
@@ -186,7 +186,7 @@ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin
186
186
  printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
187
187
  ```
188
188
 
189
- Environment API keys apply to the current scan; only `login --with-api-key`
189
+ Environment API keys apply to the current command; only `login --with-api-key`
190
190
  saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
191
191
  Access-token environment variables are not scan API keys.
192
192
 
@@ -219,6 +219,15 @@ credentials, and the default AWS credential chain. Set `AWS_REGION` and choose
219
219
  a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`
220
220
  support `--max-cost`.
221
221
 
222
+ Bedrock scans, including Deep Scan workers, default to
223
+ `model_reasoning_summary = "none"` because some Bedrock models reject
224
+ `reasoning.summary`. This leaves reasoning effort unchanged. Explicit summary
225
+ settings in `--codex` overrides or the selected Codex profile take precedence.
226
+ For standard scans on older CLI versions, append
227
+ `--codex 'model_reasoning_summary="none"'` to your scan command if Bedrock
228
+ reports that `reasoning.summary` is unsupported. Deep scans require a CLI
229
+ version that forwards this setting to workers.
230
+
222
231
  On Windows, set the API key in PowerShell:
223
232
 
224
233
  ```powershell
@@ -226,11 +235,23 @@ $env:OPENAI_API_KEY = "<your-api-key>"
226
235
  npx @openai/codex-security scan C:\code\repository
227
236
  ```
228
237
 
229
- Login, logout, and scans share a private credential home:
238
+ Login, logout, scans, validation, patching, and fix verification share a private
239
+ credential home for stored OpenAI credentials, including custom providers with
240
+ `requires_openai_auth = true`:
230
241
  `$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
242
+ `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this credential
243
+ home outside the target directory and every enclosing Git worktree, including
244
+ when running a command from a subdirectory. Codex carries
245
+ `cli_auth_credentials_store`, `forced_login_method`, and
246
+ `forced_chatgpt_workspace_id` from the ambient configuration into this home,
247
+ including removing settings that are no longer present in the ambient configuration.
248
+ Each command carries its selected provider into this home. Patching and fix
249
+ verification also synchronize the ambient home's project-trust decisions and
250
+ project-root markers, preserving which project configuration Codex loads.
251
+ They hold the credential-home lock until the app-server thread is ready,
252
+ then release it before model execution.
253
+ Managed-device policies still apply. If this home has no credentials, it imports
254
+ an existing file-based Codex sign-in. Logout disables
234
255
  imports until you log in again.
235
256
 
236
257
  Finish operations using older versions before upgrading. Runtime preparation
@@ -255,19 +276,167 @@ npx @openai/codex-security scan . --auth chatgpt
255
276
  npx @openai/codex-security scan . --auth api-key
256
277
  ```
257
278
 
279
+ `--auth` also works with `validate`, `patch`, and `verify-fix`. These commands
280
+ use the same stored login as `scan`, including a sign-in created with
281
+ `codex-security login --device-auth`:
282
+
283
+ ```bash
284
+ npx @openai/codex-security patch OCCURRENCE_ID --auth chatgpt
285
+ npx @openai/codex-security verify-fix OCCURRENCE_ID --auth api-key
286
+ ```
287
+
258
288
  `--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.
289
+ `OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; noninteractive
290
+ commands prefer `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
291
+ Patch follow-up assessment uses the same selection, and `scan --patch` keeps
292
+ the scan's choice. Environment API keys do not replace the saved login.
293
+ The SDK uses the same `auth` option on `run`, `validate`, and `preflight`.
294
+ Codex may still need ChatGPT credentials to load workspace-managed policies
295
+ when using an API key.
263
296
 
264
297
  Some cybersecurity requests and protected findings require Trusted Access for
265
298
  Cyber approval. Apply or check your access at
266
299
  [chatgpt.com/cyber](https://chatgpt.com/cyber).
267
300
 
301
+ ## Generate a security policy
302
+
303
+ `policy` drafts `SECURITY.md` guidance for future scans. It does not run a
304
+ vulnerability scan, change application settings, or install the draft in the
305
+ checkout. It uses the scan runtime and authentication, requesting read-only
306
+ access to the selected repository or component and required tools. Network access,
307
+ web search, apps, and MCP servers are disabled. Drafts stay outside the checkout.
308
+ The host resolves inherited guidance once and includes each checked descendant
309
+ policy separately. Descendant policy links must stay within the selected component.
310
+ Inherited and reporting-policy links may also resolve to ancestor `SECURITY.md`
311
+ files or the checkout's `.github/SECURITY.md` and `docs/SECURITY.md`.
312
+ The model cannot read sibling components or Git metadata. Policy turns deny
313
+ access to the resolved Git metadata and markers, including those inside the
314
+ selected source tree, nested bare repositories, and associated alternate object
315
+ stores.
316
+ Policy shell tools inherit only Codex's core environment; custom shell environment
317
+ settings, login shells, and shell snapshots are disabled for these turns.
318
+ Knowledge-base text stays with the private review artifacts during generation
319
+ and is removed afterward.
320
+
321
+ Known limitation: policy preflight and generation currently fail on Unix
322
+ directories with non-UTF-8 names.
323
+
324
+ On macOS, the pinned Codex runtime does not fully enforce write restrictions
325
+ under `/tmp` (including `/private/tmp`). Keep the repository and artifacts outside
326
+ that tree when read-only enforcement is required. See the
327
+ [upstream sandbox limitation](https://github.com/openai/codex/issues/32395).
328
+
329
+ ```bash
330
+ npx @openai/codex-security policy .
331
+ npx @openai/codex-security policy . --path services/api
332
+ npx @openai/codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high
333
+ npx @openai/codex-security policy . --dry-run --json
334
+ ```
335
+
336
+ The repository defaults to the current directory. `--path` selects a component,
337
+ which inherits policies from its Git root, with the closest policy taking
338
+ precedence. Linked worktrees and initialized submodules use their own roots.
339
+ Targets and policy links must stay in the selected checkout, outside Git
340
+ metadata; ancestor links cannot widen a component policy's scope.
341
+
342
+ For an intentional separate Git directory, set `core.worktree` to the checkout's
343
+ absolute path. Use `git worktree repair` for moved linked worktrees.
344
+
345
+ Generation uses three Codex stages: describe the system, build a threat model,
346
+ then draft the policy. The first two documents support review; they are not
347
+ additional approval steps or policies to install.
348
+ In a terminal, it asks about facts the source cannot establish and shows the
349
+ exact diff. If both ChatGPT and API-key credentials are available, it asks which
350
+ to use; `--auth chatgpt` or `--auth api-key` selects one explicitly.
351
+
352
+ | Invocation | Calls Codex? | Result |
353
+ | ---------------------------- | ------------ | ----------------------------------------------------------------------- |
354
+ | `policy .` | Yes | Ask owner questions, save documents, and preview the draft. |
355
+ | `policy . --headless --json` | Yes | Save documents without prompts and return their paths and review notes. |
356
+ | `policy . --format md` | Yes | Generate a draft and write its Markdown to stdout. |
357
+ | `policy . --dry-run --json` | No | Check local inputs and show the resolved target and settings. |
358
+
359
+ None of these commands installs `SECURITY.md` in the repository. Output formats
360
+ change presentation; they do not turn generation into a saved-draft read.
361
+
362
+ ### Review the draft
363
+
364
+ Review the saved `SECURITY.md` before copying it to the reported target. Check
365
+ links from `.github/SECURITY.md` or `docs/SECURITY.md`: copying can change their
366
+ guidance too. Preserve reporting instructions and obtain owner approval for
367
+ exclusions, accepted risks, and severity decisions. Later scans read this policy.
368
+
369
+ Generation and preview check for changes to the selected or inherited policies.
370
+ If governing guidance changes during generation, completed documents remain for
371
+ inspection, but no completed-draft manifest is written. Other source files are not
372
+ frozen; regenerate if relevant source or neighboring policies change.
373
+ A failed terminal preview reports a warning and the saved draft paths. Explicit
374
+ output formats return the draft directly without running a diff preview.
375
+
376
+ Use `--headless` or an explicit output format to skip questions. Unanswered
377
+ questions remain in the review notes. Drafts default to the Codex Security state
378
+ directory; `--output-dir` selects an empty directory outside every enclosing
379
+ Git checkout and its Git metadata.
380
+
381
+ ```bash
382
+ npx @openai/codex-security policy . --path services/api \
383
+ --headless --output-dir /path/outside/repository/api-policy --json
384
+ ```
385
+
386
+ The artifact directory contains:
387
+
388
+ | File | Purpose |
389
+ | ---------------------- | --------------------------------------------------------- |
390
+ | `SECURITY.md` | Editable policy draft. |
391
+ | `THREAT_MODEL.md` | Detailed threat model with source references. |
392
+ | `project-spec.md` | System description and security boundaries. |
393
+ | `previous-SECURITY.md` | Original policy used for the diff. |
394
+ | `policy-draft.json` | Target, policy hashes, revision, model, and review notes. |
395
+
396
+ Keep supporting documents private until reviewed for disclosure. A generated
397
+ threat scenario is neither owner approval nor a confirmed vulnerability.
398
+
399
+ `--format md` writes the draft to stdout. `--json` returns paths, review notes,
400
+ status, and estimated cost. Global filters and token options work with these
401
+ formats. Progress goes to stderr. `--full-output` reports failures with
402
+ `ok: false`. `--max-cost` applies to the whole generation. If a stage cannot
403
+ inspect required source evidence, generation stops and preserves completed
404
+ documents. Fix the reported problem and use a new output directory to retry.
405
+
406
+ ### Generate a policy from TypeScript
407
+
408
+ ```ts
409
+ import { CodexSecurity } from "@openai/codex-security";
410
+
411
+ const security = new CodexSecurity();
412
+ try {
413
+ const draft = await security.generatePolicy("/path/to/repository", {
414
+ path: "services/api",
415
+ knowledgeBasePaths: ["/path/to/architecture.md"],
416
+ onStage: (stage) => console.error(stage),
417
+ });
418
+
419
+ console.log(await security.previewPolicy(draft));
420
+ // Open draft.draftPath in an editor to review the saved policy.
421
+ } finally {
422
+ await security.close();
423
+ }
424
+ ```
425
+
426
+ `preflightPolicy()` checks local inputs without starting Codex.
427
+ `previewPolicy()` previews the supplied in-memory draft, uses the client's Python
428
+ setting, and makes terminal control characters visible. Editing the saved file
429
+ does not change that object. The standalone `securityPolicyDiff()` returns a raw diff
430
+ for files or other non-terminal uses; pass an interpreter explicitly if needed.
431
+ `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
432
+ `maxCostUsd`, `signal`, and progress and cost callbacks. An optional
433
+ `answerQuestions` callback receives each group of up to three owner questions
434
+ and a cancellation signal. Without it, the questions remain unresolved.
435
+
268
436
  ## CLI
269
437
 
270
438
  ```bash
439
+ npx @openai/codex-security policy . --path services/api
271
440
  npx @openai/codex-security scan .
272
441
  npx @openai/codex-security scan /path/to/repository --path src --path tests
273
442
  npx @openai/codex-security scan /path/to/repository --diff origin/main --json
@@ -303,6 +472,39 @@ Scans are report-only by default. Set `--fail-on-severity high` to exit with
303
472
  `1` if a completed scan finds high or critical issues. Incomplete scans exit
304
473
  with `2`, writing available results to stdout and a coverage warning to stderr.
305
474
 
475
+ ### Import findings as a saved scan
476
+
477
+ Import an existing findings CSV or JSON file into local scan history and SQLite:
478
+
479
+ ```bash
480
+ codex-security scan import --csv /path/to/findings.csv
481
+ codex-security scan import --json /path/to/findings.json --format json
482
+ codex-security scan import --csv /path/to/findings.csv --dry-run
483
+ ```
484
+
485
+ Supply exactly one of `--csv PATH` or `--json PATH`. CSV uses the existing
486
+ [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv),
487
+ including the optional `candidate_id` column. JSON accepts a complete
488
+ `codex-security.findings` document or `{ "findings": [...] }`, with each finding
489
+ matching the existing findings schema. On `scan import`, `--json` selects the
490
+ input file; use `--format json` for JSON output. Other commands retain their
491
+ existing `--json` output flag. The selected input must be a regular file, and its
492
+ path must not traverse symbolic links or directory junctions. Use the direct
493
+ filesystem path when the file or a parent directory is linked.
494
+
495
+ Each import creates one completed scan using the configured
496
+ `CODEX_SECURITY_STATE_DIR`. The target is a retained copy of the input dataset,
497
+ independent of the current repository. Every source occurrence remains a separate
498
+ finding, including duplicate reports. Original identifiers are preserved in
499
+ `extensions.import`; the original file is sealed under `artifacts/import/`.
500
+ JSON writeup paths are retained as source metadata without reading external files.
501
+
502
+ Completion means the import finished. Coverage is unknown and the report states
503
+ that no security analysis was performed. Importing requires no model calls or
504
+ authentication. `--dry-run` validates without saving a scan. `--output-dir` and
505
+ `--archive-existing` control saved output, and `scans rerun SCAN_ID` reimports the
506
+ retained input.
507
+
306
508
  ### Generate mock scan results
307
509
 
308
510
  Use `--mock` to populate a Standard scan with synthetic test data in seconds,
@@ -384,6 +586,14 @@ npx @openai/codex-security scan-components /path/to/project \
384
586
  --output-dir /path/outside/project/results
385
587
  ```
386
588
 
589
+ For large repositories, automatic planning splits inventories into separate calls
590
+ that fit Codex's input character limit. It preserves directory boundaries where
591
+ possible and subdivides oversized packages and flat directories as needed. Each
592
+ call uses a fresh context and can select only paths within its batch. Omitted
593
+ files are retained in `Other files` components within those same boundaries.
594
+ Large repositories can therefore require more planning calls and produce more
595
+ components. Review or edit the saved plan before scanning with `--components-file`.
596
+
387
597
  Components use repository-relative paths:
388
598
 
389
599
  ```json
@@ -480,7 +690,7 @@ approvals_reviewer = "auto_review"
480
690
  cli_auth_credentials_store = "auto"
481
691
  model = "gpt-5.6-sol"
482
692
  model_reasoning_effort = "xhigh"
483
- model_reasoning_summary = "detailed"
693
+ model_reasoning_summary = "detailed" # "none" for amazon-bedrock
484
694
  show_raw_agent_reasoning = true
485
695
 
486
696
  [features]
@@ -519,7 +729,7 @@ or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
519
729
  stay enabled: `agents.max_threads` and
520
730
  `features.multi_agent_v2.enabled=false` are rejected.
521
731
 
522
- `validate`, `patch`, and `verify-fix` accept `--effort` and the `model`,
732
+ `validate`, `patch`, and `verify-fix` accept `--auth`, `--effort`, and the `model`,
523
733
  `model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
524
734
  other runtime overrides.
525
735
 
@@ -536,9 +746,12 @@ The same setting works for `scan` and `bulk-scan`. An explicit setting is
536
746
  preserved when `scan --patch` starts remediation and when
537
747
  `patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
538
748
  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.
749
+ configuration and Codex defaults. Validation ignores user configuration.
750
+ For stored OpenAI credentials, patching and verification read configuration
751
+ from the shared credential home. API-key commands and custom providers that use their own credentials retain
752
+ their ambient Codex configuration. Patching and verification preserve project trust from the
753
+ ambient home; explicit `--codex` settings apply to the command and its
754
+ patch-risk assessment.
542
755
 
543
756
  This setting does not control explicitly configured OpenTelemetry log or trace
544
757
  exporters, authentication, integrations, or CLI update checks.
@@ -582,10 +795,28 @@ Interactive scans show full-screen progress; CI, redirected output, and
582
795
  diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for
583
796
  sensitive information before sharing them.
584
797
 
798
+ The token summary shows uncached input, cache reads, cache writes, output,
799
+ and total tokens. Total tokens include all input plus output; cache reads and
800
+ writes are subsets of input, not extra tokens. When cache-write usage is missing,
801
+ the summary shows uncached input and cache writes as unavailable.
802
+ The final summary preserves missing-data information from a matching session log.
803
+ If the Codex runtime converts an omitted count to zero before recording it, the
804
+ CLI cannot distinguish that zero from reported usage.
805
+
585
806
  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.
807
+ estimated cost, and `cost.pricing`: the price source, verification date, processing
808
+ tier, context category, and rates in USD per million tokens. Estimates use
809
+ [standard, short-context API prices](https://developers.openai.com/api/docs/pricing),
810
+ including cache reads and writes. They exclude long-context and other processing
811
+ tier adjustments, fees, and surcharges. GPT-5.5 and GPT-6 Astra are supported;
812
+ models without known prices show an unavailable estimate.
813
+
814
+ For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
815
+ `cacheWriteInputTokensReported: false` means at least one included usage record
816
+ did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
817
+ In that case, the estimate prices unclassified input at the ordinary input rate;
818
+ it may undercount cache-write charges. Older saved records lack this distinction
819
+ and the saved pricing basis.
589
820
 
590
821
  `--max-cost USD` stops the scan and its workers when estimated cost exceeds
591
822
  the limit, though in-flight requests can finish above it. If deep-scan
@@ -647,8 +878,45 @@ even after a failed or incomplete scan, but not after cancellation or a
647
878
  cost-limit stop.
648
879
 
649
880
  `--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.
881
+ repository per invocation. Rerunning the command continues the campaign, skips
882
+ completed results, and starts new attempts for pending repositories. If an
883
+ attempt directory is occupied, that repository stops before replacing its
884
+ checkout and the command recommends `--recover`.
885
+
886
+ #### Recovering failed or interrupted bulk scans
887
+
888
+ Use the original CSV, output directory, and campaign options with `--recover`:
889
+
890
+ ```bash
891
+ npx @openai/codex-security bulk-scan repositories.csv \
892
+ --output-dir /path/outside/repositories/security-scans --recover
893
+ ```
894
+
895
+ Recovery requires an existing campaign with a matching manifest. It skips
896
+ completed results, including partial coverage, and repositories never started.
897
+ For each failed or interrupted repository, it checks the latest attempt:
898
+
899
+ - A sealed scan is recorded in `results.jsonl` without scanning again.
900
+ - An eligible running Deep Scan resumes its original session, keeping its scan
901
+ ID, completed workers, artifacts, saved settings, and accumulated cost.
902
+ - A failed, canceled, or otherwise unavailable scan starts a new attempt at the
903
+ CSV's pinned revision. Attempt numbers account for both receipts and existing
904
+ directories. Old artifacts and checkouts are preserved; new attempts use
905
+ `recovery-checkouts/<id>/attempt-<n>`.
906
+
907
+ `--workers` still defaults to `4`; `--max-attempts` defaults to one recovery or
908
+ new attempt per repository. A resume connection failure stops that repository
909
+ for this invocation instead of starting another scan. Other repositories
910
+ continue. Failed and interrupted recovery checkouts remain available for a later
911
+ `--recover`; fresh completed checkouts are removed after recording the result.
912
+ If a reboot interrupted a receipt write, its unfinished tail is saved beside
913
+ `results.jsonl` as `results.jsonl.interrupted-<id>` before appending valid records.
914
+
915
+ Same-scan resume requires the original checkout, session logs, and Codex Security
916
+ state directory. Recovery does not reconstruct deleted checkpoints or fix the
917
+ underlying cause of execution failures. New attempts incur new scan costs.
918
+ Any remaining failures or partial coverage keep exit code `2`.
919
+ `bulk-scan --help` lists all options.
652
920
 
653
921
  ### Custom validation
654
922
 
@@ -988,6 +1256,25 @@ once before they can be reused.
988
1256
  Pass `signal` to cancel any classification operation. Keep human overrides in the
989
1257
  calling workflow or issue tracker; assessments remain separate recommendations.
990
1258
 
1259
+ ### Feedback
1260
+
1261
+ Send a problem report to OpenAI and share the returned feedback ID with support:
1262
+
1263
+ ```sh
1264
+ codex-security feedback --reason "The scan stopped before it finished"
1265
+ codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
1266
+ ```
1267
+
1268
+ Without an ID, `feedback` selects the most recently started scan in the current
1269
+ repository, including active or failed scans. If there are no saved scans, it sends
1270
+ a general report. The report includes your description, version details, and the selected
1271
+ scan and session IDs. Add `--json` for structured output.
1272
+
1273
+ Logs are off by default. `--include-logs` uploads Codex diagnostics and saved scan
1274
+ and worker activity. These can contain source code, prompts, findings, tool
1275
+ output, and other sensitive data. Only include logs you can share with OpenAI.
1276
+ The command uses Codex's feedback service and respects `feedback.enabled = false`.
1277
+
991
1278
  ### Scan history and reruns
992
1279
 
993
1280
  Commands default to the current repository. Select scans by full ID or a
@@ -998,6 +1285,7 @@ unique prefix of at least eight characters.
998
1285
  | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
999
1286
  | `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |
1000
1287
  | `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |
1288
+ | `scans resume SCAN_ID` | Resume an interrupted Deep Scan in its original session and output directory. |
1001
1289
  | `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |
1002
1290
  | `scans match BEFORE AFTER` | Link findings with the same root cause. |
1003
1291
  | `scans match --all` | Match completed scans across the repository's worktrees and clones. |
@@ -1005,6 +1293,43 @@ unique prefix of at least eight characters.
1005
1293
  | `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |
1006
1294
  | `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |
1007
1295
 
1296
+ #### Resuming an interrupted Deep Scan
1297
+
1298
+ After the CLI process or host stops unexpectedly, find the scan and rejoin it:
1299
+
1300
+ ```bash
1301
+ npx @openai/codex-security scans list --scan-root /path/to/security-scans
1302
+ npx @openai/codex-security scans resume SCAN_ID
1303
+ ```
1304
+
1305
+ The scan must still be `running`, with its original checkout, output directory,
1306
+ and owning Codex session available in the same Codex Security state directory.
1307
+ The checkout's identity, revision, and contents must match the saved target.
1308
+ Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
1309
+
1310
+ Resume uses the saved configuration and instructions with the installed plugin.
1311
+ New scans save the explicit safety identifier and post-scan prompt contents.
1312
+ Single-scan resume restores them even if the prompt file changes or disappears.
1313
+ Older records that did not save these values cannot reconstruct them. Bulk
1314
+ recovery still requires matching campaign inputs and options; it uses the supplied
1315
+ post-scan prompt when the scan has no saved prompt.
1316
+ It keeps the scan ID, completed workers, artifacts, and accumulated session cost.
1317
+ The existing coordinator recovers interrupted workers after its lease expires.
1318
+ If discovery finished before the interruption, resume completes and seals the
1319
+ same scan. No archiving or new attempt directory is needed. A failed connection
1320
+ leaves the existing scan available for another resume attempt.
1321
+
1322
+ Compatible saved scans can resume after a plugin update. Already-sealed results
1323
+ keep their original producer version and contents when completion is recorded.
1324
+ Unsupported or invalid sealed artifacts are rejected before resuming, preserving
1325
+ the saved scan state and files.
1326
+
1327
+ For bulk campaigns, use [`bulk-scan --recover`](#recovering-failed-or-interrupted-bulk-scans)
1328
+ to recover eligible attempts and update `results.jsonl`. Individual `scans resume`
1329
+ does not update campaign receipts.
1330
+
1331
+ #### Matching saved scans
1332
+
1008
1333
  Matching requires sealed artifacts and reuses saved matches unless you pass
1009
1334
  `--force`. Comparisons classify findings as new, persisting, reopened, resolved,
1010
1335
  or unknown. Missing findings aren't resolved if the later scan is incomplete
@@ -1231,7 +1556,9 @@ checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
1231
1556
  defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
1232
1557
  version, `sha-<commit>` tag, or digest for repeatable deployments.
1233
1558
 
1234
- To build from a source checkout instead:
1559
+ To build from a source checkout, first prepare the
1560
+ [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
1561
+ for that checkout. Then run from the repository root:
1235
1562
 
1236
1563
  ```bash
1237
1564
  docker build --target scanner -t codex-security:local .
@@ -1402,14 +1729,32 @@ change scan artifacts.
1402
1729
  codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
1403
1730
  ```
1404
1731
 
1732
+ Deduplication runs up to 8 jobs concurrently by default. Set `--concurrency N`
1733
+ to choose a positive integer, or `--concurrency 1` for serial execution. The SDK
1734
+ equivalent is `concurrency: N`. Candidate neighborhoods are fetched first, with
1735
+ the same concurrency limit. Luna screenings and ready Sol pair reviews then use
1736
+ two queues sharing one worker pool, with at most 8 jobs running in total by
1737
+ default. Each available worker takes a ready job as soon as its current job
1738
+ finishes; it does not wait for a batch to finish.
1739
+
1740
+ A Sol pair review becomes ready once every Luna screening covering that pair
1741
+ has finished and none voted `DISTINCT`. It can run while unrelated Luna
1742
+ screenings continue. Results are combined in input order so completion timing
1743
+ does not change the groups.
1744
+
1745
+ If a job fails after its retries, queued jobs stop and already running jobs
1746
+ finish before the command reports the failure. No groups are posted from an
1747
+ incomplete review. To retain completed reviews across runs, use a
1748
+ `--workflow-id` as described below.
1749
+
1405
1750
  The default scope is the saved scan's repository, identified by
1406
1751
  `scan.target.targetId` in its manifest. Add `--all-repositories` to search the
1407
1752
  entire stored corpus explicitly; the flag defaults to false. The SDK has the
1408
1753
  equivalent optional `allRepositories: true` setting. This narrows the previous
1409
1754
  preview's implicit all-repository behavior.
1410
1755
 
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
1756
+ Provide `--findings-url` and either `--scan` or `--workflow-id`, with no implicit
1757
+ scan or service URL. As with `publish scan --scan`, the scan selector accepts a full ID, unique
1413
1758
  prefix, or `latest` for the current repository. The saved scan must be complete
1414
1759
  and its sealed artifacts must be available.
1415
1760
 
@@ -1418,6 +1763,7 @@ import { deduplicateScan } from "@openai/codex-security";
1418
1763
 
1419
1764
  const result = await deduplicateScan("scan_example_001", {
1420
1765
  findingsUrl: "http://127.0.0.1:3000",
1766
+ // concurrency: 8, // Shared worker limit for Luna and Sol; use 1 for serial.
1421
1767
  // allRepositories: true, // Omit to search only this scan's repository.
1422
1768
  // signal: controller.signal,
1423
1769
  });
@@ -1433,6 +1779,7 @@ import { deduplicateScanDirectory } from "@openai/codex-security";
1433
1779
  const result = await deduplicateScanDirectory("/path/to/completed-scan", {
1434
1780
  repository: "/path/to/repository",
1435
1781
  findingsUrl: "http://127.0.0.1:3000",
1782
+ // concurrency: 8,
1436
1783
  // expectedScanId: "scan_example_001",
1437
1784
  // allRepositories: true,
1438
1785
  // signal: controller.signal,
@@ -1515,8 +1862,9 @@ scan. Existing output-directory and archive safeguards still apply to scan retri
1515
1862
 
1516
1863
  Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
1517
1864
  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
1865
+ publication of a completed scan. The CLI and `deduplicateScan` require local scan
1866
+ history to locate the approved source checkout; `deduplicateScanDirectory` uses
1867
+ the supplied repository. For a workflow, dedupe first completes publication
1520
1868
  if its receipt is missing. `--all-repositories` retains its existing default of
1521
1869
  false. Changing a workflow's scan, destination, or bound scope is an error: choose
1522
1870
  a different workflow ID. Use one coordinating process per workflow.
@@ -1536,6 +1884,12 @@ A completed `dedupe --workflow-id` returns its saved result without repeating
1536
1884
  reviews or group writes. A publication whose acknowledgement was lost is retried
1537
1885
  using the service's existing idempotent upsert.
1538
1886
 
1887
+ Concurrent jobs save their validated reviews independently. Resuming with the
1888
+ same workflow ID reuses completed reviews and retries unfinished jobs. The
1889
+ concurrency setting is not part of a review's checkpoint identity, so it is safe
1890
+ to change `--concurrency` when resuming. Cancellation stops active reviews and
1891
+ leaves their completed checkpoints available for the next run.
1892
+
1539
1893
  Each validated screening and pair review is checkpointed locally,
1540
1894
  including DISTINCT decisions. Screening checkpoints retain pair recommendations
1541
1895
  and rationales under host-assigned pair slots bound to the original records.
@@ -1545,8 +1899,17 @@ must satisfy the Finding schema and preserve the canonical finding ID. Validatio
1545
1899
  still happens through `review_validator.submit_decisions`; invalid submissions
1546
1900
  are corrected in the same review conversation. A completed turn without an
1547
1901
  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.
1902
+ If formatting remains invalid, the job retries in a fresh review session.
1903
+ Explicit transient Codex failures and unexpected process exits also retry, with
1904
+ at most three fresh sessions per review. Transient findings-service failures, including
1905
+ rate limits and network errors, receive up to three request attempts. Retries use
1906
+ exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to retry
1907
+ occupies the job's concurrency slot.
1908
+
1909
+ Cancellation, authentication or configuration errors, permanent HTTP errors, and
1910
+ required-source-access blockers are not retried. Exhausted retries fail deduplication;
1911
+ invalid or unfinished reviews are not cached. Completed checkpoints remain
1912
+ available when the workflow resumes.
1550
1913
 
1551
1914
  Checkpoints bind to the exact original records and ordering, approved source path,
1552
1915
  Git revision and current file contents (including ignored files), repository scope,
@@ -1570,12 +1933,15 @@ use another workflow ID for a fresh review rather than changing that saved resul
1570
1933
  1. For each distinct finding ID in the scan, request
1571
1934
  `/v1/finding/{id}/potential-duplicates` with the selected repository or
1572
1935
  explicit all-repository scope. Use the complete stored anchor and
1573
- candidates returned by that request.
1936
+ candidates returned by that request. Fetch all neighborhoods before starting
1937
+ reviews so every pair's screening dependencies are known.
1574
1938
  2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
1575
1939
  effort. The review covers every anchor-neighbor pair; nominations between
1576
1940
  neighbors are rejected.
1577
1941
  3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
1578
- reasoning effort. Only accepted pairs contribute to duplicate groups.
1942
+ reasoning effort after all Luna screenings covering that pair finish without
1943
+ a `DISTINCT` decision. Luna and ready Sol jobs share the configured worker
1944
+ pool and can run together. Only accepted pairs contribute to duplicate groups.
1579
1945
  4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
1580
1946
  decision contradicts the resulting component. Contradicted components are
1581
1947
  split deterministically, preferring legal subgroups that preserve more
@@ -1778,7 +2144,9 @@ Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
1778
2144
  Startup and listing need no key. The service does not load `.env` or authenticate
1779
2145
  requests; keep it on loopback or behind an authenticated TLS proxy.
1780
2146
 
1781
- From a source checkout's `sdk/typescript` directory:
2147
+ For a source build, first prepare the
2148
+ [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
2149
+ for that checkout. Then run from its `sdk/typescript` directory:
1782
2150
 
1783
2151
  ```bash
1784
2152
  pnpm install --frozen-lockfile
@@ -36,6 +36,7 @@
36
36
  "PYTHON",
37
37
  "PYTHONUTF8",
38
38
  "CODEX_SECURITY_KNOWLEDGE_BASE",
39
+ "CODEX_SECURITY_CONFIG_PATH",
39
40
  "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
40
41
  "CODEX_SECURITY_SCAN_ROOT",
41
42
  "CODEX_SECURITY_STATE_DIR",
@@ -0,0 +1,24 @@
1
+ import { Buffer } from "node:buffer";
2
+ import { readFile, readdir } from "node:fs/promises";
3
+ import { dirname } from "node:path";
4
+ import { createRequire } from "node:module";
5
+ import { fileURLToPath } from "node:url";
6
+ import { brotliDecompressSync } from "node:zlib";
7
+
8
+ const runtimeChunkNames = (await readdir(new URL("./", import.meta.url)))
9
+ .filter((name) => name.startsWith("helpers.mjs.br.part-"))
10
+ .sort();
11
+ if (!runtimeChunkNames.length) {
12
+ throw new Error("Missing compressed Codex Security MCP server runtime chunks.");
13
+ }
14
+ const compressedRuntime = Buffer.concat(
15
+ await Promise.all(runtimeChunkNames.map((name) => readFile(new URL(`./${name}`, import.meta.url))))
16
+ );
17
+ const runtimeSource = brotliDecompressSync(compressedRuntime).toString("utf8");
18
+ const require = createRequire(import.meta.url);
19
+ const Module = require("node:module");
20
+ const loaderPath = fileURLToPath(import.meta.url);
21
+ const runtimeModule = new Module(loaderPath);
22
+ runtimeModule.filename = loaderPath;
23
+ runtimeModule.paths = Module._nodeModulePaths(dirname(loaderPath));
24
+ runtimeModule._compile(runtimeSource, loaderPath);