@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
package/docs/cli.md CHANGED
@@ -14,14 +14,10 @@ codex-security info --json
14
14
 
15
15
  `--help` lists commands by task; `<command> --help` lists its options.
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
- `scans` and `findings` default to their `list` subcommands.
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.
17
+ `scans` and `findings` default to their `list` subcommands. Global output options
18
+ can appear around a subcommand, for example `cs scans --json show`. Use `--`
19
+ after the command to pass the remaining words as literal positional arguments,
20
+ including file names that begin with a dash.
25
21
 
26
22
  ## Find a workflow
27
23
 
@@ -31,10 +27,8 @@ without running security analysis.
31
27
  [save project settings](#project-files).
32
28
  - [Review one system across repositories](#review-one-system-across-repositories)
33
29
  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).
30
+ - [Choose an import command](#import-vendor-findings-locally) to save a scan,
31
+ collect upstream alerts, or store vendor evidence locally or in Cloud.
38
32
  - [Inspect saved scans and rerun them](#scan-history-and-reruns),
39
33
  [classify severity](#classify-finding-severity), or
40
34
  [suggest owners](#suggest-finding-owners).
@@ -46,6 +40,26 @@ without running security analysis.
46
40
  - [Use a hosted executor](#hosted-standard-scan) or
47
41
  [run bulk scans in containers](#containerized-bulk-scans).
48
42
 
43
+ ## Updating the CLI
44
+
45
+ Run `cs update` to update an npm global installation managed by the running
46
+ Node distribution. It uses Node’s bundled npm, the public npm registry, and
47
+ disabled lifecycle scripts. If you use a custom registry or proxy, run your
48
+ package manager’s update command directly.
49
+
50
+ The legacy `cs --update` spelling also works. Invoke the updater or the stdio
51
+ server (`cs --mcp`) on its own.
52
+
53
+ For a project dependency, `cs update` prints the package-manager command for
54
+ you to run in the declaring project. For other global installations it prints
55
+ the corresponding package-manager command and installation location. For npx,
56
+ use `npx @openai/codex-security@latest` on the next run. For a standalone
57
+ release, download and extract the latest release.
58
+
59
+ Interactive update notices use the same installation detection. Set
60
+ `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to disable these notices. Explicit updates
61
+ are available with notifications disabled.
62
+
49
63
  ## Authentication
50
64
 
51
65
  Sign in with ChatGPT, or supply an API key for CI:
@@ -87,7 +101,9 @@ your local browser. Keep SSH connected until login finishes.
87
101
  ### OpenAI credentials
88
102
 
89
103
  Interactive scans ask which credentials to use when both ChatGPT and an
90
- environment API key are available. Noninteractive commands prefer
104
+ environment API key are available. A dedicated sign-in takes precedence. After
105
+ `codex-security logout`, the prompt skips the ambient sign-in until you log in
106
+ again. Noninteractive commands prefer
91
107
  `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
92
108
  with `--auth`:
93
109
 
@@ -104,12 +120,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
104
120
  chosen authentication. Environment keys do not replace the saved login.
105
121
  The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
106
122
 
123
+ For a scan using a custom native provider, `auto` and `api-key` use the
124
+ environment variable declared by `model_providers.<id>.env_key`, including
125
+ when a Codex file profile selects that provider. Set that variable before
126
+ starting the scan. To use `--auth chatgpt`, select a provider configured for
127
+ account authentication. A custom provider that requires its own key cannot
128
+ honor that combination.
129
+
107
130
  Stored OpenAI credentials live in
108
131
  `$CODEX_SECURITY_STATE_DIR/codex-home`, or
109
132
  `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
110
133
  outside the target and every enclosing Git worktree. It also serves providers
111
134
  with `requires_openai_auth = true`.
112
135
 
136
+ If you manually hard-linked the two homes’ `auth.json` files, keep both homes
137
+ accessible when running `codex-security logout`. When the CLI verifies the
138
+ two hard links, it removes the private link before invoking native logout.
139
+ If the ambient home is unavailable, the configured credential store handles
140
+ logout normally.
141
+
113
142
  Codex carries credential-storage, forced-login, and workspace settings from the
114
143
  ambient configuration into this home. Managed-device policies still apply;
115
144
  workspace-managed policies may require ChatGPT credentials even with an API key.
@@ -123,8 +152,21 @@ after logout completes.
123
152
  Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
124
153
  `HOME` or `USERPROFILE` environment setting.
125
154
 
126
- If credentials cannot refresh, run `login status`. Retry if the sign-in recently
127
- changed; otherwise run `logout`, then `login`.
155
+ If you use file-based ChatGPT credentials with both Codex and Codex Security,
156
+ run `codex-security login` before your first scan or status check to give Codex
157
+ Security its own session. An imported sign-in shares a single-use refresh token.
158
+ When either client renews it, the other client's next refresh can fail even
159
+ while its login status reports that it is signed in.
160
+
161
+ If Codex Security reports that the refresh token was already used, run
162
+ `codex-security logout`, then `codex-security login`. If your Codex CLI or app
163
+ reports that error, sign out and sign back in there.
164
+
165
+ Use `codex-security login status --json` in automation. Its stdout reports `authenticated`, the effective authentication `method`, and the environment variable name when an API key takes precedence. When an API key takes precedence, stderr names the variable that configures it. This offline status check also labels the separate stored sign-in diagnostic. The command keeps the exit status of the human-readable status check.
166
+
167
+ For other refresh errors, check `codex-security login status`. Retry if the
168
+ sign-in recently changed. Otherwise run `codex-security logout`, then
169
+ `codex-security login`.
128
170
  Some cybersecurity requests and protected findings require
129
171
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
130
172
 
@@ -142,7 +184,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
142
184
  In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
143
185
  to explicitly turn it off.
144
186
  The setting carries through saved scan recipes, resumed scans, Deep Scan
145
- discovery and reducer workers, and `scan --patch`. Standalone `validate`,
187
+ discovery workers, and `scan --patch`. Standalone `validate`,
146
188
  `patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
147
189
  Threads created by these commands retain the setting when resumed in Codex.
148
190
  Scans use isolated configuration, so set it on the CLI, SDK client, or project
@@ -152,8 +194,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
152
194
  an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
153
195
  or set top-level `daybreak = true` in the configuration loaded by the runner.
154
196
  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
197
+ Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
157
198
  persisted turn context, workers use their runner configuration; CLI and SDK scans
158
199
  use the explicit scan settings above.
159
200
 
@@ -181,7 +222,7 @@ codex-security scan /path/to/repository \
181
222
  In the SDK, select your model through `codexOverrides.model` and pass
182
223
  `auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
183
224
  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)
225
+ The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
185
226
  for configuration precedence and the API-key feature setting.
186
227
 
187
228
  `access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
@@ -236,6 +277,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
236
277
  codex-security scan . --provider cheaperinference --model gpt-5.4
237
278
  ```
238
279
 
280
+ ### Hugging Face compatibility
281
+
282
+ In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
283
+ `namespace` and could request `web_search`. Hugging Face's published Responses
284
+ implementation accepts `function` and remote `mcp` tool declarations. A named
285
+ Hugging Face scan provider is deferred until the scanner and router can exchange
286
+ the tools a complete scan requires. [Hugging Face's implementation notes](https://huggingface.co/docs/inference-providers/en/guides/gpt-oss#responses-api)
287
+ and [request schema](https://github.com/huggingface/responses.js/blob/0e3e84c469a9f59ad16e2eb3a0d6f1c4de637a7b/src/schemas.ts#L219-L232).
288
+
239
289
  ### Amazon Bedrock
240
290
 
241
291
  Use AWS credentials and a region with access to the exact Bedrock model ID:
@@ -255,6 +305,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
255
305
  for credential alternatives, restricted-model access, cost estimates, and
256
306
  reasoning-summary configuration.
257
307
 
308
+ ### Google Cloud Vertex AI cost estimates
309
+
310
+ The SDK estimates Standard online inference costs for OpenAI models served by
311
+ Google Cloud's Model as a Service (MaaS). Rates are in USD per million tokens.
312
+ [Google Cloud partner model pricing](https://cloud.google.com/model-garden/partner-models/pricing)
313
+ and [OpenAI model locations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/maas/openai).
314
+
315
+ | Managed model ID | Location | Input | Cached input | Output |
316
+ | -------------------------- | ----------------------- | ----: | -----------: | -----: |
317
+ | `openai/gpt-oss-120b-maas` | `global` | $0.09 | $0.09 | $0.36 |
318
+ | `openai/gpt-oss-20b-maas` | `us-central1` (retired) | $0.07 | $0.007 | $0.25 |
319
+
320
+ Google publishes a cache-hit discount only for 20B, so the estimator uses the
321
+ ordinary input rate for cached 120B tokens. Google retired the managed 20B
322
+ endpoint on October 21, 2026. The SDK retains its rates for historical usage.
323
+ [Google Cloud retirement schedule](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/open-models).
324
+
325
+ To estimate recorded usage locally, pass the managed model ID and the GCP
326
+ provider to `estimateScanCost`.
327
+
328
+ ```ts
329
+ import { estimateScanCost } from "@openai/codex-security";
330
+
331
+ const cost = estimateScanCost(
332
+ "openai/gpt-oss-120b-maas",
333
+ { input_tokens: 1_000_000, output_tokens: 500_000 },
334
+ { provider: "gcp" },
335
+ );
336
+ // cost?.estimatedUsd is 0.27.
337
+ ```
338
+
339
+ Google documents the managed GPT OSS IDs on its shared chat-completions API.
340
+ The bundled Codex `gcp` provider uses Google's Responses API with a separate
341
+ frontier model catalog. Google has published no Standard token rates for that
342
+ catalog, including GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, and GPT-6 Luna.
343
+ Those scans record token usage and require a published price to use
344
+ `--max-cost`. Self-deployed Model Garden endpoints incur infrastructure charges.
345
+ [Google Cloud's preview announcement](https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-brings-openai-models-to-customers).
346
+
258
347
  ## Generate a security policy
259
348
 
260
349
  Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
@@ -320,11 +409,11 @@ Add context with `--knowledge-base`:
320
409
  codex-security policy . --knowledge-base architecture.md
321
410
  ```
322
411
 
323
- | Invocation | Result |
324
- | ---------------------------- | -------------------------------------------------------- |
325
- | `policy . --headless --json` | Generate without prompts; return paths and review notes. |
326
- | `policy . --format md` | Generate and write the draft to stdout. |
327
- | `policy . --dry-run --json` | Check local inputs without calling Codex. |
412
+ | Invocation | Result |
413
+ | --------------------------- | -------------------------------------------------------- |
414
+ | `policy . --json` | Generate without prompts; return paths and review notes. |
415
+ | `policy . --format md` | Generate and write the draft to stdout. |
416
+ | `policy . --dry-run --json` | Check local inputs without calling Codex. |
328
417
 
329
418
  `--headless` leaves unanswered questions in the review notes. By default, files
330
419
  go in the Codex Security state directory. To choose a location, use an empty
@@ -430,6 +519,14 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
430
519
  requested work separately from optional `coverage.openQuestions` follow-up.
431
520
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
432
521
 
522
+ A dry run reports `stateDirectory`, the root for saved scan state. It checks the
523
+ storage location without creating a scan directory. Pass boolean scan options
524
+ as bare flags or use lowercase `=true` or `=false`.
525
+
526
+ When a cost limit is configured, `scan --dry-run` shows the resolved
527
+ `maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
528
+ against the limit and why in-flight requests can exceed it.
529
+
433
530
  Whole-codebase and path scans also accept ordinary directories, including SVN
434
531
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
435
532
 
@@ -441,7 +538,8 @@ be clean and at the commit recorded by the parent.
441
538
  Committed-diff scans require a clean, full checkout at the requested head
442
539
  revision, including when using `--validate`. A different checkout revision or
443
540
  local changes are rejected before scanning; check out the requested head and
444
- commit or stash local changes before retrying.
541
+ commit or stash local changes before retrying. The check also verifies tracked
542
+ files marked `assume-unchanged` and preserves their Git index flags.
445
543
 
446
544
  `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
447
545
  committed Git scan, using the same checkout, model, and reasoning effort. Owner
@@ -456,14 +554,25 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
456
554
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
457
555
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
458
556
  explicit unsupported binary files are rejected. Bulk scans share this context
459
- with every repository.
557
+ with every repository. Select external documents directly. Links in a checkout
558
+ must stay inside it. For bulk scans with bare or separate Git storage, use
559
+ canonical paths for shared documents and prompt files.
460
560
 
461
561
  Use `--output-dir DIR` to choose where a scan saves its results. The directory
462
562
  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.
563
+ Existing directories keep their permissions. Newly created directories are
564
+ private to you by default. On Windows, the directory and its parents must be
565
+ owned by your account, Administrators, SYSTEM, or TrustedInstaller. Choose a
566
+ path where another user cannot replace the output directory or one of its
567
+ parents. A parent can allow other users to read it or create sibling directories.
568
+ For an empty write destination, grant content-writing permissions to children
569
+ through inheritance. Other users must not have permission to set reparse data
570
+ on the destination directory itself.
571
+ `--archive-existing` moves earlier output to a sibling directory with a unique
572
+ suffix, such as `results.previous-ab12cd34` for an output directory named
573
+ `results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
574
+ the archive uses a short sibling name starting with `.previous-` and a hash of the
575
+ original filename. Use `--dry-run` to preview the move.
467
576
 
468
577
  Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
469
578
  optional export fails, the scan can still complete. Use the
@@ -503,7 +612,9 @@ or JSONL output produce:
503
612
  { "status": "failed", "code": "SCAN_FAILED", "message": "..." }
504
613
  ```
505
614
 
506
- With `--full-output`, the error appears under `error` in an `ok: false` envelope.
615
+ With `--full-output`, JSON and JSONL failures put the error under `error` in an
616
+ `ok: false` envelope. YAML and TOON use the same failed envelope when retained
617
+ sealed scan results are available (including TOON selected by default).
507
618
  If the scan target changed, the error explains that the results no longer
508
619
  represent the current checkout. Retained sealed results remain available under
509
620
  `data`, including their manifest, findings, review summary, scan directory, and report
@@ -515,19 +626,25 @@ selecting an unavailable field can return `null` or omit `data`.
515
626
  Saved-scan setup failures use the same output shape with
516
627
  `SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
517
628
  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.
520
-
521
- Diagnostics stay on stderr. Each command's `--schema --format json` describes
522
- its successful output and failure codes.
629
+ scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
630
+ on stderr without `--full-output`, or when retained results are unavailable.
631
+
632
+ Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
633
+ envelope with `error.code` and `error.message`. Command schema validation errors
634
+ with JSON or JSONL retain their field details and name missing or invalid
635
+ options by their CLI flags. Diagnostics stay on stderr.
636
+ `scan --schema --format json` describes optional caller inputs before defaults
637
+ and the fields returned by preflight, completed scans, and execution failures,
638
+ including sealed results recovered after an interruption.
523
639
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
524
640
 
525
641
  ### Follow-up finding validation
526
642
 
527
643
  Scans already validate findings against local source. Add `--validate` to run
528
644
  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
645
+ the scan, using the same selected Cyber access program. Validation sends each
646
+ finding to the configured model provider. Its review tools have read-only
647
+ filesystem access, with network access and web search disabled. Each assessment uses a
531
648
  separate evidence directory; the combined report is saved as
532
649
  `<scan-dir>/validation.md`, or a uniquely suffixed report
533
650
  if that path already exists. Each completed assessment is saved immediately;
@@ -571,26 +688,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
571
688
  fail after registration but before writing its artifacts; investigate those
572
689
  failures through its history record and any available logs. When artifacts were
573
690
  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.
691
+ the saved files:
692
+
693
+ | File | What to check |
694
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
695
+ | `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. |
696
+ | `findings.json` | Reported findings, source locations and supporting evidence. |
697
+ | `report.md` | A readable summary of the scope and findings. |
698
+
699
+ When a checkpoint is retained, `checkpoint-head.json` identifies the file in
700
+ `checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
701
+ unfinished work and `reviewState.openQuestions` lists follow-up questions.
702
+ Older manifests with `scan.coverageRef` point to a separate `coverage.json`
703
+ with reviewed surfaces, explicit exclusions and deferred work. A saved source
704
+ inventory identifies inputs. Neither that inventory nor session logs establish
705
+ which files the scan reviewed in full.
594
706
 
595
707
  For a local plugin scan, ask Codex to open the saved scan and explain its scope,
596
708
  exclusions, deferred work, and follow-up questions. CLI history can also locate
@@ -612,8 +724,8 @@ Choose the next step from the recorded reason:
612
724
  start a new scan with the intended scope, including for plugin scans without
613
725
  a recipe. Retained findings can still be reviewed, but absence of findings
614
726
  from a stopped run is inconclusive.
615
- - **A Deep Scan was interrupted and is still recorded as `running`:** it may
616
- support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
727
+ - **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
728
+ support [resume](#resuming-an-interrupted-scan) with the original checkout,
617
729
  artifacts, and session. Completed, failed, and canceled scans cannot resume.
618
730
 
619
731
  For example, after identifying an omitted API directory:
@@ -634,12 +746,13 @@ completeness values to determine scan status or exit codes.
634
746
 
635
747
  ```bash
636
748
  codex-security init
637
- codex-security scan . -c codex-security.yaml --dry-run --json
638
749
  codex-security info -c codex-security.yaml --json
750
+ codex-security scan . -c codex-security.yaml --dry-run --json
639
751
  ```
640
752
 
641
753
  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`,
754
+ Keep `-c` on both `info` and the scan preview to inspect the same target and
755
+ limits. Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
643
756
  `scan-components`, and `info` accept project files. SDK calls and saved reruns
644
757
  do not load them automatically.
645
758
 
@@ -657,16 +770,18 @@ from the config directory; scope paths resolve from the repository.
657
770
  ### Import findings as a saved scan
658
771
 
659
772
  ```bash
660
- codex-security scan import --csv /path/to/findings.csv
661
- codex-security scan import --json /path/to/findings.json --format json
662
- codex-security scan import --csv /path/to/findings.csv --dry-run
773
+ codex-security scan import /path/to/findings.csv
774
+ codex-security scan import /path/to/findings.json --json
775
+ codex-security scan import /path/to/report --input-format csv --dry-run
663
776
  ```
664
777
 
665
778
  Supply exactly one input. CSV follows the
666
779
  [findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
667
780
  JSON accepts a complete `codex-security.findings` document or
668
- `{ "findings": [...] }` matching the findings schema. For this command, `--json`
669
- selects the input file; use `--format json` for JSON output. The input must be a
781
+ `{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
782
+ Use `--input-format csv|json` to override it. Put `--json` after the filename
783
+ to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
784
+ can continue to select the input that way. The input must be a
670
785
  regular file with no symlinks or directory junctions in its path.
671
786
 
672
787
  Each import creates a completed scan in local history, retains the input under
@@ -693,7 +808,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
693
808
  Paths and snippets are fictional; repository files remain unchanged.
694
809
 
695
810
  Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
696
- archiving, and severity thresholds work normally. Reruns preserve mock mode.
811
+ archiving, and severity thresholds work normally. Use `scans show` to inspect a
812
+ mock scan. Mock scans have no Codex session logs. Reruns preserve mock mode.
697
813
  Separate matching or deduplication commands still make their usual model calls.
698
814
 
699
815
  Mock mode supports Standard repository, path, and diff scans. It cannot combine
@@ -746,6 +862,13 @@ codex-security scan-components . \
746
862
  --output-dir /path/outside/project/results
747
863
  ```
748
864
 
865
+ `--plan-only` with `--component` or `--components-file` validates local paths
866
+ without signing in. The CLI prints a command to scan the saved plan into a fresh
867
+ `results` directory inside the plan directory. Running that command starts scans.
868
+ Run it from the original working directory to reuse relative paths. The command
869
+ includes the selected project configuration and scan flags. Reapply any inline
870
+ `--codex` overrides yourself, since these can contain credentials.
871
+
749
872
  Plans use literal repository-relative paths, so `~/src` selects a directory
750
873
  named `~` inside the repository rather than expanding the home directory.
751
874
  Existing absolute paths inside the repository are also accepted.
@@ -772,11 +895,18 @@ individual scan folder.
772
895
  Failures do not stop other components. Failed scans or
773
896
  failed matching return `2`; severity-policy violations return `1`. Retry with
774
897
  `--components-file retry-components.json` and a new empty output directory.
775
- The retry report covers only those components.
776
-
777
- `--max-cost` applies per component, excluding planning and matching. `--model`
778
- and `--effort` also apply to matching; `--auth` applies throughout. Planning and
779
- matching reject ambient command providers that conflict with explicit ChatGPT
898
+ The retry report covers only those components. Each registered component keeps its
899
+ scan ID in the summary, including when the scan fails.
900
+
901
+ `--max-cost` applies per component, excluding planning and matching.
902
+ Use `--max-total-cost USD` with explicit components to split one estimated
903
+ budget among them. The smaller of each component's share and its per-scan
904
+ limit applies. Findings stay separate because model-based matching is skipped.
905
+ The total limit also skips owner suggestions, including when enabled in project configuration.
906
+ Automatic planning and post-scan prompts must run separately.
907
+
908
+ `--model` and `--effort` also apply to matching. `--auth` applies throughout.
909
+ Planning and matching reject ambient command providers that conflict with explicit ChatGPT
780
910
  or API-key auth. SDK-selected command providers retain their authentication.
781
911
 
782
912
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
@@ -801,6 +931,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
801
931
  `markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
802
932
  Markdown. A supplied snapshot takes precedence over a file.
803
933
 
934
+ A dry run reads and validates an explicit rubric before reporting a successful preflight.
804
935
  The scan saves the rubric text in its local launch recipe. Retrying a Standard
805
936
  scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
806
937
  with a saved rubric reuses that copy even if the remote default or file changes.
@@ -825,7 +956,7 @@ behavior are unchanged.
825
956
 
826
957
  The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
827
958
  Each launched scan or rerun gets its own allowance after setup, and reconnects
828
- do not reset it. Standard scans still do not support resume. For batch and
959
+ do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
829
960
  component scans, the project setting applies separately to each scan attempt,
830
961
  not to planning, result matching, or the total campaign.
831
962
 
@@ -836,13 +967,20 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
836
967
  --stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
837
968
  ```
838
969
 
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.
970
+ Deep Scan repeats Standard scans in batches of up to `--workers`, with
971
+ `--subagents` per scan. Workers can share what they are investigating, ask each
972
+ other to check a source location, and reply while their audits are running. Each
973
+ worker verifies the evidence it reports. Deep Scan merges each completed batch in launch order.
974
+ It uses source locations, cited code and weakness descriptions to match repeated
975
+ findings. Each group keeps its first description, all reported locations, and
976
+ the original observations. Later batches receive the titles and primary
977
+ locations of retained findings so workers can investigate other reachable paths.
978
+ `--stop-after-no-new` counts consecutive
979
+ completed scans that added no findings. `--max-discovery-runs` caps the total
980
+ number started, including failures. `--max-time` stops discovery and returns
981
+ the findings from completed scans.
844
982
 
845
- For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
983
+ For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
846
984
 
847
985
  Use project-file `scan.deep` settings or legacy
848
986
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
@@ -850,6 +988,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
850
988
  its default and maximum are 5760 minutes (96 hours). Unlike Standard's
851
989
  advisory allowance, the Deep discovery limit is enforced. Resuming a
852
990
  Deep scan keeps its original deadline; rerunning starts a new scan.
991
+ If the deadline expires before any source review completes, the saved report
992
+ and scan manifest record that limitation.
853
993
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
854
994
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
855
995
  hours. Explicit settings override lower-priority configuration across units.
@@ -896,18 +1036,21 @@ credentials, and workflow resume behavior.
896
1036
  For `dedupe --scan latest`, matching across worktrees or clones requires a Git
897
1037
  executable outside all saved scan targets. If a historical target includes the
898
1038
  available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
899
- explicit saved scan ID. Exact-path `latest` lookup still works without Git.
1039
+ explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
1040
+ scan targets; recorded Git generations require a trusted Git executable to verify
1041
+ that the checkout still owns its saved history.
900
1042
 
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.
1043
+ Repeat `--codex KEY=VALUE` for supported native settings. For example,
1044
+ `--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
1045
+ Command Prompt, and PowerShell. Repeated or conflicting keys are rejected,
1046
+ including a `--model` or `--effort` flag plus its native equivalent.
904
1047
 
905
1048
  To select a Codex file profile, put its settings in
906
1049
  `$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
907
1050
  `CODEX_HOME` is unset), then run:
908
1051
 
909
1052
  ```bash
910
- npx @openai/codex-security scan . --codex 'profile="review"'
1053
+ npx @openai/codex-security scan . --codex "profile='review'"
911
1054
  ```
912
1055
 
913
1056
  In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
@@ -933,11 +1076,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
933
1076
 
934
1077
  ```bash
935
1078
  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"'
1079
+ --codex "model_provider='gateway'" \
1080
+ --codex "model_providers.gateway.name='Gateway'" \
1081
+ --codex "model_providers.gateway.base_url='https://gateway.example.test/v1'" \
1082
+ --codex "model_providers.gateway.wire_api='responses'" \
1083
+ --codex "model_providers.gateway.env_key='GATEWAY_API_KEY'"
941
1084
  ```
942
1085
 
943
1086
  Set the provider's key environment variable before running. Patching and
@@ -963,12 +1106,14 @@ publication uses the same request attribution; embedding requests identify
963
1106
  the package and version in their `User-Agent`.
964
1107
 
965
1108
  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.
1109
+ Bedrock. They do not create a separate telemetry collector or make another
1110
+ provider's traffic visible to OpenAI. Local operation receipts separately record
1111
+ starts, outcomes, duration, and usage coverage; see
1112
+ [telemetry and measurement](telemetry.md).
968
1113
 
969
1114
  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
1115
+ `--codex analytics.enabled=false`. The setting carries into `scan --patch`,
1116
+ patch-risk assessment, and Deep Scan discovery workers, including
972
1117
  resumed workers. Selected-profile settings take precedence over root settings.
973
1118
  Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
974
1119
  workers, including exporter choices and prompt-logging controls.
@@ -977,32 +1122,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
977
1122
  authentication, or CLI update checks. Validation uses isolated configuration;
978
1123
  patching and verification preserve ambient project trust.
979
1124
 
1125
+ For scan outcomes, the workbench saves a separate, local `lifecycle` record
1126
+ with the scan ID, launch surface, available release versions, mode, timestamps,
1127
+ and committed status. A completed scan indicates whether it produced reportable
1128
+ findings. Use `codex-security scans list --json` for the current repository.
1129
+ To find an offline import, use `codex-security scans list --scan-root <DIR> --json`
1130
+ with its output directory. Imported scans have lifecycle mode `import`. The SDK
1131
+ exposes `onLifecycle`, and the CLI includes observations in verbose diagnostics.
1132
+ Canceling a newly registered SDK scan through its abort signal, closing the
1133
+ client during the scan, or receiving a canceled hosted execution records
1134
+ `canceled`. A scan that has already completed keeps its committed outcome.
1135
+ Applications can choose how to collect and export these observations.
1136
+
980
1137
  For filesystem and approval behavior, see the
981
- [local security model](../README.md#local-security-model).
1138
+ [local security model](sdk.md#local-security-model).
982
1139
 
983
1140
  ### Environment variables
984
1141
 
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`. |
1142
+ | Variable | Effect |
1143
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
1144
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
1145
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
1146
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
1147
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
1148
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
1149
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
1150
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
1151
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
1152
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
1153
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
1154
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
1155
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
1156
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
1157
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
1158
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
1159
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
1160
+ | `CI` | Disable interactive update notices. |
1161
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
1006
1162
 
1007
1163
  Custom Codex executables need thread source attribution for `exec` and
1008
1164
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -1012,11 +1168,16 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
1012
1168
  `pythonPath`, then
1013
1169
  `PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
1014
1170
  works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
1171
+ On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
1172
+ explicit path that selects an executable. Use an absolute path or a `./`
1173
+ prefix for filenames beginning or ending in whitespace. Bare command names
1174
+ are trimmed before lookup.
1015
1175
 
1016
1176
  ### Troubleshooting
1017
1177
 
1018
1178
  Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
1019
- retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,
1179
+ retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events
1180
+ such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,
1020
1181
  saved failures, receipts, and patch-risk summaries. Review it for sensitive
1021
1182
  information before sharing; upstream Codex output may already be redacted.
1022
1183
 
@@ -1025,6 +1186,12 @@ Finish older-version operations before upgrading. Never remove
1025
1186
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
1026
1187
  credential home before manually removing an old `.codex-security-scan.lock`.
1027
1188
 
1189
+ If a scan reports that its state directory overlaps a protected root, choose a
1190
+ private directory in a separate tree, such as a sibling of the protected root.
1191
+ Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
1192
+ scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
1193
+ can match `"state"` for this case.
1194
+
1028
1195
  If credential-home preparation fails, the error includes the underlying
1029
1196
  filesystem diagnostic. For permission or read-only filesystem errors, check
1030
1197
  the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
@@ -1034,6 +1201,11 @@ and does not migrate existing credentials or reports.
1034
1201
  Sandbox startup errors include the native diagnostic followed by a command to
1035
1202
  reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
1036
1203
 
1204
+ If Windows Application Control blocks `windows.node` while validating a scan
1205
+ output directory, look for the module's block event in Event Viewer under
1206
+ Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
1207
+ [Microsoft's App Control event reference](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/operations/event-id-explanations)
1208
+
1037
1209
  On Windows, credential-home checks require trusted ownership and permissions
1038
1210
  through every ancestor, including the volume root. Codex Security can repair
1039
1211
  the credential home and its descendants; it does not change ancestor ownership
@@ -1090,10 +1262,13 @@ their own timestamps, window durations, and reset times. These are historical
1090
1262
  observations, not a live allowance check or scan-only consumption. Empty readings
1091
1263
  mean allowance was unavailable. There is no token-to-allowance conversion here.
1092
1264
 
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.
1265
+ Cost displays use Standard token rates for the model. OpenAI models use
1266
+ [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). OpenAI
1267
+ 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).
1268
+ For managed OpenAI models on Vertex AI, see [Google Cloud Vertex AI cost estimates](#google-cloud-vertex-ai-cost-estimates).
1269
+ The short/long-context range estimates usage at published rates. Other service
1270
+ tiers, account discounts, and ChatGPT subscription allowance are outside that
1271
+ estimate. Models without known prices have no estimate.
1097
1272
 
1098
1273
  JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
1099
1274
  and `context: "unknown"`). A null maximum means no upper estimate is available.
@@ -1108,13 +1283,26 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
1108
1283
  Automatic history matching gets at most one extra call with a limit; if more
1109
1284
  work is needed, the scan is preserved and you can run `scans match --all`.
1110
1285
 
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.
1286
+ A scan with a cost limit requires complete token usage for its recorded scan,
1287
+ worker, and custom validation sessions before the SDK returns a completed result.
1288
+ The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
1289
+ (Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
1290
+ Node.js decoder bundled with the plugin.
1291
+ Missing or unreadable usage fails budget verification. Without a limit, usage
1292
+ reporting remains best effort.
1293
+
1294
+ When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
1295
+ report and retains unvalidated candidates as follow-up work. The saved report and
1296
+ the manifest's `scan.scope.limitations` record that validation was deferred.
1297
+ Reaching a configured limit with a valid finalized report returns `0` by default,
1298
+ or `1` if findings meet a configured failure threshold.
1299
+
1300
+ When a worker turn fails with a known cybersecurity policy refusal or an
1301
+ exhausted usage limit, Deep Scan stops retries and replacements, cancels active
1302
+ siblings, and retains completed worker artifacts. A capability check can succeed
1303
+ before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
1304
+ scan and its retained results. To run it again from a saved recipe, use
1305
+ `scans rerun SCAN_ID`, which starts fresh discovery.
1118
1306
 
1119
1307
  At 80% of a single interactive scan's limit, the dashboard offers a higher total
1120
1308
  budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
@@ -1193,7 +1381,8 @@ the campaign a joint source review across repositories. For that workflow, use
1193
1381
 
1194
1382
  Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
1195
1383
  selection. It lists repositories pushed in the last 90 days, excluding forks
1196
- and archives, asks for output, and saves the selection as `repositories.csv`.
1384
+ and archives, asks where to save results, and saves the selection as `repositories.csv`.
1385
+ Pass `--output-dir DIR` to set the initial answer in the wizard.
1197
1386
  Private checkouts use your GitHub CLI login.
1198
1387
 
1199
1388
  For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
@@ -1209,7 +1398,32 @@ codex-security bulk-scan repositories.csv \
1209
1398
  --output-dir /path/outside/repositories/results --workers 4
1210
1399
  ```
1211
1400
 
1401
+ `--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
1402
+ estimated limit among the pending repositories and their possible attempts for
1403
+ this invocation, including recovery. For example, a $12 limit with three pending
1404
+ repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
1405
+ overrun reduces the remaining budget for queued attempts. In-flight work can
1406
+ exceed a limit. The total limit skips model-based matching and owner suggestions,
1407
+ including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
1408
+ limit and includes prior recorded usage in its cost estimate.
1409
+
1212
1410
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1411
+ Bulk checkout, scan, and recovery processes select host tools outside every local
1412
+ source and campaign checkout. Inventory uses an external ripgrep executable or
1413
+ the copy shipped with the selected Codex installation.
1414
+
1415
+ On POSIX, campaign processes and script-based inventory tools search readable
1416
+ tool directories. Launchers must be readable so their shebang interpreters can
1417
+ be checked. Use an absolute interpreter path for campaign scripts, including
1418
+ `#!/usr/bin/env sh`, because workers run in different directories. If a directory
1419
+ contains an ineligible executable, its other tools remain available through a
1420
+ temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
1421
+ their installed location when the packaged dispatcher can start. Keep other
1422
+ prefix-sensitive tools, including Python virtual environments, in directories
1423
+ where every entry can be used. On Windows, the campaign omits a tool directory
1424
+ from the child PATH if its Git, ripgrep, or Node executable link passes through a
1425
+ selected source.
1426
+
1213
1427
  CSV scopes are literal paths relative to each checkout, including names such
1214
1428
  as `~/src`.
1215
1429
  Configured diff or working-tree scopes are rejected unless every affected row
@@ -1224,6 +1438,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
1224
1438
  attempt per pending repository per invocation. Repeating the command continues
1225
1439
  the campaign, skips completed results, and starts pending attempts. Occupied
1226
1440
  attempt directories stop that repository and suggest `--recover`.
1441
+ If an ordinary attempt finds its checkout path already occupied, it stops before
1442
+ fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
1443
+ existing checkout before an ordinary retry.
1444
+ If checkout cleanup previously failed, the next invocation removes it only when
1445
+ its marker still identifies the same directory and scan attempt. Older or
1446
+ replacement checkouts without a matching marker are preserved.
1227
1447
  Completed results are skipped only when their saved contract and seal are valid
1228
1448
  and the manifest records a completed scan. Damaged or unsuccessful results get a
1229
1449
  new attempt, including with `--recover`, while the old artifacts remain available.
@@ -1234,6 +1454,12 @@ require a new output directory. Version 1 manifests also require a new directory
1234
1454
  because their original knowledge inputs and direct overrides cannot be verified.
1235
1455
  Worker and retry counts can change when resuming.
1236
1456
 
1457
+ On POSIX, local repository paths retain `..` components in the campaign manifest
1458
+ so distinct symlink traversals remain distinct sources. Older campaigns may have
1459
+ recorded a normalized absolute path instead. Use that recorded path to resume the
1460
+ previously selected source; it can differ from the physical target selected by
1461
+ the original traversal. Use a new output directory to scan the corrected target.
1462
+
1237
1463
  ### Recovering failed or interrupted bulk scans
1238
1464
 
1239
1465
  Use the original CSV, output directory, and options:
@@ -1253,10 +1479,12 @@ failed or interrupted attempt:
1253
1479
  - An unavailable, failed, or canceled scan starts a new attempt at the pinned
1254
1480
  revision, preserving old artifacts and checkouts.
1255
1481
 
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`.
1482
+ Each nonempty committed line in `results.jsonl` must be valid JSON with a string
1483
+ task ID and a positive safe integer attempt number. If a line fails these checks,
1484
+ the command reports its line number and preserves the ledger. Restore a complete
1485
+ ledger backup that includes every committed attempt, or start a separate campaign
1486
+ in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
1487
+ a fresh attempt requires a new campaign.
1260
1488
 
1261
1489
  New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
1262
1490
  workers and one recovery/new attempt per repository. A resume connection failure
@@ -1326,32 +1554,56 @@ Supply the validation prompt again when rerunning.
1326
1554
 
1327
1555
  ## Import vendor findings locally
1328
1556
 
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.
1557
+ 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
1558
 
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.
1559
+ | Input and goal | Command | Service contacted | Where to find the result |
1560
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1561
+ | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1562
+ | 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. |
1563
+ | 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`. |
1564
+ | 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. |
1565
+ | 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
1566
 
1340
1567
  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.
1568
+ takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
1569
+ The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
1570
+ saving findings or calling a model. For example, preview a complete Endor
1571
+ Finding export from the matching checkout, replacing the namespace, project
1572
+ and branch in the source key.
1573
+
1574
+ ```sh
1575
+ codex-security publish findings /private/path/endor-findings.json --provider endor \
1576
+ --to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
1577
+ ```
1578
+
1579
+ After reviewing the findings and exclusions, rerun the command without
1580
+ `--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).
1581
+
1582
+ 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
1583
 
1345
1584
  Local readback uses `findings imported [PATH]`. The path defaults to the current
1346
1585
  directory. Each imported record starts as `not_assessed`. Unknown revisions and
1347
1586
  locations stay unknown. Repository-scoped sources are checked against comparable
1348
1587
  configured Git remotes as described in the provider guide. Reimporting the same
1349
1588
  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.
1589
+ Records omitted from the new selection stay stored. Local imports can retain
1590
+ evidence that exceeds Cloud's per-finding limits.
1591
+
1592
+ If a report contains both ready and excluded records, the local dry run exits
1593
+ with status 0. After confirmation, the import stores the ready records and
1594
+ exits with status 1. If all records are excluded, both commands exit with
1595
+ status 2. A clean empty report exits with status 0 in either mode and stores
1596
+ no findings.
1597
+
1598
+ Preview the same file and source key again for the intended destination before
1599
+ publishing. Semgrep Guardian selections, Web API SAST selections and full
1600
+ 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.
1352
1601
 
1353
- For completed scans exported in the Codex Security JSON or CSV format, use
1354
- [scan import](#import-findings-as-a-saved-scan).
1602
+ ## Import Trivy dependency findings
1603
+
1604
+ Use `--provider trivy` for language-package vulnerabilities in schema-v2
1605
+ repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
1606
+ to set the scan root and check manifest paths.
1355
1607
 
1356
1608
  ## Import Endor Labs findings
1357
1609
 
@@ -1359,31 +1611,88 @@ Use `--provider endor` for one Endor project and context. The
1359
1611
  [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1360
1612
  SARIF compatibility, and the local preview.
1361
1613
 
1614
+ ## Import SonarQube Cloud issues
1615
+
1616
+ `import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
1617
+ that capture for the intended destination before confirming. A Cloud confirmation
1618
+ saves the issues locally and publishes them. Use `--full-output` with
1619
+ `--format json` or `--format jsonl` for a structured result.
1620
+ [Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
1621
+
1622
+ ## Import GitHub findings locally or to Cloud
1623
+
1624
+ Use `--provider github` with separate source keys for
1625
+ [code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
1626
+ [Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
1627
+ [security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1628
+ Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
1629
+
1630
+ ### Import GHSA advisories separately
1631
+
1632
+ Use `import github-advisories OWNER/REPO` for published repository advisories
1633
+ or add `--github-advisory-source global` and one or more `--github-advisory`
1634
+ IDs to collect global advisories. Check the installed dependency against each
1635
+ affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1636
+
1637
+ ## Import alerts from the CLI
1638
+
1639
+ Collect open code-scanning alerts on the default branch and save the complete
1640
+ array outside the checkout. Use a private temporary directory and run
1641
+ validation from the matching checkout. Validation sends the evidence to your
1642
+ configured model provider.
1643
+
1644
+ ```sh
1645
+ out=$(mktemp -d) &&
1646
+ codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
1647
+ codex-security validate "$out/alerts.json"
1648
+ ```
1649
+
1650
+ The collector reads alerts, including third-party SARIF uploads. It does not
1651
+ start a scan. For filters, ref selection and SDK validation, see the
1652
+ [code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
1653
+
1362
1654
  ## Publish findings to Cloud
1363
1655
 
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.
1656
+ Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
1657
+ 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
1658
 
1369
1659
  ### Preview and publish
1370
1660
 
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`.
1661
+ Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
1662
+ Enterprise repository URL or its Cloud ID. Either works for retries. If
1663
+ several connectors share the URL, use the ID. You can import before the
1664
+ repository's first native scan.
1665
+
1666
+ Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
1667
+ `cli_auth_credentials_store` set in your Codex `config.toml`
1668
+ (`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
1669
+ can be saved in the system keyring. To publish, set
1670
+ `cli_auth_credentials_store = "file"` there, then run `codex-security login`
1671
+ with the ChatGPT account you want to use. `codex-security login status`
1672
+ checks the current sign-in without changing credential storage.
1673
+
1674
+ ### Review the Cloud destination
1675
+
1676
+ Run the command with `--dry-run --format json`. Check `accountId`,
1677
+ `cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
1678
+ `excluded` with the records you meant to import.
1679
+
1680
+ - **Private findings inbox.** If the preview includes `privateImport`, the
1681
+ report goes to your inbox. The repository and connector identify the
1682
+ suggested assessment target. Check `format`, `bytes` and `sha256` in
1683
+ `privateImport` to identify the upload. The CLI and SDK encode the reviewed
1684
+ occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
1685
+ inbox that requires native records or has a smaller upload limit can receive
1686
+ native records that reproduce the reviewed evidence.
1687
+ - **Repository publisher.** Check `repository.environment_id` in each entry
1688
+ of `requests`. The publisher checks the current source versions. Existing
1689
+ records keep their environment. New records use the repository's authorized
1690
+ default.
1691
+
1692
+ To import, run the same command without `--dry-run` and confirm. The terminal
1693
+ shows the file, exclusions, severities and up to five finding IDs and titles.
1694
+ The prompt defaults to No. For a noninteractive import, add `--yes` after
1695
+ reviewing the full JSON preview.
1387
1696
 
1388
1697
  ### Configure an alternate Cloud deployment
1389
1698
 
@@ -1402,23 +1711,62 @@ instructions. API requests always use the API root. The older
1402
1711
 
1403
1712
  ### Resume interrupted imports
1404
1713
 
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.
1714
+ If the result includes `savedSubmission`, keep that checkpoint. Rerun the
1715
+ original command with `--dry-run --format json` using the same build, input, account,
1716
+ destination, API endpoint and state directory. Check `cloudApiUrl`. If
1717
+ `resumed` is true, confirm to continue the saved submission. If it's false,
1718
+ review the new submission before confirming. Finish older-format pending submissions with the client that created them. If a response was lost, check the inbox job or repository records before starting a fresh upload.
1719
+
1720
+ - **Private inbox.** The CLI checks the report digest and reuses its saved
1721
+ request IDs. It can read an accepted job even if the deployment has since
1722
+ disabled uploads. After an inbox reset, check the new report format, size
1723
+ and digest before confirming.
1724
+ - **Repository publisher.** The CLI saves each request privately before
1725
+ sending up to 100 findings. Retries use the same publisher, request IDs and
1726
+ bodies. If the repository has been reset, preview and confirm a fresh
1727
+ submission.
1728
+
1412
1729
  [Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
1413
1730
 
1414
1731
  ### Results and exit codes
1415
1732
 
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. |
1733
+ | Status | Exit code | Meaning |
1734
+ | ------------- | --------- | -------------------------------------------------------------------------------------- |
1735
+ | `empty` | 0 | No records were available to upload. |
1736
+ | `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
1737
+ | `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
1738
+ | `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
1739
+ | `failed` | 2 | Preparation failed before upload. |
1740
+
1741
+ A clean empty report needs no confirmation. Self-contained file imports can
1742
+ finish before Cloud sign-in; Semgrep Platform and Snyk REST captures use the
1743
+ Cloud catalog to verify their repository. Local imports still validate the
1744
+ checkout and create no workbench database. Explicit scanner errors
1745
+ and selections containing only excluded records fail; JSON output retains their
1746
+ diagnostics and exclusion reasons. Existing findings stay open.
1747
+
1748
+ For automation, check the scanner's exit status as well as the import's. SARIF
1749
+ can contain no runs or omit results in a rules-only export. `empty` describes
1750
+ the selected report, not whether a scan completed successfully.
1751
+
1752
+ For a partial or interrupted import, check `excluded` and any `error` before
1753
+ retrying. Some records may already have reached Cloud.
1754
+
1755
+ - **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
1756
+ and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
1757
+ uploaded file (`input.file_id`). The CLI reads the job receipt, so a
1758
+ successful import can show `verified: 0`. To share a finding, open it in
1759
+ your inbox, assess it against a pinned repository revision and publish the
1760
+ reportable assessment.
1761
+ - **Repository publisher.** `verified` counts records whose identity the CLI
1762
+ confirmed by reading them back. If the version matches the receipt, the CLI
1763
+ also checks the evidence. A newer version can have different evidence and
1764
+ still count as verified. `unacknowledged` counts records awaiting a receipt,
1765
+ including records Cloud accepted if the response was lost. Use `client_id`
1766
+ to match a receipt item to its request and `source_finding_id` in `failures`
1767
+ to find a failed vendor record. Counts include earlier batches with receipts.
1768
+ When present, `cloudUrl` opens the repository. Assessment and sharing are
1769
+ separate steps.
1422
1770
 
1423
1771
  With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
1424
1772
  Failed and interrupted imports set `ok` to `false` and `error.code` to
@@ -1426,235 +1774,37 @@ Failed and interrupted imports set `ok` to `false` and `error.code` to
1426
1774
  Other formats reject `--full-output` before reading the file or contacting
1427
1775
  Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
1428
1776
 
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.
1777
+ Progress goes to stderr and JSON results to stdout. The repository publisher
1778
+ uploads sequentially and uses up to four concurrent requests for lookups and
1779
+ readback.
1435
1780
 
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.
1781
+ ### Import Snyk findings
1441
1782
 
1442
- ### Import Snyk Open Source findings
1443
-
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.
1783
+ Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
1784
+ monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
1785
+ covers saved files, distinct source keys for each format, and collection with
1786
+ `import snyk`.
1448
1787
 
1449
1788
  ### Import Wiz findings
1450
1789
 
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
- ```
1537
-
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
- ```
1790
+ <a id="select-findings-and-a-destination"></a>
1791
+ <a id="package-vulnerability-inputs"></a>
1792
+ <a id="sast-repository-secrets-and-iac-inputs"></a>
1793
+ <a id="preserved-evidence"></a>
1794
+ <a id="convert-csv-reports"></a>
1608
1795
 
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.
1796
+ Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
1797
+ The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
1798
+ [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),
1799
+ [retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
1800
+ [conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
1654
1801
 
1655
1802
  ### Publish completed scans
1656
1803
 
1657
- Preview selected completed scans before uploading:
1804
+ The public `publish scan --help` menu describes Linear and custom publication
1805
+ from saved scans. The CSV input below belongs to Cloud publication.
1806
+ The following workflow is available to installations with Cloud publication access.
1807
+ Preview selected completed scans locally before uploading them.
1658
1808
 
1659
1809
  ```bash
1660
1810
  codex-security publish scan --to cloud --dry-run --json
@@ -1668,12 +1818,15 @@ prefix of at least eight characters, or `latest` for the current repository.
1668
1818
  Local sealed artifacts are required. Dry runs need no login or network access.
1669
1819
 
1670
1820
  Uploads require ChatGPT credentials saved to a file. Set
1671
- `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.
1672
- Cloud publication rejects automatic/keyring storage even when `auth.json` exists,
1673
- because that file may be stale or belong to another account.
1674
-
1675
- Use a positional scan directory or repeated `--scan-dir PATH` for artifacts
1676
- outside history. Each must contain one completed sealed scan, not a bulk-run
1821
+ `cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
1822
+ `codex-security login` again. Login, scans and other commands use that setting
1823
+ for the Codex Security sign-in.
1824
+ A dedicated login using automatic storage can publish if Codex Security
1825
+ recorded the native file fallback. An unverified file can belong to another
1826
+ account, so Cloud publication requires an explicit file store for an ambient login.
1827
+
1828
+ Use `publish scan DIR --to cloud` for one directory outside history. For
1829
+ multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
1677
1830
  directory or `results.jsonl`. Do not mix directories with `--scan`.
1678
1831
  Cloud also accepts exported CSV:
1679
1832
 
@@ -1705,7 +1858,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
1705
1858
  for the picker. Live publication and `--skip-existing` require local history.
1706
1859
  A directory-only dry run does not.
1707
1860
 
1708
- `--linear-project PROJECT_ID` (`--project`) selects a project. Flags override
1861
+ `--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
1862
+ `--project PROJECT_ID` spelling continue to work. Flags override
1709
1863
  `CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
1710
1864
  previews titles offline; `--json` returns structured output.
1711
1865
 
@@ -1717,10 +1871,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
1717
1871
 
1718
1872
  ```bash
1719
1873
  codex-security publish check /path/to/completed-scan \
1720
- --to linear --linear-team TEAM_ID --json
1874
+ --linear-team TEAM_ID --json
1721
1875
  ```
1722
1876
 
1723
- `publish check` verifies artifacts and recorded publications. With an API key,
1877
+ `publish check` verifies scan artifacts and recorded Linear publications. With an API key,
1724
1878
  it also checks authentication and destination access. It does not test issue
1725
1879
  creation; connected-app access is reported as `not-checked`.
1726
1880
 
@@ -1729,15 +1883,16 @@ Choose a destination authorized to receive that content. Local history records
1729
1883
  successful issue IDs separately from sealed artifacts. The CLI and the plugin's
1730
1884
  finding-tracking workflow share these records when using the same Codex Security
1731
1885
  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
1886
 
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.
1887
+ By default, publishing the same scan again creates new issues. With
1888
+ `--skip-existing`, the CLI skips occurrences with a recorded success for the
1889
+ same team and project. This includes issues the plugin created or reused.
1890
+ The CLI checks local history only. After an interrupted or concurrent run,
1891
+ check Linear for an existing issue before retrying.
1892
+
1893
+ If the CLI and plugin share a database from an older installation, upgrade
1894
+ both together. The shared history preserves existing Linear receipts, but
1895
+ publishers that require the old table can no longer record new ones.
1741
1896
 
1742
1897
  ```ts
1743
1898
  import { publishScan } from "@openai/codex-security";
@@ -1778,7 +1933,9 @@ request. It sends the config name without findings or account identifiers.
1778
1933
  If the request fails, times out, or returns an invalid rubric, the built-in
1779
1934
  rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
1780
1935
  uses your policy for every review. Rubrics and repeatable `--knowledge-base`
1781
- context accept text, PDF, DOCX, and directories.
1936
+ context accept text, PDF, DOCX, and directories. Select external documents directly.
1937
+ Links in the artifact directory or a saved checkout must stay inside their source.
1938
+ When `--scan` cannot verify the saved checkout, use the document's canonical path.
1782
1939
 
1783
1940
  Each finding is classified three times by default. `--runs N` accepts
1784
1941
  an integer from 1 through 10; SDK options use `classificationRuns` with the same
@@ -1820,15 +1977,17 @@ or effort. A successful
1820
1977
  run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
1821
1978
  unchanged.
1822
1979
 
1823
- Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
1824
- `uniqueFindingIds` can represent findings from another scan; replace an outside-scan
1825
- representative with a member of its `duplicateGroups` entry from this scan.
1980
+ Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
1981
+ `scanRepresentativeFindingIds` for this selection, in the same order as its
1982
+ corpus-wide `uniqueFindingIds`.
1826
1983
  Linear publication defaults to saved classification selection, omits exclusions,
1827
1984
  and uses assessed severity for title and priority. Descriptions retain original
1828
1985
  severity and add the classification rationale. Publication rejects incomplete or
1829
1986
  stale assessments. It never reclassifies or rereads the rubric at publication time.
1830
1987
 
1831
1988
  ```bash
1989
+ # List the IDs you can pass to --finding-id.
1990
+ codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
1832
1991
  codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
1833
1992
  --finding-id FINDING_ID
1834
1993
  codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
@@ -1843,46 +2002,32 @@ import {
1843
2002
  classifySeverity,
1844
2003
  classifyScanSeverity,
1845
2004
  classifyScanDirectorySeverity,
2005
+ deduplicateScanDirectory,
1846
2006
  publishScan,
1847
- type FindingsDocument,
1848
2007
  } from "@openai/codex-security";
1849
- import { readFile } from "node:fs/promises";
1850
- import { join } from "node:path";
1851
2008
 
1852
2009
  // Assess supplied reports in memory.
1853
- const classification = await classifySeverity(findings, {
2010
+ await classifySeverity(findings, {
1854
2011
  rubricPath: "/path/to/policy.md",
1855
2012
  knowledgeBasePaths: ["/path/to/context.md"],
1856
2013
  });
1857
2014
 
1858
2015
  // Save assessments for a scan ID or sealed directory.
1859
2016
  await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
1860
- const scanFindings = (
1861
- JSON.parse(
1862
- await readFile(join(scanDirectory, "findings.json"), "utf8"),
1863
- ) as FindingsDocument
1864
- ).findings;
1865
- const scanFindingIds = new Set(
1866
- scanFindings.map((finding) => finding.findingId),
1867
- );
1868
- // dedupeResult was produced by deduplicating this same scan.
1869
- const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
1870
- if (scanFindingIds.has(representative)) return representative;
1871
- return dedupeResult.duplicateGroups
1872
- .find((group) => group.includes(representative))!
1873
- .find((member) => scanFindingIds.has(member))!;
2017
+ const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
2018
+ repository: "/path/to/repository",
1874
2019
  });
1875
- await classifyScanDirectorySeverity(scanDirectory, {
2020
+ const classification = await classifyScanDirectorySeverity(scanDirectory, {
1876
2021
  rubricPath: "/path/to/policy.md",
1877
- findingIds: selectedIds,
2022
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1878
2023
  });
1879
2024
 
1880
- // Or supply an in-memory assessment directly to publication.
2025
+ // Preview Linear publication for those same findings using their assessments.
1881
2026
  await publishScan(scanDirectory, {
1882
2027
  destination: "linear",
1883
2028
  teamId: "TEAM_ID",
1884
2029
  classification,
1885
- findingIds: classification.assessments.map(({ findingId }) => findingId),
2030
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1886
2031
  dryRun: true,
1887
2032
  });
1888
2033
  ```
@@ -1989,24 +2134,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
1989
2134
  ## Scan history and reruns
1990
2135
 
1991
2136
  Commands default to the current repository. IDs accept unique prefixes of at
1992
- least eight characters.
1993
-
1994
- | Command | Purpose |
1995
- | ----------------------------------------------------- | ---------------------------------------------------------- |
1996
- | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
1997
- | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
1998
- | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
1999
- | `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |
2000
- | `scans rerun [SCAN_ID]` | Repeat on the current checkout. |
2001
- | `scans match BEFORE AFTER` | Link findings with the same root cause. |
2002
- | `scans match --all` | Match completed scans across worktrees/clones. |
2003
- | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2004
- | `findings list [REPOSITORY]` | List open findings. |
2005
- | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2006
- | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2007
-
2008
- Without an ID, `scans show` selects the latest completed scan, while `scans logs`
2009
- selects the latest scan of any status. After a successful scan followed by a
2137
+ least eight characters. Reading empty history leaves the workbench database uninitialized.
2138
+
2139
+ Linked Git worktrees share scans, findings, and reviewer decisions when their
2140
+ scans record the same repository generation in the selected state database.
2141
+ Older scans without this evidence remain target-local. Removed worktrees retain
2142
+ their recorded history; a reused checkout path does not inherit its previous
2143
+ owner's history. Separately verified clones can still be compared explicitly,
2144
+ but their finding histories remain separate.
2145
+
2146
+ Finding confirmation and automatic post-scan matching follow completion order
2147
+ in the workbench, without changing sealed report timestamps.
2148
+
2149
+ | Command | Purpose |
2150
+ | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
2151
+ | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
2152
+ | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
2153
+ | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
2154
+ | `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
2155
+ | `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
2156
+ | `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
2157
+ | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2158
+ | `findings list [REPOSITORY]` | List open findings. |
2159
+ | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2160
+ | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2161
+
2162
+ In the terminal, `findings list` shows the occurrence ID for each open finding.
2163
+ Copy that ID into `findings false-positive` with your reason. Subsequent scans can
2164
+ use the explanation while it applies. In `scans show SCAN_ID --json`, each
2165
+ displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
2166
+ a repository with no saved scan history separately from one with zero open findings.
2167
+ From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
2168
+
2169
+ With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
2170
+ selects the latest scan of any status. Both prefer a scan in the current
2171
+ worktree when one qualifies. After a successful scan followed by a
2010
2172
  failed or active scan, these defaults refer to different runs. Human output
2011
2173
  identifies the selected run, labels its saved update time, and gives matching
2012
2174
  commands with its full scan ID:
@@ -2024,9 +2186,24 @@ history. Inspect its saved status before choosing resume or rerun, and supply
2024
2186
  the original custom prompt files for reruns. Structured history and log output
2025
2187
  and command selection defaults are unchanged.
2026
2188
 
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:
2189
+ Without an ID, rerun selects the latest completed scan in the current worktree.
2190
+ If only a related checkout has a completed scan, rerun shows its ID, path, and
2191
+ revision. Pass that ID to run the saved recipe using the files currently at its
2192
+ saved checkout and context paths. Reruns do not reload project files.
2193
+ The readable scan recipe records your authentication choice. A separate private
2194
+ replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
2195
+ `model_providers` settings, including any credentials written directly in
2196
+ `http_headers`. If you use `env_key` or `env_http_headers`, the profile stores
2197
+ the variable names. Set those variables when you rerun or resume. Settings
2198
+ inherited from a named file profile are reloaded from that file. If an older
2199
+ scan omitted your endpoint, start a new scan with the original `--codex` override.
2200
+
2201
+ When routing through environment variables, set them for each launch, including
2202
+ rerun and resume. Deep workers inherit `CODEX_OSS_BASE_URL` and `CODEX_OSS_PORT`
2203
+ for Ollama and LM Studio, and `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`,
2204
+ and `GOOGLE_APPLICATION_CREDENTIALS` for Vertex AI.
2205
+
2206
+ Supply replacement scan and custom-validation prompts when the original used them:
2030
2207
 
2031
2208
  ```bash
2032
2209
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
@@ -2048,25 +2225,64 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
2048
2225
  writable, and outside the target repository. Session logs may contain sensitive
2049
2226
  data even though scan recipes do not store credentials.
2050
2227
 
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.
2228
+ Keep the same state directory across linked worktrees. Changing it selects
2229
+ separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
2230
+ filters recorded artifact paths; it does not import another directory's scans.
2231
+
2232
+ The workbench records the outer checkout directory when it registers a target.
2233
+ A later nested checkout cannot make tools from that directory eligible for
2234
+ automatic discovery. When an older saved target lacks a recorded checkout
2235
+ directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
2236
+ executable outside the checkouts. If you use a system Python instead of the
2237
+ Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
2238
+
2239
+ Saved scan logs retain the finishing turn, including its final response, and
2240
+ exclude later turns once the scan records a completion boundary. Older scans
2241
+ retain the full history of their attributed sessions and keep their existing
2242
+ worker-selection boundaries. This also applies to logs attached with
2243
+ `feedback --include-logs`.
2244
+
2245
+ Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
2246
+ work on all supported Node.js versions, including logs, feedback attachments,
2247
+ usage accounting, and saved-session discovery for resume. A bundled decoder
2248
+ reads concatenated frames and reports truncated streams as collection errors.
2056
2249
 
2057
- ### Resuming an interrupted Deep Scan
2250
+ ### Resuming an interrupted scan
2058
2251
 
2059
2252
  ```bash
2060
2253
  codex-security scans list --scan-root /path/to/security-scans
2061
2254
  codex-security scans resume SCAN_ID
2062
2255
  ```
2063
2256
 
2257
+ The terminal list shows the full scan ID and labels the last activity of a
2258
+ `running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
2259
+ launch recipe and its original session, it also shows the resume command to use after interruption.
2260
+
2064
2261
  The scan must still be `running`, with its original checkout, output directory,
2065
2262
  and Codex session in the same state directory. Checkout identity, revision, and
2066
2263
  contents must match. Completed, failed, and canceled scans need a rerun instead.
2067
2264
 
2068
- Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
2069
- settings/instructions. Knowledge-bearing scans save their extracted documents in
2265
+ On Windows, keep the protected `.codex-security-resume` directory in the scan
2266
+ output. It lets the workbench verify the original output even before the first
2267
+ checkpoint. If an older scan stopped with an empty output, start a new scan with
2268
+ `codex-security scans rerun SCAN_ID`.
2269
+
2270
+ New Windows Standard and Deep Scans also record the checkout's native volume and file ID
2271
+ when the filesystem supplies them. Validation and remediation verify the same
2272
+ checkout identity. An older scan can resume across Python
2273
+ versions when its saved checkout identity can be verified. If the workbench
2274
+ cannot verify it, resume with the Python runtime that started the scan or use
2275
+ `codex-security scans rerun SCAN_ID` to start a new scan.
2276
+
2277
+ Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
2278
+ and accumulated cost. A Standard scan continues in its original Codex session with
2279
+ the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
2280
+ can run it at a time. If the connection fails after the session is saved, the CLI
2281
+ prints the resume command. Work since the last checkpoint may need to be repeated.
2282
+ Use `scans rerun` for canceled or failed scans, including authentication failures.
2283
+ For custom validation, rerun with the original validation instructions.
2284
+
2285
+ Knowledge-bearing scans save their extracted documents in
2070
2286
  the private `.scan-knowledge.json` continuation file beside the scan artifacts.
2071
2287
  Resume verifies and uses that snapshot even if the original files changed or were
2072
2288
  deleted. Preserve it with the scan directory; canonical reports do not embed its
@@ -2084,7 +2300,10 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
2084
2300
 
2085
2301
  ### Matching saved scans
2086
2302
 
2087
- Matching uses sealed artifacts and cached decisions unless `--force` is supplied.
2303
+ Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
2304
+ and save its matching decisions. Pass `--force` to recompute saved matches.
2305
+ The older `scans match BEFORE AFTER` spelling is also supported.
2306
+ Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
2088
2307
  Comparisons classify findings as new, persisting, reopened, not observed, resolved,
2089
2308
  or unknown. An absent finding in the later scope is not observed; absence alone
2090
2309
  does not verify remediation. A finding is resolved only after it was explicitly
@@ -2095,6 +2314,13 @@ One comparison ID is compared with the latest completed scan.
2095
2314
  codex-security scans match --all --force --model gpt-6.1-sol --effort high
2096
2315
  ```
2097
2316
 
2317
+ When a saved Standard scan and a Deep scan have the same recorded target,
2318
+ revision, and snapshot digest, matching flags findings that have different
2319
+ anchors but share a unique rule, first displayed source range, and optional
2320
+ instance. Matching preserves the case of saved paths. Codex can request the
2321
+ saved evidence to distinguish separate causes at that site. Automatic matching
2322
+ under a cost limit keeps its single comparison call.
2323
+
2098
2324
  Only high-confidence root-cause matches are grouped. Uncertain and related
2099
2325
  findings remain separate. Rebuilding retains stable identities, triage, and
2100
2326
  sealed artifacts; interruption preserves completed comparisons. Model/effort
@@ -2144,6 +2370,10 @@ must already exist.
2144
2370
 
2145
2371
  SARIF is the default format, and `./results.sarif` is the default output path.
2146
2372
  Use `--export-format json` or `--export-format csv` to choose another format.
2373
+ An existing default output file is preserved. Pass `--output FILE` to choose
2374
+ a filename or explicitly replace it. Use `--output -` to pipe the complete
2375
+ artifact. Response filters, token controls, and `--full-output` require a
2376
+ command that returns a formatted response.
2147
2377
  To select a saved scan by its ID and export JSON, run:
2148
2378
 
2149
2379
  ```bash
@@ -2292,9 +2522,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
2292
2522
 
2293
2523
  ### Local pre-commit checks
2294
2524
 
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.
2525
+ The generated hook runs a `--working-tree` scan and blocks the commit on scan
2526
+ failure or findings at or above its threshold (`high` by default). It uses the
2527
+ checkout's normal index for staged and unstaged changes, so it can include changes
2528
+ outside a partial commit and miss content staged only in a separate index.
2529
+ Use required CI for enforcement because local hooks are optional.
2298
2530
 
2299
2531
  Install the CLI outside the target repository and run that copy directly. `npx`
2300
2532
  can select a repository-local package. Before installation, inspect:
@@ -2312,148 +2544,14 @@ codex-security install-hook /path/to/repository
2312
2544
  ```
2313
2545
 
2314
2546
  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.
2547
+ this repository and contains only the generated commands. Rerun `install-hook`
2548
+ with the desired `--fail-on-severity` level to change the threshold. The installer
2549
+ recognizes the legacy `npx` hook and earlier generated templates with matching
2550
+ absolute Node and CLI paths. It refuses to replace a hand-edited hook.
2551
+ On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
2552
+ could not execute it. The installer checks that the resulting hook is executable.
2553
+ The installer uses host Git for the selected repository and respects
2554
+ `core.hooksPath`.
2457
2555
 
2458
2556
  ## Validate and patch findings
2459
2557
 
@@ -2461,12 +2559,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
2461
2559
  This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
2462
2560
  See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
2463
2561
 
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.
2562
+ `validate` sends the finding to your configured model provider. Its review
2563
+ tools can read the checkout, with network access and web search disabled.
2564
+ The assessment uses source evidence and skips builds, tests, PoCs and application
2565
+ execution. Both `validate` and `patch` accept files or literal text in the
2566
+ current directory. Patching by saved finding or occurrence ID selects the
2567
+ original repository.
2470
2568
 
2471
2569
  Basic patching also works in ordinary directories and Git worktrees before their
2472
2570
  first commit. Directory change tracking excludes `.git` and `.svn` metadata.
@@ -2480,6 +2578,14 @@ codex-security patch --scan SCAN_ID --severity high --json
2480
2578
  codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
2481
2579
  ```
2482
2580
 
2581
+ For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
2582
+ `file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
2583
+ requires the file to exist. A missing file stops the command before the model
2584
+ runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
2585
+ special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
2586
+ also require an existing file. Use `text:/path is exposed` to pass path-shaped
2587
+ prose verbatim, or `text:text:example` for a finding that starts with `text:`.
2588
+
2483
2589
  Context inputs are optional and can be combined:
2484
2590
 
2485
2591
  - `--context TEXT` adds inline security context or reviewer feedback.
@@ -2487,6 +2593,7 @@ Context inputs are optional and can be combined:
2487
2593
  - Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
2488
2594
  document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
2489
2595
  are searched recursively; binary files, symlinks, and Git metadata are skipped.
2596
+ When validating from a Git checkout, select external documents directly.
2490
2597
 
2491
2598
  Inline and file context are included in the prompt. Knowledge-base documents are
2492
2599
  prepared in a temporary directory for Codex to read during the assessment, then
@@ -2508,7 +2615,7 @@ locally does not guarantee provider support. Keep the schema small and use it on
2508
2615
  when the caller needs structured results. It checks the result's shape, not whether
2509
2616
  the security conclusion is correct. Relative paths resolve from the current directory.
2510
2617
 
2511
- The validator no longer writes reports. Save the assessment by redirecting stdout:
2618
+ Save the assessment by redirecting stdout:
2512
2619
  `codex-security validate findings.json > assessment.md`. For runtime proof, run a
2513
2620
  separate reproduction step. Missing facts are reported as proof gaps; a finding
2514
2621
  supported by source evidence does not require runtime reproduction.
@@ -2570,7 +2677,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
2570
2677
 
2571
2678
  An illustrative result is below. Actual decisions depend on the repository;
2572
2679
  this example assumes a tenant filter exists but deployment routing is unavailable.
2573
- Both candidate IDs remain in the output, including the unresolved claim.
2680
+ Before updating finding records, [check that each input ID appears exactly
2681
+ once](validate-records.md#check-the-returned-ids), including unresolved
2682
+ candidates.
2574
2683
 
2575
2684
  ```json
2576
2685
  {
@@ -2635,7 +2744,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
2635
2744
  task. The container must provide it. There is no automatic fallback; optional
2636
2745
  patch-risk assessment still uses its read-only sandbox.
2637
2746
 
2638
- `scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
2747
+ `scan --patch` runs after a complete scan without a cost limit. A cost-limited
2748
+ scan saves the findings and skips the interactive patch offer. Use
2749
+ `codex-security patch --scan SCAN_ID` to patch separately.
2750
+ `--patch-severity` defaults to `low`;
2639
2751
  `high` selects high and critical findings. Interactive users can select findings
2640
2752
  and add instructions. The interactive finding browser lists critical, high,
2641
2753
  medium, then low findings, preserving scan order within each severity.
@@ -2658,8 +2770,13 @@ including code, HTML, and math, retain their original text.
2658
2770
  GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
2659
2771
  ```
2660
2772
 
2661
- Both providers return `pullRequest: { branch, url }`. Supplied-issue patching
2662
- requires a clean tree. If publication fails, run the printed
2773
+ Both providers return `pullRequest: { branch, url }`. Saved-finding publication
2774
+ includes files changed and verified in the same patch turn. If a selected file
2775
+ already had local edits, the CLI keeps the patch in the working tree for review.
2776
+ The risk assessment and commit use the same verified tree. If staging changed
2777
+ during the run and Git cannot update the index, the CLI reports it and keeps
2778
+ the existing staging.
2779
+ Supplied-issue patching requires a clean tree. If publication fails, run the printed
2663
2780
  `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
2664
2781
  commit and refuses changed branches. Retain the GitLab host setting on resume.
2665
2782
 
@@ -2687,16 +2804,20 @@ truncating any selected finding. The CLI prints verdicts in selection order
2687
2804
  after every request returns valid results. For these selections the CLI omits
2688
2805
  per-event progress and update notices so stderr cannot delay the verdicts.
2689
2806
 
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`.
2807
+ If a finding would exceed the input limit, `validate`, `patch`, and `verify-fix`
2808
+ put the complete finding data in a temporary file for Codex to search alongside
2809
+ the checkout. A single input file keeps its original text and line breaks.
2810
+ The file remains available until the task finishes and is then removed. The
2811
+ SDK's local `validate()` and `patch()` methods use the same fallback.
2694
2812
 
2695
2813
  `--verification-mode static` selects source-only assessment, as described above
2696
2814
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2697
2815
 
2698
2816
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2699
- `--json` returns structured output. Exit codes are `0` when all findings are
2817
+ Without output options, each finding prints a verdict and its evidence.
2818
+ Explicit output formats, field selection and token controls operate on the
2819
+ structured result containing `repository`, optional `scanId`, and `results`.
2820
+ Exit codes are `0` when all findings are
2700
2821
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2701
2822
  With `--json` or `--format jsonl`, authentication and execution failures return
2702
2823
  `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
@@ -2709,9 +2830,21 @@ retain exit codes `130` and `143` without a result.
2709
2830
 
2710
2831
  ## Command discovery and integrations
2711
2832
 
2712
- Use `--llms` for the command manifest, `scan --schema --format json` for its
2713
- schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
2714
- `--format toon|json|yaml|jsonl` and `--full-output`.
2833
+ Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
2834
+
2835
+ Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
2836
+ `--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
2837
+ `--filter-output`, `--token-limit`, and `--token-offset` options accept either
2838
+ `--option value` or `--option=value`.
2839
+
2840
+ `--token-limit` and `--token-offset` take nonnegative integers and select a
2841
+ text view of the formatted result. Truncated JSON and JSONL views are returned
2842
+ as a JSON string containing the excerpt and its token range. With
2843
+ `--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
2844
+ the next page when more tokens are available. `--token-count` returns the
2845
+ estimated size instead. A failed full-output JSON or JSONL response always
2846
+ retains its error code and message. If the failure carries result data,
2847
+ `--token-count` reports its size in `meta.tokenCount`.
2715
2848
 
2716
2849
  `skills add` syncs generated CLI command guidance; it does not install the full
2717
2850
  Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
@@ -2719,9 +2852,90 @@ only read-only `info` because the transport cannot cancel scans. For the plugin'
2719
2852
  scan, triage, patch, and verification workflows, see the
2720
2853
  [agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
2721
2854
 
2855
+ Both installers default to `--scope user`. Use `--scope project` for the current
2856
+ directory. Existing scripts can continue using `--no-global` for project scope.
2857
+ Inspect either command with `--help`, `--schema`, or `--version` before installing.
2858
+
2859
+ `skills add --depth 0` creates a single skill. The default depth of 1 groups
2860
+ guidance by top-level command. To check the installed files, use the same
2861
+ depth with `skills list`, for example `skills list --depth 0 --json`. Each
2862
+ entry includes its canonical `SKILL.md` locations in the current project and
2863
+ user profile.
2864
+
2865
+ `mcp add` registers detected compatible clients. If it finds none in the
2866
+ selected scope, choose a client with `--agent NAME` (repeatable), or register
2867
+ every compatible client with `--all`. For example, `mcp add --scope project
2868
+ --agent cursor` writes Cursor's project configuration. In user scope, Codex
2869
+ detection and registration use `CODEX_HOME` when set. Amp supports user
2870
+ registration only.
2871
+
2872
+ The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
2873
+ an installed executable, use its name or path with `--exec` and repeat
2874
+ `--arg=VALUE` for each argument. Each value is stored literally, including
2875
+ spaces, empty arguments, and leading dashes. To run an npm package, select
2876
+ `--package NAME`. The existing `--command` accepts a command line or HTTP(S)
2877
+ URL. Quotes group command-line words, and backslashes are literal. A bare
2878
+ executable name is stored directly. Use `--exec` for a path with
2879
+ spaces, including when the executable will be installed on another machine.
2880
+
2881
+ ```bash
2882
+ codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
2883
+ codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
2884
+ ```
2885
+
2886
+ `mcp doctor` checks the current CLI's server startup and tool catalog. To
2887
+ verify a registered launcher, connect from the client where it was registered.
2888
+
2722
2889
  For local findings storage, deduplication, and custom endpoints, see the
2723
2890
  [findings guide](findings-service.md).
2724
2891
 
2892
+ ### Shell completions
2893
+
2894
+ The generated scripts register both `codex-security` and `cs`. Choose your shell
2895
+ and open a new session after saving the setup.
2896
+
2897
+ **Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
2898
+
2899
+ ```bash
2900
+ source <(codex-security completions bash)
2901
+ ```
2902
+
2903
+ **Zsh.** In `~/.zshrc`, load the generated script after your completion system
2904
+ calls `compinit`. If you initialize completions yourself, use:
2905
+
2906
+ ```zsh
2907
+ autoload -Uz compinit
2908
+ compinit
2909
+ source <(codex-security completions zsh)
2910
+ ```
2911
+
2912
+ **Fish.** Add this line to `~/.config/fish/config.fish`:
2913
+
2914
+ ```fish
2915
+ codex-security completions fish | source
2916
+ ```
2917
+
2918
+ **Nushell.** Save the generated closures alongside `config.nu`:
2919
+
2920
+ ```nu
2921
+ codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
2922
+ ```
2923
+
2924
+ In `config.nu`, source the file and dispatch the two names to their completers:
2925
+
2926
+ ```nu
2927
+ source codex-security-completions.nu
2928
+ let previous_completer = $env.config.completions.external.completer?
2929
+ $env.config.completions.external.enable = true
2930
+ $env.config.completions.external.completer = {|spans|
2931
+ match $spans.0 {
2932
+ "codex-security" => { do $_incur_complete_codex_security $spans }
2933
+ "cs" => { do $_incur_complete_cs $spans }
2934
+ _ => { if $previous_completer != null { do $previous_completer $spans } }
2935
+ }
2936
+ }
2937
+ ```
2938
+
2725
2939
  ### Hosted Standard scan
2726
2940
 
2727
2941
  `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.