@openai/codex-security 0.8.3 → 0.9.1

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 (534) hide show
  1. package/README.md +192 -151
  2. package/_bundled_plugin/.mcp.json +5 -1
  3. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  4. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  6. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  7. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  8. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  9. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  10. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/package.json +1 -0
  19. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  20. package/_bundled_plugin/mcp/server.mjs +2 -11
  21. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  22. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  23. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  24. package/_bundled_plugin/references/final-report.md +5 -3
  25. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  26. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  27. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  28. package/_bundled_plugin/references/scan-contract.md +27 -33
  29. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  30. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  31. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  32. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  33. package/_bundled_plugin/scripts/deep_scan_workbench.py +165 -342
  34. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  35. package/_bundled_plugin/scripts/finalize_scan_contract.py +153 -227
  36. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  37. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  38. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  39. package/_bundled_plugin/scripts/posix_scan_local_files.py +11 -0
  40. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  41. package/_bundled_plugin/scripts/report_projection.py +81 -43
  42. package/_bundled_plugin/scripts/review_state.py +8 -2
  43. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  44. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  45. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  46. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  47. package/_bundled_plugin/scripts/windows_scan_local_files.py +388 -17
  48. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  49. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  50. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  51. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  52. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  53. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  54. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  55. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  56. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  57. package/_bundled_plugin/scripts/workbench_cli.py +30 -12
  58. package/_bundled_plugin/scripts/workbench_constants.py +10 -0
  59. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  60. package/_bundled_plugin/scripts/workbench_db.py +369 -137
  61. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  62. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  63. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  64. package/_bundled_plugin/scripts/workbench_native_indexes.py +12 -12
  65. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  66. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  67. package/_bundled_plugin/scripts/workbench_remediation.py +13 -0
  68. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  69. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -55
  70. package/_bundled_plugin/scripts/workbench_scan_start.py +83 -24
  71. package/_bundled_plugin/scripts/workbench_scan_usage.py +644 -68
  72. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  73. package/_bundled_plugin/scripts/workbench_setup.py +13 -1
  74. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  75. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  76. package/_bundled_plugin/scripts/workbench_target.py +127 -56
  77. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  78. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  79. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -23
  80. package/_bundled_plugin/shared/workbench-migrations.json +34 -0
  81. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  82. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  83. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -1
  84. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -25
  85. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  86. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  87. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  88. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  90. package/dist/api.d.ts +39 -4
  91. package/dist/api.d.ts.map +1 -1
  92. package/dist/api.js +774 -292
  93. package/dist/api.js.map +1 -1
  94. package/dist/auth.d.ts.map +1 -1
  95. package/dist/auth.js +4 -6
  96. package/dist/auth.js.map +1 -1
  97. package/dist/bedrock-oss-pricing.d.ts +6 -0
  98. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  99. package/dist/bedrock-oss-pricing.js +58 -0
  100. package/dist/bedrock-oss-pricing.js.map +1 -0
  101. package/dist/bedrock-pricing.d.ts +15 -0
  102. package/dist/bedrock-pricing.d.ts.map +1 -0
  103. package/dist/bedrock-pricing.js +117 -0
  104. package/dist/bedrock-pricing.js.map +1 -0
  105. package/dist/blackduck-findings.d.ts.map +1 -1
  106. package/dist/blackduck-findings.js +35 -20
  107. package/dist/blackduck-findings.js.map +1 -1
  108. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  109. package/dist/bulk-scan-discovery.js +4 -4
  110. package/dist/bulk-scan-discovery.js.map +1 -1
  111. package/dist/checkmarx-evidence.d.ts +19 -0
  112. package/dist/checkmarx-evidence.d.ts.map +1 -0
  113. package/dist/checkmarx-evidence.js +36 -0
  114. package/dist/checkmarx-evidence.js.map +1 -0
  115. package/dist/checkmarx-findings.d.ts +4 -0
  116. package/dist/checkmarx-findings.d.ts.map +1 -0
  117. package/dist/checkmarx-findings.js +27 -0
  118. package/dist/checkmarx-findings.js.map +1 -0
  119. package/dist/checkmarx-one.d.ts +4 -0
  120. package/dist/checkmarx-one.d.ts.map +1 -0
  121. package/dist/checkmarx-one.js +53 -0
  122. package/dist/checkmarx-one.js.map +1 -0
  123. package/dist/checkmarx-repository.d.ts +12 -0
  124. package/dist/checkmarx-repository.d.ts.map +1 -0
  125. package/dist/checkmarx-repository.js +181 -0
  126. package/dist/checkmarx-repository.js.map +1 -0
  127. package/dist/checkmarx-xml.d.ts +12 -0
  128. package/dist/checkmarx-xml.d.ts.map +1 -0
  129. package/dist/checkmarx-xml.js +196 -0
  130. package/dist/checkmarx-xml.js.map +1 -0
  131. package/dist/classify-severity-records.d.ts +1 -9
  132. package/dist/classify-severity-records.d.ts.map +1 -1
  133. package/dist/classify-severity-records.js +3 -13
  134. package/dist/classify-severity-records.js.map +1 -1
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +2 -4
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli.d.ts +11 -5
  139. package/dist/cli.d.ts.map +1 -1
  140. package/dist/cli.js +1734 -1238
  141. package/dist/cli.js.map +1 -1
  142. package/dist/cloud-publish.js +2 -2
  143. package/dist/cloud-publish.js.map +1 -1
  144. package/dist/component-scan.d.ts +16 -3
  145. package/dist/component-scan.d.ts.map +1 -1
  146. package/dist/component-scan.js +27 -2
  147. package/dist/component-scan.js.map +1 -1
  148. package/dist/config.d.ts.map +1 -1
  149. package/dist/config.js +100 -66
  150. package/dist/config.js.map +1 -1
  151. package/dist/continuum-findings.d.ts.map +1 -1
  152. package/dist/continuum-findings.js +80 -12
  153. package/dist/continuum-findings.js.map +1 -1
  154. package/dist/contract-values.d.ts +2 -0
  155. package/dist/contract-values.d.ts.map +1 -1
  156. package/dist/contract-values.js +12 -9
  157. package/dist/contract-values.js.map +1 -1
  158. package/dist/cost-model.d.ts +13 -1
  159. package/dist/cost-model.d.ts.map +1 -1
  160. package/dist/cost-model.js +66 -112
  161. package/dist/cost-model.js.map +1 -1
  162. package/dist/cost.d.ts +42 -3
  163. package/dist/cost.d.ts.map +1 -1
  164. package/dist/cost.js +483 -104
  165. package/dist/cost.js.map +1 -1
  166. package/dist/custom-publish.d.ts +4 -0
  167. package/dist/custom-publish.d.ts.map +1 -1
  168. package/dist/custom-publish.js +40 -3
  169. package/dist/custom-publish.js.map +1 -1
  170. package/dist/deduplication/local.d.ts +2 -2
  171. package/dist/deduplication/local.d.ts.map +1 -1
  172. package/dist/deduplication/local.js +2 -2
  173. package/dist/deduplication/local.js.map +1 -1
  174. package/dist/deduplication/refusal.d.ts.map +1 -1
  175. package/dist/deduplication/refusal.js +25 -5
  176. package/dist/deduplication/refusal.js.map +1 -1
  177. package/dist/deduplication/scan.d.ts +3 -0
  178. package/dist/deduplication/scan.d.ts.map +1 -1
  179. package/dist/deduplication/scan.js +1 -1
  180. package/dist/deduplication/scan.js.map +1 -1
  181. package/dist/deep-config.d.ts +0 -1
  182. package/dist/deep-config.d.ts.map +1 -1
  183. package/dist/deep-config.js +22 -33
  184. package/dist/deep-config.js.map +1 -1
  185. package/dist/deep-scan-defaults.d.ts +2 -0
  186. package/dist/deep-scan-defaults.d.ts.map +1 -1
  187. package/dist/deep-scan-defaults.js +28 -1
  188. package/dist/deep-scan-defaults.js.map +1 -1
  189. package/dist/deep-scan.d.ts +2 -0
  190. package/dist/deep-scan.d.ts.map +1 -1
  191. package/dist/deep-scan.js +28 -4
  192. package/dist/deep-scan.js.map +1 -1
  193. package/dist/default-severity-rubric.d.ts +1 -1
  194. package/dist/default-severity-rubric.d.ts.map +1 -1
  195. package/dist/default-severity-rubric.js +1 -1
  196. package/dist/default-severity-rubric.js.map +1 -1
  197. package/dist/endor-findings.d.ts +3 -1
  198. package/dist/endor-findings.d.ts.map +1 -1
  199. package/dist/endor-findings.js +103 -45
  200. package/dist/endor-findings.js.map +1 -1
  201. package/dist/errors.d.ts +1 -1
  202. package/dist/errors.d.ts.map +1 -1
  203. package/dist/errors.js +8 -1
  204. package/dist/errors.js.map +1 -1
  205. package/dist/external-findings-import.d.ts +5 -3
  206. package/dist/external-findings-import.d.ts.map +1 -1
  207. package/dist/external-findings-import.js +7 -6
  208. package/dist/external-findings-import.js.map +1 -1
  209. package/dist/external-findings-local.d.ts +7 -5
  210. package/dist/external-findings-local.d.ts.map +1 -1
  211. package/dist/external-findings-local.js +337 -89
  212. package/dist/external-findings-local.js.map +1 -1
  213. package/dist/external-findings-publish.d.ts +8 -6
  214. package/dist/external-findings-publish.d.ts.map +1 -1
  215. package/dist/external-findings-publish.js +1318 -258
  216. package/dist/external-findings-publish.js.map +1 -1
  217. package/dist/external-findings-read.d.ts +20 -2
  218. package/dist/external-findings-read.d.ts.map +1 -1
  219. package/dist/external-findings-read.js +148 -66
  220. package/dist/external-findings-read.js.map +1 -1
  221. package/dist/external-findings.d.ts +15 -3
  222. package/dist/external-findings.d.ts.map +1 -1
  223. package/dist/external-findings.js +42 -1
  224. package/dist/external-findings.js.map +1 -1
  225. package/dist/external-import-contract.d.ts +5 -1
  226. package/dist/external-import-contract.d.ts.map +1 -1
  227. package/dist/external-import-contract.js +23 -9
  228. package/dist/external-import-contract.js.map +1 -1
  229. package/dist/external-import-models.d.ts +1 -1
  230. package/dist/external-import-models.d.ts.map +1 -1
  231. package/dist/external-import-models.js.map +1 -1
  232. package/dist/feedback.d.ts.map +1 -1
  233. package/dist/feedback.js +5 -4
  234. package/dist/feedback.js.map +1 -1
  235. package/dist/finding-prompt.d.ts +5 -0
  236. package/dist/finding-prompt.d.ts.map +1 -0
  237. package/dist/finding-prompt.js +32 -0
  238. package/dist/finding-prompt.js.map +1 -0
  239. package/dist/findings-client.d.ts +1 -0
  240. package/dist/findings-client.d.ts.map +1 -1
  241. package/dist/findings-client.js +27 -3
  242. package/dist/findings-client.js.map +1 -1
  243. package/dist/github-advisories.d.ts.map +1 -1
  244. package/dist/github-advisories.js +0 -2
  245. package/dist/github-advisories.js.map +1 -1
  246. package/dist/github-dependabot-findings.d.ts.map +1 -1
  247. package/dist/github-dependabot-findings.js +15 -4
  248. package/dist/github-dependabot-findings.js.map +1 -1
  249. package/dist/github-findings.d.ts +4 -1
  250. package/dist/github-findings.d.ts.map +1 -1
  251. package/dist/github-findings.js +55 -30
  252. package/dist/github-findings.js.map +1 -1
  253. package/dist/hosted-git-remotes.d.ts +5 -0
  254. package/dist/hosted-git-remotes.d.ts.map +1 -0
  255. package/dist/hosted-git-remotes.js +285 -0
  256. package/dist/hosted-git-remotes.js.map +1 -0
  257. package/dist/hosted-git-repository.d.ts +28 -0
  258. package/dist/hosted-git-repository.d.ts.map +1 -0
  259. package/dist/hosted-git-repository.js +222 -0
  260. package/dist/hosted-git-repository.js.map +1 -0
  261. package/dist/hosted-scan-protocol.js +2 -2
  262. package/dist/hosted-scan-protocol.js.map +1 -1
  263. package/dist/hosted-scan.d.ts.map +1 -1
  264. package/dist/hosted-scan.js +16 -11
  265. package/dist/hosted-scan.js.map +1 -1
  266. package/dist/hosted-scanner-http.d.ts +21 -0
  267. package/dist/hosted-scanner-http.d.ts.map +1 -0
  268. package/dist/hosted-scanner-http.js +204 -0
  269. package/dist/hosted-scanner-http.js.map +1 -0
  270. package/dist/hosted-scanner-v1.d.ts +6 -0
  271. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  272. package/dist/hosted-scanner-v1.js +60 -0
  273. package/dist/hosted-scanner-v1.js.map +1 -0
  274. package/dist/import-scan.d.ts.map +1 -1
  275. package/dist/import-scan.js +3 -0
  276. package/dist/import-scan.js.map +1 -1
  277. package/dist/index.d.ts +18 -7
  278. package/dist/index.d.ts.map +1 -1
  279. package/dist/index.js +10 -2
  280. package/dist/index.js.map +1 -1
  281. package/dist/inspector-findings.d.ts.map +1 -1
  282. package/dist/inspector-findings.js +47 -65
  283. package/dist/inspector-findings.js.map +1 -1
  284. package/dist/knowledge-base.d.ts.map +1 -1
  285. package/dist/knowledge-base.js +68 -5
  286. package/dist/knowledge-base.js.map +1 -1
  287. package/dist/local-git-metadata.d.ts +1 -1
  288. package/dist/local-git-metadata.d.ts.map +1 -1
  289. package/dist/local-git-metadata.js +1 -2
  290. package/dist/local-git-metadata.js.map +1 -1
  291. package/dist/multiscan.d.ts +6 -4
  292. package/dist/multiscan.d.ts.map +1 -1
  293. package/dist/multiscan.js +138 -65
  294. package/dist/multiscan.js.map +1 -1
  295. package/dist/native-json-findings.d.ts +2 -1
  296. package/dist/native-json-findings.d.ts.map +1 -1
  297. package/dist/native-json-findings.js +12 -2
  298. package/dist/native-json-findings.js.map +1 -1
  299. package/dist/opengrep-findings.d.ts +1 -0
  300. package/dist/opengrep-findings.d.ts.map +1 -1
  301. package/dist/opengrep-findings.js +17 -13
  302. package/dist/opengrep-findings.js.map +1 -1
  303. package/dist/operation-telemetry.d.ts +104 -0
  304. package/dist/operation-telemetry.d.ts.map +1 -0
  305. package/dist/operation-telemetry.js +293 -0
  306. package/dist/operation-telemetry.js.map +1 -0
  307. package/dist/plugin-python-probe.d.ts +4 -0
  308. package/dist/plugin-python-probe.d.ts.map +1 -0
  309. package/dist/plugin-python-probe.js +10 -0
  310. package/dist/plugin-python-probe.js.map +1 -0
  311. package/dist/private-finding-import.d.ts +97 -2
  312. package/dist/private-finding-import.d.ts.map +1 -1
  313. package/dist/private-finding-import.js +58 -34
  314. package/dist/private-finding-import.js.map +1 -1
  315. package/dist/provider-profile.d.ts +1 -1
  316. package/dist/provider-profile.d.ts.map +1 -1
  317. package/dist/provider-profile.js +8 -1
  318. package/dist/provider-profile.js.map +1 -1
  319. package/dist/publication-telemetry.d.ts +45 -0
  320. package/dist/publication-telemetry.d.ts.map +1 -0
  321. package/dist/publication-telemetry.js +50 -0
  322. package/dist/publication-telemetry.js.map +1 -0
  323. package/dist/publish.d.ts +4 -0
  324. package/dist/publish.d.ts.map +1 -1
  325. package/dist/publish.js +42 -2
  326. package/dist/publish.js.map +1 -1
  327. package/dist/reader-selection.d.ts +2 -0
  328. package/dist/reader-selection.d.ts.map +1 -1
  329. package/dist/reader-selection.js +8 -0
  330. package/dist/reader-selection.js.map +1 -1
  331. package/dist/remediation.d.ts +1 -4
  332. package/dist/remediation.d.ts.map +1 -1
  333. package/dist/remediation.js +3 -7
  334. package/dist/remediation.js.map +1 -1
  335. package/dist/request-metadata.d.ts +3 -0
  336. package/dist/request-metadata.d.ts.map +1 -1
  337. package/dist/request-metadata.js +9 -0
  338. package/dist/request-metadata.js.map +1 -1
  339. package/dist/result.d.ts +4 -0
  340. package/dist/result.d.ts.map +1 -1
  341. package/dist/result.js +1 -1
  342. package/dist/result.js.map +1 -1
  343. package/dist/retry-windows-rename.d.ts +8 -0
  344. package/dist/retry-windows-rename.d.ts.map +1 -0
  345. package/dist/retry-windows-rename.js +24 -0
  346. package/dist/retry-windows-rename.js.map +1 -0
  347. package/dist/runtime.d.ts +20 -0
  348. package/dist/runtime.d.ts.map +1 -1
  349. package/dist/runtime.js +313 -110
  350. package/dist/runtime.js.map +1 -1
  351. package/dist/saved-scan-bootstrap.d.ts +1 -0
  352. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  353. package/dist/saved-scan-bootstrap.js +18 -15
  354. package/dist/saved-scan-bootstrap.js.map +1 -1
  355. package/dist/scan-activity.d.ts.map +1 -1
  356. package/dist/scan-activity.js +141 -56
  357. package/dist/scan-activity.js.map +1 -1
  358. package/dist/scan-comparison.d.ts +10 -5
  359. package/dist/scan-comparison.d.ts.map +1 -1
  360. package/dist/scan-comparison.js +60 -15
  361. package/dist/scan-comparison.js.map +1 -1
  362. package/dist/scan-dashboard.d.ts +6 -6
  363. package/dist/scan-dashboard.d.ts.map +1 -1
  364. package/dist/scan-dashboard.js +75 -42
  365. package/dist/scan-dashboard.js.map +1 -1
  366. package/dist/scan-executor.d.ts +10 -1
  367. package/dist/scan-executor.d.ts.map +1 -1
  368. package/dist/scan-executor.js +22 -2
  369. package/dist/scan-executor.js.map +1 -1
  370. package/dist/scan-history-renderer.d.ts.map +1 -1
  371. package/dist/scan-history-renderer.js +9 -19
  372. package/dist/scan-history-renderer.js.map +1 -1
  373. package/dist/scan-logs.d.ts +12 -0
  374. package/dist/scan-logs.d.ts.map +1 -1
  375. package/dist/scan-logs.js +106 -77
  376. package/dist/scan-logs.js.map +1 -1
  377. package/dist/scan-measurement.d.ts +26 -0
  378. package/dist/scan-measurement.d.ts.map +1 -0
  379. package/dist/scan-measurement.js +77 -0
  380. package/dist/scan-measurement.js.map +1 -0
  381. package/dist/scan-progress.d.ts +1 -0
  382. package/dist/scan-progress.d.ts.map +1 -1
  383. package/dist/scan-progress.js +3 -0
  384. package/dist/scan-progress.js.map +1 -1
  385. package/dist/scan-sessions.d.ts.map +1 -1
  386. package/dist/scan-sessions.js +4 -1
  387. package/dist/scan-sessions.js.map +1 -1
  388. package/dist/scan-settings.d.ts +1 -1
  389. package/dist/scan-settings.d.ts.map +1 -1
  390. package/dist/scan-settings.js +1 -24
  391. package/dist/scan-settings.js.map +1 -1
  392. package/dist/scanner-import.d.ts +20 -2
  393. package/dist/scanner-import.d.ts.map +1 -1
  394. package/dist/scanner-import.js +200 -8
  395. package/dist/scanner-import.js.map +1 -1
  396. package/dist/scanner-repository-url.d.ts +4 -1
  397. package/dist/scanner-repository-url.d.ts.map +1 -1
  398. package/dist/scanner-repository-url.js +10 -6
  399. package/dist/scanner-repository-url.js.map +1 -1
  400. package/dist/security-policy.d.ts +1 -1
  401. package/dist/security-policy.d.ts.map +1 -1
  402. package/dist/security-policy.js.map +1 -1
  403. package/dist/semgrep-findings.d.ts +6 -3
  404. package/dist/semgrep-findings.d.ts.map +1 -1
  405. package/dist/semgrep-findings.js +107 -43
  406. package/dist/semgrep-findings.js.map +1 -1
  407. package/dist/semgrep-guardian-findings.d.ts +38 -0
  408. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  409. package/dist/semgrep-guardian-findings.js +165 -0
  410. package/dist/semgrep-guardian-findings.js.map +1 -0
  411. package/dist/semgrep-platform-collector.d.ts +26 -0
  412. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  413. package/dist/semgrep-platform-collector.js +108 -0
  414. package/dist/semgrep-platform-collector.js.map +1 -0
  415. package/dist/semgrep-platform-findings.d.ts +207 -6
  416. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  417. package/dist/semgrep-platform-findings.js +983 -103
  418. package/dist/semgrep-platform-findings.js.map +1 -1
  419. package/dist/semgrep-platform-v1.d.ts +6 -0
  420. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  421. package/dist/semgrep-platform-v1.js +83 -0
  422. package/dist/semgrep-platform-v1.js.map +1 -0
  423. package/dist/server/api.d.ts +1 -1
  424. package/dist/server/api.d.ts.map +1 -1
  425. package/dist/server/api.js.map +1 -1
  426. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  427. package/dist/server/embedding-tokenizer.d.ts +2 -0
  428. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  429. package/dist/server/embedding-tokenizer.js +322 -0
  430. package/dist/server/embedding-tokenizer.js.map +6 -0
  431. package/dist/server/embeddings.d.ts +16 -2
  432. package/dist/server/embeddings.d.ts.map +1 -1
  433. package/dist/server/embeddings.js +35 -5
  434. package/dist/server/embeddings.js.map +1 -1
  435. package/dist/session-lines.d.ts +5 -0
  436. package/dist/session-lines.d.ts.map +1 -0
  437. package/dist/session-lines.js +60 -0
  438. package/dist/session-lines.js.map +1 -0
  439. package/dist/severity-review.d.ts +3 -1
  440. package/dist/severity-review.d.ts.map +1 -1
  441. package/dist/severity-review.js +3 -2
  442. package/dist/severity-review.js.map +1 -1
  443. package/dist/skill-authentication.d.ts +1 -0
  444. package/dist/skill-authentication.d.ts.map +1 -1
  445. package/dist/skill-authentication.js +1 -0
  446. package/dist/skill-authentication.js.map +1 -1
  447. package/dist/snyk-findings.d.ts +7 -2
  448. package/dist/snyk-findings.d.ts.map +1 -1
  449. package/dist/snyk-findings.js +93 -70
  450. package/dist/snyk-findings.js.map +1 -1
  451. package/dist/snyk-rest-findings.d.ts +76 -0
  452. package/dist/snyk-rest-findings.d.ts.map +1 -0
  453. package/dist/snyk-rest-findings.js +1051 -0
  454. package/dist/snyk-rest-findings.js.map +1 -0
  455. package/dist/snyk-rest-v1.d.ts +28 -0
  456. package/dist/snyk-rest-v1.d.ts.map +1 -0
  457. package/dist/snyk-rest-v1.js +132 -0
  458. package/dist/snyk-rest-v1.js.map +1 -0
  459. package/dist/snyk-token-origin.d.ts +4 -0
  460. package/dist/snyk-token-origin.d.ts.map +1 -0
  461. package/dist/snyk-token-origin.js +82 -0
  462. package/dist/snyk-token-origin.js.map +1 -0
  463. package/dist/sonar-collector.d.ts.map +1 -1
  464. package/dist/sonar-collector.js +0 -3
  465. package/dist/sonar-collector.js.map +1 -1
  466. package/dist/sonar-import.d.ts.map +1 -1
  467. package/dist/sonar-import.js +2 -4
  468. package/dist/sonar-import.js.map +1 -1
  469. package/dist/target-drift.d.ts +9 -0
  470. package/dist/target-drift.d.ts.map +1 -0
  471. package/dist/target-drift.js +27 -0
  472. package/dist/target-drift.js.map +1 -0
  473. package/dist/targets.d.ts +2 -0
  474. package/dist/targets.d.ts.map +1 -1
  475. package/dist/targets.js +56 -20
  476. package/dist/targets.js.map +1 -1
  477. package/dist/tenable-findings.d.ts +9 -0
  478. package/dist/tenable-findings.d.ts.map +1 -0
  479. package/dist/tenable-findings.js +122 -0
  480. package/dist/tenable-findings.js.map +1 -0
  481. package/dist/terminal-stream.d.ts +13 -0
  482. package/dist/terminal-stream.d.ts.map +1 -0
  483. package/dist/terminal-stream.js +35 -0
  484. package/dist/terminal-stream.js.map +1 -0
  485. package/dist/trivy-findings.d.ts +19 -0
  486. package/dist/trivy-findings.d.ts.map +1 -0
  487. package/dist/trivy-findings.js +435 -0
  488. package/dist/trivy-findings.js.map +1 -0
  489. package/dist/trivy-import.d.ts +19 -0
  490. package/dist/trivy-import.d.ts.map +1 -0
  491. package/dist/trivy-import.js +151 -0
  492. package/dist/trivy-import.js.map +1 -0
  493. package/dist/validation-records.js +1 -1
  494. package/dist/validation-records.js.map +1 -1
  495. package/dist/veracode-findings.d.ts +2 -0
  496. package/dist/veracode-findings.d.ts.map +1 -1
  497. package/dist/veracode-findings.js +49 -11
  498. package/dist/veracode-findings.js.map +1 -1
  499. package/dist/vertex-pricing.d.ts +8 -0
  500. package/dist/vertex-pricing.d.ts.map +1 -0
  501. package/dist/vertex-pricing.js +20 -0
  502. package/dist/vertex-pricing.js.map +1 -0
  503. package/dist/windows-path.d.ts +1 -0
  504. package/dist/windows-path.d.ts.map +1 -1
  505. package/dist/windows-path.js +26 -1
  506. package/dist/windows-path.js.map +1 -1
  507. package/dist/wiz-findings.d.ts +4 -0
  508. package/dist/wiz-findings.d.ts.map +1 -1
  509. package/dist/wiz-findings.js +57 -3
  510. package/dist/wiz-findings.js.map +1 -1
  511. package/docs/classify-severity-records.md +27 -12
  512. package/docs/cli.md +497 -550
  513. package/docs/dedupe-records.md +44 -24
  514. package/docs/findings-service.md +66 -39
  515. package/docs/hosted-remediation.md +14 -7
  516. package/docs/hosted-scans.md +50 -42
  517. package/docs/telemetry.md +236 -0
  518. package/docs/validate-records.md +78 -44
  519. package/package.json +18 -15
  520. package/schemas/external-findings.schema.json +3 -1
  521. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  522. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  523. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  524. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  525. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  526. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  527. package/dist/external-imports-feature.d.ts +0 -6
  528. package/dist/external-imports-feature.d.ts.map +0 -1
  529. package/dist/external-imports-feature.js +0 -51
  530. package/dist/external-imports-feature.js.map +0 -1
  531. package/dist/finding-normalization.d.ts +0 -5
  532. package/dist/finding-normalization.d.ts.map +0 -1
  533. package/dist/finding-normalization.js +0 -155
  534. package/dist/finding-normalization.js.map +0 -1
