@openai/codex-security 0.6.0 → 0.7.0

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 (243) hide show
  1. package/README.md +68 -37
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/access-advisory.md +11 -0
  17. package/_bundled_plugin/references/core-scan.md +30 -77
  18. package/_bundled_plugin/references/final-report.md +45 -189
  19. package/_bundled_plugin/references/scan-contract.md +2 -0
  20. package/_bundled_plugin/references/scan-prologue.md +1 -1
  21. package/_bundled_plugin/references/scan-runtime.md +1 -5
  22. package/_bundled_plugin/references/threat-model.md +33 -41
  23. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  24. package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
  25. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  26. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  27. package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
  29. package/_bundled_plugin/scripts/report_projection.py +44 -15
  30. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  31. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  32. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
  33. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  34. package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
  35. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  36. package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
  37. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  38. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  39. package/_bundled_plugin/scripts/workbench_db.py +51 -22
  40. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  41. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
  45. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  47. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  48. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  51. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  52. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  53. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  54. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  56. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  57. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  58. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  59. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  60. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  61. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  62. package/_bundled_plugin/skills/publish-findings/SKILL.md +28 -24
  63. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  64. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  65. package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
  66. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  67. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  68. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  69. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  70. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  71. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  72. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  73. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  74. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  75. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  76. package/dist/api.d.ts +5 -3
  77. package/dist/api.d.ts.map +1 -1
  78. package/dist/api.js +341 -37
  79. package/dist/api.js.map +1 -1
  80. package/dist/auth.d.ts.map +1 -1
  81. package/dist/auth.js +4 -1
  82. package/dist/auth.js.map +1 -1
  83. package/dist/cli.d.ts +2 -2
  84. package/dist/cli.d.ts.map +1 -1
  85. package/dist/cli.js +674 -419
  86. package/dist/cli.js.map +1 -1
  87. package/dist/component-scan.d.ts +8 -2
  88. package/dist/component-scan.d.ts.map +1 -1
  89. package/dist/component-scan.js +2 -0
  90. package/dist/component-scan.js.map +1 -1
  91. package/dist/contract.d.ts +2 -0
  92. package/dist/contract.d.ts.map +1 -1
  93. package/dist/contract.js +67 -33
  94. package/dist/contract.js.map +1 -1
  95. package/dist/cost.d.ts +18 -0
  96. package/dist/cost.d.ts.map +1 -1
  97. package/dist/cost.js +107 -12
  98. package/dist/cost.js.map +1 -1
  99. package/dist/coverage-presentation.d.ts +6 -0
  100. package/dist/coverage-presentation.d.ts.map +1 -0
  101. package/dist/coverage-presentation.js +34 -0
  102. package/dist/coverage-presentation.js.map +1 -0
  103. package/dist/custom-validation-prompt.js +3 -3
  104. package/dist/custom-validation-prompt.js.map +1 -1
  105. package/dist/custom-validation.d.ts.map +1 -1
  106. package/dist/custom-validation.js +30 -4
  107. package/dist/custom-validation.js.map +1 -1
  108. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  109. package/dist/deduplication/checkpointed-review.js +3 -1
  110. package/dist/deduplication/checkpointed-review.js.map +1 -1
  111. package/dist/deduplication/scan.d.ts.map +1 -1
  112. package/dist/deduplication/scan.js +7 -5
  113. package/dist/deduplication/scan.js.map +1 -1
  114. package/dist/endor-findings.d.ts +4 -3
  115. package/dist/endor-findings.d.ts.map +1 -1
  116. package/dist/endor-findings.js +16 -11
  117. package/dist/endor-findings.js.map +1 -1
  118. package/dist/external-findings-import.d.ts.map +1 -1
  119. package/dist/external-findings-import.js +13 -5
  120. package/dist/external-findings-import.js.map +1 -1
  121. package/dist/external-findings-local.d.ts.map +1 -1
  122. package/dist/external-findings-local.js +8 -1
  123. package/dist/external-findings-local.js.map +1 -1
  124. package/dist/external-findings-publish.d.ts +1 -1
  125. package/dist/external-findings-publish.d.ts.map +1 -1
  126. package/dist/external-findings-publish.js +11 -3
  127. package/dist/external-findings-publish.js.map +1 -1
  128. package/dist/external-findings-read.d.ts +11 -1
  129. package/dist/external-findings-read.d.ts.map +1 -1
  130. package/dist/external-findings-read.js +15 -6
  131. package/dist/external-findings-read.js.map +1 -1
  132. package/dist/external-import-contract.d.ts +3 -1
  133. package/dist/external-import-contract.d.ts.map +1 -1
  134. package/dist/external-import-contract.js +33 -25
  135. package/dist/external-import-contract.js.map +1 -1
  136. package/dist/external-imports-feature.d.ts +6 -0
  137. package/dist/external-imports-feature.d.ts.map +1 -0
  138. package/dist/external-imports-feature.js +51 -0
  139. package/dist/external-imports-feature.js.map +1 -0
  140. package/dist/finding-workflow.d.ts +22 -5
  141. package/dist/finding-workflow.d.ts.map +1 -1
  142. package/dist/finding-workflow.js +21 -9
  143. package/dist/finding-workflow.js.map +1 -1
  144. package/dist/github-advisories.d.ts.map +1 -1
  145. package/dist/github-advisories.js +3 -1
  146. package/dist/github-advisories.js.map +1 -1
  147. package/dist/github-findings.d.ts +4 -3
  148. package/dist/github-findings.d.ts.map +1 -1
  149. package/dist/github-findings.js +16 -14
  150. package/dist/github-findings.js.map +1 -1
  151. package/dist/hosted-remediation.d.ts.map +1 -1
  152. package/dist/hosted-remediation.js +19 -2
  153. package/dist/hosted-remediation.js.map +1 -1
  154. package/dist/hosted-scan.d.ts +1 -1
  155. package/dist/hosted-scan.d.ts.map +1 -1
  156. package/dist/hosted-scan.js +0 -5
  157. package/dist/hosted-scan.js.map +1 -1
  158. package/dist/import-scan.js +1 -1
  159. package/dist/import-scan.js.map +1 -1
  160. package/dist/index.d.ts +3 -3
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +1 -1
  163. package/dist/index.js.map +1 -1
  164. package/dist/knowledge-base.d.ts +1 -0
  165. package/dist/knowledge-base.d.ts.map +1 -1
  166. package/dist/knowledge-base.js +17 -8
  167. package/dist/knowledge-base.js.map +1 -1
  168. package/dist/models.d.ts +1 -0
  169. package/dist/models.d.ts.map +1 -1
  170. package/dist/models.js.map +1 -1
  171. package/dist/owner-evidence.d.ts +2 -0
  172. package/dist/owner-evidence.d.ts.map +1 -1
  173. package/dist/owner-evidence.js +2 -1
  174. package/dist/owner-evidence.js.map +1 -1
  175. package/dist/publish.d.ts +2 -0
  176. package/dist/publish.d.ts.map +1 -1
  177. package/dist/publish.js +1 -1
  178. package/dist/publish.js.map +1 -1
  179. package/dist/remediation.d.ts +1 -25
  180. package/dist/remediation.d.ts.map +1 -1
  181. package/dist/remediation.js +3 -24
  182. package/dist/remediation.js.map +1 -1
  183. package/dist/runtime.d.ts.map +1 -1
  184. package/dist/runtime.js +7 -7
  185. package/dist/runtime.js.map +1 -1
  186. package/dist/scan-dashboard.d.ts +5 -3
  187. package/dist/scan-dashboard.d.ts.map +1 -1
  188. package/dist/scan-dashboard.js +79 -26
  189. package/dist/scan-dashboard.js.map +1 -1
  190. package/dist/scan-history-renderer.d.ts.map +1 -1
  191. package/dist/scan-history-renderer.js +8 -2
  192. package/dist/scan-history-renderer.js.map +1 -1
  193. package/dist/scan-owner-suggestions.d.ts +1 -1
  194. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  195. package/dist/scan-owner-suggestions.js +4 -4
  196. package/dist/scan-owner-suggestions.js.map +1 -1
  197. package/dist/scan-usage-display.d.ts +8 -0
  198. package/dist/scan-usage-display.d.ts.map +1 -0
  199. package/dist/scan-usage-display.js +46 -0
  200. package/dist/scan-usage-display.js.map +1 -0
  201. package/dist/scanner-import.d.ts +1 -1
  202. package/dist/scanner-import.d.ts.map +1 -1
  203. package/dist/scanner-import.js +7 -3
  204. package/dist/scanner-import.js.map +1 -1
  205. package/dist/security-policy.d.ts.map +1 -1
  206. package/dist/security-policy.js +1 -20
  207. package/dist/security-policy.js.map +1 -1
  208. package/dist/semgrep-findings.d.ts +4 -3
  209. package/dist/semgrep-findings.d.ts.map +1 -1
  210. package/dist/semgrep-findings.js +9 -9
  211. package/dist/semgrep-findings.js.map +1 -1
  212. package/dist/skill-authentication.d.ts +18 -0
  213. package/dist/skill-authentication.d.ts.map +1 -0
  214. package/dist/skill-authentication.js +82 -0
  215. package/dist/skill-authentication.js.map +1 -0
  216. package/dist/snyk-findings.d.ts +5 -4
  217. package/dist/snyk-findings.d.ts.map +1 -1
  218. package/dist/snyk-findings.js +18 -17
  219. package/dist/snyk-findings.js.map +1 -1
  220. package/dist/suggest-owners.d.ts +4 -1
  221. package/dist/suggest-owners.d.ts.map +1 -1
  222. package/dist/suggest-owners.js +53 -21
  223. package/dist/suggest-owners.js.map +1 -1
  224. package/dist/targets.d.ts.map +1 -1
  225. package/dist/targets.js +4 -1
  226. package/dist/targets.js.map +1 -1
  227. package/dist/wiz-csv.d.ts +2 -1
  228. package/dist/wiz-csv.d.ts.map +1 -1
  229. package/dist/wiz-csv.js +3 -3
  230. package/dist/wiz-csv.js.map +1 -1
  231. package/dist/wiz-findings.d.ts +2 -1
  232. package/dist/wiz-findings.d.ts.map +1 -1
  233. package/dist/wiz-findings.js +27 -23
  234. package/dist/wiz-findings.js.map +1 -1
  235. package/docs/classify-severity-records.md +3 -4
  236. package/docs/cli.md +155 -38
  237. package/docs/findings-service.md +119 -118
  238. package/docs/hosted-remediation.md +19 -17
  239. package/docs/hosted-scans.md +37 -11
  240. package/package.json +8 -8
  241. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  242. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  243. package/_bundled_plugin/scripts/rank_preview.py +0 -129
package/docs/cli.md CHANGED
@@ -23,6 +23,28 @@ findings file in local scan history, use
23
23
  GitHub import returns upstream alerts for validation; file import saves findings
24
24
  without running security analysis.
25
25
 
26
+ ## Find a workflow
27
+
28
+ - [Sign in or configure a provider](#authentication).
29
+ - [Scan a repository or selected paths](#scan-options-and-output),
30
+ [configure a Deep Scan](#configure-deep-scans), or
31
+ [save project settings](#project-files).
32
+ - [Review one system across repositories](#review-one-system-across-repositories)
33
+ or [run independent bulk scans](#bulk-scans).
34
+ - [Import vendor findings locally](#import-vendor-findings-locally),
35
+ [save findings as a scan](#import-findings-as-a-saved-scan), or
36
+ [retrieve GitHub alerts](#import-alerts-from-the-cli).
37
+ - [Inspect saved scans and rerun them](#scan-history-and-reruns),
38
+ [classify severity](#classify-finding-severity), or
39
+ [suggest owners](#suggest-finding-owners).
40
+ - [Validate and patch findings](#validate-and-patch-findings) or
41
+ [verify an existing fix](#verify-fixes).
42
+ - [Publish to Cloud](#publish-findings-to-cloud) or
43
+ [Linear](#publish-completed-scans-to-linear), or [export results](#exports-and-ci).
44
+ - [Draft a security policy](#generate-a-security-policy).
45
+ - [Use a hosted executor](#hosted-standard-scan) or
46
+ [run bulk scans in containers](#containerized-bulk-scans).
47
+
26
48
  ## Authentication
27
49
 
28
50
  Sign in with ChatGPT, or supply an API key for CI:
@@ -404,6 +426,11 @@ codex-security scan . --owner-suggestions
404
426
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
405
427
  ```
406
428
 
429
+ `--path` selects files or directories. The scan summary and saved scan details
430
+ show requested paths and exclusions. `coverage.deferred` records unfinished
431
+ requested work separately from optional `coverage.openQuestions` follow-up.
432
+ Human-readable output quotes ambiguous paths, while JSON retains their original strings.
433
+
407
434
  Whole-codebase and path scans also accept ordinary directories, including SVN
408
435
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
409
436
 
@@ -412,12 +439,20 @@ changes. Both require Git. Deep scans support whole repositories and path scopes
412
439
  Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
413
440
  be clean and at the commit recorded by the parent.
414
441
 
442
+ Committed-diff scans require a clean, full checkout at the requested head
443
+ revision, including when using `--validate`. A different checkout revision or
444
+ local changes are rejected before scanning; check out the requested head and
445
+ commit or stash local changes before retrying.
446
+
415
447
  `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
416
448
  committed Git scan, using the same checkout, model, and reasoning effort. Owner
417
449
  errors leave the base scan completed. The JSON result includes
418
450
  `ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
419
451
  manifest stay unchanged. This option is unsupported for working-tree and
420
- directory snapshots, and is skipped with a warning when `--max-cost` is set.
452
+ directory snapshots. It works with `--max-cost`: hints are recorded within the
453
+ existing scan execution and budget, and the report is finalized without another
454
+ model call. Missing hints abstain; invalid hints produce per-finding owner errors.
455
+ Use the separate `suggest-owners` command for explicit owner-only jobs.
421
456
 
422
457
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
423
458
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
@@ -487,6 +522,38 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
487
522
  its successful output and failure codes.
488
523
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
489
524
 
525
+ ### Follow-up finding validation
526
+
527
+ Scans already validate findings against local source. Add `--validate` to run
528
+ the existing standalone validation workflow for each reported finding after
529
+ the scan, using the same selected Cyber access program. Validation has read-only
530
+ filesystem access with network and web search disabled. Each assessment uses a
531
+ separate evidence directory; the combined report is saved as
532
+ `<scan-dir>/validation.md`, or a uniquely suffixed report
533
+ if that path already exists. Each completed assessment is saved immediately;
534
+ failed or interrupted runs retain the partial report. JSON scan output includes
535
+ the execution status, completed assessment count, and report path. Completion means the assessments finished,
536
+ not that every finding was confirmed. A scan with no findings needs no second
537
+ pass.
538
+
539
+ With `--workflow-id`, retries reuse completed assessments for unchanged findings,
540
+ source, validation settings, and saved evidence. Missing or changed evidence
541
+ causes validation to run again, as do older assessments without recorded evidence
542
+ fingerprints. By default, regeneration uses a new evidence directory. An explicit
543
+ SDK validation `outputDir` reuses an assessment only when it points to the same
544
+ evidence directory. A different destination starts a new assessment. The requested
545
+ directory must be empty when regenerating; existing files are never overwritten.
546
+ When `--knowledge-base` is supplied, the scan and all follow-up assessments use
547
+ one captured copy of those documents. A workflow retry must use the same document
548
+ contents. Use a new workflow ID if they changed or if the workflow was created
549
+ before document snapshots were bound to follow-up validation.
550
+
551
+ The report is supplemental: its assessments are not applied to the saved
552
+ findings or the `--fail-on-severity` decision. Validation failures exit with
553
+ `2` while retaining the completed scan. The additional model calls are not
554
+ cost-tracked, so `--validate` cannot be combined with `--max-cost` (including a
555
+ configured scan cost limit), `--dry-run`, or `--mock`.
556
+
490
557
  ### Understand scan scope and follow-up work
491
558
 
492
559
  A completed scan means the requested workflow finished. It does not mean every
@@ -739,16 +806,9 @@ not to planning, result matching, or the total campaign.
739
806
 
740
807
  ### Configure deep scans
741
808
 
742
- ```ts
743
- await security.run("/path/to/repository", {
744
- mode: "deep",
745
- workers: 2,
746
- subagents: 0,
747
- stopAfterNoNew: 3,
748
- stopAfterConsecutiveErrors: 2,
749
- maxDiscoveryRuns: 10,
750
- maxTimeMinutes: 90,
751
- });
809
+ ```bash
810
+ codex-security scan . --mode deep --workers 2 --subagents 0 \
811
+ --stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
752
812
  ```
753
813
 
754
814
  For `scan --mode deep`, `--workers` controls discovery concurrency and
@@ -757,11 +817,13 @@ For `scan --mode deep`, `--workers` controls discovery concurrency and
757
817
  or duration. At the deadline, discovery stops; the scan then combines and returns
758
818
  completed findings.
759
819
 
820
+ For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
821
+
760
822
  Use project-file `scan.deep` settings or legacy
761
823
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
762
824
  that `subagents` can be zero. Discovery time accepts positive fractional minutes;
763
- its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
764
- advisory allowance, this existing Deep discovery limit is enforced. Resuming a
825
+ its default and maximum are 5760 minutes (96 hours). Unlike Standard's
826
+ advisory allowance, the Deep discovery limit is enforced. Resuming a
765
827
  Deep scan keeps its original deadline; rerunning starts a new scan.
766
828
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
767
829
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
@@ -877,26 +939,27 @@ For filesystem and approval behavior, see the
877
939
 
878
940
  ### Environment variables
879
941
 
880
- | Variable | Effect |
881
- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
882
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
883
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
884
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
885
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
886
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
887
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
888
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
889
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
890
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
891
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
892
- | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
893
- | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
894
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
895
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
896
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
897
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
898
- | `CI` | Disable interactive update notices. |
899
- | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
942
+ | Variable | Effect |
943
+ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
944
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
945
+ | `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS` | Set to `1` to enable vendor finding imports, imported-findings readback, and GitHub advisory acquisition; disabled otherwise. |
946
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
947
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
948
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
949
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
950
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
951
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
952
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
953
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
954
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
955
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
956
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
957
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
958
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
959
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
960
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
961
+ | `CI` | Disable interactive update notices. |
962
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
900
963
 
901
964
  Custom Codex executables need thread source attribution for `exec` and
902
965
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -961,6 +1024,14 @@ work could not be measured, including in-flight turns or missing earlier attempt
961
1024
  The parent can continue after report completion, so final CLI tokens can exceed
962
1025
  the saved measurement window.
963
1026
 
1027
+ During a scan, progress shows when Codex reported the displayed token and cost
1028
+ totals, in UTC. If the report has no timestamp, progress says so.
1029
+ In-flight requests may add tokens and cost after that time. When Codex supplies
1030
+ account allowance, progress shows the percentage used in each reported window
1031
+ and the time of that reading. On a short terminal, resize the window or press
1032
+ `d` to scroll through the full readings in Details. With ChatGPT authentication,
1033
+ progress also says when Codex has yet to report allowance.
1034
+
964
1035
  `usage.accountRateLimits` saves the latest observed account-wide readings with
965
1036
  their own timestamps, window durations, and reset times. These are historical
966
1037
  observations, not a live allowance check or scan-only consumption. Empty readings
@@ -1197,6 +1268,24 @@ Supply the validation prompt again when rerunning.
1197
1268
 
1198
1269
  ## Import vendor findings locally
1199
1270
 
1271
+ External finding imports are disabled by default. Opt in for the current shell:
1272
+
1273
+ ```bash
1274
+ export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
1275
+ ```
1276
+
1277
+ In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
1278
+ Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
1279
+ and `import github-advisories` are absent from command help and schemas and cannot
1280
+ run. The SDK's external publication, local import/readback, and advisory
1281
+ acquisition APIs require the same flag in their effective environment. An explicit
1282
+ `dependencies.environment` is used instead of the process environment. Pure
1283
+ normalizers and file readers remain available as library utilities.
1284
+
1285
+ This flag does not affect `publish scan`, `publish check`, `scan import`, or the
1286
+ existing `import github` alert collector. Disabling it retains previously imported
1287
+ records; enable it again to read them with `findings imported`.
1288
+
1200
1289
  Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
1201
1290
  reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
1202
1291
  inputs only for providers and report profiles that support them. A JSON API
@@ -1366,6 +1455,8 @@ network findings are not supported by this repository importer. Cloud destinatio
1366
1455
  currently support connected GitHub and GitHub Enterprise repositories, including
1367
1456
  custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
1368
1457
 
1458
+ #### Select findings and a destination
1459
+
1369
1460
  Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
1370
1461
  connection to acquire findings and save the supported native JSON. A configured
1371
1462
  plugin may provide that connection; an official Codex plugin is not a prerequisite.
@@ -1412,6 +1503,8 @@ gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
1412
1503
  filename extension. **Raw Event** on Code & Build Scans contains scan metadata
1413
1504
  rather than findings.
1414
1505
 
1506
+ #### Configure an alternate Cloud deployment
1507
+
1415
1508
  For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
1416
1509
  API root before previewing or uploading, for example
1417
1510
  `https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
@@ -1432,6 +1525,8 @@ the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
1432
1525
  For custom API destinations without a configured app URL, completion retains
1433
1526
  the manual navigation guidance rather than guessing a UI host or port.
1434
1527
 
1528
+ #### Preview and publish
1529
+
1435
1530
  Preview the selection and destination:
1436
1531
 
1437
1532
  ```bash
@@ -1457,6 +1552,8 @@ exclusions. `--dry-run --format json` retains all normalized findings and comple
1457
1552
  evidence for inspection. A prompt explicitly includes any records that will be
1458
1553
  skipped.
1459
1554
 
1555
+ #### Package vulnerability inputs
1556
+
1460
1557
  Native package input can be a Wiz JSON vulnerability report, a vulnerability
1461
1558
  finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1462
1559
  with one package record per line. The repository package-vulnerability CSV
@@ -1507,6 +1604,8 @@ fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1507
1604
  Findings from external network scans are excluded from this package vulnerability
1508
1605
  mapping.
1509
1606
 
1607
+ #### SAST, repository secrets, and IaC inputs
1608
+
1510
1609
  For SAST, repository secrets, and IaC, save the documented JSON API collection:
1511
1610
 
1512
1611
  | Finding family | Collection | Raw occurrence identity |
@@ -1565,6 +1664,8 @@ collection:
1565
1664
  }
1566
1665
  ```
1567
1666
 
1667
+ #### Preserved evidence
1668
+
1568
1669
  The adapters preserve each selected raw node exactly in `source_data`. Typed
1569
1670
  `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1570
1671
  and family-specific evidence:
@@ -1583,6 +1684,8 @@ does not establish that it is deployed. Precise original timestamps remain in
1583
1684
  `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1584
1685
  timestamps.
1585
1686
 
1687
+ #### Convert CSV reports
1688
+
1586
1689
  Native SAST and secret report downloads can be CSV, including gzip-compressed
1587
1690
  CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1588
1691
  for its actual column headers into normalized JSONL, preserving each original row
@@ -1607,6 +1710,8 @@ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1607
1710
  integer range is rejected; export those values as strings to preserve them
1608
1711
  exactly. Invalid records appear in `excluded` with their source ID and reason.
1609
1712
 
1713
+ #### Resume interrupted imports
1714
+
1610
1715
  Requests contain at most 100 findings and respect the Cloud payload limits.
1611
1716
  Before uploading, the publisher saves request IDs and bodies privately under
1612
1717
  the configured Codex Security state directory. After an uncertain response,
@@ -1618,6 +1723,8 @@ API endpoint, not a link to the Cloud UI. A reset
1618
1723
  retires the old request without republishing; review and explicitly approve a
1619
1724
  fresh invocation.
1620
1725
 
1726
+ #### Results and exit codes
1727
+
1621
1728
  Results distinguish completion from partial or interrupted work:
1622
1729
 
1623
1730
  | Status | Exit code | Meaning |
@@ -1768,7 +1875,7 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
1768
1875
  report snapshots and delegates model execution to the host.
1769
1876
 
1770
1877
  For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1771
- Omitting `--rubric` runs classification with the [built-in severity rubric](../src/default-severity-rubric.ts).
1878
+ Omitting `--rubric` runs classification with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/sdk/typescript/src/default-severity-rubric.ts).
1772
1879
  It evaluates attacker access, boundary crossing, additional harm, and evidence for
1773
1880
  Critical, High, Medium, Low, and Informational findings. Confidence remains separate
1774
1881
  from severity; missing proof alone does not justify a downgrade. An explicit
@@ -2278,6 +2385,9 @@ installation fails. The installer respects `core.hooksPath`.
2278
2385
 
2279
2386
  ## Import GitHub findings locally or to Cloud
2280
2387
 
2388
+ Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
2389
+ The existing alert collector remains available without it.
2390
+
2281
2391
  Acquire code-scanning findings with the existing `import github` collector and
2282
2392
  save its complete JSON output. In Codex, the official
2283
2393
  [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
@@ -2369,6 +2479,8 @@ import file directly. Read records with `listLocalExternalFindings({ repository
2369
2479
 
2370
2480
  ### Import GHSA advisories separately
2371
2481
 
2482
+ Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
2483
+
2372
2484
  **Importing a GHSA advisory does not establish an installed dependency or
2373
2485
  applicability to the destination repository.** Repository advisories are
2374
2486
  disclosures maintained by a repository; global advisories describe affected
@@ -2705,6 +2817,11 @@ for `patch`. Omit it or use `--verification-mode standard` for the default check
2705
2817
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2706
2818
  `--json` returns structured output. Exit codes are `0` when all findings are
2707
2819
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2820
+ Authentication and execution failures print diagnostics on stderr and return
2821
+ `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message` with `--json`
2822
+ or `--format jsonl`. With JSON/JSONL `--full-output`, failures use an `ok: false`
2823
+ error envelope. Other formats retain stderr-only failures. Interruptions retain
2824
+ exit codes `130` and `143` without a result.
2708
2825
 
2709
2826
  ## Command discovery and integrations
2710
2827
 
@@ -2721,6 +2838,10 @@ scan, triage, patch, and verification workflows, see the
2721
2838
  For local findings storage, deduplication, and custom endpoints, see the
2722
2839
  [findings guide](findings-service.md).
2723
2840
 
2841
+ ### Hosted Standard scan
2842
+
2843
+ `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
2844
+
2724
2845
  ## Containerized bulk scans
2725
2846
 
2726
2847
  Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
@@ -2760,7 +2881,3 @@ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested us
2760
2881
  namespaces do not need it. The legacy Landlock fallback is unsupported.
2761
2882
  See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
2762
2883
  for deployment and source-build instructions.
2763
-
2764
- ### Hosted Standard scan
2765
-
2766
- `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
@@ -5,124 +5,7 @@ Deduplication reads that database directly; no local HTTP service is needed.
5
5
  The CLI can also publish to and deduplicate against independently operated
6
6
  compatible endpoints through explicit `--findings-url` settings.
7
7
 
8
- ## Local service removal
9
-
10
- The `serve` command (including `--port`), `start:server` script,
11
- `dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
12
- dashboard, and findings-service Compose deployment have been removed.
13
- `HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
14
- service. The dashboard storage projection is also removed.
15
-
16
- Existing SQLite databases, migrations, saved scans, findings, and duplicate
17
- groups are retained. No data migration or deletion is performed. Keep any
18
- existing service volume or state directory and back it up before changing
19
- deployments; local deduplication uses the database selected by
20
- `CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
21
-
22
- `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
23
- `SqliteFindingsStore`, and their storage types for direct storage users.
24
-
25
- For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
26
- static key or `() => string | Promise<string>` as its first argument. It calls
27
- the callback before each HTTP batch; the caller handles token acquisition.
28
- Cancellation prevents a new callback or HTTP request. Direct embedder callers
29
- still await a key callback that has already started.
30
- Pass `fetch` as the second argument and the full endpoint URL as the third.
31
- By default, the saved-scan deduplication APIs use environment credentials. A
32
- custom SDK `embedding` binding can supply an adapter with its own credentials,
33
- including an `OpenAiFindingEmbedder` with a renewable key callback.
34
-
35
- Custom publication, explicit remote deduplication, Cloud publication, the
36
- plugin MCP server, and Codex app-server are unchanged.
37
-
38
- ## Direct storage helpers
39
-
40
- Direct callers of the retired Python findings helpers can use the retained Node
41
- helpers from an installed plugin directory:
42
-
43
- ```bash
44
- scripts/launch_codex_security_mcp --helper list-stored-findings < request.json
45
- ```
46
-
47
- On Windows, use `scripts\launch_codex_security_mcp.cmd` with the same arguments
48
- and JSON on stdin. For example, `request.json` selects the existing database:
49
-
50
- ```json
51
- {
52
- "stateDirectory": "/absolute/path/to/state",
53
- "payload": { "limit": 50, "offset": 0 }
54
- }
55
- ```
56
-
57
- Use an absolute Windows path on Windows. The retained helper commands accept
58
- these `payload` fields:
59
-
60
- | Command | Payload |
61
- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
62
- | `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
63
- | `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
64
- | `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
65
- | `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
66
- | `list-dedupe-groups` | `findingId`. |
67
-
68
- Retained scan commands such as `workbench_db.py list-findings` keep their existing
69
- interface. The dashboard projection is removed along with the browser dashboard.
70
-
71
- ## Publish a scan
72
-
73
- Send a completed scan to an independently operated compatible endpoint:
74
-
75
- ```bash
76
- codex-security publish scan --scan SCAN_ID --to custom \
77
- --findings-url https://findings.example.com --json
78
- ```
79
-
80
- `--findings-url` is required. The client appends `/v1/bulk/findings` to this
81
- base URL, preserving any base path. Custom endpoints must implement that API
82
- and return the stored finding IDs.
83
-
84
- Publication sends the complete sealed findings and the manifest's
85
- `scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged
86
- and does not forward model credentials. The endpoint is responsible for storing the batch before acknowledging it.
87
-
88
- Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
89
- the interactive picker. Custom publication accepts one scan; CSV input and
90
- Linear options do not apply. Add `--dry-run` to preview the payload without an
91
- HTTP request. Upload failures and incomplete receipts fail the command. Uploads
92
- are not automatically retried because a lost response may have been committed.
93
-
94
- ```typescript
95
- import { publishScanToCustom } from "@openai/codex-security";
96
-
97
- const receipt = await publishScanToCustom("/path/to/completed-scan", {
98
- findingsUrl: "https://findings.example.com",
99
- // dryRun: true,
100
- // signal: controller.signal,
101
- });
102
- console.log(receipt.repositoryId, receipt.findingIds);
103
- ```
104
-
105
- ## Compatible endpoint contract
106
-
107
- The retained HTTP clients use these endpoints on the supplied base URL,
108
- preserving its base path:
109
-
110
- | Method | Path | Response |
111
- | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
112
- | `POST` | `/v1/bulk/findings` | An array acknowledging all submitted finding IDs; order does not matter. |
113
- | `GET` | `/v1/finding/{id}/potential-duplicates` | `{finding, potentialDuplicates}` containing complete finding records. |
114
- | `POST` | `/v1/dedupe-groups` | A successful JSON acknowledgement, such as `{}`. |
115
-
116
- Publication sends `{findings, repositoryId}`. Candidate requests include either
117
- `repositoryId` or `allRepositories=true`. Group writes send
118
- `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
119
- workflow retries. Both POST endpoints must persist their writes before
120
- acknowledging them and return a JSON body. An explicit URL selects this remote
121
- contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
122
-
123
- SDK findings client failures preserve the endpoint's error code and message with
124
- the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
125
- behavior uses the HTTP status and `Retry-After`.
8
+ For an older service deployment or helper integration, see [compatibility](#compatibility).
126
9
 
127
10
  ## Deduplicate a scan
128
11
 
@@ -405,3 +288,121 @@ including `text-embedding-3-large`, 1,536-dimensional float vectors, and token
405
288
  array inputs. Requests encode the complete finding JSON with `cl100k_base` and
406
289
  send the API key as a bearer token. Long inputs are combined without truncation.
407
290
  Cached compatible vectors avoid new requests.
291
+
292
+ ## Publish a scan
293
+
294
+ Send a completed scan to an independently operated compatible endpoint:
295
+
296
+ ```bash
297
+ codex-security publish scan --scan SCAN_ID --to custom \
298
+ --findings-url https://findings.example.com --json
299
+ ```
300
+
301
+ `--findings-url` is required. The client appends `/v1/bulk/findings` to this
302
+ base URL, preserving any base path. Custom endpoints must implement that API
303
+ and return the stored finding IDs.
304
+
305
+ Publication sends the complete sealed findings and the manifest's
306
+ `scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged
307
+ and does not forward model credentials. The endpoint is responsible for storing the batch before acknowledging it.
308
+
309
+ Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
310
+ the interactive picker. Custom publication accepts one scan; CSV input and
311
+ Linear options do not apply. Add `--dry-run` to preview the payload without an
312
+ HTTP request. Upload failures and incomplete receipts fail the command. Uploads
313
+ are not automatically retried because a lost response may have been committed.
314
+
315
+ ```typescript
316
+ import { publishScanToCustom } from "@openai/codex-security";
317
+
318
+ const receipt = await publishScanToCustom("/path/to/completed-scan", {
319
+ findingsUrl: "https://findings.example.com",
320
+ // dryRun: true,
321
+ // signal: controller.signal,
322
+ });
323
+ console.log(receipt.repositoryId, receipt.findingIds);
324
+ ```
325
+
326
+ ## Compatible endpoint contract
327
+
328
+ The retained HTTP clients use these endpoints on the supplied base URL,
329
+ preserving its base path:
330
+
331
+ | Method | Path | Response |
332
+ | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
333
+ | `POST` | `/v1/bulk/findings` | An array acknowledging all submitted finding IDs; order does not matter. |
334
+ | `GET` | `/v1/finding/{id}/potential-duplicates` | `{finding, potentialDuplicates}` containing complete finding records. |
335
+ | `POST` | `/v1/dedupe-groups` | A successful JSON acknowledgement, such as `{}`. |
336
+
337
+ Publication sends `{findings, repositoryId}`. Candidate requests include either
338
+ `repositoryId` or `allRepositories=true`. Group writes send
339
+ `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
340
+ workflow retries. Both POST endpoints must persist their writes before
341
+ acknowledging them and return a JSON body. An explicit URL selects this remote
342
+ contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
343
+
344
+ SDK findings client failures preserve the endpoint's error code and message with
345
+ the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
346
+ behavior uses the HTTP status and `Retry-After`.
347
+
348
+ ## Compatibility
349
+
350
+ ### Local service removal
351
+
352
+ The `serve` command (including `--port`), `start:server` script,
353
+ `dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
354
+ dashboard, and findings-service Compose deployment have been removed.
355
+ `HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
356
+ service. The dashboard storage projection is also removed.
357
+
358
+ Existing SQLite databases, migrations, saved scans, findings, and duplicate
359
+ groups are retained. No data migration or deletion is performed. Keep any
360
+ existing service volume or state directory and back it up before changing
361
+ deployments; local deduplication uses the database selected by
362
+ `CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
363
+
364
+ `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
365
+ `SqliteFindingsStore`, and their storage types for direct storage users.
366
+
367
+ For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
368
+ static key or `() => string | Promise<string>` as its first argument. It calls
369
+ the callback before each HTTP batch; the caller handles token acquisition.
370
+ Cancellation prevents a new callback or HTTP request. Direct embedder callers
371
+ still await a key callback that has already started.
372
+ Pass `fetch` as the second argument and the full endpoint URL as the third.
373
+ By default, the saved-scan deduplication APIs use environment credentials. A
374
+ custom SDK `embedding` binding can supply an adapter with its own credentials,
375
+ including an `OpenAiFindingEmbedder` with a renewable key callback.
376
+
377
+ ### Direct storage helpers
378
+
379
+ Direct callers of the retired Python findings helpers can use the retained Node
380
+ helpers from an installed plugin directory:
381
+
382
+ ```bash
383
+ scripts/launch_codex_security_mcp --helper list-stored-findings < request.json
384
+ ```
385
+
386
+ On Windows, use `scripts\launch_codex_security_mcp.cmd` with the same arguments
387
+ and JSON on stdin. For example, `request.json` selects the existing database:
388
+
389
+ ```json
390
+ {
391
+ "stateDirectory": "/absolute/path/to/state",
392
+ "payload": { "limit": 50, "offset": 0 }
393
+ }
394
+ ```
395
+
396
+ Use an absolute Windows path on Windows. The retained helper commands accept
397
+ these `payload` fields:
398
+
399
+ | Command | Payload |
400
+ | --------------------------- | ------------------------------------------------------------------------------------------------------- |
401
+ | `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
402
+ | `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
403
+ | `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
404
+ | `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
405
+ | `list-dedupe-groups` | `findingId`. |
406
+
407
+ Retained scan commands such as `workbench_db.py list-findings` keep their existing
408
+ interface.