package/docs/cli.md CHANGED
@@ -16,13 +16,6 @@ codex-security info --json
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
17
  `scans` and `findings` default to their `list` subcommands.
18
18
 
19
- To retrieve GitHub code scanning alerts without an MCP server, use
20
- [`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
21
- findings file in local scan history, use
22
- [`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
23
- GitHub import returns upstream alerts for validation; file import saves findings
24
- without running security analysis.
25
-
26
19
  ## Find a workflow
27
20
 
28
21
  - [Sign in or configure a provider](#authentication).
@@ -31,10 +24,8 @@ without running security analysis.
31
24
  [save project settings](#project-files).
32
25
  - [Review one system across repositories](#review-one-system-across-repositories)
33
26
  or [run independent bulk scans](#bulk-scans).
34
- - [Import vendor findings locally](#import-vendor-findings-locally),
35
- [import Sonar issues selected in Codex](#import-sonarqube-cloud-issues),
36
- [save findings as a scan](#import-findings-as-a-saved-scan), or
37
- [retrieve GitHub alerts](#import-alerts-from-the-cli).
27
+ - [Choose an import command](#import-vendor-findings-locally) to save a scan,
28
+ collect upstream alerts, or store vendor evidence locally or in Cloud.
38
29
  - [Inspect saved scans and rerun them](#scan-history-and-reruns),
39
30
  [classify severity](#classify-finding-severity), or
40
31
  [suggest owners](#suggest-finding-owners).
@@ -87,7 +78,9 @@ your local browser. Keep SSH connected until login finishes.
87
78
  ### OpenAI credentials
88
79
 
89
80
  Interactive scans ask which credentials to use when both ChatGPT and an
90
- environment API key are available. Noninteractive commands prefer
81
+ environment API key are available. A dedicated sign-in takes precedence. After
82
+ `codex-security logout`, the prompt skips the ambient sign-in until you log in
83
+ again. Noninteractive commands prefer
91
84
  `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
92
85
  with `--auth`:
93
86
 
@@ -104,12 +97,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
104
97
  chosen authentication. Environment keys do not replace the saved login.
105
98
  The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
106
99
 
100
+ For a scan using a custom native provider, `auto` and `api-key` use the
101
+ environment variable declared by `model_providers.<id>.env_key`, including
102
+ when a Codex file profile selects that provider. Set that variable before
103
+ starting the scan. To use `--auth chatgpt`, select a provider configured for
104
+ account authentication. A custom provider that requires its own key cannot
105
+ honor that combination.
106
+
107
107
  Stored OpenAI credentials live in
108
108
  `$CODEX_SECURITY_STATE_DIR/codex-home`, or
109
109
  `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
110
110
  outside the target and every enclosing Git worktree. It also serves providers
111
111
  with `requires_openai_auth = true`.
112
112
 
113
+ If you manually hard-linked the two homes’ `auth.json` files, keep both homes
114
+ accessible when running `codex-security logout`. When the CLI verifies the
115
+ two hard links, it removes the private link before invoking native logout.
116
+ If the ambient home is unavailable, the configured credential store handles
117
+ logout normally.
118
+
113
119
  Codex carries credential-storage, forced-login, and workspace settings from the
114
120
  ambient configuration into this home. Managed-device policies still apply;
115
121
  workspace-managed policies may require ChatGPT credentials even with an API key.
@@ -123,8 +129,19 @@ after logout completes.
123
129
  Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
124
130
  `HOME` or `USERPROFILE` environment setting.
125
131
 
126
- If credentials cannot refresh, run `login status`. Retry if the sign-in recently
127
- changed; otherwise run `logout`, then `login`.
132
+ If you use file-based ChatGPT credentials with both Codex and Codex Security,
133
+ run `codex-security login` before your first scan or status check to give Codex
134
+ Security its own session. An imported sign-in shares a single-use refresh token.
135
+ When either client renews it, the other client's next refresh can fail even
136
+ while its login status reports that it is signed in.
137
+
138
+ If Codex Security reports that the refresh token was already used, run
139
+ `codex-security logout`, then `codex-security login`. If your Codex CLI or app
140
+ reports that error, sign out and sign back in there.
141
+
142
+ For other refresh errors, check `codex-security login status`. Retry if the
143
+ sign-in recently changed. Otherwise run `codex-security logout`, then
144
+ `codex-security login`.
128
145
  Some cybersecurity requests and protected findings require
129
146
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
130
147
 
@@ -142,7 +159,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
142
159
  In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
143
160
  to explicitly turn it off.
144
161
  The setting carries through saved scan recipes, resumed scans, Deep Scan
145
- discovery and reducer workers, and `scan --patch`. Standalone `validate`,
162
+ discovery workers, and `scan --patch`. Standalone `validate`,
146
163
  `patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
147
164
  Threads created by these commands retain the setting when resumed in Codex.
148
165
  Scans use isolated configuration, so set it on the CLI, SDK client, or project
@@ -152,8 +169,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
152
169
  an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
153
170
  or set top-level `daybreak = true` in the configuration loaded by the runner.
154
171
  Deep Scan inherits the active turn's effective access program from its saved
155
- Codex session, including an explicit Standard selection. Discovery and reducer
156
- workers retain that selection when resumed. If the host does not supply a
172
+ Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
157
173
  persisted turn context, workers use their runner configuration; CLI and SDK scans
158
174
  use the explicit scan settings above.
159
175
 
@@ -181,7 +197,7 @@ codex-security scan /path/to/repository \
181
197
  In the SDK, select your model through `codexOverrides.model` and pass
182
198
  `auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
183
199
  Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
184
- The selection reaches discovery and reducer workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
200
+ The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
185
201
  for configuration precedence and the API-key feature setting.
186
202
 
187
203
  `access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
@@ -236,6 +252,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
236
252
  codex-security scan . --provider cheaperinference --model gpt-5.4
237
253
  ```
238
254
 
255
+ ### Hugging Face compatibility
256
+
257
+ In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
258
+ `namespace` and could request `web_search`. Hugging Face's published Responses
259
+ implementation accepts `function` and remote `mcp` tool declarations. A named
260
+ Hugging Face scan provider is deferred until the scanner and router can exchange
261
+ the tools a complete scan requires. [Hugging Face's implementation notes](https://huggingface.co/docs/inference-providers/en/guides/gpt-oss#responses-api)
262
+ and [request schema](https://github.com/huggingface/responses.js/blob/0e3e84c469a9f59ad16e2eb3a0d6f1c4de637a7b/src/schemas.ts#L219-L232).
263
+
239
264
  ### Amazon Bedrock
240
265
 
241
266
  Use AWS credentials and a region with access to the exact Bedrock model ID:
@@ -255,6 +280,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
255
280
  for credential alternatives, restricted-model access, cost estimates, and
256
281
  reasoning-summary configuration.
257
282
 
283
+ ### Google Cloud Vertex AI cost estimates
284
+
285
+ The SDK estimates Standard online inference costs for OpenAI models served by
286
+ Google Cloud's Model as a Service (MaaS). Rates are in USD per million tokens.
287
+ [Google Cloud partner model pricing](https://cloud.google.com/model-garden/partner-models/pricing)
288
+ and [OpenAI model locations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/maas/openai).
289
+
290
+ | Managed model ID | Location | Input | Cached input | Output |
291
+ | -------------------------- | ----------------------- | ----: | -----------: | -----: |
292
+ | `openai/gpt-oss-120b-maas` | `global` | $0.09 | $0.09 | $0.36 |
293
+ | `openai/gpt-oss-20b-maas` | `us-central1` (retired) | $0.07 | $0.007 | $0.25 |
294
+
295
+ Google publishes a cache-hit discount only for 20B, so the estimator uses the
296
+ ordinary input rate for cached 120B tokens. Google retired the managed 20B
297
+ endpoint on October 21, 2026. The SDK retains its rates for historical usage.
298
+ [Google Cloud retirement schedule](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/open-models).
299
+
300
+ To estimate recorded usage locally, pass the managed model ID and the GCP
301
+ provider to `estimateScanCost`.
302
+
303
+ ```ts
304
+ import { estimateScanCost } from "@openai/codex-security";
305
+
306
+ const cost = estimateScanCost(
307
+ "openai/gpt-oss-120b-maas",
308
+ { input_tokens: 1_000_000, output_tokens: 500_000 },
309
+ { provider: "gcp" },
310
+ );
311
+ // cost?.estimatedUsd is 0.27.
312
+ ```
313
+
314
+ Google documents the managed GPT OSS IDs on its shared chat-completions API.
315
+ The bundled Codex `gcp` provider uses Google's Responses API with a separate
316
+ frontier model catalog. Google has published no Standard token rates for that
317
+ catalog, including GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, and GPT-6 Luna.
318
+ Those scans record token usage and require a published price to use
319
+ `--max-cost`. Self-deployed Model Garden endpoints incur infrastructure charges.
320
+ [Google Cloud's preview announcement](https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-brings-openai-models-to-customers).
321
+
258
322
  ## Generate a security policy
259
323
 
260
324
  Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
@@ -430,6 +494,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
430
494
  requested work separately from optional `coverage.openQuestions` follow-up.
431
495
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
432
496
 
497
+ When a cost limit is configured, `scan --dry-run` shows the resolved
498
+ `maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
499
+ against the limit and why in-flight requests can exceed it.
500
+
433
501
  Whole-codebase and path scans also accept ordinary directories, including SVN
434
502
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
435
503
 
@@ -460,10 +528,17 @@ with every repository.
460
528
 
461
529
  Use `--output-dir DIR` to choose where a scan saves its results. The directory
462
530
  must be empty and outside the scanned directory and enclosing Git worktree.
463
- Existing directories keep their permissions; newly created directories are
464
- private to you by default.
465
- `--archive-existing` moves earlier output to
466
- `<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
531
+ Existing directories keep their permissions. Newly created directories are
532
+ private to you by default. On Windows, the directory and its parents must be
533
+ owned by your account, Administrators, SYSTEM, or TrustedInstaller. Choose a
534
+ path where another user cannot replace the output directory or one of its
535
+ parents. A parent can allow other users to read it or create sibling directories.
536
+ For an empty write destination, grant content-writing permissions to children
537
+ through inheritance. Other users must not have permission to set reparse data
538
+ on the destination directory itself.
539
+ `--archive-existing` moves earlier output to a sibling directory with a unique
540
+ suffix, such as `results.previous-ab12cd34` for an output directory named
541
+ `results`. Use `--dry-run` to preview the move.
467
542
 
468
543
  Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
469
544
  optional export fails, the scan can still complete. Use the
@@ -503,7 +578,9 @@ or JSONL output produce:
503
578
  { "status": "failed", "code": "SCAN_FAILED", "message": "..." }
504
579
  ```
505
580
 
506
- With `--full-output`, the error appears under `error` in an `ok: false` envelope.
581
+ With `--full-output`, JSON and JSONL failures put the error under `error` in an
582
+ `ok: false` envelope. YAML and TOON use the same failed envelope when retained
583
+ sealed scan results are available (including TOON selected by default).
507
584
  If the scan target changed, the error explains that the results no longer
508
585
  represent the current checkout. Retained sealed results remain available under
509
586
  `data`, including their manifest, findings, review summary, scan directory, and report
@@ -515,8 +592,8 @@ selecting an unavailable field can return `null` or omit `data`.
515
592
  Saved-scan setup failures use the same output shape with
516
593
  `SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
517
594
  available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
518
- scan uses `SCAN_IMPORT_FAILED` if the import fails. Other output formats retain
519
- stderr-only failures, including when `--full-output` is selected.
595
+ scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
596
+ on stderr without `--full-output`, or when retained results are unavailable.
520
597
 
521
598
  Diagnostics stay on stderr. Each command's `--schema --format json` describes
522
599
  its successful output and failure codes.
@@ -526,8 +603,9 @@ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
526
603
 
527
604
  Scans already validate findings against local source. Add `--validate` to run
528
605
  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
606
+ the scan, using the same selected Cyber access program. Validation sends each
607
+ finding to the configured model provider. Its review tools have read-only
608
+ filesystem access, with network access and web search disabled. Each assessment uses a
531
609
  separate evidence directory; the combined report is saved as
532
610
  `<scan-dir>/validation.md`, or a uniquely suffixed report
533
611
  if that path already exists. Each completed assessment is saved immediately;
@@ -571,26 +649,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
571
649
  fail after registration but before writing its artifacts; investigate those
572
650
  failures through its history record and any available logs. When artifacts were
573
651
  retained, use the saved results directory returned by `scans show` to inspect
574
- whichever of these files are present:
575
-
576
- | File | What to check |
577
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
578
- | `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
579
- | `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
580
- | `coverage.json` | `includePaths` and `excludePaths` for scope boundaries; `explicitExclusions` for recorded exclusion reasons; `surfaces` for reviewed areas; `deferred` for unfinished review work; and optional `openQuestions`. |
581
-
582
- Deferred items can identify affected `paths` or `surfaceIds`. Surface
583
- `receiptRefs` link to retained evidence under `artifacts/` when available.
584
- Deep Scan summaries retain coverage from accepted worker reviews, including
585
- worker-specific deferred work. Check those details as well as the final findings.
586
-
587
- These records describe what the scan recorded, not an exhaustive file-by-file
588
- audit. A retained source inventory, when present, lists inputs rather than
589
- proving that each file was reviewed. An absent path in a surface summary does not
590
- establish whether it was read, and the scan ID cannot reconstruct evidence that
591
- was never saved.
592
- Session logs can help explain failures and tool activity, but do not prove
593
- complete review either.
652
+ the saved files:
653
+
654
+ | File | What to check |
655
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
656
+ | `scan-manifest.json` | `scan.status` and `scan.target` identify the outcome and snapshot. `scan.scope` lists requested inclusions and exclusions. `scan.review.excludedPaths` lists additional excluded paths in current scans. |
657
+ | `findings.json` | Reported findings, source locations and supporting evidence. |
658
+ | `report.md` | A readable summary of the scope and findings. |
659
+
660
+ When a checkpoint is retained, `checkpoint-head.json` identifies the file in
661
+ `checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
662
+ unfinished work and `reviewState.openQuestions` lists follow-up questions.
663
+ Older manifests with `scan.coverageRef` point to a separate `coverage.json`
664
+ with reviewed surfaces, explicit exclusions and deferred work. A saved source
665
+ inventory identifies inputs. Neither that inventory nor session logs establish
666
+ which files the scan reviewed in full.
594
667
 
595
668
  For a local plugin scan, ask Codex to open the saved scan and explain its scope,
596
669
  exclusions, deferred work, and follow-up questions. CLI history can also locate
@@ -634,12 +707,13 @@ completeness values to determine scan status or exit codes.
634
707
 
635
708
  ```bash
636
709
  codex-security init
637
- codex-security scan . -c codex-security.yaml --dry-run --json
638
710
  codex-security info -c codex-security.yaml --json
711
+ codex-security scan . -c codex-security.yaml --dry-run --json
639
712
  ```
640
713
 
641
714
  Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
642
- Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
715
+ Keep `-c` on both `info` and the scan preview to inspect the same target and
716
+ limits. Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
643
717
  `scan-components`, and `info` accept project files. SDK calls and saved reruns
644
718
  do not load them automatically.
645
719
 
@@ -693,7 +767,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
693
767
  Paths and snippets are fictional; repository files remain unchanged.
694
768
 
695
769
  Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
696
- archiving, and severity thresholds work normally. Reruns preserve mock mode.
770
+ archiving, and severity thresholds work normally. Use `scans show` to inspect a
771
+ mock scan. Mock scans have no Codex session logs. Reruns preserve mock mode.
697
772
  Separate matching or deduplication commands still make their usual model calls.
698
773
 
699
774
  Mock mode supports Standard repository, path, and diff scans. It cannot combine
@@ -772,7 +847,8 @@ individual scan folder.
772
847
  Failures do not stop other components. Failed scans or
773
848
  failed matching return `2`; severity-policy violations return `1`. Retry with
774
849
  `--components-file retry-components.json` and a new empty output directory.
775
- The retry report covers only those components.
850
+ The retry report covers only those components. Each registered component keeps its
851
+ scan ID in the summary, including when the scan fails.
776
852
 
777
853
  `--max-cost` applies per component, excluding planning and matching. `--model`
778
854
  and `--effort` also apply to matching; `--auth` applies throughout. Planning and
@@ -836,11 +912,18 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
836
912
  --stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
837
913
  ```
838
914
 
839
- For `scan --mode deep`, `--workers` controls discovery concurrency and
840
- `--subagents` controls subagents per worker. `--stop-after-no-new`,
841
- `--max-discovery-runs`, and `--max-time` stop discovery by novelty, count,
842
- or duration. At the deadline, discovery stops; the scan then combines and returns
843
- completed findings.
915
+ Deep Scan repeats Standard scans in batches of up to `--workers`, with
916
+ `--subagents` per scan. Workers can share what they are investigating, ask each
917
+ other to check a source location, and reply while their audits are running. Each
918
+ worker verifies the evidence it reports. Deep Scan merges each completed batch in launch order.
919
+ It uses source locations, cited code and weakness descriptions to match repeated
920
+ findings. Each group keeps its first description, all reported locations, and
921
+ the original observations. Later batches receive the titles and primary
922
+ locations of retained findings so workers can investigate other reachable paths.
923
+ `--stop-after-no-new` counts consecutive
924
+ completed scans that added no findings. `--max-discovery-runs` caps the total
925
+ number started, including failures. `--max-time` stops discovery and returns
926
+ the findings from completed scans.
844
927
 
845
928
  For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
846
929
 
@@ -850,6 +933,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
850
933
  its default and maximum are 5760 minutes (96 hours). Unlike Standard's
851
934
  advisory allowance, the Deep discovery limit is enforced. Resuming a
852
935
  Deep scan keeps its original deadline; rerunning starts a new scan.
936
+ If the deadline expires before any source review completes, the saved report
937
+ and scan manifest record that limitation.
853
938
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
854
939
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
855
940
  hours. Explicit settings override lower-priority configuration across units.
@@ -898,16 +983,17 @@ executable outside all saved scan targets. If a historical target includes the
898
983
  available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
899
984
  explicit saved scan ID. Exact-path `latest` lookup still works without Git.
900
985
 
901
- Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:
902
- `--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are
903
- rejected, including a `--model` or `--effort` flag plus its native equivalent.
986
+ Repeat `--codex KEY=VALUE` for supported native settings. For example,
987
+ `--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
988
+ Command Prompt, and PowerShell. Repeated or conflicting keys are rejected,
989
+ including a `--model` or `--effort` flag plus its native equivalent.
904
990
 
905
991
  To select a Codex file profile, put its settings in
906
992
  `$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
907
993
  `CODEX_HOME` is unset), then run:
908
994
 
909
995
  ```bash
910
- npx @openai/codex-security scan . --codex 'profile="review"'
996
+ npx @openai/codex-security scan . --codex "profile='review'"
911
997
  ```
912
998
 
913
999
  In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
@@ -933,11 +1019,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
933
1019
 
934
1020
  ```bash
935
1021
  codex-security patch "Security issue" --model gateway-model \
936
- --codex 'model_provider="gateway"' \
937
- --codex 'model_providers.gateway.name="Gateway"' \
938
- --codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \
939
- --codex 'model_providers.gateway.wire_api="responses"' \
940
- --codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'
1022
+ --codex "model_provider='gateway'" \
1023
+ --codex "model_providers.gateway.name='Gateway'" \
1024
+ --codex "model_providers.gateway.base_url='https://gateway.example.test/v1'" \
1025
+ --codex "model_providers.gateway.wire_api='responses'" \
1026
+ --codex "model_providers.gateway.env_key='GATEWAY_API_KEY'"
941
1027
  ```
942
1028
 
943
1029
  Set the provider's key environment variable before running. Patching and
@@ -963,12 +1049,14 @@ publication uses the same request attribution; embedding requests identify
963
1049
  the package and version in their `User-Agent`.
964
1050
 
965
1051
  These fields provide request attribution for supported inference providers, including
966
- Bedrock. They do not create a separate telemetry collector, record command
967
- starts or outcomes, or make another provider's traffic visible to OpenAI.
1052
+ Bedrock. They do not create a separate telemetry collector or make another
1053
+ provider's traffic visible to OpenAI. Local operation receipts separately record
1054
+ starts, outcomes, duration, and usage coverage; see
1055
+ [telemetry and measurement](telemetry.md).
968
1056
 
969
1057
  Disable Codex usage analytics and built-in metrics with
970
- `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
971
- patch-risk assessment, and Deep Scan discovery and reducer workers, including
1058
+ `--codex analytics.enabled=false`. The setting carries into `scan --patch`,
1059
+ patch-risk assessment, and Deep Scan discovery workers, including
972
1060
  resumed workers. Selected-profile settings take precedence over root settings.
973
1061
  Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
974
1062
  workers, including exporter choices and prompt-logging controls.
@@ -977,32 +1065,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
977
1065
  authentication, or CLI update checks. Validation uses isolated configuration;
978
1066
  patching and verification preserve ambient project trust.
979
1067
 
1068
+ For scan outcomes, the workbench saves a separate, local `lifecycle` record
1069
+ with the scan ID, launch surface, available release versions, mode, timestamps,
1070
+ and committed status. A completed scan indicates whether it produced reportable
1071
+ findings. Use `codex-security scans list --json` for the current repository.
1072
+ To find an offline import, use `codex-security scans list --scan-root <DIR> --json`
1073
+ with its output directory. Imported scans have lifecycle mode `import`. The SDK
1074
+ exposes `onLifecycle`, and the CLI includes observations in verbose diagnostics.
1075
+ Canceling a newly registered SDK scan through its abort signal, closing the
1076
+ client during the scan, or receiving a canceled hosted execution records
1077
+ `canceled`. A scan that has already completed keeps its committed outcome.
1078
+ Applications can choose how to collect and export these observations.
1079
+
980
1080
  For filesystem and approval behavior, see the
981
1081
  [local security model](../README.md#local-security-model).
982
1082
 
983
1083
  ### Environment variables
984
1084
 
985
- | Variable | Effect |
986
- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
987
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
988
- | `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS` | Set to `1` to enable vendor finding imports, imported-findings readback, and GitHub advisory acquisition; disabled otherwise. |
989
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
990
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
991
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
992
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
993
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
994
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
995
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
996
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
997
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
998
- | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
999
- | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
1000
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
1001
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
1002
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
1003
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
1004
- | `CI` | Disable interactive update notices. |
1005
- | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
1085
+ | Variable | Effect |
1086
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
1087
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
1088
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
1089
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
1090
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
1091
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
1092
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
1093
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
1094
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
1095
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
1096
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
1097
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
1098
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
1099
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
1100
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
1101
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
1102
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
1103
+ | `CI` | Disable interactive update notices. |
1104
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
1006
1105
 
1007
1106
  Custom Codex executables need thread source attribution for `exec` and
1008
1107
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -1016,7 +1115,8 @@ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage
1016
1115
  ### Troubleshooting
1017
1116
 
1018
1117
  Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
1019
- retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,
1118
+ retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events
1119
+ such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,
1020
1120
  saved failures, receipts, and patch-risk summaries. Review it for sensitive
1021
1121
  information before sharing; upstream Codex output may already be redacted.
1022
1122
 
@@ -1025,6 +1125,12 @@ Finish older-version operations before upgrading. Never remove
1025
1125
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
1026
1126
  credential home before manually removing an old `.codex-security-scan.lock`.
1027
1127
 
1128
+ If a scan reports that its state directory overlaps a protected root, choose a
1129
+ private directory in a separate tree, such as a sibling of the protected root.
1130
+ Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
1131
+ scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
1132
+ can match `"state"` for this case.
1133
+
1028
1134
  If credential-home preparation fails, the error includes the underlying
1029
1135
  filesystem diagnostic. For permission or read-only filesystem errors, check
1030
1136
  the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
@@ -1090,10 +1196,13 @@ their own timestamps, window durations, and reset times. These are historical
1090
1196
  observations, not a live allowance check or scan-only consumption. Empty readings
1091
1197
  mean allowance was unavailable. There is no token-to-allowance conversion here.
1092
1198
 
1093
- Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
1094
- and show a short/long-context range. They estimate model usage, excluding other
1095
- tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
1096
- subscription allowance. Models without known prices have no estimate.
1199
+ Cost displays use Standard token rates for the model. OpenAI models use
1200
+ [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). OpenAI
1201
+ models on Bedrock use [AWS pricing for the model, inference route, and region](https://github.com/openai/codex-security/blob/main/docs/bedrock.md#scan-cost-estimates).
1202
+ For managed OpenAI models on Vertex AI, see [Google Cloud Vertex AI cost estimates](#google-cloud-vertex-ai-cost-estimates).
1203
+ The short/long-context range estimates usage at published rates. Other service
1204
+ tiers, account discounts, and ChatGPT subscription allowance are outside that
1205
+ estimate. Models without known prices have no estimate.
1097
1206
 
1098
1207
  JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
1099
1208
  and `context: "unknown"`). A null maximum means no upper estimate is available.
@@ -1108,13 +1217,25 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
1108
1217
  Automatic history matching gets at most one extra call with a limit; if more
1109
1218
  work is needed, the scan is preserved and you can run `scans match --all`.
1110
1219
 
1111
- When Deep discovery has finished at a cost stop, the scan returns a sealed
1112
- report and lists unvalidated candidates as follow-up work. Reaching a configured
1113
- limit with a valid finalized report returns `0` by default, or `1` if findings
1114
- meet a configured failure threshold.
1115
-
1116
- When Codex reports an exhausted usage limit, Deep Scan cancels active workers
1117
- and stops retrying or launching replacements. Completed worker artifacts are retained.
1220
+ A scan with a cost limit requires complete token usage for its recorded scan,
1221
+ worker, and custom validation sessions before the SDK returns a completed result.
1222
+ Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
1223
+ `backports.zstd` installed in the selected Python environment.
1224
+ Missing or unreadable usage fails budget verification. Without a limit, usage
1225
+ reporting remains best effort.
1226
+
1227
+ When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
1228
+ report and retains unvalidated candidates as follow-up work. The saved report and
1229
+ the manifest's `scan.scope.limitations` record that validation was deferred.
1230
+ Reaching a configured limit with a valid finalized report returns `0` by default,
1231
+ or `1` if findings meet a configured failure threshold.
1232
+
1233
+ When a worker turn fails with a known cybersecurity policy refusal or an
1234
+ exhausted usage limit, Deep Scan stops retries and replacements, cancels active
1235
+ siblings, and retains completed worker artifacts. A capability check can succeed
1236
+ before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
1237
+ scan and its retained results. To run it again from a saved recipe, use
1238
+ `scans rerun SCAN_ID`, which starts fresh discovery.
1118
1239
 
1119
1240
  At 80% of a single interactive scan's limit, the dashboard offers a higher total
1120
1241
  budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
@@ -1224,6 +1345,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
1224
1345
  attempt per pending repository per invocation. Repeating the command continues
1225
1346
  the campaign, skips completed results, and starts pending attempts. Occupied
1226
1347
  attempt directories stop that repository and suggest `--recover`.
1348
+ If an ordinary attempt finds its checkout path already occupied, it stops before
1349
+ fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
1350
+ existing checkout before an ordinary retry.
1351
+ If checkout cleanup previously failed, the next invocation removes it only when
1352
+ its marker still identifies the same directory and scan attempt. Older or
1353
+ replacement checkouts without a matching marker are preserved.
1227
1354
  Completed results are skipped only when their saved contract and seal are valid
1228
1355
  and the manifest records a completed scan. Damaged or unsuccessful results get a
1229
1356
  new attempt, including with `--recover`, while the old artifacts remain available.
@@ -1253,10 +1380,12 @@ failed or interrupted attempt:
1253
1380
  - An unavailable, failed, or canceled scan starts a new attempt at the pinned
1254
1381
  revision, preserving old artifacts and checkouts.
1255
1382
 
1256
- If a nonempty committed line in `results.jsonl` contains invalid JSON or lacks
1257
- a string task ID, the command reports its line number and leaves the ledger untouched.
1258
- Restore a complete ledger backup that includes every committed attempt, or start
1259
- a separate campaign in a new `--output-dir`.
1383
+ Each nonempty committed line in `results.jsonl` must be valid JSON with a string
1384
+ task ID and a positive safe integer attempt number. If a line fails these checks,
1385
+ the command reports its line number and preserves the ledger. Restore a complete
1386
+ ledger backup that includes every committed attempt, or start a separate campaign
1387
+ in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
1388
+ a fresh attempt requires a new campaign.
1260
1389
 
1261
1390
  New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
1262
1391
  workers and one recovery/new attempt per repository. A resume connection failure
@@ -1326,32 +1455,56 @@ Supply the validation prompt again when rerunning.
1326
1455
 
1327
1456
  ## Import vendor findings locally
1328
1457
 
1329
- Choose an input in the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
1330
- Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
1331
- to confirm the import and read the resulting records.
1458
+ Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
1332
1459
 
1333
- Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` to enable `publish findings`,
1334
- `findings imported`, `import sonar`, and `import github-advisories`. Only `1`
1335
- enables these commands in help and schemas. The SDK's corresponding operations
1336
- require the flag in their effective environment. Pure normalizers, file readers,
1337
- and the existing `import github` alert collector remain available independently.
1338
- Disabling the flag retains saved records.
1460
+ | Input and goal | Command | Service contacted | Where to find the result |
1461
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1462
+ | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1463
+ | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1464
+ | Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1465
+ | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1466
+ | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1339
1467
 
1340
1468
  For `publish findings`, `--to` is required. With `--to local`, `--repository`
1341
- takes a checkout path. The reader detects the file format, and `--format json`
1342
- selects the output format. A local preview writes no findings and needs no Cloud
1343
- login, network connection, or model call.
1469
+ takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
1470
+ The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
1471
+ saving findings or calling a model. For example, preview a complete Endor
1472
+ Finding export from the matching checkout, replacing the namespace, project
1473
+ and branch in the source key.
1474
+
1475
+ ```sh
1476
+ codex-security publish findings /private/path/endor-findings.json --provider endor \
1477
+ --to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
1478
+ ```
1479
+
1480
+ After reviewing the findings and exclusions, rerun the command without
1481
+ `--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
1482
+
1483
+ For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
1344
1484
 
1345
1485
  Local readback uses `findings imported [PATH]`. The path defaults to the current
1346
1486
  directory. Each imported record starts as `not_assessed`. Unknown revisions and
1347
1487
  locations stay unknown. Repository-scoped sources are checked against comparable
1348
1488
  configured Git remotes as described in the provider guide. Reimporting the same
1349
1489
  source key and finding ID reports created, updated, or unchanged records.
1350
- Records omitted from the new selection stay stored. An import with exclusions
1351
- exits with status 1. Local imports can retain evidence that exceeds Cloud's per-finding limits.
1490
+ Records omitted from the new selection stay stored. Local imports can retain
1491
+ evidence that exceeds Cloud's per-finding limits.
1492
+
1493
+ If a report contains both ready and excluded records, the local dry run exits
1494
+ with status 0. After confirmation, the import stores the ready records and
1495
+ exits with status 1. If all records are excluded, both commands exit with
1496
+ status 2. A clean empty report exits with status 0 in either mode and stores
1497
+ no findings.
1352
1498
 
1353
- For completed scans exported in the Codex Security JSON or CSV format, use
1354
- [scan import](#import-findings-as-a-saved-scan).
1499
+ Preview the same file and source key again for the intended destination before
1500
+ publishing. Semgrep Guardian selections, Web API SAST selections and full
1501
+ project collections support both destinations. Choose the [Semgrep import method](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) that matches your source.
1502
+
1503
+ ## Import Trivy dependency findings
1504
+
1505
+ Use `--provider trivy` for language-package vulnerabilities in schema-v2
1506
+ repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
1507
+ to set the scan root and check manifest paths.
1355
1508
 
1356
1509
  ## Import Endor Labs findings
1357
1510
 
@@ -1359,31 +1512,85 @@ Use `--provider endor` for one Endor project and context. The
1359
1512
  [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1360
1513
  SARIF compatibility, and the local preview.
1361
1514
 
1515
+ ## Import SonarQube Cloud issues
1516
+
1517
+ `import sonar --dry-run` writes a private capture and returns its path. Preview
1518
+ that capture for the intended destination before confirming. A Cloud confirmation
1519
+ saves the issues locally and publishes them. Use `--full-output` with
1520
+ `--format json` or `--format jsonl` for a structured result.
1521
+ [Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
1522
+
1523
+ ## Import GitHub findings locally or to Cloud
1524
+
1525
+ Use `--provider github` with separate source keys for
1526
+ [code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
1527
+ [Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
1528
+ [security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1529
+ Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
1530
+
1531
+ ### Import GHSA advisories separately
1532
+
1533
+ Use `import github-advisories OWNER/REPO` for published repository advisories
1534
+ or add `--github-advisory-source global` and one or more `--github-advisory`
1535
+ IDs to collect global advisories. Check the installed dependency against each
1536
+ affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1537
+
1538
+ ## Import alerts from the CLI
1539
+
1540
+ Collect open code-scanning alerts on the default branch and save the complete
1541
+ array outside the checkout. Use a private temporary directory and run
1542
+ validation from the matching checkout. Validation sends the evidence to your
1543
+ configured model provider.
1544
+
1545
+ ```sh
1546
+ out=$(mktemp -d) &&
1547
+ codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
1548
+ codex-security validate "$out/alerts.json"
1549
+ ```
1550
+
1551
+ The collector reads alerts, including third-party SARIF uploads. It does not
1552
+ start a scan. For filters, ref selection and SDK validation, see the
1553
+ [code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
1554
+
1362
1555
  ## Publish findings to Cloud
1363
1556
 
1364
- Use the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) to prepare a supported input
1365
- and follow the [shared publication steps](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
1366
- to preview and confirm it. The following settings and result fields apply to
1367
- scanner publication across providers.
1557
+ Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
1558
+ If you're collecting live issues with `import sonar`, [publish from the Sonar preview's saved capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
1368
1559
 
1369
1560
  ### Preview and publish
1370
1561
 
1371
- With `--to cloud`, `--repository` accepts a connected GitHub or GitHub Enterprise
1372
- repository URL or Cloud repository ID. A unique URL and its ID resolve to the
1373
- same destination and saved submission. Use the ID if several connectors share
1374
- the URL. Use a file-backed ChatGPT login for the selected Cloud
1375
- account. If you use your regular Codex login, set `cli_auth_credentials_store = "file"`
1376
- in Codex `config.toml` and sign in again. API-key-only and keyring-only logins
1377
- cannot publish. The destination needs an authorized environment. It can receive
1378
- scanner findings before its first native scan.
1379
-
1380
- Cloud preview reads current source versions and lists the account, endpoint,
1381
- repository, and environments. Existing source records keep their environment.
1382
- New records use the repository's current authorized default. The terminal
1383
- summarizes severities, shows up to five finding IDs and titles, and identifies
1384
- the evidence file and exclusions. Inspect the full preview with `--dry-run --format json`.
1385
- The interactive confirmation defaults to No and identifies skipped records.
1386
- Without a terminal, uploading requires `--yes`.
1562
+ Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
1563
+ Enterprise repository URL or its Cloud ID. Either works for retries. If
1564
+ several connectors share the URL, use the ID. You can import before the
1565
+ repository's first native scan.
1566
+
1567
+ Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
1568
+ set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
1569
+ again with the ChatGPT account you want to use.
1570
+
1571
+ ### Review the Cloud destination
1572
+
1573
+ Run the command with `--dry-run --format json`. Check `accountId`,
1574
+ `cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
1575
+ `excluded` with the records you meant to import.
1576
+
1577
+ - **Private findings inbox.** If the preview includes `privateImport`, the
1578
+ report goes to your inbox. The repository and connector identify the
1579
+ suggested assessment target. Check `format`, `bytes` and `sha256` in
1580
+ `privateImport` to identify the upload. For an Endor Finding, an Endor
1581
+ `list.objects` response or a Wiz vulnerability JSON export, the CLI can
1582
+ send the original bytes when Cloud accepts the format and every record
1583
+ matches your selection. Other inputs, including arrays of selected Endor
1584
+ Findings, use `security.findings.v1`.
1585
+ - **Repository publisher.** Check `repository.environment_id` in each entry
1586
+ of `requests`. The publisher checks the current source versions. Existing
1587
+ records keep their environment. New records use the repository's authorized
1588
+ default.
1589
+
1590
+ To import, run the same command without `--dry-run` and confirm. The terminal
1591
+ shows the file, exclusions, severities and up to five finding IDs and titles.
1592
+ The prompt defaults to No. For a noninteractive import, add `--yes` after
1593
+ reviewing the full JSON preview.
1387
1594
 
1388
1595
  ### Configure an alternate Cloud deployment
1389
1596
 
@@ -1402,23 +1609,62 @@ instructions. API requests always use the API root. The older
1402
1609
 
1403
1610
  ### Resume interrupted imports
1404
1611
 
1405
- The publisher saves request IDs and bodies privately in the configured state
1406
- directory before uploading batches of up to 100 findings within Cloud payload
1407
- limits. After a lost response, use the same input, destination, account, API
1408
- endpoint, and state directory to resume. Deployments have separate checkpoints
1409
- even if their account and repository IDs match. Check `cloudApiUrl` for the API
1410
- endpoint and `savedSubmission` for the checkpoint. A repository reset retires
1411
- the old request and requires a fresh preview and approval.
1612
+ If the result includes `savedSubmission`, keep that checkpoint. Rerun the
1613
+ original command with `--dry-run --format json` using the same input, account,
1614
+ destination, API endpoint and state directory. Check `cloudApiUrl`. If
1615
+ `resumed` is true, confirm to continue the saved submission. If it's false,
1616
+ review the new submission before confirming.
1617
+
1618
+ - **Private inbox.** The CLI checks the report digest and reuses its saved
1619
+ request IDs. It can read an accepted job even if the deployment has since
1620
+ disabled uploads. After an inbox reset, check the new report format, size
1621
+ and digest before confirming.
1622
+ - **Repository publisher.** The CLI saves each request privately before
1623
+ sending up to 100 findings. Retries use the same publisher, request IDs and
1624
+ bodies. If the repository has been reset, preview and confirm a fresh
1625
+ submission.
1626
+
1412
1627
  [Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
1413
1628
 
1414
1629
  ### Results and exit codes
1415
1630
 
1416
- | Status | Exit code | Meaning |
1417
- | ------------- | --------- | ----------------------------------------------------------------------- |
1418
- | `complete` | 0 | All selected records were acknowledged and read back. |
1419
- | `partial` | 1 | Some records were excluded locally or rejected by Cloud. |
1420
- | `interrupted` | 2 | Upload, verification, or receipt persistence stopped after preparation. |
1421
- | `failed` | 2 | Preparation failed before upload. |
1631
+ | Status | Exit code | Meaning |
1632
+ | ------------- | --------- | -------------------------------------------------------------------------------------- |
1633
+ | `empty` | 0 | No records were available to upload. |
1634
+ | `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
1635
+ | `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
1636
+ | `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
1637
+ | `failed` | 2 | Preparation failed before upload. |
1638
+
1639
+ A clean empty report needs no confirmation. Self-contained file imports can
1640
+ finish before Cloud sign-in; Semgrep Platform and Snyk REST captures use the
1641
+ Cloud catalog to verify their repository. Local imports still validate the
1642
+ checkout and create no workbench database. Explicit scanner errors
1643
+ and selections containing only excluded records fail; JSON output retains their
1644
+ diagnostics and exclusion reasons. Existing findings stay open.
1645
+
1646
+ For automation, check the scanner's exit status as well as the import's. SARIF
1647
+ can contain no runs or omit results in a rules-only export. `empty` describes
1648
+ the selected report, not whether a scan completed successfully.
1649
+
1650
+ For a partial or interrupted import, check `excluded` and any `error` before
1651
+ retrying. Some records may already have reached Cloud.
1652
+
1653
+ - **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
1654
+ and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
1655
+ uploaded file (`input.file_id`). The CLI reads the job receipt, so a
1656
+ successful import can show `verified: 0`. To share a finding, open it in
1657
+ your inbox, assess it against a pinned repository revision and publish the
1658
+ reportable assessment.
1659
+ - **Repository publisher.** `verified` counts records whose identity the CLI
1660
+ confirmed by reading them back. If the version matches the receipt, the CLI
1661
+ also checks the evidence. A newer version can have different evidence and
1662
+ still count as verified. `unacknowledged` counts records awaiting a receipt,
1663
+ including records Cloud accepted if the response was lost. Use `client_id`
1664
+ to match a receipt item to its request and `source_finding_id` in `failures`
1665
+ to find a failed vendor record. Counts include earlier batches with receipts.
1666
+ When present, `cloudUrl` opens the repository. Assessment and sharing are
1667
+ separate steps.
1422
1668
 
1423
1669
  With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
1424
1670
  Failed and interrupted imports set `ok` to `false` and `error.code` to
@@ -1426,231 +1672,30 @@ Failed and interrupted imports set `ok` to `false` and `error.code` to
1426
1672
  Other formats reject `--full-output` before reading the file or contacting
1427
1673
  Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
1428
1674
 
1429
- `verified` and `unacknowledged` are counts. Each receipt item identifies a
1430
- request item by `client_id`. Each entry in `failures` identifies the vendor
1431
- record by `source_finding_id`. A lost response can leave accepted records
1432
- unacknowledged. Review `error` before retrying, and check `excluded` for local
1433
- input errors. Counts include previously acknowledged batches in the same
1434
- saved submission.
1435
-
1436
- Progress goes to stderr and JSON results to stdout. Lookups and readback use up
1437
- to four concurrent requests. Uploads are sequential. Saved receipts and
1438
- readback verify source-record identity and evidence. Codex assessment and
1439
- visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
1440
- available, links to the destination repository in Cloud.
1675
+ Progress goes to stderr and JSON results to stdout. The repository publisher
1676
+ uploads sequentially and uses up to four concurrent requests for lookups and
1677
+ readback.
1441
1678
 
1442
- ### Import Snyk Open Source findings
1679
+ ### Import Snyk findings
1443
1680
 
1444
- Use `--provider snyk` for Open Source SCA vulnerabilities. Native CLI JSON, plugin
1445
- exports, and Open Source SARIF can produce different occurrence IDs. Use a
1446
- separate source key for each format. See the [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for
1447
- collection and preview commands.
1681
+ Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
1682
+ monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
1683
+ covers saved files, distinct source keys for each format, and collection with
1684
+ `import snyk`.
1448
1685
 
1449
1686
  ### Import Wiz findings
1450
1687
 
1451
- The [Wiz guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md) shows how to preview saved package vulnerabilities,
1452
- SAST findings, repository secrets, or IaC findings. The format reference below
1453
- describes the fields to preserve when preparing those exports.
1454
-
1455
- #### Review the Cloud destination
1456
-
1457
- The preview shows which Cloud destination will receive the selected records.
1458
- When the deployment advertises private import for the scanner, the CLI puts a
1459
- report in the signed-in account’s **private findings inbox**. The preview
1460
- identifies its format and byte count. For complete Endor findings and Wiz
1461
- vulnerability JSON exports, the CLI sends the original bytes when Cloud
1462
- advertises the format and every record matches the reviewed selection. Other
1463
- selections and in-memory collectors use `security.findings.v1`. The CLI
1464
- attaches the selected repository and connector as a suggested assessment
1465
- target. Review the selection, exclusions, source key and destination before
1466
- confirming.
1467
-
1468
- The job receipt contains the file and job identifiers and record counts. To
1469
- share a finding, open it in Cloud, assess it against a pinned repository
1470
- revision, and explicitly publish a reportable assessment. An import can
1471
- finish with record errors. Check the error and unprocessed counts in the
1472
- receipt.
1473
-
1474
- Repeat the same command to recover an interrupted private import. The CLI
1475
- checks the report digest, reuses its saved request IDs, and reads an accepted
1476
- job even when new uploads are disabled. Resetting the inbox requires a new
1477
- preview and confirmation. Deployments and scanners using the repository
1478
- publisher continue to show the repository destination and per-finding receipts.
1479
- An in-flight repository publication resumes on its original protocol.
1480
-
1481
- #### Select findings and a destination
1482
-
1483
- Acquire selected findings through an authorized Wiz connection and save the
1484
- complete native response. The publisher reads the saved file. MCP summaries,
1485
- Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
1486
- the selected response against the format for its finding family. Acquisition
1487
- against a live Wiz tenant requires separate qualification.
1488
-
1489
- For saved reports, use the detailed repository package vulnerability export
1490
- shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
1491
- metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
1492
-
1493
- #### Package vulnerability inputs
1494
-
1495
- Native package input can be a Wiz JSON vulnerability report, a vulnerability
1496
- finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1497
- with one package record per line. The repository package-vulnerability CSV
1498
- profile below is also supported. Plain and gzip-compressed files are accepted.
1499
- A response that advertises another page is rejected. Complete the requested pages
1500
- or save only the explicitly selected records; retain the named collection for
1501
- SAST, repository secrets, and IaC.
1502
-
1503
- For native package records, include `id`, `name`, `detailedName`,
1504
- `vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
1505
- package, image, and repository metadata.
1506
-
1507
- The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
1508
- `CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
1509
- this profile; other Wiz report types use different fields.
1510
- For repository imports, `CloudPlatform` must identify GitHub and
1511
- `CloudProviderURL` must identify a repository branch. The repository URL must
1512
- match the selected Cloud repository or, for local import, one of the checkout's
1513
- Git remotes when configured. This also applies when the parsed findings are saved and
1514
- read again as normalized JSONL. Other resource types are excluded.
1515
-
1516
- CSV imports use `ID` as the occurrence identity and retain every parsed field,
1517
- including unknown columns and quoted multiline values, in `source_data.row`.
1518
- Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
1519
- Vendor resolution status stays in the original evidence. The importer does not
1520
- derive a branch or revision from a tree URL, or treat last-detected time as a
1521
- record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
1522
- and duplicate occurrence IDs among otherwise importable records stop the import.
1523
- Review any excluded records in the preview before publishing.
1524
-
1525
- Normalized JSONL is also accepted:
1526
-
1527
- ```json
1528
- {
1529
- "source_finding_id": "vendor-finding-42",
1530
- "evidence": {
1531
- "title": "Vulnerable example package",
1532
- "severity": "high",
1533
- "source_data": { "id": "vendor-finding-42" }
1534
- }
1535
- }
1536
- ```
1688
+ <a id="select-findings-and-a-destination"></a>
1689
+ <a id="package-vulnerability-inputs"></a>
1690
+ <a id="sast-repository-secrets-and-iac-inputs"></a>
1691
+ <a id="preserved-evidence"></a>
1692
+ <a id="convert-csv-reports"></a>
1537
1693
 
1538
- Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
1539
- exports; a selected project filter does not change the vendor namespace. Confirm
1540
- that the selected assets or builds map to this repository. The raw Wiz adapter
1541
- retains each record in `source_data`, uses reported severity, and leaves unknown
1542
- branch/revision empty. Repository-branch findings retain their repository-relative
1543
- file paths; container and other workload paths remain vendor evidence rather than
1544
- source-code locations. It does not
1545
- fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1546
- Findings from external network scans are excluded from this package vulnerability
1547
- mapping.
1548
-
1549
- #### SAST, repository secrets, and IaC inputs
1550
-
1551
- For SAST, repository secrets, and IaC, save the documented JSON API collection:
1552
-
1553
- | Finding family | Collection | Raw occurrence identity |
1554
- | ------------------ | ---------------------------- | ----------------------- |
1555
- | SAST | `data.sastFindings.nodes` | `sast:<id>` |
1556
- | Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
1557
- | IaC | `data.iacFindings.nodes` | `iac:<id>` |
1558
-
1559
- The collection identifies the mapping. Bare arrays of these raw findings are
1560
- excluded because their overlapping fields do not identify a family. An export
1561
- may contain multiple named collections. GraphQL errors and unfinished pages stop
1562
- the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
1563
- relationship to source code does not make it a repository secret.
1564
-
1565
- Each new finding needs a verified source repository URL. Supply `repository.url`
1566
- in the finding's repository metadata, or include the matching repository inventory
1567
- in `data.versionControlResources.nodes`. For secrets, repository metadata is under
1568
- `resource.typedProperties.repository`. The importer joins the inventory's
1569
- `repository.id` to that source ID and uses `repository.url`; inventory node IDs,
1570
- `providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
1571
- must agree with the inventory and with the selected Cloud repository before any
1572
- finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
1573
- establishes case-insensitive repository matching on custom GitHub Enterprise
1574
- hosts. Fresh imports preserve the reported branch name literally. Duplicate
1575
- entries for one repository ID must agree on their platform and repository URL.
1576
- For example, this synthetic selection supplies the inventory alongside its SAST
1577
- collection:
1578
-
1579
- ```json
1580
- {
1581
- "data": {
1582
- "sastFindings": {
1583
- "nodes": [
1584
- {
1585
- "id": "finding-42",
1586
- "name": "Untrusted query construction",
1587
- "severity": "HIGH",
1588
- "repository": { "id": "source-repository-1" },
1589
- "filePath": "src/query.ts",
1590
- "startLine": 10,
1591
- "endLine": 12
1592
- }
1593
- ]
1594
- },
1595
- "versionControlResources": {
1596
- "nodes": [
1597
- {
1598
- "repository": {
1599
- "id": "source-repository-1",
1600
- "url": "https://github.com/example/project"
1601
- }
1602
- }
1603
- ]
1604
- }
1605
- }
1606
- }
1607
- ```
1608
-
1609
- #### Preserved evidence
1610
-
1611
- The adapters preserve each selected raw node exactly in `source_data`. Typed
1612
- `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1613
- and family-specific evidence:
1614
-
1615
- | Family | Evidence retained in typed fields |
1616
- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1617
- | SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
1618
- | Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
1619
- | IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
1620
-
1621
- Vendor status and verdict remain separate from Codex assessment. A secret's
1622
- introduced commit is not its scanned revision. Missing source revisions and scan
1623
- IDs stay unknown. A logical IaC resource is retained in the original record and
1624
- does not establish that it is deployed. Precise original timestamps remain in
1625
- `source_data`; only an explicit record-update timestamp maps to the whole-second
1626
- `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1627
- timestamps.
1628
-
1629
- #### Convert CSV reports
1630
-
1631
- Native SAST and secret report downloads can be CSV, including gzip-compressed
1632
- CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1633
- for its actual column headers into normalized JSONL, preserving each original row
1634
- in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
1635
- verifying the source repository. Use the same prefixed occurrence ID shown above
1636
- so API and report imports update the same finding; normalized IDs are accepted
1637
- exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
1638
- for a vendor occurrence ID. Missing IDs or severity must be corrected at the
1639
- source rather than invented.
1640
-
1641
- For repository-secret reports, select `path` and `lineNumber` for source
1642
- navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
1643
- as the introduced commit. The standard secret metadata API does not supply a
1644
- path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
1645
- `rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
1646
- repository/branch metadata. Preserve the original fields; source locations must
1647
- be repository-relative, and an end line requires a start line. Keep credential
1648
- values out of the metadata selection; the importer does not retrieve or test
1649
- credentials or apply remediation instructions.
1650
-
1651
- Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1652
- integer range is rejected; export those values as strings to preserve them
1653
- exactly. Invalid records appear in `excluded` with their source ID and reason.
1694
+ Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
1695
+ The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
1696
+ [named SAST, secret and IaC collections](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#sast-repository-secrets-and-iac-inputs),
1697
+ [retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
1698
+ [conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
1654
1699
 
1655
1700
  ### Publish completed scans
1656
1701
 
@@ -1729,15 +1774,16 @@ Choose a destination authorized to receive that content. Local history records
1729
1774
  successful issue IDs separately from sealed artifacts. The CLI and the plugin's
1730
1775
  finding-tracking workflow share these records when using the same Codex Security
1731
1776
  state directory. Accepted writes remain recorded even if a later issue read fails.
1732
- The shared-history migration preserves existing Linear receipts and replaces their
1733
- old table. Upgrade CLI and plugin installations together when they share state;
1734
- older publishers cannot write to the migrated database.
1735
1777
 
1736
- Republishing creates duplicates unless `--skip-existing` finds a recorded success
1737
- for that occurrence, team, and project, including issues created or reused through
1738
- the plugin. It does not check remote issues or cover
1739
- unrecorded/concurrent publication. After interruption, inspect the handoff,
1740
- evidence, and destination before retrying.
1778
+ By default, publishing the same scan again creates new issues. With
1779
+ `--skip-existing`, the CLI skips occurrences with a recorded success for the
1780
+ same team and project. This includes issues the plugin created or reused.
1781
+ The CLI checks local history only. After an interrupted or concurrent run,
1782
+ check Linear for an existing issue before retrying.
1783
+
1784
+ If the CLI and plugin share a database from an older installation, upgrade
1785
+ both together. The shared history preserves existing Linear receipts, but
1786
+ publishers that require the old table can no longer record new ones.
1741
1787
 
1742
1788
  ```ts
1743
1789
  import { publishScan } from "@openai/codex-security";
@@ -2024,9 +2070,21 @@ history. Inspect its saved status before choosing resume or rerun, and supply
2024
2070
  the original custom prompt files for reruns. Structured history and log output
2025
2071
  and command selection defaults are unchanged.
2026
2072
 
2027
- Recipes save settings and authentication choice, not credentials. Reruns use the
2028
- current checkout/context files and do not reload project files. Supply replacement
2029
- scan and custom-validation prompts when the original used them:
2073
+ Reruns use the current checkout/context files and do not reload project files.
2074
+ The readable scan recipe records your authentication choice. A separate private
2075
+ replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
2076
+ `model_providers` settings, including any credentials written directly in
2077
+ `http_headers`. If you use `env_key` or `env_http_headers`, the profile stores
2078
+ the variable names. Set those variables when you rerun or resume. Settings
2079
+ inherited from a named file profile are reloaded from that file. If an older
2080
+ scan omitted your endpoint, start a new scan with the original `--codex` override.
2081
+
2082
+ When routing through environment variables, set them for each launch, including
2083
+ rerun and resume. Deep workers inherit `CODEX_OSS_BASE_URL` and `CODEX_OSS_PORT`
2084
+ for Ollama and LM Studio, and `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`,
2085
+ and `GOOGLE_APPLICATION_CREDENTIALS` for Vertex AI.
2086
+
2087
+ Supply replacement scan and custom-validation prompts when the original used them:
2030
2088
 
2031
2089
  ```bash
2032
2090
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
@@ -2048,11 +2106,16 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
2048
2106
  writable, and outside the target repository. Session logs may contain sensitive
2049
2107
  data even though scan recipes do not store credentials.
2050
2108
 
2051
- Codex may compress saved session logs to `.jsonl.zst`. Reading those logs requires
2052
- Node.js 22.15.0+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14,
2053
- compressed sessions are unavailable to `scans logs`, feedback attachments, and
2054
- `scans resume`. Upgrade Node.js to read or resume these sessions. Plain `.jsonl`
2055
- logs work on all supported runtimes.
2109
+ Saved scan logs retain the finishing turn, including its final response, and
2110
+ exclude later turns once the scan records a completion boundary. Older scans
2111
+ retain the full history of their attributed sessions and keep their existing
2112
+ worker-selection boundaries. This also applies to logs attached with
2113
+ `feedback --include-logs`.
2114
+
2115
+ Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
2116
+ work on all supported Node.js versions, including logs, feedback attachments,
2117
+ usage accounting, and saved-session discovery for resume. A bundled decoder
2118
+ reads concatenated frames and reports truncated streams as collection errors.
2056
2119
 
2057
2120
  ### Resuming an interrupted Deep Scan
2058
2121
 
@@ -2095,6 +2158,13 @@ One comparison ID is compared with the latest completed scan.
2095
2158
  codex-security scans match --all --force --model gpt-6.1-sol --effort high
2096
2159
  ```
2097
2160
 
2161
+ When a saved Standard scan and a Deep scan have the same recorded target,
2162
+ revision, and snapshot digest, matching flags findings that have different
2163
+ anchors but share a unique rule, first displayed source range, and optional
2164
+ instance. Matching preserves the case of saved paths. Codex can request the
2165
+ saved evidence to distinguish separate causes at that site. Automatic matching
2166
+ under a cost limit keeps its single comparison call.
2167
+
2098
2168
  Only high-confidence root-cause matches are grouped. Uncertain and related
2099
2169
  findings remain separate. Rebuilding retains stable identities, triage, and
2100
2170
  sealed artifacts; interruption preserves completed comparisons. Model/effort
@@ -2292,9 +2362,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
2292
2362
 
2293
2363
  ### Local pre-commit checks
2294
2364
 
2295
- `install-hook` checks staged and unstaged changes, blocking the commit on scan
2296
- failure or findings at/above its threshold (`high` by default). Use required CI
2297
- for enforcement; local hooks are optional.
2365
+ The generated hook runs a `--working-tree` scan and blocks the commit on scan
2366
+ failure or findings at or above its threshold (`high` by default). It uses the
2367
+ checkout's normal index for staged and unstaged changes, so it can include changes
2368
+ outside a partial commit and miss content staged only in a separate index.
2369
+ Use required CI for enforcement because local hooks are optional.
2298
2370
 
2299
2371
  Install the CLI outside the target repository and run that copy directly. `npx`
2300
2372
  can select a repository-local package. Before installation, inspect:
@@ -2312,148 +2384,13 @@ codex-security install-hook /path/to/repository
2312
2384
  ```
2313
2385
 
2314
2386
  To migrate an existing generated hook, verify it is a regular file used only by
2315
- this repository and contains only the generated command. Preserve its severity.
2316
- The installer can update older `npx` hooks when the severity matches. New hooks
2317
- record absolute Node/CLI paths. If those change, back up and remove the verified
2318
- generated hook, then reinstall with the same threshold. Restore the backup if
2319
- installation fails. The installer respects `core.hooksPath`.
2320
-
2321
- ## Import SonarQube Cloud issues
2322
-
2323
- The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
2324
- binding, saved issue-search pages, and replay. Unlike a saved-file
2325
- `publish findings` preview, `import sonar --dry-run` writes a private capture
2326
- and returns its path. Confirm with the capture from the preview for the intended
2327
- destination. A Cloud confirmation imports the selected issues locally and
2328
- publishes them to Cloud. Use `--full-output` with `--format json` or
2329
- `--format jsonl` for a structured success or error envelope.
2330
-
2331
- ## Import GitHub findings locally or to Cloud
2332
-
2333
- Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
2334
- [Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
2335
- [GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
2336
- and preview findings. All three use `--provider github`. Keep a separate source
2337
- key for each family. Saving locally or publishing to Cloud requires the
2338
- [external-import opt-in](#import-vendor-findings-locally).
2339
-
2340
- The code-scanning and advisory CLI collectors use `gh` to authenticate for
2341
- `GH_HOST` (default `github.com`). A GitHub
2342
- plugin connection can select alerts but does not sign the CLI in.
2343
- Collection retains the selected ref's instance. Branches keep separate
2344
- evidence. An alert-wide dismissal takes precedence over the selected instance's
2345
- open or fixed state. Missing security severity stays `unknown`. See
2346
- [code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
2347
-
2348
- The SDK offers the same preview and publication boundary for Cloud:
2349
-
2350
- ```ts
2351
- import {
2352
- importGitHubCodeScanningAlerts,
2353
- normalizeGitHubCodeScanningAlerts,
2354
- prepareNormalizedExternalPublication,
2355
- } from "@openai/codex-security";
2356
-
2357
- const alerts = await importGitHubCodeScanningAlerts({
2358
- repository: "example/project",
2359
- });
2360
- const prepared = await prepareNormalizedExternalPublication(
2361
- normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
2362
- {
2363
- provider: "github",
2364
- repository: "https://github.com/example/project",
2365
- sourceKey: "github.com/example/project/code-scanning",
2366
- },
2367
- );
2368
- console.log(prepared.preview);
2369
- // After reviewing the preview:
2370
- const receipt = await prepared.publish();
2371
- ```
2372
-
2373
- For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
2374
- the original alerts to retain evidence that exceeds Cloud limits. Pass the result
2375
- to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
2376
- its preview, and call `import()`. Alternatively, pass the saved alert file directly
2377
- to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
2378
-
2379
- ### Import GHSA advisories separately
2380
-
2381
- See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
2382
- to save repository advisories or selected global database records and preview
2383
- them for the chosen destination. Advisories report affected ranges and
2384
- available fixes. Verify installed dependencies and applicability in the
2385
- destination repository separately.
2386
-
2387
- Repository lists default to published advisories. When selecting exact IDs, omit
2388
- `--github-state`. Selecting a repository advisory by its GHSA ID can return a
2389
- draft if you have access.
2390
- Global collection requires one or more explicit IDs.
2391
- Acquisition failure yields no partial selection. Access to private or
2392
- unpublished repository advisories requires the repository advisory read
2393
- permission and access to the record. See
2394
- [GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
2395
-
2396
- In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
2397
- pass `normalizeGitHubAdvisories(advisories, "cloud")` to
2398
- `prepareNormalizedExternalPublication()`. For local storage, pass
2399
- `normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
2400
- `importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
2401
- `{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
2402
- records. Both forms require `repository: "OWNER/REPO"` as source or target context.
2403
- Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
2404
-
2405
- ## Import alerts from the CLI
2406
-
2407
- ```bash
2408
- codex-security import github example/repository --format json > /path/outside/repository/alerts.json
2409
- codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
2410
- codex-security validate /path/outside/repository/alerts.json
2411
- ```
2412
-
2413
- Run validation from the matching local repository. Import defaults to open alerts
2414
- on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
2415
- `--github-ref REF` to filter. Exact alert numbers ignore state and reject a
2416
- nondefault state.
2417
-
2418
- Import is read-only and returns an array. Save validation inputs without output
2419
- filters or token limits. It includes third-party SARIF uploads, does not start
2420
- Codex, and does not check out code. Each record contains `source`, `repository`,
2421
- `number`, `url`, and the full upstream `alert`.
2422
-
2423
- For a disposition per alert, import and validate through the SDK:
2424
-
2425
- ```ts
2426
- import {
2427
- CodexSecurity,
2428
- importGitHubCodeScanningAlerts,
2429
- } from "@openai/codex-security";
2430
-
2431
- const findings = await importGitHubCodeScanningAlerts({
2432
- repository: "example/repository",
2433
- alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
2434
- githubHost: "github.com",
2435
- githubToken: process.env["GH_TOKEN"],
2436
- });
2437
-
2438
- const security = new CodexSecurity();
2439
- try {
2440
- for (const finding of findings) {
2441
- const result = await security.validate({
2442
- repositoryPath: "/path/to/repository",
2443
- finding,
2444
- });
2445
- console.log(finding.url, result.disposition, result.outputDir);
2446
- }
2447
- } finally {
2448
- await security.close();
2449
- }
2450
- ```
2451
-
2452
- SDK options include `state` (default `"open"`), `ref`, and `signal`.
2453
- Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
2454
- If you omit the token, the SDK asks the GitHub CLI for credentials, including
2455
- its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
2456
- The token needs code-scanning read access; access failures reject the import.
2387
+ this repository and contains only the generated commands. Rerun `install-hook`
2388
+ with `--fail-on-severity` set to its original threshold. It recognizes the legacy
2389
+ `npx` hook and supported earlier templates with matching absolute Node and CLI
2390
+ paths. If it refuses to overwrite the verified hook, back it up, remove it and
2391
+ reinstall with the same threshold. Restore the backup if installation fails.
2392
+ The installer uses host Git for the selected repository and respects
2393
+ `core.hooksPath`.
2457
2394
 
2458
2395
  ## Validate and patch findings
2459
2396
 
@@ -2461,12 +2398,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
2461
2398
  This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
2462
2399
  See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
2463
2400
 
2464
- `validate` assesses candidates from local source evidence without building the
2465
- target, executing application code, running tests or PoCs, or contacting services.
2466
- It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
2467
- validation, and `patch` still fixes and verifies findings. Both commands accept files
2468
- or literal text and work in the current directory. Saved finding/occurrence IDs
2469
- select their original repository for patching.
2401
+ `validate` sends the finding to your configured model provider. Its review
2402
+ tools can read the checkout, with network access and web search disabled.
2403
+ The assessment uses source evidence and skips builds, tests, PoCs and application
2404
+ execution. Both `validate` and `patch` accept files or literal text in the
2405
+ current directory. Patching by saved finding or occurrence ID selects the
2406
+ original repository.
2470
2407
 
2471
2408
  Basic patching also works in ordinary directories and Git worktrees before their
2472
2409
  first commit. Directory change tracking excludes `.git` and `.svn` metadata.
@@ -2508,7 +2445,7 @@ locally does not guarantee provider support. Keep the schema small and use it on
2508
2445
  when the caller needs structured results. It checks the result's shape, not whether
2509
2446
  the security conclusion is correct. Relative paths resolve from the current directory.
2510
2447
 
2511
- The validator no longer writes reports. Save the assessment by redirecting stdout:
2448
+ Save the assessment by redirecting stdout:
2512
2449
  `codex-security validate findings.json > assessment.md`. For runtime proof, run a
2513
2450
  separate reproduction step. Missing facts are reported as proof gaps; a finding
2514
2451
  supported by source evidence does not require runtime reproduction.
@@ -2570,7 +2507,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
2570
2507
 
2571
2508
  An illustrative result is below. Actual decisions depend on the repository;
2572
2509
  this example assumes a tenant filter exists but deployment routing is unavailable.
2573
- Both candidate IDs remain in the output, including the unresolved claim.
2510
+ Before updating finding records, [check that each input ID appears exactly
2511
+ once](validate-records.md#check-the-returned-ids), including unresolved
2512
+ candidates.
2574
2513
 
2575
2514
  ```json
2576
2515
  {
@@ -2658,8 +2597,13 @@ including code, HTML, and math, retain their original text.
2658
2597
  GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
2659
2598
  ```
2660
2599
 
2661
- Both providers return `pullRequest: { branch, url }`. Supplied-issue patching
2662
- requires a clean tree. If publication fails, run the printed
2600
+ Both providers return `pullRequest: { branch, url }`. Saved-finding publication
2601
+ includes files changed and verified in the same patch turn. If a selected file
2602
+ already had local edits, the CLI keeps the patch in the working tree for review.
2603
+ The risk assessment and commit use the same verified tree. If staging changed
2604
+ during the run and Git cannot update the index, the CLI reports it and keeps
2605
+ the existing staging.
2606
+ Supplied-issue patching requires a clean tree. If publication fails, run the printed
2663
2607
  `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
2664
2608
  commit and refuses changed branches. Retain the GitLab host setting on resume.
2665
2609
 
@@ -2687,10 +2631,11 @@ truncating any selected finding. The CLI prints verdicts in selection order
2687
2631
  after every request returns valid results. For these selections the CLI omits
2688
2632
  per-event progress and update notices so stderr cannot delay the verdicts.
2689
2633
 
2690
- If one finding exceeds the input limit on its own, verification stops before
2691
- the first request. The error reports its occurrence ID and required request
2692
- size. To verify another open occurrence from that scan, run
2693
- `codex-security verify-fix --scan SCAN_ID OCCURRENCE_ID`.
2634
+ If a finding would exceed the input limit, `validate`, `patch`, and `verify-fix`
2635
+ put the complete finding data in a temporary file for Codex to search alongside
2636
+ the checkout. A single input file keeps its original text and line breaks.
2637
+ The file remains available until the task finishes and is then removed. The
2638
+ SDK's local `validate()` and `patch()` methods use the same fallback.
2694
2639
 
2695
2640
  `--verification-mode static` selects source-only assessment, as described above
2696
2641
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
@@ -2711,7 +2656,9 @@ retain exit codes `130` and `143` without a result.
2711
2656
 
2712
2657
  Use `--llms` for the command manifest, `scan --schema --format json` for its
2713
2658
  schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
2714
- `--format toon|json|yaml|jsonl` and `--full-output`.
2659
+ `--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
2660
+ `--filter-output`, `--token-limit`, and `--token-offset` options accept either
2661
+ `--option value` or `--option=value`.
2715
2662
 
2716
2663
  `skills add` syncs generated CLI command guidance; it does not install the full
2717
2664
  Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing