@openai/codex-security 0.8.2 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (649) hide show
  1. package/README.md +201 -178
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +6 -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 +51 -14
  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/core-scan.md +14 -5
  26. package/_bundled_plugin/references/default-severity-rubric.md +33 -0
  27. package/_bundled_plugin/references/final-report.md +5 -3
  28. package/_bundled_plugin/references/finding-detail-fields.md +19 -18
  29. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  30. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  31. package/_bundled_plugin/references/scan-contract.md +27 -33
  32. package/_bundled_plugin/references/threat-model.md +1 -0
  33. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  34. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  35. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  36. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  37. package/_bundled_plugin/scripts/deep_scan_workbench.py +188 -454
  38. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  39. package/_bundled_plugin/scripts/finalize_scan_contract.py +317 -377
  40. package/_bundled_plugin/scripts/finding_preview.py +25 -29
  41. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  42. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  43. package/_bundled_plugin/scripts/posix_scan_local_files.py +198 -0
  44. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  45. package/_bundled_plugin/scripts/report_projection.py +167 -178
  46. package/_bundled_plugin/scripts/review_state.py +8 -2
  47. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  48. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  49. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  50. package/_bundled_plugin/scripts/validate_scan_contract.py +9 -7
  51. package/_bundled_plugin/scripts/windows_scan_local_files.py +600 -72
  52. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  53. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  54. package/_bundled_plugin/scripts/workbench/retained_coverage.py +38 -75
  55. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  56. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  57. package/_bundled_plugin/scripts/workbench/saved_coverage.py +152 -248
  58. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  59. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  60. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  61. package/_bundled_plugin/scripts/workbench_cli.py +121 -14
  62. package/_bundled_plugin/scripts/workbench_constants.py +19 -0
  63. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  64. package/_bundled_plugin/scripts/workbench_db.py +550 -492
  65. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  66. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  67. package/_bundled_plugin/scripts/workbench_finding_workflows.py +90 -4
  68. package/_bundled_plugin/scripts/workbench_native_indexes.py +29 -33
  69. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  70. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  71. package/_bundled_plugin/scripts/workbench_remediation.py +508 -11
  72. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  73. package/_bundled_plugin/scripts/workbench_scan_history.py +139 -80
  74. package/_bundled_plugin/scripts/workbench_scan_start.py +84 -25
  75. package/_bundled_plugin/scripts/workbench_scan_usage.py +666 -117
  76. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  77. package/_bundled_plugin/scripts/workbench_setup.py +251 -0
  78. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  79. package/_bundled_plugin/scripts/workbench_source_scopes.py +33 -23
  80. package/_bundled_plugin/scripts/workbench_target.py +330 -66
  81. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  82. package/_bundled_plugin/scripts/workbench_validation.py +44 -12
  83. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -16
  84. package/_bundled_plugin/shared/workbench-migrations.json +53 -0
  85. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  86. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  87. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  88. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  89. package/_bundled_plugin/skills/cloud-findings/SKILL.md +6 -4
  90. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  91. package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -2
  92. package/_bundled_plugin/skills/publish-findings/SKILL.md +81 -45
  93. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  94. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +5 -24
  95. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  96. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +36 -9
  97. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  98. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  99. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +12 -6
  100. package/dist/api.d.ts +45 -5
  101. package/dist/api.d.ts.map +1 -1
  102. package/dist/api.js +1144 -411
  103. package/dist/api.js.map +1 -1
  104. package/dist/auth.d.ts.map +1 -1
  105. package/dist/auth.js +10 -7
  106. package/dist/auth.js.map +1 -1
  107. package/dist/bedrock-oss-pricing.d.ts +6 -0
  108. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  109. package/dist/bedrock-oss-pricing.js +58 -0
  110. package/dist/bedrock-oss-pricing.js.map +1 -0
  111. package/dist/bedrock-pricing.d.ts +15 -0
  112. package/dist/bedrock-pricing.d.ts.map +1 -0
  113. package/dist/bedrock-pricing.js +117 -0
  114. package/dist/bedrock-pricing.js.map +1 -0
  115. package/dist/blackduck-findings.d.ts +8 -0
  116. package/dist/blackduck-findings.d.ts.map +1 -0
  117. package/dist/blackduck-findings.js +320 -0
  118. package/dist/blackduck-findings.js.map +1 -0
  119. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  120. package/dist/bulk-scan-discovery.js +51 -36
  121. package/dist/bulk-scan-discovery.js.map +1 -1
  122. package/dist/checkmarx-evidence.d.ts +19 -0
  123. package/dist/checkmarx-evidence.d.ts.map +1 -0
  124. package/dist/checkmarx-evidence.js +36 -0
  125. package/dist/checkmarx-evidence.js.map +1 -0
  126. package/dist/checkmarx-findings.d.ts +4 -0
  127. package/dist/checkmarx-findings.d.ts.map +1 -0
  128. package/dist/checkmarx-findings.js +27 -0
  129. package/dist/checkmarx-findings.js.map +1 -0
  130. package/dist/checkmarx-one.d.ts +4 -0
  131. package/dist/checkmarx-one.d.ts.map +1 -0
  132. package/dist/checkmarx-one.js +53 -0
  133. package/dist/checkmarx-one.js.map +1 -0
  134. package/dist/checkmarx-repository.d.ts +12 -0
  135. package/dist/checkmarx-repository.d.ts.map +1 -0
  136. package/dist/checkmarx-repository.js +181 -0
  137. package/dist/checkmarx-repository.js.map +1 -0
  138. package/dist/checkmarx-xml.d.ts +12 -0
  139. package/dist/checkmarx-xml.d.ts.map +1 -0
  140. package/dist/checkmarx-xml.js +196 -0
  141. package/dist/checkmarx-xml.js.map +1 -0
  142. package/dist/classify-severity-records.d.ts +6 -9
  143. package/dist/classify-severity-records.d.ts.map +1 -1
  144. package/dist/classify-severity-records.js +9 -21
  145. package/dist/classify-severity-records.js.map +1 -1
  146. package/dist/classify-severity.d.ts +4 -1
  147. package/dist/classify-severity.d.ts.map +1 -1
  148. package/dist/classify-severity.js +30 -13
  149. package/dist/classify-severity.js.map +1 -1
  150. package/dist/cli.d.ts +14 -5
  151. package/dist/cli.d.ts.map +1 -1
  152. package/dist/cli.js +2112 -1266
  153. package/dist/cli.js.map +1 -1
  154. package/dist/cloud-publish.js +2 -2
  155. package/dist/cloud-publish.js.map +1 -1
  156. package/dist/codex-prompt.d.ts +2 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +6 -0
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/component-scan.d.ts +16 -3
  161. package/dist/component-scan.d.ts.map +1 -1
  162. package/dist/component-scan.js +32 -6
  163. package/dist/component-scan.js.map +1 -1
  164. package/dist/config.d.ts +2 -1
  165. package/dist/config.d.ts.map +1 -1
  166. package/dist/config.js +221 -65
  167. package/dist/config.js.map +1 -1
  168. package/dist/continuum-findings.d.ts +7 -0
  169. package/dist/continuum-findings.d.ts.map +1 -0
  170. package/dist/continuum-findings.js +225 -0
  171. package/dist/continuum-findings.js.map +1 -0
  172. package/dist/contract-values.d.ts +30 -0
  173. package/dist/contract-values.d.ts.map +1 -0
  174. package/dist/contract-values.js +78 -0
  175. package/dist/contract-values.js.map +1 -0
  176. package/dist/contract.d.ts +2 -20
  177. package/dist/contract.d.ts.map +1 -1
  178. package/dist/contract.js +58 -669
  179. package/dist/contract.js.map +1 -1
  180. package/dist/cost-model.d.ts +13 -1
  181. package/dist/cost-model.d.ts.map +1 -1
  182. package/dist/cost-model.js +66 -115
  183. package/dist/cost-model.js.map +1 -1
  184. package/dist/cost.d.ts +61 -4
  185. package/dist/cost.d.ts.map +1 -1
  186. package/dist/cost.js +2560 -100
  187. package/dist/cost.js.map +1 -1
  188. package/dist/custom-publish.d.ts +4 -0
  189. package/dist/custom-publish.d.ts.map +1 -1
  190. package/dist/custom-publish.js +40 -3
  191. package/dist/custom-publish.js.map +1 -1
  192. package/dist/custom-validation-prompt.d.ts +1 -1
  193. package/dist/custom-validation-prompt.d.ts.map +1 -1
  194. package/dist/custom-validation-prompt.js +5 -0
  195. package/dist/custom-validation-prompt.js.map +1 -1
  196. package/dist/custom-validation.d.ts +2 -0
  197. package/dist/custom-validation.d.ts.map +1 -1
  198. package/dist/custom-validation.js +4 -0
  199. package/dist/custom-validation.js.map +1 -1
  200. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  201. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.js +2 -2
  203. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  204. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  205. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.js +11 -4
  207. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  208. package/dist/deduplication/deduplication.js.map +1 -1
  209. package/dist/deduplication/finding-schema.d.ts +19 -1
  210. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  211. package/dist/deduplication/finding-schema.js +25 -0
  212. package/dist/deduplication/finding-schema.js.map +1 -1
  213. package/dist/deduplication/local.d.ts +2 -2
  214. package/dist/deduplication/local.d.ts.map +1 -1
  215. package/dist/deduplication/local.js +5 -10
  216. package/dist/deduplication/local.js.map +1 -1
  217. package/dist/deduplication/records.d.ts +8 -2
  218. package/dist/deduplication/records.d.ts.map +1 -1
  219. package/dist/deduplication/records.js +36 -8
  220. package/dist/deduplication/records.js.map +1 -1
  221. package/dist/deduplication/refusal.d.ts.map +1 -1
  222. package/dist/deduplication/refusal.js +25 -5
  223. package/dist/deduplication/refusal.js.map +1 -1
  224. package/dist/deduplication/scan.d.ts +3 -0
  225. package/dist/deduplication/scan.d.ts.map +1 -1
  226. package/dist/deduplication/scan.js +1 -1
  227. package/dist/deduplication/scan.js.map +1 -1
  228. package/dist/deep-config.d.ts +0 -1
  229. package/dist/deep-config.d.ts.map +1 -1
  230. package/dist/deep-config.js +22 -33
  231. package/dist/deep-config.js.map +1 -1
  232. package/dist/deep-scan-defaults.d.ts +2 -0
  233. package/dist/deep-scan-defaults.d.ts.map +1 -1
  234. package/dist/deep-scan-defaults.js +28 -1
  235. package/dist/deep-scan-defaults.js.map +1 -1
  236. package/dist/deep-scan.d.ts +13 -0
  237. package/dist/deep-scan.d.ts.map +1 -1
  238. package/dist/deep-scan.js +262 -7
  239. package/dist/deep-scan.js.map +1 -1
  240. package/dist/default-severity-rubric.d.ts +1 -2
  241. package/dist/default-severity-rubric.d.ts.map +1 -1
  242. package/dist/default-severity-rubric.js +2 -66
  243. package/dist/default-severity-rubric.js.map +1 -1
  244. package/dist/endor-findings.d.ts +3 -1
  245. package/dist/endor-findings.d.ts.map +1 -1
  246. package/dist/endor-findings.js +108 -80
  247. package/dist/endor-findings.js.map +1 -1
  248. package/dist/errors.d.ts +1 -1
  249. package/dist/errors.d.ts.map +1 -1
  250. package/dist/errors.js +9 -2
  251. package/dist/errors.js.map +1 -1
  252. package/dist/external-findings-import.d.ts +5 -3
  253. package/dist/external-findings-import.d.ts.map +1 -1
  254. package/dist/external-findings-import.js +11 -16
  255. package/dist/external-findings-import.js.map +1 -1
  256. package/dist/external-findings-local.d.ts +15 -4
  257. package/dist/external-findings-local.d.ts.map +1 -1
  258. package/dist/external-findings-local.js +619 -225
  259. package/dist/external-findings-local.js.map +1 -1
  260. package/dist/external-findings-publish.d.ts +20 -6
  261. package/dist/external-findings-publish.d.ts.map +1 -1
  262. package/dist/external-findings-publish.js +2356 -308
  263. package/dist/external-findings-publish.js.map +1 -1
  264. package/dist/external-findings-read.d.ts +28 -2
  265. package/dist/external-findings-read.d.ts.map +1 -1
  266. package/dist/external-findings-read.js +174 -81
  267. package/dist/external-findings-read.js.map +1 -1
  268. package/dist/external-findings.d.ts +17 -3
  269. package/dist/external-findings.d.ts.map +1 -1
  270. package/dist/external-findings.js +153 -1
  271. package/dist/external-findings.js.map +1 -1
  272. package/dist/external-import-contract.d.ts +33 -1
  273. package/dist/external-import-contract.d.ts.map +1 -1
  274. package/dist/external-import-contract.js +335 -51
  275. package/dist/external-import-contract.js.map +1 -1
  276. package/dist/external-import-models.d.ts +1 -1
  277. package/dist/external-import-models.d.ts.map +1 -1
  278. package/dist/external-import-models.js.map +1 -1
  279. package/dist/feedback.d.ts.map +1 -1
  280. package/dist/feedback.js +5 -4
  281. package/dist/feedback.js.map +1 -1
  282. package/dist/finding-prompt.d.ts +5 -0
  283. package/dist/finding-prompt.d.ts.map +1 -0
  284. package/dist/finding-prompt.js +32 -0
  285. package/dist/finding-prompt.js.map +1 -0
  286. package/dist/finding-retrieval.d.ts +3 -3
  287. package/dist/finding-retrieval.d.ts.map +1 -1
  288. package/dist/finding-retrieval.js.map +1 -1
  289. package/dist/finding-workflow.d.ts +6 -1
  290. package/dist/finding-workflow.d.ts.map +1 -1
  291. package/dist/finding-workflow.js +2 -2
  292. package/dist/finding-workflow.js.map +1 -1
  293. package/dist/findings-client.d.ts +1 -0
  294. package/dist/findings-client.d.ts.map +1 -1
  295. package/dist/findings-client.js +27 -3
  296. package/dist/findings-client.js.map +1 -1
  297. package/dist/git-remote.d.ts +4 -0
  298. package/dist/git-remote.d.ts.map +1 -1
  299. package/dist/git-remote.js +20 -0
  300. package/dist/git-remote.js.map +1 -1
  301. package/dist/github-advisories.d.ts +3 -12
  302. package/dist/github-advisories.d.ts.map +1 -1
  303. package/dist/github-advisories.js +9 -31
  304. package/dist/github-advisories.js.map +1 -1
  305. package/dist/github-dependabot-findings.d.ts.map +1 -1
  306. package/dist/github-dependabot-findings.js +22 -20
  307. package/dist/github-dependabot-findings.js.map +1 -1
  308. package/dist/github-findings.d.ts +4 -1
  309. package/dist/github-findings.d.ts.map +1 -1
  310. package/dist/github-findings.js +392 -79
  311. package/dist/github-findings.js.map +1 -1
  312. package/dist/github.d.ts +17 -7
  313. package/dist/github.d.ts.map +1 -1
  314. package/dist/github.js +43 -30
  315. package/dist/github.js.map +1 -1
  316. package/dist/host-protocol.d.ts +2 -2
  317. package/dist/host-protocol.d.ts.map +1 -1
  318. package/dist/host-protocol.js.map +1 -1
  319. package/dist/host-records-protocol.d.ts +10 -11
  320. package/dist/host-records-protocol.d.ts.map +1 -1
  321. package/dist/host-records-protocol.js +69 -9
  322. package/dist/host-records-protocol.js.map +1 -1
  323. package/dist/hosted-git-remotes.d.ts +5 -0
  324. package/dist/hosted-git-remotes.d.ts.map +1 -0
  325. package/dist/hosted-git-remotes.js +285 -0
  326. package/dist/hosted-git-remotes.js.map +1 -0
  327. package/dist/hosted-git-repository.d.ts +28 -0
  328. package/dist/hosted-git-repository.d.ts.map +1 -0
  329. package/dist/hosted-git-repository.js +222 -0
  330. package/dist/hosted-git-repository.js.map +1 -0
  331. package/dist/hosted-scan-protocol.js +2 -2
  332. package/dist/hosted-scan-protocol.js.map +1 -1
  333. package/dist/hosted-scan.d.ts +15 -0
  334. package/dist/hosted-scan.d.ts.map +1 -1
  335. package/dist/hosted-scan.js +71 -44
  336. package/dist/hosted-scan.js.map +1 -1
  337. package/dist/hosted-scanner-http.d.ts +21 -0
  338. package/dist/hosted-scanner-http.d.ts.map +1 -0
  339. package/dist/hosted-scanner-http.js +204 -0
  340. package/dist/hosted-scanner-http.js.map +1 -0
  341. package/dist/hosted-scanner-v1.d.ts +6 -0
  342. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  343. package/dist/hosted-scanner-v1.js +60 -0
  344. package/dist/hosted-scanner-v1.js.map +1 -0
  345. package/dist/import-scan.d.ts.map +1 -1
  346. package/dist/import-scan.js +3 -0
  347. package/dist/import-scan.js.map +1 -1
  348. package/dist/index.d.ts +24 -6
  349. package/dist/index.d.ts.map +1 -1
  350. package/dist/index.js +15 -1
  351. package/dist/index.js.map +1 -1
  352. package/dist/inspector-findings.d.ts.map +1 -1
  353. package/dist/inspector-findings.js +58 -81
  354. package/dist/inspector-findings.js.map +1 -1
  355. package/dist/knowledge-base.d.ts.map +1 -1
  356. package/dist/knowledge-base.js +86 -10
  357. package/dist/knowledge-base.js.map +1 -1
  358. package/dist/local-git-metadata.d.ts +5 -0
  359. package/dist/local-git-metadata.d.ts.map +1 -0
  360. package/dist/local-git-metadata.js +130 -0
  361. package/dist/local-git-metadata.js.map +1 -0
  362. package/dist/multiscan.d.ts +6 -4
  363. package/dist/multiscan.d.ts.map +1 -1
  364. package/dist/multiscan.js +160 -77
  365. package/dist/multiscan.js.map +1 -1
  366. package/dist/native-json-findings.d.ts +2 -1
  367. package/dist/native-json-findings.d.ts.map +1 -1
  368. package/dist/native-json-findings.js +12 -2
  369. package/dist/native-json-findings.js.map +1 -1
  370. package/dist/opengrep-findings.d.ts +1 -0
  371. package/dist/opengrep-findings.d.ts.map +1 -1
  372. package/dist/opengrep-findings.js +49 -31
  373. package/dist/opengrep-findings.js.map +1 -1
  374. package/dist/operation-telemetry.d.ts +104 -0
  375. package/dist/operation-telemetry.d.ts.map +1 -0
  376. package/dist/operation-telemetry.js +293 -0
  377. package/dist/operation-telemetry.js.map +1 -0
  378. package/dist/patch-tui.d.ts.map +1 -1
  379. package/dist/patch-tui.js +90 -35
  380. package/dist/patch-tui.js.map +1 -1
  381. package/dist/plugin-python-probe.d.ts +4 -0
  382. package/dist/plugin-python-probe.d.ts.map +1 -0
  383. package/dist/plugin-python-probe.js +10 -0
  384. package/dist/plugin-python-probe.js.map +1 -0
  385. package/dist/private-finding-import.d.ts +341 -0
  386. package/dist/private-finding-import.d.ts.map +1 -0
  387. package/dist/private-finding-import.js +411 -0
  388. package/dist/private-finding-import.js.map +1 -0
  389. package/dist/project-config.d.ts.map +1 -1
  390. package/dist/project-config.js +2 -2
  391. package/dist/project-config.js.map +1 -1
  392. package/dist/provider-profile.d.ts +11 -3
  393. package/dist/provider-profile.d.ts.map +1 -1
  394. package/dist/provider-profile.js +80 -11
  395. package/dist/provider-profile.js.map +1 -1
  396. package/dist/publication-telemetry.d.ts +45 -0
  397. package/dist/publication-telemetry.d.ts.map +1 -0
  398. package/dist/publication-telemetry.js +50 -0
  399. package/dist/publication-telemetry.js.map +1 -0
  400. package/dist/publication.js +7 -1
  401. package/dist/publication.js.map +1 -1
  402. package/dist/publish.d.ts +4 -0
  403. package/dist/publish.d.ts.map +1 -1
  404. package/dist/publish.js +42 -2
  405. package/dist/publish.js.map +1 -1
  406. package/dist/reader-selection.d.ts +15 -0
  407. package/dist/reader-selection.d.ts.map +1 -0
  408. package/dist/reader-selection.js +89 -0
  409. package/dist/reader-selection.js.map +1 -0
  410. package/dist/record.d.ts +6 -1
  411. package/dist/record.d.ts.map +1 -1
  412. package/dist/record.js +53 -2
  413. package/dist/record.js.map +1 -1
  414. package/dist/remediation.d.ts +3 -1
  415. package/dist/remediation.d.ts.map +1 -1
  416. package/dist/remediation.js +28 -2
  417. package/dist/remediation.js.map +1 -1
  418. package/dist/request-metadata.d.ts +3 -0
  419. package/dist/request-metadata.d.ts.map +1 -1
  420. package/dist/request-metadata.js +9 -0
  421. package/dist/request-metadata.js.map +1 -1
  422. package/dist/result.d.ts +6 -0
  423. package/dist/result.d.ts.map +1 -1
  424. package/dist/result.js +3 -1
  425. package/dist/result.js.map +1 -1
  426. package/dist/retry-windows-rename.d.ts +8 -0
  427. package/dist/retry-windows-rename.d.ts.map +1 -0
  428. package/dist/retry-windows-rename.js +24 -0
  429. package/dist/retry-windows-rename.js.map +1 -0
  430. package/dist/runtime.d.ts +22 -1
  431. package/dist/runtime.d.ts.map +1 -1
  432. package/dist/runtime.js +408 -162
  433. package/dist/runtime.js.map +1 -1
  434. package/dist/saved-scan-bootstrap.d.ts +1 -0
  435. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  436. package/dist/saved-scan-bootstrap.js +18 -15
  437. package/dist/saved-scan-bootstrap.js.map +1 -1
  438. package/dist/scan-activity.d.ts.map +1 -1
  439. package/dist/scan-activity.js +172 -64
  440. package/dist/scan-activity.js.map +1 -1
  441. package/dist/scan-comparison.d.ts +10 -5
  442. package/dist/scan-comparison.d.ts.map +1 -1
  443. package/dist/scan-comparison.js +68 -25
  444. package/dist/scan-comparison.js.map +1 -1
  445. package/dist/scan-dashboard.d.ts +7 -6
  446. package/dist/scan-dashboard.d.ts.map +1 -1
  447. package/dist/scan-dashboard.js +91 -79
  448. package/dist/scan-dashboard.js.map +1 -1
  449. package/dist/scan-executor.d.ts +12 -1
  450. package/dist/scan-executor.d.ts.map +1 -1
  451. package/dist/scan-executor.js +22 -2
  452. package/dist/scan-executor.js.map +1 -1
  453. package/dist/scan-history-renderer.d.ts.map +1 -1
  454. package/dist/scan-history-renderer.js +31 -28
  455. package/dist/scan-history-renderer.js.map +1 -1
  456. package/dist/scan-logs.d.ts +12 -0
  457. package/dist/scan-logs.d.ts.map +1 -1
  458. package/dist/scan-logs.js +106 -77
  459. package/dist/scan-logs.js.map +1 -1
  460. package/dist/scan-measurement.d.ts +26 -0
  461. package/dist/scan-measurement.d.ts.map +1 -0
  462. package/dist/scan-measurement.js +77 -0
  463. package/dist/scan-measurement.js.map +1 -0
  464. package/dist/scan-progress.d.ts +1 -0
  465. package/dist/scan-progress.d.ts.map +1 -1
  466. package/dist/scan-progress.js +3 -0
  467. package/dist/scan-progress.js.map +1 -1
  468. package/dist/scan-sessions.d.ts.map +1 -1
  469. package/dist/scan-sessions.js +4 -1
  470. package/dist/scan-sessions.js.map +1 -1
  471. package/dist/scan-settings.d.ts +1 -1
  472. package/dist/scan-settings.d.ts.map +1 -1
  473. package/dist/scan-settings.js +1 -24
  474. package/dist/scan-settings.js.map +1 -1
  475. package/dist/scanner-import.d.ts +64 -6
  476. package/dist/scanner-import.d.ts.map +1 -1
  477. package/dist/scanner-import.js +406 -48
  478. package/dist/scanner-import.js.map +1 -1
  479. package/dist/scanner-repository-url.d.ts +17 -0
  480. package/dist/scanner-repository-url.d.ts.map +1 -0
  481. package/dist/scanner-repository-url.js +71 -0
  482. package/dist/scanner-repository-url.js.map +1 -0
  483. package/dist/security-policy.d.ts +1 -1
  484. package/dist/security-policy.d.ts.map +1 -1
  485. package/dist/security-policy.js.map +1 -1
  486. package/dist/semgrep-findings.d.ts +6 -3
  487. package/dist/semgrep-findings.d.ts.map +1 -1
  488. package/dist/semgrep-findings.js +124 -88
  489. package/dist/semgrep-findings.js.map +1 -1
  490. package/dist/semgrep-guardian-findings.d.ts +38 -0
  491. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  492. package/dist/semgrep-guardian-findings.js +165 -0
  493. package/dist/semgrep-guardian-findings.js.map +1 -0
  494. package/dist/semgrep-platform-collector.d.ts +26 -0
  495. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  496. package/dist/semgrep-platform-collector.js +108 -0
  497. package/dist/semgrep-platform-collector.js.map +1 -0
  498. package/dist/semgrep-platform-findings.d.ts +213 -0
  499. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  500. package/dist/semgrep-platform-findings.js +1078 -0
  501. package/dist/semgrep-platform-findings.js.map +1 -0
  502. package/dist/semgrep-platform-v1.d.ts +6 -0
  503. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  504. package/dist/semgrep-platform-v1.js +83 -0
  505. package/dist/semgrep-platform-v1.js.map +1 -0
  506. package/dist/server/api.d.ts +1 -1
  507. package/dist/server/api.d.ts.map +1 -1
  508. package/dist/server/api.js.map +1 -1
  509. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  510. package/dist/server/embedding-tokenizer.d.ts +2 -0
  511. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  512. package/dist/server/embedding-tokenizer.js +322 -0
  513. package/dist/server/embedding-tokenizer.js.map +6 -0
  514. package/dist/server/embeddings.d.ts +16 -2
  515. package/dist/server/embeddings.d.ts.map +1 -1
  516. package/dist/server/embeddings.js +35 -5
  517. package/dist/server/embeddings.js.map +1 -1
  518. package/dist/session-lines.d.ts +5 -0
  519. package/dist/session-lines.d.ts.map +1 -0
  520. package/dist/session-lines.js +60 -0
  521. package/dist/session-lines.js.map +1 -0
  522. package/dist/severity-review.d.ts +3 -1
  523. package/dist/severity-review.d.ts.map +1 -1
  524. package/dist/severity-review.js +3 -2
  525. package/dist/severity-review.js.map +1 -1
  526. package/dist/severity-rubric.d.ts +20 -0
  527. package/dist/severity-rubric.d.ts.map +1 -0
  528. package/dist/severity-rubric.js +73 -0
  529. package/dist/severity-rubric.js.map +1 -0
  530. package/dist/severity-store.js +15 -5
  531. package/dist/severity-store.js.map +1 -1
  532. package/dist/skill-authentication.d.ts +1 -0
  533. package/dist/skill-authentication.d.ts.map +1 -1
  534. package/dist/skill-authentication.js +1 -0
  535. package/dist/skill-authentication.js.map +1 -1
  536. package/dist/snyk-findings.d.ts +7 -2
  537. package/dist/snyk-findings.d.ts.map +1 -1
  538. package/dist/snyk-findings.js +108 -84
  539. package/dist/snyk-findings.js.map +1 -1
  540. package/dist/snyk-rest-findings.d.ts +76 -0
  541. package/dist/snyk-rest-findings.d.ts.map +1 -0
  542. package/dist/snyk-rest-findings.js +1051 -0
  543. package/dist/snyk-rest-findings.js.map +1 -0
  544. package/dist/snyk-rest-v1.d.ts +28 -0
  545. package/dist/snyk-rest-v1.d.ts.map +1 -0
  546. package/dist/snyk-rest-v1.js +132 -0
  547. package/dist/snyk-rest-v1.js.map +1 -0
  548. package/dist/snyk-token-origin.d.ts +4 -0
  549. package/dist/snyk-token-origin.d.ts.map +1 -0
  550. package/dist/snyk-token-origin.js +82 -0
  551. package/dist/snyk-token-origin.js.map +1 -0
  552. package/dist/sonar-collector.d.ts +16 -0
  553. package/dist/sonar-collector.d.ts.map +1 -0
  554. package/dist/sonar-collector.js +380 -0
  555. package/dist/sonar-collector.js.map +1 -0
  556. package/dist/sonar-findings.d.ts +49 -0
  557. package/dist/sonar-findings.d.ts.map +1 -0
  558. package/dist/sonar-findings.js +288 -0
  559. package/dist/sonar-findings.js.map +1 -0
  560. package/dist/sonar-import.d.ts +111 -0
  561. package/dist/sonar-import.d.ts.map +1 -0
  562. package/dist/sonar-import.js +277 -0
  563. package/dist/sonar-import.js.map +1 -0
  564. package/dist/suggest-owners.d.ts.map +1 -1
  565. package/dist/suggest-owners.js +2 -1
  566. package/dist/suggest-owners.js.map +1 -1
  567. package/dist/target-drift.d.ts +9 -0
  568. package/dist/target-drift.d.ts.map +1 -0
  569. package/dist/target-drift.js +27 -0
  570. package/dist/target-drift.js.map +1 -0
  571. package/dist/targets.d.ts +5 -0
  572. package/dist/targets.d.ts.map +1 -1
  573. package/dist/targets.js +73 -31
  574. package/dist/targets.js.map +1 -1
  575. package/dist/tenable-findings.d.ts +9 -0
  576. package/dist/tenable-findings.d.ts.map +1 -0
  577. package/dist/tenable-findings.js +122 -0
  578. package/dist/tenable-findings.js.map +1 -0
  579. package/dist/terminal-columns.d.ts +4 -0
  580. package/dist/terminal-columns.d.ts.map +1 -0
  581. package/dist/terminal-columns.js +19 -0
  582. package/dist/terminal-columns.js.map +1 -0
  583. package/dist/terminal-stream.d.ts +13 -0
  584. package/dist/terminal-stream.d.ts.map +1 -0
  585. package/dist/terminal-stream.js +35 -0
  586. package/dist/terminal-stream.js.map +1 -0
  587. package/dist/trivy-findings.d.ts +19 -0
  588. package/dist/trivy-findings.d.ts.map +1 -0
  589. package/dist/trivy-findings.js +435 -0
  590. package/dist/trivy-findings.js.map +1 -0
  591. package/dist/trivy-import.d.ts +19 -0
  592. package/dist/trivy-import.d.ts.map +1 -0
  593. package/dist/trivy-import.js +151 -0
  594. package/dist/trivy-import.js.map +1 -0
  595. package/dist/validation-records.d.ts +0 -3
  596. package/dist/validation-records.d.ts.map +1 -1
  597. package/dist/validation-records.js +1 -17
  598. package/dist/validation-records.js.map +1 -1
  599. package/dist/veracode-findings.d.ts +9 -0
  600. package/dist/veracode-findings.d.ts.map +1 -0
  601. package/dist/veracode-findings.js +409 -0
  602. package/dist/veracode-findings.js.map +1 -0
  603. package/dist/vertex-pricing.d.ts +8 -0
  604. package/dist/vertex-pricing.d.ts.map +1 -0
  605. package/dist/vertex-pricing.js +20 -0
  606. package/dist/vertex-pricing.js.map +1 -0
  607. package/dist/windows-path.d.ts +1 -0
  608. package/dist/windows-path.d.ts.map +1 -1
  609. package/dist/windows-path.js +27 -1
  610. package/dist/windows-path.js.map +1 -1
  611. package/dist/wiz-csv.d.ts +2 -2
  612. package/dist/wiz-csv.d.ts.map +1 -1
  613. package/dist/wiz-csv.js +1 -3
  614. package/dist/wiz-csv.js.map +1 -1
  615. package/dist/wiz-findings.d.ts +14 -2
  616. package/dist/wiz-findings.d.ts.map +1 -1
  617. package/dist/wiz-findings.js +143 -50
  618. package/dist/wiz-findings.js.map +1 -1
  619. package/docs/classify-severity-records.md +28 -13
  620. package/docs/cli.md +623 -843
  621. package/docs/dedupe-records.md +54 -24
  622. package/docs/findings-service.md +87 -47
  623. package/docs/hosted-remediation.md +14 -7
  624. package/docs/hosted-scans.md +64 -41
  625. package/docs/telemetry.md +236 -0
  626. package/docs/validate-records.md +78 -44
  627. package/package.json +19 -17
  628. package/schemas/external-findings.schema.json +14 -1
  629. package/schemas/hosted-scan-v2.fixture.json +16 -1
  630. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  631. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  632. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  633. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  634. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  635. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  636. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  637. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  638. package/dist/deduplication/records-protocol.d.ts +0 -4
  639. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  640. package/dist/deduplication/records-protocol.js +0 -49
  641. package/dist/deduplication/records-protocol.js.map +0 -1
  642. package/dist/external-imports-feature.d.ts +0 -6
  643. package/dist/external-imports-feature.d.ts.map +0 -1
  644. package/dist/external-imports-feature.js +0 -51
  645. package/dist/external-imports-feature.js.map +0 -1
  646. package/dist/finding-normalization.d.ts +0 -5
  647. package/dist/finding-normalization.d.ts.map +0 -1
  648. package/dist/finding-normalization.js +0 -120
  649. package/dist/finding-normalization.js.map +0 -1
package/docs/cli.md CHANGED
@@ -16,13 +16,6 @@ codex-security info --json
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
17
  `scans` and `findings` default to their `list` subcommands.
18
18
 
19
- To retrieve GitHub code scanning alerts without an MCP server, use
20
- [`import github`](#import-alerts-from-the-cli). To save an existing CSV or JSON
21
- findings file in local scan history, use
22
- [`scan import`](#import-findings-as-a-saved-scan). These are separate workflows:
23
- GitHub import returns upstream alerts for validation; file import saves findings
24
- without running security analysis.
25
-
26
19
  ## Find a workflow
27
20
 
28
21
  - [Sign in or configure a provider](#authentication).
@@ -31,9 +24,8 @@ without running security analysis.
31
24
  [save project settings](#project-files).
32
25
  - [Review one system across repositories](#review-one-system-across-repositories)
33
26
  or [run independent bulk scans](#bulk-scans).
34
- - [Import vendor findings locally](#import-vendor-findings-locally),
35
- [save findings as a scan](#import-findings-as-a-saved-scan), or
36
- [retrieve GitHub alerts](#import-alerts-from-the-cli).
27
+ - [Choose an import command](#import-vendor-findings-locally) to save a scan,
28
+ collect upstream alerts, or store vendor evidence locally or in Cloud.
37
29
  - [Inspect saved scans and rerun them](#scan-history-and-reruns),
38
30
  [classify severity](#classify-finding-severity), or
39
31
  [suggest owners](#suggest-finding-owners).
@@ -86,7 +78,9 @@ your local browser. Keep SSH connected until login finishes.
86
78
  ### OpenAI credentials
87
79
 
88
80
  Interactive scans ask which credentials to use when both ChatGPT and an
89
- environment API key are available. Noninteractive commands prefer
81
+ environment API key are available. A dedicated sign-in takes precedence. After
82
+ `codex-security logout`, the prompt skips the ambient sign-in until you log in
83
+ again. Noninteractive commands prefer
90
84
  `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
91
85
  with `--auth`:
92
86
 
@@ -103,12 +97,25 @@ the stored login. Patch follow-up assessments and `scan --patch` retain the
103
97
  chosen authentication. Environment keys do not replace the saved login.
104
98
  The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
105
99
 
100
+ For a scan using a custom native provider, `auto` and `api-key` use the
101
+ environment variable declared by `model_providers.<id>.env_key`, including
102
+ when a Codex file profile selects that provider. Set that variable before
103
+ starting the scan. To use `--auth chatgpt`, select a provider configured for
104
+ account authentication. A custom provider that requires its own key cannot
105
+ honor that combination.
106
+
106
107
  Stored OpenAI credentials live in
107
108
  `$CODEX_SECURITY_STATE_DIR/codex-home`, or
108
109
  `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
109
110
  outside the target and every enclosing Git worktree. It also serves providers
110
111
  with `requires_openai_auth = true`.
111
112
 
113
+ If you manually hard-linked the two homes’ `auth.json` files, keep both homes
114
+ accessible when running `codex-security logout`. When the CLI verifies the
115
+ two hard links, it removes the private link before invoking native logout.
116
+ If the ambient home is unavailable, the configured credential store handles
117
+ logout normally.
118
+
112
119
  Codex carries credential-storage, forced-login, and workspace settings from the
113
120
  ambient configuration into this home. Managed-device policies still apply;
114
121
  workspace-managed policies may require ChatGPT credentials even with an API key.
@@ -122,8 +129,19 @@ after logout completes.
122
129
  Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
123
130
  `HOME` or `USERPROFILE` environment setting.
124
131
 
125
- If credentials cannot refresh, run `login status`. Retry if the sign-in recently
126
- changed; otherwise run `logout`, then `login`.
132
+ If you use file-based ChatGPT credentials with both Codex and Codex Security,
133
+ run `codex-security login` before your first scan or status check to give Codex
134
+ Security its own session. An imported sign-in shares a single-use refresh token.
135
+ When either client renews it, the other client's next refresh can fail even
136
+ while its login status reports that it is signed in.
137
+
138
+ If Codex Security reports that the refresh token was already used, run
139
+ `codex-security logout`, then `codex-security login`. If your Codex CLI or app
140
+ reports that error, sign out and sign back in there.
141
+
142
+ For other refresh errors, check `codex-security login status`. Retry if the
143
+ sign-in recently changed. Otherwise run `codex-security logout`, then
144
+ `codex-security login`.
127
145
  Some cybersecurity requests and protected findings require
128
146
  [Trusted Access for Cyber](https://chatgpt.com/cyber).
129
147
 
@@ -141,7 +159,7 @@ In the SDK, use `new CodexSecurity({ codexOverrides: { daybreak: true } })`.
141
159
  In project files, set `daybreak: true` inside the `codex` mapping. Use `false`
142
160
  to explicitly turn it off.
143
161
  The setting carries through saved scan recipes, resumed scans, Deep Scan
144
- discovery and reducer workers, and `scan --patch`. Standalone `validate`,
162
+ discovery workers, and `scan --patch`. Standalone `validate`,
145
163
  `patch`, and `verify-fix` accept the same `--codex daybreak=true` override.
146
164
  Threads created by these commands retain the setting when resumed in Codex.
147
165
  Scans use isolated configuration, so set it on the CLI, SDK client, or project
@@ -151,8 +169,7 @@ For the plugin inside Codex, use the desktop Daybreak toggle or `/daybreak` in
151
169
  an interactive CLI session. For headless Codex, use `codex exec -c daybreak=true`
152
170
  or set top-level `daybreak = true` in the configuration loaded by the runner.
153
171
  Deep Scan inherits the active turn's effective access program from its saved
154
- Codex session, including an explicit Standard selection. Discovery and reducer
155
- workers retain that selection when resumed. If the host does not supply a
172
+ Codex session, including an explicit Standard selection. Discovery workers retain that selection when resumed. If the host does not supply a
156
173
  persisted turn context, workers use their runner configuration; CLI and SDK scans
157
174
  use the explicit scan settings above.
158
175
 
@@ -169,7 +186,8 @@ and project have access. An omitted `access_programs.cyber` field does not by
169
186
  itself mean that Daybreak treatment is disabled.
170
187
 
171
188
  Choose a compatible model available to your project and select Daybreak Blue
172
- explicitly:
189
+ explicitly. If you use `--max-cost` or the SDK's `maxCostUsd`, choose a model
190
+ with built-in pricing so the scan can enforce the limit.
173
191
 
174
192
  ```bash
175
193
  codex-security scan /path/to/repository \
@@ -179,14 +197,11 @@ codex-security scan /path/to/repository \
179
197
  In the SDK, select your model through `codexOverrides.model` and pass
180
198
  `auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
181
199
  Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
182
- The selection reaches discovery and reducer workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
200
+ The selection reaches discovery workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
183
201
  for configuration precedence and the API-key feature setting.
184
202
 
185
- The previously documented `gpt-daybreak-blue-latest` alias is
186
- [deprecated](https://developers.openai.com/api/docs/models/gpt-daybreak-blue-latest).
187
- Use a current model available to your project. `access_programs.cyber` is a
188
- Responses API field; use the supported selector instead of passing it as a
189
- `--codex` configuration key.
203
+ `access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
204
+ instead of passing it as a `--codex` configuration key.
190
205
 
191
206
  ### Select a Cyber access program
192
207
 
@@ -237,6 +252,15 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
237
252
  codex-security scan . --provider cheaperinference --model gpt-5.4
238
253
  ```
239
254
 
255
+ ### Hugging Face compatibility
256
+
257
+ In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
258
+ `namespace` and could request `web_search`. Hugging Face's published Responses
259
+ implementation accepts `function` and remote `mcp` tool declarations. A named
260
+ Hugging Face scan provider is deferred until the scanner and router can exchange
261
+ the tools a complete scan requires. [Hugging Face's implementation notes](https://huggingface.co/docs/inference-providers/en/guides/gpt-oss#responses-api)
262
+ and [request schema](https://github.com/huggingface/responses.js/blob/0e3e84c469a9f59ad16e2eb3a0d6f1c4de637a7b/src/schemas.ts#L219-L232).
263
+
240
264
  ### Amazon Bedrock
241
265
 
242
266
  Use AWS credentials and a region with access to the exact Bedrock model ID:
@@ -256,6 +280,45 @@ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/
256
280
  for credential alternatives, restricted-model access, cost estimates, and
257
281
  reasoning-summary configuration.
258
282
 
283
+ ### Google Cloud Vertex AI cost estimates
284
+
285
+ The SDK estimates Standard online inference costs for OpenAI models served by
286
+ Google Cloud's Model as a Service (MaaS). Rates are in USD per million tokens.
287
+ [Google Cloud partner model pricing](https://cloud.google.com/model-garden/partner-models/pricing)
288
+ and [OpenAI model locations](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/maas/openai).
289
+
290
+ | Managed model ID | Location | Input | Cached input | Output |
291
+ | -------------------------- | ----------------------- | ----: | -----------: | -----: |
292
+ | `openai/gpt-oss-120b-maas` | `global` | $0.09 | $0.09 | $0.36 |
293
+ | `openai/gpt-oss-20b-maas` | `us-central1` (retired) | $0.07 | $0.007 | $0.25 |
294
+
295
+ Google publishes a cache-hit discount only for 20B, so the estimator uses the
296
+ ordinary input rate for cached 120B tokens. Google retired the managed 20B
297
+ endpoint on October 21, 2026. The SDK retains its rates for historical usage.
298
+ [Google Cloud retirement schedule](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/deprecations/open-models).
299
+
300
+ To estimate recorded usage locally, pass the managed model ID and the GCP
301
+ provider to `estimateScanCost`.
302
+
303
+ ```ts
304
+ import { estimateScanCost } from "@openai/codex-security";
305
+
306
+ const cost = estimateScanCost(
307
+ "openai/gpt-oss-120b-maas",
308
+ { input_tokens: 1_000_000, output_tokens: 500_000 },
309
+ { provider: "gcp" },
310
+ );
311
+ // cost?.estimatedUsd is 0.27.
312
+ ```
313
+
314
+ Google documents the managed GPT OSS IDs on its shared chat-completions API.
315
+ The bundled Codex `gcp` provider uses Google's Responses API with a separate
316
+ frontier model catalog. Google has published no Standard token rates for that
317
+ catalog, including GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, and GPT-6 Luna.
318
+ Those scans record token usage and require a published price to use
319
+ `--max-cost`. Self-deployed Model Garden endpoints incur infrastructure charges.
320
+ [Google Cloud's preview announcement](https://cloud.google.com/blog/products/ai-machine-learning/google-cloud-brings-openai-models-to-customers).
321
+
259
322
  ## Generate a security policy
260
323
 
261
324
  Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
@@ -431,6 +494,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
431
494
  requested work separately from optional `coverage.openQuestions` follow-up.
432
495
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
433
496
 
497
+ When a cost limit is configured, `scan --dry-run` shows the resolved
498
+ `maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
499
+ against the limit and why in-flight requests can exceed it.
500
+
434
501
  Whole-codebase and path scans also accept ordinary directories, including SVN
435
502
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
436
503
 
@@ -461,10 +528,17 @@ with every repository.
461
528
 
462
529
  Use `--output-dir DIR` to choose where a scan saves its results. The directory
463
530
  must be empty and outside the scanned directory and enclosing Git worktree.
464
- Existing directories keep their permissions; newly created directories are
465
- private to you by default.
466
- `--archive-existing` moves earlier output to
467
- `<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
531
+ Existing directories keep their permissions. Newly created directories are
532
+ private to you by default. On Windows, the directory and its parents must be
533
+ owned by your account, Administrators, SYSTEM, or TrustedInstaller. Choose a
534
+ path where another user cannot replace the output directory or one of its
535
+ parents. A parent can allow other users to read it or create sibling directories.
536
+ For an empty write destination, grant content-writing permissions to children
537
+ through inheritance. Other users must not have permission to set reparse data
538
+ on the destination directory itself.
539
+ `--archive-existing` moves earlier output to a sibling directory with a unique
540
+ suffix, such as `results.previous-ab12cd34` for an output directory named
541
+ `results`. Use `--dry-run` to preview the move.
468
542
 
469
543
  Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
470
544
  optional export fails, the scan can still complete. Use the
@@ -504,7 +578,9 @@ or JSONL output produce:
504
578
  { "status": "failed", "code": "SCAN_FAILED", "message": "..." }
505
579
  ```
506
580
 
507
- With `--full-output`, the error appears under `error` in an `ok: false` envelope.
581
+ With `--full-output`, JSON and JSONL failures put the error under `error` in an
582
+ `ok: false` envelope. YAML and TOON use the same failed envelope when retained
583
+ sealed scan results are available (including TOON selected by default).
508
584
  If the scan target changed, the error explains that the results no longer
509
585
  represent the current checkout. Retained sealed results remain available under
510
586
  `data`, including their manifest, findings, review summary, scan directory, and report
@@ -516,8 +592,8 @@ selecting an unavailable field can return `null` or omit `data`.
516
592
  Saved-scan setup failures use the same output shape with
517
593
  `SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
518
594
  available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
519
- scan uses `SCAN_IMPORT_FAILED` if the import fails. Other output formats retain
520
- stderr-only failures, including when `--full-output` is selected.
595
+ scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
596
+ on stderr without `--full-output`, or when retained results are unavailable.
521
597
 
522
598
  Diagnostics stay on stderr. Each command's `--schema --format json` describes
523
599
  its successful output and failure codes.
@@ -527,8 +603,9 @@ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
527
603
 
528
604
  Scans already validate findings against local source. Add `--validate` to run
529
605
  the existing standalone validation workflow for each reported finding after
530
- the scan, using the same selected Cyber access program. Validation has read-only
531
- filesystem access with network and web search disabled. Each assessment uses a
606
+ the scan, using the same selected Cyber access program. Validation sends each
607
+ finding to the configured model provider. Its review tools have read-only
608
+ filesystem access, with network access and web search disabled. Each assessment uses a
532
609
  separate evidence directory; the combined report is saved as
533
610
  `<scan-dir>/validation.md`, or a uniquely suffixed report
534
611
  if that path already exists. Each completed assessment is saved immediately;
@@ -572,26 +649,21 @@ Replace `SCAN_ID` with the ID from the completion or failure summary. A scan can
572
649
  fail after registration but before writing its artifacts; investigate those
573
650
  failures through its history record and any available logs. When artifacts were
574
651
  retained, use the saved results directory returned by `scans show` to inspect
575
- whichever of these files are present:
576
-
577
- | File | What to check |
578
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
579
- | `scan-manifest.json` | `scan.status`, the target snapshot, and any recorded `scan.scope` limitations. |
580
- | `report.md` | Scope, reviewed surfaces, and open questions or follow-up work. |
581
- | `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`. |
582
-
583
- Deferred items can identify affected `paths` or `surfaceIds`. Surface
584
- `receiptRefs` link to retained evidence under `artifacts/` when available.
585
- Deep Scan summaries retain coverage from accepted worker reviews, including
586
- worker-specific deferred work. Check those details as well as the final findings.
587
-
588
- These records describe what the scan recorded, not an exhaustive file-by-file
589
- audit. A retained source inventory, when present, lists inputs rather than
590
- proving that each file was reviewed. An absent path in a surface summary does not
591
- establish whether it was read, and the scan ID cannot reconstruct evidence that
592
- was never saved.
593
- Session logs can help explain failures and tool activity, but do not prove
594
- complete review either.
652
+ the saved files:
653
+
654
+ | File | What to check |
655
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
656
+ | `scan-manifest.json` | `scan.status` and `scan.target` identify the outcome and snapshot. `scan.scope` lists requested inclusions and exclusions. `scan.review.excludedPaths` lists additional excluded paths in current scans. |
657
+ | `findings.json` | Reported findings, source locations and supporting evidence. |
658
+ | `report.md` | A readable summary of the scope and findings. |
659
+
660
+ When a checkpoint is retained, `checkpoint-head.json` identifies the file in
661
+ `checkpoints/`. In a retained draft or checkpoint, `reviewState.deferred` lists
662
+ unfinished work and `reviewState.openQuestions` lists follow-up questions.
663
+ Older manifests with `scan.coverageRef` point to a separate `coverage.json`
664
+ with reviewed surfaces, explicit exclusions and deferred work. A saved source
665
+ inventory identifies inputs. Neither that inventory nor session logs establish
666
+ which files the scan reviewed in full.
595
667
 
596
668
  For a local plugin scan, ask Codex to open the saved scan and explain its scope,
597
669
  exclusions, deferred work, and follow-up questions. CLI history can also locate
@@ -635,15 +707,19 @@ completeness values to determine scan status or exit codes.
635
707
 
636
708
  ```bash
637
709
  codex-security init
638
- codex-security scan . -c codex-security.yaml --dry-run --json
639
710
  codex-security info -c codex-security.yaml --json
711
+ codex-security scan . -c codex-security.yaml --dry-run --json
640
712
  ```
641
713
 
642
714
  Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
643
- Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
715
+ Keep `-c` on both `info` and the scan preview to inspect the same target and
716
+ limits. Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
644
717
  `scan-components`, and `info` accept project files. SDK calls and saved reruns
645
718
  do not load them automatically.
646
719
 
720
+ JSON project files and component plans (`--components-file`) accept UTF-8 with
721
+ or without a leading byte-order mark.
722
+
647
723
  Treat the selected file as trusted operator configuration: native settings can
648
724
  start MCP processes and choose model-service destinations. Keep CI scanner
649
725
  configuration outside the untrusted checkout being assessed.
@@ -691,7 +767,8 @@ runs, four with new identities, and two duplicate pairs for testing deduplicatio
691
767
  Paths and snippets are fictional; repository files remain unchanged.
692
768
 
693
769
  Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
694
- archiving, and severity thresholds work normally. Reruns preserve mock mode.
770
+ archiving, and severity thresholds work normally. Use `scans show` to inspect a
771
+ mock scan. Mock scans have no Codex session logs. Reruns preserve mock mode.
695
772
  Separate matching or deduplication commands still make their usual model calls.
696
773
 
697
774
  Mock mode supports Standard repository, path, and diff scans. It cannot combine
@@ -770,7 +847,8 @@ individual scan folder.
770
847
  Failures do not stop other components. Failed scans or
771
848
  failed matching return `2`; severity-policy violations return `1`. Retry with
772
849
  `--components-file retry-components.json` and a new empty output directory.
773
- The retry report covers only those components.
850
+ The retry report covers only those components. Each registered component keeps its
851
+ scan ID in the summary, including when the scan fails.
774
852
 
775
853
  `--max-cost` applies per component, excluding planning and matching. `--model`
776
854
  and `--effort` also apply to matching; `--auth` applies throughout. Planning and
@@ -782,6 +860,28 @@ Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
782
860
  planning and authentication choices. Custom `createSecurity` clients receive
783
861
  absolute targets; saved plans and component receipts retain relative paths.
784
862
 
863
+ ### Choose a severity rubric
864
+
865
+ Standalone Standard and Deep scans grade findings with the bundled rubric by
866
+ default. Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the
867
+ current default from Statsig once when starting a scan. If that lookup fails,
868
+ the scan uses the bundled rubric.
869
+
870
+ ```bash
871
+ CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1 codex-security scan .
872
+ codex-security scan . --mode deep --rubric ./severity.md
873
+ ```
874
+
875
+ An explicit Markdown file takes precedence and skips the lookup, even when
876
+ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
877
+ `markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
878
+ Markdown. A supplied snapshot takes precedence over a file.
879
+
880
+ The scan saves the rubric text in its local launch recipe. Retrying a Standard
881
+ scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
882
+ with a saved rubric reuses that copy even if the remote default or file changes.
883
+ Older scans without a saved rubric continue to resume using their existing workflow.
884
+
785
885
  ### Set investigation time
786
886
 
787
887
  ```bash
@@ -812,11 +912,18 @@ codex-security scan . --mode deep --workers 2 --subagents 0 \
812
912
  --stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
813
913
  ```
814
914
 
815
- For `scan --mode deep`, `--workers` controls discovery concurrency and
816
- `--subagents` controls subagents per worker. `--stop-after-no-new`,
817
- `--max-discovery-runs`, and `--max-time` stop discovery by novelty, count,
818
- or duration. At the deadline, discovery stops; the scan then combines and returns
819
- completed findings.
915
+ Deep Scan repeats Standard scans in batches of up to `--workers`, with
916
+ `--subagents` per scan. Workers can share what they are investigating, ask each
917
+ other to check a source location, and reply while their audits are running. Each
918
+ worker verifies the evidence it reports. Deep Scan merges each completed batch in launch order.
919
+ It uses source locations, cited code and weakness descriptions to match repeated
920
+ findings. Each group keeps its first description, all reported locations, and
921
+ the original observations. Later batches receive the titles and primary
922
+ locations of retained findings so workers can investigate other reachable paths.
923
+ `--stop-after-no-new` counts consecutive
924
+ completed scans that added no findings. `--max-discovery-runs` caps the total
925
+ number started, including failures. `--max-time` stops discovery and returns
926
+ the findings from completed scans.
820
927
 
821
928
  For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
822
929
 
@@ -826,6 +933,8 @@ that `subagents` can be zero. Discovery time accepts positive fractional minutes
826
933
  its default and maximum are 5760 minutes (96 hours). Unlike Standard's
827
934
  advisory allowance, the Deep discovery limit is enforced. Resuming a
828
935
  Deep scan keeps its original deadline; rerunning starts a new scan.
936
+ If the deadline expires before any source review completes, the saved report
937
+ and scan manifest record that limitation.
829
938
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
830
939
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
831
940
  hours. Explicit settings override lower-priority configuration across units.
@@ -874,9 +983,28 @@ executable outside all saved scan targets. If a historical target includes the
874
983
  available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
875
984
  explicit saved scan ID. Exact-path `latest` lookup still works without Git.
876
985
 
877
- Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:
878
- `--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are
879
- rejected, including a `--model` or `--effort` flag plus its native equivalent.
986
+ Repeat `--codex KEY=VALUE` for supported native settings. For example,
987
+ `--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
988
+ Command Prompt, and PowerShell. Repeated or conflicting keys are rejected,
989
+ including a `--model` or `--effort` flag plus its native equivalent.
990
+
991
+ To select a Codex file profile, put its settings in
992
+ `$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
993
+ `CODEX_HOME` is unset), then run:
994
+
995
+ ```bash
996
+ npx @openai/codex-security scan . --codex "profile='review'"
997
+ ```
998
+
999
+ In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
1000
+ set `codex.profile: review`. The profile file uses top-level Codex TOML keys.
1001
+ Its settings override scanner defaults. Explicit scan settings take precedence.
1002
+ Relative file paths, including `model_instructions_file`, resolve from the
1003
+ profile directory. Saved launches retain the profile name and reload its settings.
1004
+ Include custom provider definitions in the file so the scan
1005
+ can use them from its isolated Codex home. An absent file contributes no
1006
+ settings. Existing inline `profiles` tables still work.
1007
+
880
1008
  Choose plugins with `--plugin-path`; native plugin and marketplace overrides are
881
1009
  rejected. New and resumed Deep Scans require the current plugin's direct engine,
882
1010
  worker provider snapshot, and isolated worker configuration capabilities. Update
@@ -891,11 +1019,11 @@ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
891
1019
 
892
1020
  ```bash
893
1021
  codex-security patch "Security issue" --model gateway-model \
894
- --codex 'model_provider="gateway"' \
895
- --codex 'model_providers.gateway.name="Gateway"' \
896
- --codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \
897
- --codex 'model_providers.gateway.wire_api="responses"' \
898
- --codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'
1022
+ --codex "model_provider='gateway'" \
1023
+ --codex "model_providers.gateway.name='Gateway'" \
1024
+ --codex "model_providers.gateway.base_url='https://gateway.example.test/v1'" \
1025
+ --codex "model_providers.gateway.wire_api='responses'" \
1026
+ --codex "model_providers.gateway.env_key='GATEWAY_API_KEY'"
899
1027
  ```
900
1028
 
901
1029
  Set the provider's key environment variable before running. Patching and
@@ -921,12 +1049,14 @@ publication uses the same request attribution; embedding requests identify
921
1049
  the package and version in their `User-Agent`.
922
1050
 
923
1051
  These fields provide request attribution for supported inference providers, including
924
- Bedrock. They do not create a separate telemetry collector, record command
925
- starts or outcomes, or make another provider's traffic visible to OpenAI.
1052
+ Bedrock. They do not create a separate telemetry collector or make another
1053
+ provider's traffic visible to OpenAI. Local operation receipts separately record
1054
+ starts, outcomes, duration, and usage coverage; see
1055
+ [telemetry and measurement](telemetry.md).
926
1056
 
927
1057
  Disable Codex usage analytics and built-in metrics with
928
- `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
929
- patch-risk assessment, and Deep Scan discovery and reducer workers, including
1058
+ `--codex analytics.enabled=false`. The setting carries into `scan --patch`,
1059
+ patch-risk assessment, and Deep Scan discovery workers, including
930
1060
  resumed workers. Selected-profile settings take precedence over root settings.
931
1061
  Explicit OpenTelemetry settings also carry into scan patches and Deep Scan
932
1062
  workers, including exporter choices and prompt-logging controls.
@@ -935,32 +1065,43 @@ The setting does not control configured OpenTelemetry exporters, integrations,
935
1065
  authentication, or CLI update checks. Validation uses isolated configuration;
936
1066
  patching and verification preserve ambient project trust.
937
1067
 
1068
+ For scan outcomes, the workbench saves a separate, local `lifecycle` record
1069
+ with the scan ID, launch surface, available release versions, mode, timestamps,
1070
+ and committed status. A completed scan indicates whether it produced reportable
1071
+ findings. Use `codex-security scans list --json` for the current repository.
1072
+ To find an offline import, use `codex-security scans list --scan-root <DIR> --json`
1073
+ with its output directory. Imported scans have lifecycle mode `import`. The SDK
1074
+ exposes `onLifecycle`, and the CLI includes observations in verbose diagnostics.
1075
+ Canceling a newly registered SDK scan through its abort signal, closing the
1076
+ client during the scan, or receiving a canceled hosted execution records
1077
+ `canceled`. A scan that has already completed keeps its committed outcome.
1078
+ Applications can choose how to collect and export these observations.
1079
+
938
1080
  For filesystem and approval behavior, see the
939
1081
  [local security model](../README.md#local-security-model).
940
1082
 
941
1083
  ### Environment variables
942
1084
 
943
- | Variable | Effect |
944
- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
945
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
946
- | `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS` | Set to `1` to enable vendor finding imports, imported-findings readback, and GitHub advisory acquisition; disabled otherwise. |
947
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
948
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
949
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
950
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
951
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
952
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
953
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
954
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
955
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
956
- | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
957
- | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
958
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
959
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
960
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
961
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
962
- | `CI` | Disable interactive update notices. |
963
- | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
1085
+ | Variable | Effect |
1086
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
1087
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
1088
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
1089
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
1090
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
1091
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
1092
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
1093
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
1094
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
1095
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
1096
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
1097
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
1098
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
1099
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
1100
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
1101
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
1102
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
1103
+ | `CI` | Disable interactive update notices. |
1104
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
964
1105
 
965
1106
  Custom Codex executables need thread source attribution for `exec` and
966
1107
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -974,7 +1115,8 @@ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage
974
1115
  ### Troubleshooting
975
1116
 
976
1117
  Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
977
- retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,
1118
+ retry, and worker diagnostics on stderr. Direct Deep Scans include coordinator events
1119
+ such as worker retries and duplicate-comparison failures. Diagnostic text is preserved in output,
978
1120
  saved failures, receipts, and patch-risk summaries. Review it for sensitive
979
1121
  information before sharing; upstream Codex output may already be redacted.
980
1122
 
@@ -983,6 +1125,21 @@ Finish older-version operations before upgrading. Never remove
983
1125
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
984
1126
  credential home before manually removing an old `.codex-security-scan.lock`.
985
1127
 
1128
+ If a scan reports that its state directory overlaps a protected root, choose a
1129
+ private directory in a separate tree, such as a sibling of the protected root.
1130
+ Set `CODEX_SECURITY_STATE_DIR` for local scans or `stateDirectory` on a hosted
1131
+ scan request. SDK callers handling `OutputInsideProtectedRootError.pathKind`
1132
+ can match `"state"` for this case.
1133
+
1134
+ If credential-home preparation fails, the error includes the underlying
1135
+ filesystem diagnostic. For permission or read-only filesystem errors, check
1136
+ the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
1137
+ directory outside the repository. A new state directory has separate history
1138
+ and does not migrate existing credentials or reports.
1139
+
1140
+ Sandbox startup errors include the native diagnostic followed by a command to
1141
+ reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
1142
+
986
1143
  On Windows, credential-home checks require trusted ownership and permissions
987
1144
  through every ancestor, including the volume root. Codex Security can repair
988
1145
  the credential home and its descendants; it does not change ancestor ownership
@@ -1039,10 +1196,13 @@ their own timestamps, window durations, and reset times. These are historical
1039
1196
  observations, not a live allowance check or scan-only consumption. Empty readings
1040
1197
  mean allowance was unavailable. There is no token-to-allowance conversion here.
1041
1198
 
1042
- Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
1043
- and show a short/long-context range. They estimate model usage, excluding other
1044
- tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
1045
- subscription allowance. Models without known prices have no estimate.
1199
+ Cost displays use Standard token rates for the model. OpenAI models use
1200
+ [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). OpenAI
1201
+ models on Bedrock use [AWS pricing for the model, inference route, and region](https://github.com/openai/codex-security/blob/main/docs/bedrock.md#scan-cost-estimates).
1202
+ For managed OpenAI models on Vertex AI, see [Google Cloud Vertex AI cost estimates](#google-cloud-vertex-ai-cost-estimates).
1203
+ The short/long-context range estimates usage at published rates. Other service
1204
+ tiers, account discounts, and ChatGPT subscription allowance are outside that
1205
+ estimate. Models without known prices have no estimate.
1046
1206
 
1047
1207
  JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
1048
1208
  and `context: "unknown"`). A null maximum means no upper estimate is available.
@@ -1057,13 +1217,25 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
1057
1217
  Automatic history matching gets at most one extra call with a limit; if more
1058
1218
  work is needed, the scan is preserved and you can run `scans match --all`.
1059
1219
 
1060
- When Deep discovery has finished at a cost stop, the scan returns a sealed
1061
- report and lists unvalidated candidates as follow-up work. Reaching a configured
1062
- limit with a valid finalized report returns `0` by default, or `1` if findings
1063
- meet a configured failure threshold.
1064
-
1065
- When Codex reports an exhausted usage limit, Deep Scan cancels active workers
1066
- and stops retrying or launching replacements. Completed worker artifacts are retained.
1220
+ A scan with a cost limit requires complete token usage for its recorded scan,
1221
+ worker, and custom validation sessions before the SDK returns a completed result.
1222
+ Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
1223
+ `backports.zstd` installed in the selected Python environment.
1224
+ Missing or unreadable usage fails budget verification. Without a limit, usage
1225
+ reporting remains best effort.
1226
+
1227
+ When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
1228
+ report and retains unvalidated candidates as follow-up work. The saved report and
1229
+ the manifest's `scan.scope.limitations` record that validation was deferred.
1230
+ Reaching a configured limit with a valid finalized report returns `0` by default,
1231
+ or `1` if findings meet a configured failure threshold.
1232
+
1233
+ When a worker turn fails with a known cybersecurity policy refusal or an
1234
+ exhausted usage limit, Deep Scan stops retries and replacements, cancels active
1235
+ siblings, and retains completed worker artifacts. A capability check can succeed
1236
+ before a later request is refused. Use `scans show SCAN_ID` to inspect the failed
1237
+ scan and its retained results. To run it again from a saved recipe, use
1238
+ `scans rerun SCAN_ID`, which starts fresh discovery.
1067
1239
 
1068
1240
  At 80% of a single interactive scan's limit, the dashboard offers a higher total
1069
1241
  budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
@@ -1173,6 +1345,12 @@ Concurrency defaults to four repositories. `--max-attempts` defaults to one
1173
1345
  attempt per pending repository per invocation. Repeating the command continues
1174
1346
  the campaign, skips completed results, and starts pending attempts. Occupied
1175
1347
  attempt directories stop that repository and suggest `--recover`.
1348
+ If an ordinary attempt finds its checkout path already occupied, it stops before
1349
+ fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
1350
+ existing checkout before an ordinary retry.
1351
+ If checkout cleanup previously failed, the next invocation removes it only when
1352
+ its marker still identifies the same directory and scan attempt. Older or
1353
+ replacement checkouts without a matching marker are preserved.
1176
1354
  Completed results are skipped only when their saved contract and seal are valid
1177
1355
  and the manifest records a completed scan. Damaged or unsuccessful results get a
1178
1356
  new attempt, including with `--recover`, while the old artifacts remain available.
@@ -1202,6 +1380,13 @@ failed or interrupted attempt:
1202
1380
  - An unavailable, failed, or canceled scan starts a new attempt at the pinned
1203
1381
  revision, preserving old artifacts and checkouts.
1204
1382
 
1383
+ Each nonempty committed line in `results.jsonl` must be valid JSON with a string
1384
+ task ID and a positive safe integer attempt number. If a line fails these checks,
1385
+ the command reports its line number and preserves the ledger. Restore a complete
1386
+ ledger backup that includes every committed attempt, or start a separate campaign
1387
+ in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
1388
+ a fresh attempt requires a new campaign.
1389
+
1205
1390
  New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
1206
1391
  workers and one recovery/new attempt per repository. A resume connection failure
1207
1392
  stops only that repository for this invocation. Failed recovery checkouts remain;
@@ -1270,512 +1455,247 @@ Supply the validation prompt again when rerunning.
1270
1455
 
1271
1456
  ## Import vendor findings locally
1272
1457
 
1273
- Use the [scanner file import schema and capability guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md) to compare provider identities, mapped evidence and destination behavior before selecting a report.
1458
+ Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
1274
1459
 
1275
- External finding imports are disabled by default. Opt in for the current shell:
1460
+ | Input and goal | Command | Service contacted | Where to find the result |
1461
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1462
+ | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1463
+ | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1464
+ | Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1465
+ | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1466
+ | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1276
1467
 
1277
- ```bash
1278
- export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
1279
- ```
1280
-
1281
- In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
1282
- Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
1283
- and `import github-advisories` are absent from command help and schemas and cannot
1284
- run. The SDK's external publication, local import/readback, and advisory
1285
- acquisition APIs require the same flag in their effective environment. An explicit
1286
- `dependencies.environment` is used instead of the process environment. Pure
1287
- normalizers and file readers remain available as library utilities.
1288
-
1289
- This flag does not affect `publish scan`, `publish check`, `scan import`, or the
1290
- existing `import github` alert collector. Disabling it retains previously imported
1291
- records; enable it again to read them with `findings imported`.
1292
-
1293
- Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
1294
- reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
1295
- inputs only for providers and report profiles that support them. A JSON API
1296
- summary is not automatically a supported report; follow the provider's acquisition
1297
- instructions and retain the original records. The readers detect supported input
1298
- formats; `--format json` selects command output, not the input format.
1299
-
1300
- Keep the acquisition format consistent across imports. Depending on the provider,
1301
- switching formats can create separate records for the same vulnerability or
1302
- replace a richer evidence snapshot with less detail. The importer does not merge
1303
- evidence or deduplicate equivalent vulnerabilities across different source IDs.
1304
-
1305
- Use the same vendor input and parser as Cloud publication, selecting a local
1306
- repository path instead of a Cloud repository ID or URL. Supported inputs include
1307
- Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
1308
- [Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
1309
- [Amazon Inspector repository findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md),
1310
- [Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
1311
- [OpenGrep native JSON](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md),
1312
- [GitHub Dependabot repository alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md),
1313
- and [saved GitHub code-scanning alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
1468
+ For `publish findings`, `--to` is required. With `--to local`, `--repository`
1469
+ takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
1470
+ The reader detects the file format. `--format json` selects the output format. A local preview checks the file offline without
1471
+ saving findings or calling a model. For example, preview a complete Endor
1472
+ Finding export from the matching checkout, replacing the namespace, project
1473
+ and branch in the source key.
1314
1474
 
1315
- ```bash
1316
- codex-security publish findings selected-wiz.json \
1317
- --to local --repository ./project --provider wiz \
1318
- --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1475
+ ```sh
1476
+ codex-security publish findings /private/path/endor-findings.json --provider endor \
1477
+ --to local --repository . --source-key NAMESPACE/PROJECT/main --dry-run --format json
1319
1478
  ```
1320
1479
 
1321
- Review the normalized evidence, repository, source namespace, and exclusions.
1322
- Run the same command without `--dry-run` to confirm interactively, or add `--yes`
1323
- after reviewing the preview. `--to` is required; there is no default destination.
1324
- Local import uses the workbench SQLite database and requires no Cloud login,
1325
- network connection, or model call. `--dry-run` does not write findings.
1480
+ After reviewing the findings and exclusions, rerun the command without
1481
+ `--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
1326
1482
 
1327
- Read the saved evidence with:
1483
+ For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
1328
1484
 
1329
- ```bash
1330
- codex-security findings imported ./project --format json
1331
- ```
1332
-
1333
- The repository argument defaults to the current directory. Local imports are
1334
- separate from the assessed findings shown by `findings list`: they remain
1335
- `not_assessed`, retain the original vendor evidence, and do not create a completed
1336
- scan or automatically validate or patch findings. Missing revisions, locations,
1337
- and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
1338
- Git remotes, the URL must match one of those remotes; the importer does not
1339
- substitute the checkout's current commit for an unknown scanner revision.
1340
-
1341
- Repeated imports update the same record by repository, provider, source key, and
1342
- source finding ID. The result reports created, updated, and unchanged counts.
1343
- Keep the source key stable across exports. Records omitted from a later selection
1344
- remain stored; omission does not resolve or delete a finding. Excluded records
1345
- are reported, and an import with exclusions exits with status 1. Both destinations
1346
- read the same vendor formats; Cloud's field, size and nesting limits do not apply
1347
- to local file imports.
1348
-
1349
- For OpenGrep, use `--provider opengrep` and supply `--source-repository-url`.
1350
- The reader supports native JSON and gzip for both destinations. It uses the
1351
- existing `semgrep` source-provider contract while retaining `OpenGrep` as the
1352
- scanner origin; keep a stable OpenGrep-specific source key. Review report
1353
- diagnostics as well as findings: import completion does not establish scan
1354
- coverage. The [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md)
1355
- covers evidence identity, empty reports, and assessing an imported finding with
1356
- the existing SDK validator.
1357
-
1358
- `scan import --json` and `scan import --csv` remain separate commands for importing
1359
- Codex Security's findings schema as a saved scan; they do not accept vendor
1360
- exports.
1485
+ Local readback uses `findings imported [PATH]`. The path defaults to the current
1486
+ directory. Each imported record starts as `not_assessed`. Unknown revisions and
1487
+ locations stay unknown. Repository-scoped sources are checked against comparable
1488
+ configured Git remotes as described in the provider guide. Reimporting the same
1489
+ source key and finding ID reports created, updated, or unchanged records.
1490
+ Records omitted from the new selection stay stored. Local imports can retain
1491
+ evidence that exceeds Cloud's per-finding limits.
1361
1492
 
1362
- ## Import Endor Labs findings
1493
+ If a report contains both ready and excluded records, the local dry run exits
1494
+ with status 0. After confirmation, the import stores the ready records and
1495
+ exits with status 1. If all records are excluded, both commands exit with
1496
+ status 2. A clean empty report exits with status 0 in either mode and stores
1497
+ no findings.
1363
1498
 
1364
- For local or Cloud import, prefer complete native Finding JSON from authenticated
1365
- `endorctl`, scoped to one project and context. Omit `--field-mask` and use
1366
- `--list-all` to finish pagination:
1499
+ Preview the same file and source key again for the intended destination before
1500
+ publishing. Semgrep Guardian selections, Web API SAST selections and full
1501
+ project collections support both destinations. Choose the [Semgrep import method](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) that matches your source.
1367
1502
 
1368
- ```sh
1369
- endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
1370
- --filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
1371
- --list-all --output-type json > endor-findings.json
1372
- codex-security publish findings endor-findings.json --to local \
1373
- --provider endor --repository ./project \
1374
- --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
1375
- ```
1376
-
1377
- Replace the example namespace, project UUID and local repository with your selection.
1378
- Review the preview, remove `--dry-run` to confirm, then read the stored evidence
1379
- with `codex-security findings imported ./project --format json`. To publish to
1380
- Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
1381
- file, provider and source key. The official
1382
- [Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
1383
- can help with setup and investigation, but summaries, counts and field-masked
1384
- results do not replace complete Finding objects. `endorctl` reads the Endor API;
1385
- the importer reads the saved export without maintaining an API connection or
1386
- writing changes back to Endor.
1387
-
1388
- Native JSON retains severity, package and advisory data, primary SAST/AI SAST
1389
- locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
1390
- reports are a lossy compatibility format, retaining finding links and UUIDs;
1391
- unavailable severity and revisions stay unknown. Both formats use the Endor UUID
1392
- within the selected repository and stable source key as identity. Importing SARIF
1393
- after native JSON for that UUID updates the same record by replacing its evidence
1394
- snapshot, not merging it. Native detail absent from SARIF is removed from the
1395
- snapshot. Use native JSON consistently for ongoing imports.
1396
-
1397
- Local and Cloud records remain unassessed source evidence. Local imports use the
1398
- SQLite readback described above; Cloud imports use the login, preview,
1399
- confirmation and retry flow below.
1503
+ ## Import Trivy dependency findings
1400
1504
 
1401
- ## Publish findings to Cloud
1505
+ Use `--provider trivy` for language-package vulnerabilities in schema-v2
1506
+ repository or filesystem JSON. The [Trivy guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/trivy.md) explains how
1507
+ to set the scan root and check manifest paths.
1402
1508
 
1403
- ### Import Snyk Open Source findings
1509
+ ## Import Endor Labs findings
1404
1510
 
1405
- Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
1406
- SBOM results and platform backlog ingestion are outside this adapter.
1511
+ Use `--provider endor` for one Endor project and context. The
1512
+ [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1513
+ SARIF compatibility, and the local preview.
1407
1514
 
1408
- Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
1409
- with its `snyk-findings-export` skill to collect SCA findings from the repository's
1410
- Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
1411
- it does not retrieve existing platform project findings.
1515
+ ## Import SonarQube Cloud issues
1412
1516
 
1413
- The same saved bundle supports [local import](#import-vendor-findings-locally)
1414
- without a Cloud login:
1517
+ `import sonar --dry-run` writes a private capture and returns its path. Preview
1518
+ that capture for the intended destination before confirming. A Cloud confirmation
1519
+ saves the issues locally and publishes them. Use `--full-output` with
1520
+ `--format json` or `--format jsonl` for a structured result.
1521
+ [Collect and replay a Sonar capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
1415
1522
 
1416
- ```sh
1417
- codex-security publish findings snyk-findings.json --to local \
1418
- --provider snyk --repository ./project \
1419
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
1420
- ```
1523
+ ## Import GitHub findings locally or to Cloud
1421
1524
 
1422
- Or preview publication to a connected Cloud repository:
1525
+ Use `--provider github` with separate source keys for
1526
+ [code scanning alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
1527
+ [Dependabot alerts](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md) and
1528
+ [security advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1529
+ Sign in with `gh` for the CLI collectors. `GH_HOST` defaults to `github.com`.
1423
1530
 
1424
- ```sh
1425
- codex-security publish findings snyk-findings.json --to cloud \
1426
- --provider snyk --repository https://github.com/example/project \
1427
- --source-key github.com/example/project/main/root/plugin-sca --dry-run
1428
- ```
1429
-
1430
- Check the collection's scan outcomes and limitations. Only Open Source SCA
1431
- vulnerabilities are imported; other products and licenses are explicit exclusions.
1432
- The importer retains the selected finding, native MCP record and collection
1433
- context. MCP may shorten descriptions and omit dependency paths. Plugin paths
1434
- remain in original evidence because v1 lacks their offset from the Git root.
1435
-
1436
- For automation, prefer native JSON from
1437
- `snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
1438
- stop on other nonzero exits before importing. The existing `--provider snyk`
1439
- autodetects a single project object or an `--all-projects` array; any project error
1440
- stops the import. Use default ungrouped output, without `--group-issues`.
1441
- Native JSON preserves individual dependency paths and remediation fields. Its
1442
- paths remain original evidence because it does not establish their Git-root offset.
1443
-
1444
- Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
1445
- for compatibility. Its target-relative manifest paths and synthetic line numbers
1446
- remain original evidence, without being projected as repository locations or
1447
- package manifest paths. All three formats accept either destination. Use a consistent
1448
- format and stable source key per repository, branch and scan target, for example
1449
- `github.com/example/project/main/root/native-sca` for native JSON. Their source
1450
- identities differ: use separate keys when switching acquisition formats. Imports
1451
- do not deduplicate across formats or remove earlier imported records.
1452
-
1453
- Known repository claims must
1454
- match the selected Cloud repository or, when available, a configured local Git
1455
- remote. Unknown repository context still requires selecting the correct target;
1456
- the importer does not infer provenance from the current checkout.
1457
-
1458
- Remove `--dry-run` from the selected command to review and confirm the import, or
1459
- use `--yes` after reviewing the preview. Read local records with
1460
- `codex-security findings imported ./project --format json`. Imported source
1461
- evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
1462
- [Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
1463
- acquisition details.
1531
+ ### Import GHSA advisories separately
1464
1532
 
1465
- ### Import Wiz findings
1533
+ Use `import github-advisories OWNER/REPO` for published repository advisories
1534
+ or add `--github-advisory-source global` and one or more `--github-advisory`
1535
+ IDs to collect global advisories. Check the installed dependency against each
1536
+ affected range. [Advisory selection and SDK examples](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md).
1466
1537
 
1467
- Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
1468
- and IaC findings without creating a scan. Imported records retain vendor evidence
1469
- and remain **not assessed by Codex**, including when Wiz marks them resolved or
1470
- reports an AI verdict. Workload secrets, cloud configuration findings, and external
1471
- network findings are not supported by this repository importer. Cloud destinations
1472
- currently support connected GitHub and GitHub Enterprise repositories, including
1473
- custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
1474
-
1475
- #### Select findings and a destination
1476
-
1477
- Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
1478
- connection to acquire findings and save the supported native JSON. A configured
1479
- plugin may provide that connection; an official Codex plugin is not a prerequisite.
1480
- The publisher reads the saved records. It does not fetch from Wiz or require a
1481
- manual website download. The acquisition path still needs validation against
1482
- actual responses from an authorized Wiz tenant; local parser checks do not
1483
- establish that qualification.
1484
-
1485
- Inspect the connection's actual response before importing it. MCP summaries,
1486
- Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
1487
- this finding mapper. Keep the original occurrence IDs and evidence; use the
1488
- named collections below when the response contains repository findings.
1489
-
1490
- Before the first import:
1491
-
1492
- 1. Select an existing repository in Codex Security Cloud and copy its URL or
1493
- Cloud repository ID. The repository needs an
1494
- authorized environment, but does not need a completed native scan.
1495
- 2. Read the selected records through the authorized connection and save their
1496
- JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
1497
- `vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
1498
- package, image, and source metadata. For SAST, repository secrets, and IaC,
1499
- retain the named API collections and repository metadata described below.
1500
- Complete the selected pages before importing; a summary or unfinished page
1501
- is not a complete finding selection.
1502
- 3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
1503
- for that Wiz tenant and finding class across exports. Do not create a new key
1504
- for each project filter or import; that creates different source identities.
1505
- 4. Check the ChatGPT account used by your existing file-backed Codex Security
1506
- login. API-key-only and keyring-only logins are not supported for Cloud
1507
- publication. See the credential-storage instructions below.
1508
-
1509
- Prefer the supported native JSON. Existing package-vulnerability CSV reports are
1510
- accepted as a compatibility input. **CSV support covers repository package
1511
- vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
1512
- Wiz code-to-cloud coverage.** The named JSON readers described below handle their
1513
- respective finding families separately.
1514
-
1515
- When a UI report is needed, retain the repository and finding filters in Wiz
1516
- **Vulnerability Findings**, choose **Save as → Report**, select **Repository
1517
- Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
1518
- report. CSV must use the columns described below and a comma delimiter. Plain and
1519
- gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
1520
- filename extension. **Raw Event** on Code & Build Scans contains scan metadata
1521
- rather than findings.
1522
-
1523
- #### Configure an alternate Cloud deployment
1524
-
1525
- For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
1526
- API root before previewing or uploading, for example
1527
- `https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
1528
- HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
1529
- `::1`). Use a login issued by that deployment and an isolated
1530
- `CODEX_SECURITY_STATE_DIR` for testing. The endpoint
1531
- does not change your login or sign you into another deployment. An invalid or
1532
- empty configured URL stops the import before authentication or network requests.
1533
- With the variable unset, the existing production endpoint remains the default.
1534
- The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
1535
- publication endpoint; it does not route vendor imports.
1536
-
1537
- If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
1538
- to the full Cloud app URL shown in the browser. The import handoff supplies both
1539
- deployment settings. The preview and result include a repository-specific
1540
- `cloudUrl`, and terminal completion prints the link. This setting only controls
1541
- the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
1542
- For custom API destinations without a configured app URL, completion retains
1543
- the manual navigation guidance rather than guessing a UI host or port.
1544
-
1545
- #### Preview and publish
1546
-
1547
- Preview the selection and destination:
1538
+ ## Import alerts from the CLI
1548
1539
 
1549
- ```bash
1550
- codex-security publish findings selected-wiz.json \
1551
- --to cloud --repository https://github.com/example/project --provider wiz \
1552
- --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1553
- ```
1554
-
1555
- `--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
1556
- destination and resume the same saved submission. This command reads the
1557
- authorized destination and current source versions during
1558
- preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
1559
- repository needs an existing environment; no native scan is required. Review the
1560
- Cloud API endpoint, account, repository, environments, findings, and exclusions,
1561
- then rerun without
1562
- `--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
1563
- reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
1564
- occurs. Existing source findings keep their Cloud environment; new findings use
1565
- the repository’s current authorized default. Preview shows the environments that
1566
- will receive the selected findings. The terminal preview summarizes severities,
1567
- shows up to five finding IDs and titles, and identifies the evidence file and
1568
- exclusions. `--dry-run --format json` retains all normalized findings and complete
1569
- evidence for inspection. A prompt explicitly includes any records that will be
1570
- skipped.
1571
-
1572
- #### Package vulnerability inputs
1573
-
1574
- Native package input can be a Wiz JSON vulnerability report, a vulnerability
1575
- finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1576
- with one package record per line. The repository package-vulnerability CSV
1577
- profile below is also supported. Plain and gzip-compressed files are accepted.
1578
- A response that advertises another page is rejected. Complete the requested pages
1579
- or save only the explicitly selected records; retain the named collection for
1580
- SAST, repository secrets, and IaC.
1581
-
1582
- The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
1583
- `CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
1584
- this profile; other Wiz report types use different fields.
1585
- For repository imports, `CloudPlatform` must identify GitHub and
1586
- `CloudProviderURL` must identify a repository branch. The repository URL must
1587
- match the selected Cloud repository or, for local import, one of the checkout's
1588
- Git remotes when configured. This also applies when the parsed findings are saved and
1589
- read again as normalized JSONL. Other resource types are excluded.
1590
-
1591
- CSV imports use `ID` as the occurrence identity and retain every parsed field,
1592
- including unknown columns and quoted multiline values, in `source_data.row`.
1593
- Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
1594
- Vendor resolution status stays in the original evidence. The importer does not
1595
- derive a branch or revision from a tree URL, or treat last-detected time as a
1596
- record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
1597
- and duplicate occurrence IDs among otherwise importable records stop the import.
1598
- Review any excluded records in the preview before publishing.
1599
-
1600
- Normalized JSONL is also accepted:
1540
+ Collect open code-scanning alerts on the default branch and save the complete
1541
+ array outside the checkout. Use a private temporary directory and run
1542
+ validation from the matching checkout. Validation sends the evidence to your
1543
+ configured model provider.
1601
1544
 
1602
- ```json
1603
- {
1604
- "source_finding_id": "vendor-finding-42",
1605
- "evidence": {
1606
- "title": "Vulnerable example package",
1607
- "severity": "high",
1608
- "source_data": { "id": "vendor-finding-42" }
1609
- }
1610
- }
1545
+ ```sh
1546
+ out=$(mktemp -d) &&
1547
+ codex-security import github OWNER/REPO --format json > "$out/alerts.json" &&
1548
+ codex-security validate "$out/alerts.json"
1611
1549
  ```
1612
1550
 
1613
- Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
1614
- exports; a selected project filter does not change the vendor namespace. Confirm
1615
- that the selected assets or builds map to this repository. The raw Wiz adapter
1616
- retains each record in `source_data`, uses reported severity, and leaves unknown
1617
- branch/revision empty. Repository-branch findings retain their repository-relative
1618
- file paths; container and other workload paths remain vendor evidence rather than
1619
- source-code locations. It does not
1620
- fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1621
- Findings from external network scans are excluded from this package vulnerability
1622
- mapping.
1623
-
1624
- #### SAST, repository secrets, and IaC inputs
1625
-
1626
- For SAST, repository secrets, and IaC, save the documented JSON API collection:
1627
-
1628
- | Finding family | Collection | Raw occurrence identity |
1629
- | ------------------ | ---------------------------- | ----------------------- |
1630
- | SAST | `data.sastFindings.nodes` | `sast:<id>` |
1631
- | Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
1632
- | IaC | `data.iacFindings.nodes` | `iac:<id>` |
1633
-
1634
- The collection identifies the mapping. Bare arrays of these raw findings are
1635
- excluded because their overlapping fields do not identify a family. An export
1636
- may contain multiple named collections. GraphQL errors and unfinished pages stop
1637
- the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
1638
- relationship to source code does not make it a repository secret.
1639
-
1640
- Each new finding needs a verified source repository URL. Supply `repository.url`
1641
- in the finding's repository metadata, or include the matching repository inventory
1642
- in `data.versionControlResources.nodes`. For secrets, repository metadata is under
1643
- `resource.typedProperties.repository`. The importer joins the inventory's
1644
- `repository.id` to that source ID and uses `repository.url`; inventory node IDs,
1645
- `providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
1646
- must agree with the inventory and with the selected Cloud repository before any
1647
- finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
1648
- establishes case-insensitive repository matching on custom GitHub Enterprise
1649
- hosts. Fresh imports preserve the reported branch name literally. Duplicate
1650
- entries for one repository ID must agree on their platform and repository URL.
1651
- For example, this synthetic selection supplies the inventory alongside its SAST
1652
- collection:
1551
+ The collector reads alerts, including third-party SARIF uploads. It does not
1552
+ start a scan. For filters, ref selection and SDK validation, see the
1553
+ [code scanning guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md).
1653
1554
 
1654
- ```json
1655
- {
1656
- "data": {
1657
- "sastFindings": {
1658
- "nodes": [
1659
- {
1660
- "id": "finding-42",
1661
- "name": "Untrusted query construction",
1662
- "severity": "HIGH",
1663
- "repository": { "id": "source-repository-1" },
1664
- "filePath": "src/query.ts",
1665
- "startLine": 10,
1666
- "endLine": 12
1667
- }
1668
- ]
1669
- },
1670
- "versionControlResources": {
1671
- "nodes": [
1672
- {
1673
- "repository": {
1674
- "id": "source-repository-1",
1675
- "url": "https://github.com/example/project"
1676
- }
1677
- }
1678
- ]
1679
- }
1680
- }
1681
- }
1682
- ```
1555
+ ## Publish findings to Cloud
1683
1556
 
1684
- #### Preserved evidence
1685
-
1686
- The adapters preserve each selected raw node exactly in `source_data`. Typed
1687
- `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1688
- and family-specific evidence:
1689
-
1690
- | Family | Evidence retained in typed fields |
1691
- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1692
- | SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
1693
- | Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
1694
- | IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
1695
-
1696
- Vendor status and verdict remain separate from Codex assessment. A secret's
1697
- introduced commit is not its scanned revision. Missing source revisions and scan
1698
- IDs stay unknown. A logical IaC resource is retained in the original record and
1699
- does not establish that it is deployed. Precise original timestamps remain in
1700
- `source_data`; only an explicit record-update timestamp maps to the whole-second
1701
- `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1702
- timestamps.
1703
-
1704
- #### Convert CSV reports
1705
-
1706
- Native SAST and secret report downloads can be CSV, including gzip-compressed
1707
- CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1708
- for its actual column headers into normalized JSONL, preserving each original row
1709
- in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
1710
- verifying the source repository. Use the same prefixed occurrence ID shown above
1711
- so API and report imports update the same finding; normalized IDs are accepted
1712
- exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
1713
- for a vendor occurrence ID. Missing IDs or severity must be corrected at the
1714
- source rather than invented.
1715
-
1716
- For repository-secret reports, select `path` and `lineNumber` for source
1717
- navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
1718
- as the introduced commit. The standard secret metadata API does not supply a
1719
- path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
1720
- `rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
1721
- repository/branch metadata. Preserve the original fields; source locations must
1722
- be repository-relative, and an end line requires a start line. Keep credential
1723
- values out of the metadata selection; the importer does not retrieve or test
1724
- credentials or apply remediation instructions.
1725
-
1726
- Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1727
- integer range is rejected; export those values as strings to preserve them
1728
- exactly. Invalid records appear in `excluded` with their source ID and reason.
1729
-
1730
- #### Resume interrupted imports
1731
-
1732
- Requests contain at most 100 findings and respect the Cloud payload limits.
1733
- Before uploading, the publisher saves request IDs and bodies privately under
1734
- the configured Codex Security state directory. After an uncertain response,
1735
- repeat the same command with unchanged input and Cloud API endpoint to resume those
1736
- requests. Different deployments have separate saved submissions, including when
1737
- their account and repository IDs match. The preview and result include
1738
- `cloudApiUrl` so scripts can verify which API received the findings; this is an
1739
- API endpoint, not a link to the Cloud UI. A reset
1740
- retires the old request without republishing; review and explicitly approve a
1741
- fresh invocation.
1742
-
1743
- #### Results and exit codes
1744
-
1745
- Results distinguish completion from partial or interrupted work:
1746
-
1747
- | Status | Exit code | Meaning |
1748
- | ------------- | --------- | -------------------------------------------------------------------------------------------------- |
1749
- | `complete` | 0 | All selected records were acknowledged and their source records read back. |
1750
- | `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
1751
- | `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
1752
- | `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
1753
-
1754
- For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
1755
- Failed and interrupted imports set the envelope's `ok` to `false`, with
1756
- `error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
1757
- counts under `data`. Other full-output format combinations are rejected before
1758
- reading the input or contacting Cloud; omit `--full-output` to use those formats.
1759
-
1760
- Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
1761
- `receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
1762
- `unacknowledged`. A lost response can mean unacknowledged findings were accepted;
1763
- resume the saved submission rather than treating them as never uploaded. When
1764
- available, `savedSubmission` identifies the checkpoint to resume by repeating the
1765
- same command. Review `error` before retrying; a repository reset retires the old
1766
- submission and requires fresh approval. Correct local exclusions or final source
1767
- conflicts before preparing a new submission.
1768
-
1769
- Counts are cumulative for the saved submission: a resumed result includes
1770
- batches acknowledged by earlier invocations, not just the latest upload attempt.
1771
-
1772
- Terminal progress reports preparation, acknowledged uploads, and verification
1773
- on stderr; JSON results stay on stdout. Lookups and readback use at most four
1774
- concurrent requests, while uploads remain sequential. Successful receipts are
1775
- saved locally. Verification reads the imported source records and checks their
1776
- identities and evidence against the receipts. This does not establish a Codex
1777
- assessment or visibility in the shared Cloud Findings view.
1778
- When available, `cloudUrl` links to the destination repository in Cloud.
1557
+ Use `publish findings FILE` for a [saved scanner report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
1558
+ If you're collecting live issues with `import sonar`, [publish from the Sonar preview's saved capture](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md#import-and-verify).
1559
+
1560
+ ### Preview and publish
1561
+
1562
+ Set `--to cloud`. For `--repository`, use the connected GitHub or GitHub
1563
+ Enterprise repository URL or its Cloud ID. Either works for retries. If
1564
+ several connectors share the URL, use the ID. You can import before the
1565
+ repository's first native scan.
1566
+
1567
+ Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
1568
+ set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
1569
+ again with the ChatGPT account you want to use.
1570
+
1571
+ ### Review the Cloud destination
1572
+
1573
+ Run the command with `--dry-run --format json`. Check `accountId`,
1574
+ `cloudApiUrl`, `destination` and `source.source_key`. Compare `findings` and
1575
+ `excluded` with the records you meant to import.
1576
+
1577
+ - **Private findings inbox.** If the preview includes `privateImport`, the
1578
+ report goes to your inbox. The repository and connector identify the
1579
+ suggested assessment target. Check `format`, `bytes` and `sha256` in
1580
+ `privateImport` to identify the upload. For an Endor Finding, an Endor
1581
+ `list.objects` response or a Wiz vulnerability JSON export, the CLI can
1582
+ send the original bytes when Cloud accepts the format and every record
1583
+ matches your selection. Other inputs, including arrays of selected Endor
1584
+ Findings, use `security.findings.v1`.
1585
+ - **Repository publisher.** Check `repository.environment_id` in each entry
1586
+ of `requests`. The publisher checks the current source versions. Existing
1587
+ records keep their environment. New records use the repository's authorized
1588
+ default.
1589
+
1590
+ To import, run the same command without `--dry-run` and confirm. The terminal
1591
+ shows the file, exclusions, severities and up to five finding IDs and titles.
1592
+ The prompt defaults to No. For a noninteractive import, add `--yes` after
1593
+ reviewing the full JSON preview.
1594
+
1595
+ ### Configure an alternate Cloud deployment
1596
+
1597
+ Set `CODEX_SECURITY_CLOUD_BASE_URL` to the deployment's API root, such as
1598
+ `https://cloud.example.test/backend-api/aardvark`. Use a login issued by that
1599
+ deployment. Remote API roots require HTTPS. Loopback development also accepts
1600
+ HTTP on `localhost`, `127.0.0.0/8`, or `::1`. An empty or invalid setting
1601
+ stops preparation before authentication or network requests. Leaving it unset
1602
+ selects production. For testing, use an isolated `CODEX_SECURITY_STATE_DIR`.
1603
+
1604
+ For a separately hosted Cloud UI, set `CODEX_SECURITY_CLOUD_WEB_URL` to the
1605
+ full app URL. The preview and result can then supply a repository-specific
1606
+ `cloudUrl`. With a custom API and no web URL, the CLI prints navigation
1607
+ instructions. API requests always use the API root. The older
1608
+ `CODEX_SECURITY_CLOUD_PUBLISH_URL` setting applies only to native scan publishing.
1609
+
1610
+ ### Resume interrupted imports
1611
+
1612
+ If the result includes `savedSubmission`, keep that checkpoint. Rerun the
1613
+ original command with `--dry-run --format json` using the same input, account,
1614
+ destination, API endpoint and state directory. Check `cloudApiUrl`. If
1615
+ `resumed` is true, confirm to continue the saved submission. If it's false,
1616
+ review the new submission before confirming.
1617
+
1618
+ - **Private inbox.** The CLI checks the report digest and reuses its saved
1619
+ request IDs. It can read an accepted job even if the deployment has since
1620
+ disabled uploads. After an inbox reset, check the new report format, size
1621
+ and digest before confirming.
1622
+ - **Repository publisher.** The CLI saves each request privately before
1623
+ sending up to 100 findings. Retries use the same publisher, request IDs and
1624
+ bodies. If the repository has been reset, preview and confirm a fresh
1625
+ submission.
1626
+
1627
+ [Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
1628
+
1629
+ ### Results and exit codes
1630
+
1631
+ | Status | Exit code | Meaning |
1632
+ | ------------- | --------- | -------------------------------------------------------------------------------------- |
1633
+ | `empty` | 0 | No records were available to upload. |
1634
+ | `complete` | 0 | The inbox job processed every record successfully, or the publisher verified each one. |
1635
+ | `partial` | 1 | The import had exclusions or record errors, or the inbox job failed or was cancelled. |
1636
+ | `interrupted` | 2 | The CLI stopped while uploading, checking the result or saving a receipt. |
1637
+ | `failed` | 2 | Preparation failed before upload. |
1638
+
1639
+ A clean empty report needs no confirmation. Self-contained file imports can
1640
+ finish before Cloud sign-in; Semgrep Platform and Snyk REST captures use the
1641
+ Cloud catalog to verify their repository. Local imports still validate the
1642
+ checkout and create no workbench database. Explicit scanner errors
1643
+ and selections containing only excluded records fail; JSON output retains their
1644
+ diagnostics and exclusion reasons. Existing findings stay open.
1645
+
1646
+ For automation, check the scanner's exit status as well as the import's. SARIF
1647
+ can contain no runs or omit results in a rules-only export. `empty` describes
1648
+ the selected report, not whether a scan completed successfully.
1649
+
1650
+ For a partial or interrupted import, check `excluded` and any `error` before
1651
+ retrying. Some records may already have reached Cloud.
1652
+
1653
+ - **Private inbox.** In `privateJob`, check the job `status`, `counts.error`
1654
+ and `counts.unprocessed`. The receipt also identifies the job (`id`) and the
1655
+ uploaded file (`input.file_id`). The CLI reads the job receipt, so a
1656
+ successful import can show `verified: 0`. To share a finding, open it in
1657
+ your inbox, assess it against a pinned repository revision and publish the
1658
+ reportable assessment.
1659
+ - **Repository publisher.** `verified` counts records whose identity the CLI
1660
+ confirmed by reading them back. If the version matches the receipt, the CLI
1661
+ also checks the evidence. A newer version can have different evidence and
1662
+ still count as verified. `unacknowledged` counts records awaiting a receipt,
1663
+ including records Cloud accepted if the response was lost. Use `client_id`
1664
+ to match a receipt item to its request and `source_finding_id` in `failures`
1665
+ to find a failed vendor record. Counts include earlier batches with receipts.
1666
+ When present, `cloudUrl` opens the repository. Assessment and sharing are
1667
+ separate steps.
1668
+
1669
+ With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
1670
+ Failed and interrupted imports set `ok` to `false` and `error.code` to
1671
+ `IMPORT_FAILED`. Available results, receipts, and counts remain under `data`.
1672
+ Other formats reject `--full-output` before reading the file or contacting
1673
+ Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
1674
+
1675
+ Progress goes to stderr and JSON results to stdout. The repository publisher
1676
+ uploads sequentially and uses up to four concurrent requests for lookups and
1677
+ readback.
1678
+
1679
+ ### Import Snyk findings
1680
+
1681
+ Use `--provider snyk` for native Open Source JSON, plugin exports, SARIF or
1682
+ monitored Open Source and Code issues. The [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md)
1683
+ covers saved files, distinct source keys for each format, and collection with
1684
+ `import snyk`.
1685
+
1686
+ ### Import Wiz findings
1687
+
1688
+ <a id="select-findings-and-a-destination"></a>
1689
+ <a id="package-vulnerability-inputs"></a>
1690
+ <a id="sast-repository-secrets-and-iac-inputs"></a>
1691
+ <a id="preserved-evidence"></a>
1692
+ <a id="convert-csv-reports"></a>
1693
+
1694
+ Use `--provider wiz` for a [saved Wiz report](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#quick-start).
1695
+ The provider guide describes [package JSON and CSV](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#package-vulnerability-inputs),
1696
+ [named SAST, secret and IaC collections](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#sast-repository-secrets-and-iac-inputs),
1697
+ [retained evidence](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#preserved-evidence) and
1698
+ [conversion to normalized JSONL](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md#convert-csv-reports).
1779
1699
 
1780
1700
  ### Publish completed scans
1781
1701
 
@@ -1854,15 +1774,16 @@ Choose a destination authorized to receive that content. Local history records
1854
1774
  successful issue IDs separately from sealed artifacts. The CLI and the plugin's
1855
1775
  finding-tracking workflow share these records when using the same Codex Security
1856
1776
  state directory. Accepted writes remain recorded even if a later issue read fails.
1857
- The shared-history migration preserves existing Linear receipts and replaces their
1858
- old table. Upgrade CLI and plugin installations together when they share state;
1859
- older publishers cannot write to the migrated database.
1860
1777
 
1861
- Republishing creates duplicates unless `--skip-existing` finds a recorded success
1862
- for that occurrence, team, and project, including issues created or reused through
1863
- the plugin. It does not check remote issues or cover
1864
- unrecorded/concurrent publication. After interruption, inspect the handoff,
1865
- evidence, and destination before retrying.
1778
+ By default, publishing the same scan again creates new issues. With
1779
+ `--skip-existing`, the CLI skips occurrences with a recorded success for the
1780
+ same team and project. This includes issues the plugin created or reused.
1781
+ The CLI checks local history only. After an interrupted or concurrent run,
1782
+ check Linear for an existing issue before retrying.
1783
+
1784
+ If the CLI and plugin share a database from an older installation, upgrade
1785
+ both together. The shared history preserves existing Linear receipts, but
1786
+ publishers that require the old table can no longer record new ones.
1866
1787
 
1867
1788
  ```ts
1868
1789
  import { publishScan } from "@openai/codex-security";
@@ -1892,12 +1813,19 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
1892
1813
  report snapshots and delegates model execution to the host.
1893
1814
 
1894
1815
  For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1895
- Omitting `--rubric` runs classification with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/sdk/typescript/src/default-severity-rubric.ts).
1816
+ By default, saved findings are classified with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/plugins/codex-security/references/default-severity-rubric.md).
1896
1817
  It evaluates attacker access, boundary crossing, additional harm, and evidence for
1897
1818
  Critical, High, Medium, Low, and Informational findings. Confidence remains separate
1898
- from severity; missing proof alone does not justify a downgrade. An explicit
1899
- `--rubric` replaces the default policy completely. Rubrics and repeatable
1900
- `--knowledge-base` context accept text, PDF, DOCX, and directories.
1819
+ from severity; missing proof alone does not justify a downgrade.
1820
+
1821
+ Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the current default
1822
+ from Statsig once per reclassification. Only the exact value `1` enables the
1823
+ request. It sends the config name without findings or account identifiers.
1824
+ If the request fails, times out, or returns an invalid rubric, the built-in
1825
+ rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
1826
+ uses your policy for every review. Rubrics and repeatable `--knowledge-base`
1827
+ context accept text, PDF, DOCX, and directories.
1828
+
1901
1829
  Each finding is classified three times by default. `--runs N` accepts
1902
1830
  an integer from 1 through 10; SDK options use `classificationRuns` with the same
1903
1831
  default and bounds. Each review runs in an independent read-only turn using the
@@ -1918,6 +1846,12 @@ the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
1918
1846
  missing facts that could change the result. Exclusions have a null level.
1919
1847
  Finding/occurrence IDs and input hashes bind each assessment to its evidence.
1920
1848
 
1849
+ For a single rubric document, the classification result reports the SHA-256 of
1850
+ the exact UTF-8 text supplied to the reviewer in `rubricSha256`. For multiple
1851
+ documents it reports the digest of the ordered text collection. A bundled or
1852
+ remote default also records its `rubricRevision`. Older saved results retain
1853
+ their original digest and may omit the revision.
1854
+
1921
1855
  Successful assessments checkpoint immediately in local SQLite. Retries reuse
1922
1856
  matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
1923
1857
  work. Default-rubric assessments use `source: "rubric"` and a content hash; former
@@ -2001,7 +1935,7 @@ await publishScan(scanDirectory, {
2001
1935
 
2002
1936
  `classifySeverity()` accepts `findingId`, `title`, `summary`, and available
2003
1937
  evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
2004
- `rubricPath` uses the built-in policy even when a scanner severity is present.
1938
+ `rubricPath` uses the selected default policy even when a scanner severity is present.
2005
1939
  Scan wrappers persist checkpoints (including for
2006
1940
  external directories), accept `reprocess: true`, and treat `findingIds: []` as an
2007
1941
  empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
@@ -2136,9 +2070,21 @@ history. Inspect its saved status before choosing resume or rerun, and supply
2136
2070
  the original custom prompt files for reruns. Structured history and log output
2137
2071
  and command selection defaults are unchanged.
2138
2072
 
2139
- Recipes save settings and authentication choice, not credentials. Reruns use the
2140
- current checkout/context files and do not reload project files. Supply replacement
2141
- scan and custom-validation prompts when the original used them:
2073
+ Reruns use the current checkout/context files and do not reload project files.
2074
+ The readable scan recipe records your authentication choice. A separate private
2075
+ replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
2076
+ `model_providers` settings, including any credentials written directly in
2077
+ `http_headers`. If you use `env_key` or `env_http_headers`, the profile stores
2078
+ the variable names. Set those variables when you rerun or resume. Settings
2079
+ inherited from a named file profile are reloaded from that file. If an older
2080
+ scan omitted your endpoint, start a new scan with the original `--codex` override.
2081
+
2082
+ When routing through environment variables, set them for each launch, including
2083
+ rerun and resume. Deep workers inherit `CODEX_OSS_BASE_URL` and `CODEX_OSS_PORT`
2084
+ for Ollama and LM Studio, and `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`,
2085
+ and `GOOGLE_APPLICATION_CREDENTIALS` for Vertex AI.
2086
+
2087
+ Supply replacement scan and custom-validation prompts when the original used them:
2142
2088
 
2143
2089
  ```bash
2144
2090
  codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
@@ -2160,11 +2106,16 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
2160
2106
  writable, and outside the target repository. Session logs may contain sensitive
2161
2107
  data even though scan recipes do not store credentials.
2162
2108
 
2163
- Codex may compress saved session logs to `.jsonl.zst`. Reading those logs requires
2164
- Node.js 22.15.0+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14,
2165
- compressed sessions are unavailable to `scans logs`, feedback attachments, and
2166
- `scans resume`. Upgrade Node.js to read or resume these sessions. Plain `.jsonl`
2167
- logs work on all supported runtimes.
2109
+ Saved scan logs retain the finishing turn, including its final response, and
2110
+ exclude later turns once the scan records a completion boundary. Older scans
2111
+ retain the full history of their attributed sessions and keep their existing
2112
+ worker-selection boundaries. This also applies to logs attached with
2113
+ `feedback --include-logs`.
2114
+
2115
+ Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
2116
+ work on all supported Node.js versions, including logs, feedback attachments,
2117
+ usage accounting, and saved-session discovery for resume. A bundled decoder
2118
+ reads concatenated frames and reports truncated streams as collection errors.
2168
2119
 
2169
2120
  ### Resuming an interrupted Deep Scan
2170
2121
 
@@ -2207,6 +2158,13 @@ One comparison ID is compared with the latest completed scan.
2207
2158
  codex-security scans match --all --force --model gpt-6.1-sol --effort high
2208
2159
  ```
2209
2160
 
2161
+ When a saved Standard scan and a Deep scan have the same recorded target,
2162
+ revision, and snapshot digest, matching flags findings that have different
2163
+ anchors but share a unique rule, first displayed source range, and optional
2164
+ instance. Matching preserves the case of saved paths. Codex can request the
2165
+ saved evidence to distinguish separate causes at that site. Automatic matching
2166
+ under a cost limit keeps its single comparison call.
2167
+
2210
2168
  Only high-confidence root-cause matches are grouped. Uncertain and related
2211
2169
  findings remain separate. Rebuilding retains stable identities, triage, and
2212
2170
  sealed artifacts; interruption preserves completed comparisons. Model/effort
@@ -2310,7 +2268,8 @@ marks shortened text. Other template columns keep their original values.
2310
2268
 
2311
2269
  The output defaults to `servicenow-avit.csv`. Upload the completed file in the
2312
2270
  same ServiceNow screen. Each upload creates a new penetration-test form for the
2313
- application. See [ServiceNow's upload instructions](https://www.servicenow.com/docs/r/security-management/application-vulnerability-response/ingest-vulnerabilities-manually-avr.html).
2271
+ application. If the submission result is unclear, check its status and log notes
2272
+ on the Vulnerability Integration Push Queues page before uploading again. See [ServiceNow's upload instructions](https://www.servicenow.com/docs/r/security-management/application-vulnerability-response/ingest-vulnerabilities-manually-avr.html).
2314
2273
 
2315
2274
  ### Export a threat model
2316
2275
 
@@ -2403,9 +2362,11 @@ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/exa
2403
2362
 
2404
2363
  ### Local pre-commit checks
2405
2364
 
2406
- `install-hook` checks staged and unstaged changes, blocking the commit on scan
2407
- failure or findings at/above its threshold (`high` by default). Use required CI
2408
- for enforcement; local hooks are optional.
2365
+ The generated hook runs a `--working-tree` scan and blocks the commit on scan
2366
+ failure or findings at or above its threshold (`high` by default). It uses the
2367
+ checkout's normal index for staged and unstaged changes, so it can include changes
2368
+ outside a partial commit and miss content staged only in a separate index.
2369
+ Use required CI for enforcement because local hooks are optional.
2409
2370
 
2410
2371
  Install the CLI outside the target repository and run that copy directly. `npx`
2411
2372
  can select a repository-local package. Before installation, inspect:
@@ -2423,222 +2384,13 @@ codex-security install-hook /path/to/repository
2423
2384
  ```
2424
2385
 
2425
2386
  To migrate an existing generated hook, verify it is a regular file used only by
2426
- this repository and contains only the generated command. Preserve its severity.
2427
- The installer can update older `npx` hooks when the severity matches. New hooks
2428
- record absolute Node/CLI paths. If those change, back up and remove the verified
2429
- generated hook, then reinstall with the same threshold. Restore the backup if
2430
- installation fails. The installer respects `core.hooksPath`.
2431
-
2432
- ## Import GitHub findings locally or to Cloud
2433
-
2434
- Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
2435
- The existing alert collector remains available without it.
2436
-
2437
- Acquire code-scanning findings with the existing `import github` collector and
2438
- save its complete JSON output. In Codex, the official
2439
- [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
2440
- can help select the repository, alert numbers and ref through GitHub's MCP
2441
- server. Pass that selection to the collector. For Dependabot, use a token with
2442
- **Dependabot alerts: read** and follow
2443
- the [repository alert export guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md)
2444
- to save the native REST records from one repository and preview them with
2445
- `--provider github`. For GHSA disclosures, use the
2446
- [advisory collector](#import-ghsa-advisories-separately).
2447
- The following example previews local storage of a code-scanning export.
2448
-
2449
- ```bash
2450
- codex-security import github example/project --format json > /path/outside/repository/alerts.json
2451
- codex-security publish findings /path/outside/repository/alerts.json \
2452
- --to local --provider github --repository ./project \
2453
- --source-key github.com/example/project/code-scanning --dry-run --format json
2454
- ```
2455
-
2456
- Or preview publication to a connected Cloud repository:
2457
-
2458
- ```bash
2459
- codex-security publish findings /path/outside/repository/alerts.json \
2460
- --to cloud --provider github --repository https://github.com/example/project \
2461
- --source-key github.com/example/project/code-scanning --dry-run --format json
2462
- ```
2463
-
2464
- The importer fetches every page, retrieves alert details, and retains the selected
2465
- ref's instance. It writes the saved input for publication; no website download or
2466
- hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
2467
- selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
2468
- the default branch. MCP list calls are paginated separately. Code-scanning
2469
- imports require the saved collector output, which includes the selected instance.
2470
-
2471
- The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
2472
- the plugin's connection does not sign in `gh`. Reading code-scanning alerts requires
2473
- [code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
2474
- **Code scanning alerts: read** for a fine-grained token, or `security_events` for
2475
- a classic token (`public_repo` is sufficient for public repositories). The source
2476
- repository must have code scanning available. For Cloud publication, the
2477
- destination must be connected in the selected Cloud account. For local import,
2478
- the source repository must match a configured Git remote when remotes are
2479
- available; no Cloud login is required to store the acquired evidence.
2480
-
2481
- Review the destination, source, exclusions and evidence in the preview. Repeat the
2482
- selected command without `--dry-run` and confirm it, or add `--yes` for a
2483
- previously reviewed input. Local persistence and readback follow the
2484
- [local import flow](#import-vendor-findings-locally); use
2485
- `codex-security findings imported ./project --format json` to read the records.
2486
- Cloud authentication, batching, saved receipts, partial results and
2487
- interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
2488
- JSON, JSONL and gzip are supported. Save complete import output without field or
2489
- token filters or `--full-output`.
2490
-
2491
- Use a stable source key for the GitHub host, repository and finding family.
2492
- Code-scanning identities include the selected ref, so branches retain separate
2493
- evidence. The original alert, rule, scanner, location, revision and source state
2494
- remain attached. An alert-wide dismissal takes precedence over the selected
2495
- instance's open/fixed state. Missing security severity stays `unknown`;
2496
- SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
2497
- remains unassessed by Codex.
2498
-
2499
- The SDK offers the same preview and publication boundary for Cloud:
2500
-
2501
- ```ts
2502
- import {
2503
- importGitHubCodeScanningAlerts,
2504
- normalizeGitHubCodeScanningAlerts,
2505
- prepareNormalizedExternalPublication,
2506
- } from "@openai/codex-security";
2507
-
2508
- const alerts = await importGitHubCodeScanningAlerts({
2509
- repository: "example/project",
2510
- });
2511
- const prepared = await prepareNormalizedExternalPublication(
2512
- normalizeGitHubCodeScanningAlerts(alerts),
2513
- {
2514
- provider: "github",
2515
- repository: "https://github.com/example/project",
2516
- sourceKey: "github.com/example/project/code-scanning",
2517
- },
2518
- );
2519
- console.log(prepared.preview);
2520
- // After reviewing the preview:
2521
- const receipt = await prepared.publish();
2522
- ```
2523
-
2524
- For local storage, pass the same normalized evidence to
2525
- `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
2526
- its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
2527
- import file directly. Read records with `listLocalExternalFindings({ repository })`.
2528
-
2529
- ### Import GHSA advisories separately
2530
-
2531
- Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
2532
-
2533
- **Importing a GHSA advisory does not establish an installed dependency or
2534
- applicability to the destination repository.** Repository advisories are
2535
- disclosures maintained by a repository; global advisories describe affected
2536
- software in GitHub's public advisory database. Both are evidence for
2537
- investigation, not Dependabot alerts. Check the repository’s dependency versions
2538
- and applicability separately.
2539
-
2540
- ```bash
2541
- # Read only published advisories for this repository.
2542
- codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
2543
-
2544
- # Select individual public database records without enumerating the database.
2545
- codex-security import github-advisories example/project \
2546
- --github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
2547
- --format json > /path/outside/repository/advisories.json
2548
-
2549
- codex-security publish findings /path/outside/repository/advisories.json \
2550
- --to cloud --provider github --repository https://github.com/example/project \
2551
- --source-key github.com/example/project/security-advisories --dry-run --format json
2552
- ```
2553
-
2554
- For local storage, use the same advisory file, provider and source key with
2555
- `--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
2556
- to review, confirm and read the stored evidence.
2557
-
2558
- `--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
2559
- to select exact IDs from that API, regardless of advisory state. Repository
2560
- lists default to `--github-state published`; `draft`, `triage`, and `closed`
2561
- require explicit selection. A nondefault state cannot be combined with exact
2562
- IDs. Global selection requires at least one ID and never lists the advisory
2563
- database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
2564
- the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
2565
- [repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
2566
- require **Repository security advisories: read**, or the classic `repo` or
2567
- `repository_advisories:read` scope, plus access to the advisory. Public records
2568
- need no additional advisory permission.
2569
-
2570
- Review the saved evidence before local import or Cloud publication, including any
2571
- selected private advisories. Acquisition failure returns no partial selection.
2572
- Both destinations report invalid records as exclusions. Cloud publication retains
2573
- acknowledged receipts if a later batch or readback fails.
2574
-
2575
- Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
2576
- patched versions, source status and original JSON. It does not infer an installed
2577
- version or source location. Global advisories omit a source repository; the
2578
- explicit local or Cloud destination binds the import for investigation. Repository
2579
- advisories retain their source repository and check it against the Cloud target
2580
- or configured local Git remotes when available. Withdrawal remains vendor
2581
- state, and all imported evidence remains not assessed by Codex. Use a separate
2582
- source key from code-scanning alerts; shared advisory IDs do not combine source
2583
- records from different providers.
2584
-
2585
- In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
2586
- with `prepareNormalizedExternalPublication()` for Cloud or
2587
- `prepareNormalizedLocalImport()` for local storage as described above.
2588
- `importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
2589
- `{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
2590
- records. Both forms require `repository: "OWNER/REPO"` as source or target context.
2591
-
2592
- ## Import alerts from the CLI
2593
-
2594
- ```bash
2595
- codex-security import github example/repository --format json > /path/outside/repository/alerts.json
2596
- codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
2597
- codex-security validate /path/outside/repository/alerts.json
2598
- ```
2599
-
2600
- Run validation from the matching local repository. Import defaults to open alerts
2601
- on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
2602
- `--github-ref REF` to filter. Exact alert numbers ignore state and reject a
2603
- nondefault state.
2604
-
2605
- Import is read-only and returns an array. Save validation inputs without output
2606
- filters or token limits. It includes third-party SARIF uploads, does not start
2607
- Codex, and does not check out code. Each record contains `source`, `repository`,
2608
- `number`, `url`, and the full upstream `alert`.
2609
-
2610
- For a disposition per alert, import and validate through the SDK:
2611
-
2612
- ```ts
2613
- import {
2614
- CodexSecurity,
2615
- importGitHubCodeScanningAlerts,
2616
- } from "@openai/codex-security";
2617
-
2618
- const findings = await importGitHubCodeScanningAlerts({
2619
- repository: "example/repository",
2620
- alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
2621
- githubToken: process.env["GH_TOKEN"],
2622
- });
2623
-
2624
- const security = new CodexSecurity();
2625
- try {
2626
- for (const finding of findings) {
2627
- const result = await security.validate({
2628
- repositoryPath: "/path/to/repository",
2629
- finding,
2630
- });
2631
- console.log(finding.url, result.disposition, result.outputDir);
2632
- }
2633
- } finally {
2634
- await security.close();
2635
- }
2636
- ```
2637
-
2638
- SDK options include `state` (default `"open"`), `ref`, and `signal`.
2639
- Supply `githubToken` or use `gh auth token` credentials, including GitHub CLI
2640
- token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
2641
- The token needs code-scanning read access; access failures reject the import.
2387
+ this repository and contains only the generated commands. Rerun `install-hook`
2388
+ with `--fail-on-severity` set to its original threshold. It recognizes the legacy
2389
+ `npx` hook and supported earlier templates with matching absolute Node and CLI
2390
+ paths. If it refuses to overwrite the verified hook, back it up, remove it and
2391
+ reinstall with the same threshold. Restore the backup if installation fails.
2392
+ The installer uses host Git for the selected repository and respects
2393
+ `core.hooksPath`.
2642
2394
 
2643
2395
  ## Validate and patch findings
2644
2396
 
@@ -2646,12 +2398,12 @@ Hosts that manage their own model execution can use `codex-security validate --r
2646
2398
  This mode exchanges a review over JSON-RPC and checks the returned answer against a caller-provided schema.
2647
2399
  See [host-provided standalone validation](validate-records.md) for the protocol and execution requirements.
2648
2400
 
2649
- `validate` assesses candidates from local source evidence without building the
2650
- target, executing application code, running tests or PoCs, or contacting services.
2651
- It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
2652
- validation, and `patch` still fixes and verifies findings. Both commands accept files
2653
- or literal text and work in the current directory. Saved finding/occurrence IDs
2654
- select their original repository for patching.
2401
+ `validate` sends the finding to your configured model provider. Its review
2402
+ tools can read the checkout, with network access and web search disabled.
2403
+ The assessment uses source evidence and skips builds, tests, PoCs and application
2404
+ execution. Both `validate` and `patch` accept files or literal text in the
2405
+ current directory. Patching by saved finding or occurrence ID selects the
2406
+ original repository.
2655
2407
 
2656
2408
  Basic patching also works in ordinary directories and Git worktrees before their
2657
2409
  first commit. Directory change tracking excludes `.git` and `.svn` metadata.
@@ -2684,13 +2436,16 @@ native structured output. The CLI also checks the completed JSON before writing
2684
2436
  stdout; it does not convert a prose assessment into JSON afterward. Invalid JSON
2685
2437
  or a schema mismatch fails with exit code 2 and no assessment on stdout.
2686
2438
 
2439
+ Save the output schema as UTF-8 without a byte-order mark so both the CLI and
2440
+ Codex can read it.
2441
+
2687
2442
  Use a self-contained schema in the subset supported by the selected Codex model
2688
2443
  and provider. The local checker uses JSON Schema 2020-12, but accepting a schema
2689
2444
  locally does not guarantee provider support. Keep the schema small and use it only
2690
2445
  when the caller needs structured results. It checks the result's shape, not whether
2691
2446
  the security conclusion is correct. Relative paths resolve from the current directory.
2692
2447
 
2693
- The validator no longer writes reports. Save the assessment by redirecting stdout:
2448
+ Save the assessment by redirecting stdout:
2694
2449
  `codex-security validate findings.json > assessment.md`. For runtime proof, run a
2695
2450
  separate reproduction step. Missing facts are reported as proof gaps; a finding
2696
2451
  supported by source evidence does not require runtime reproduction.
@@ -2752,7 +2507,9 @@ codex-security validate findings.json --output-schema result.schema.json > asses
2752
2507
 
2753
2508
  An illustrative result is below. Actual decisions depend on the repository;
2754
2509
  this example assumes a tenant filter exists but deployment routing is unavailable.
2755
- Both candidate IDs remain in the output, including the unresolved claim.
2510
+ Before updating finding records, [check that each input ID appears exactly
2511
+ once](validate-records.md#check-the-returned-ids), including unresolved
2512
+ candidates.
2756
2513
 
2757
2514
  ```json
2758
2515
  {
@@ -2840,8 +2597,13 @@ including code, HTML, and math, retain their original text.
2840
2597
  GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
2841
2598
  ```
2842
2599
 
2843
- Both providers return `pullRequest: { branch, url }`. Supplied-issue patching
2844
- requires a clean tree. If publication fails, run the printed
2600
+ Both providers return `pullRequest: { branch, url }`. Saved-finding publication
2601
+ includes files changed and verified in the same patch turn. If a selected file
2602
+ already had local edits, the CLI keeps the patch in the working tree for review.
2603
+ The risk assessment and commit use the same verified tree. If staging changed
2604
+ during the run and Git cannot update the index, the CLI reports it and keeps
2605
+ the existing staging.
2606
+ Supplied-issue patching requires a clean tree. If publication fails, run the printed
2845
2607
  `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
2846
2608
  commit and refuses changed branches. Retain the GitLab host setting on resume.
2847
2609
 
@@ -2862,23 +2624,41 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
2862
2624
  finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
2863
2625
  filter for completed Linear issues to check a finished backlog.
2864
2626
 
2627
+ The CLI selects findings from the workbench and loads their evidence from the
2628
+ saved scan artifacts. It measures the verification request with that evidence
2629
+ included. Large selections use multiple requests without splitting or further
2630
+ truncating any selected finding. The CLI prints verdicts in selection order
2631
+ after every request returns valid results. For these selections the CLI omits
2632
+ per-event progress and update notices so stderr cannot delay the verdicts.
2633
+
2634
+ If a finding would exceed the input limit, `validate`, `patch`, and `verify-fix`
2635
+ put the complete finding data in a temporary file for Codex to search alongside
2636
+ the checkout. A single input file keeps its original text and line breaks.
2637
+ The file remains available until the task finishes and is then removed. The
2638
+ SDK's local `validate()` and `patch()` methods use the same fallback.
2639
+
2865
2640
  `--verification-mode static` selects source-only assessment, as described above
2866
2641
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2867
2642
 
2868
2643
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2869
2644
  `--json` returns structured output. Exit codes are `0` when all findings are
2870
2645
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2871
- Authentication and execution failures print diagnostics on stderr and return
2872
- `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message` with `--json`
2873
- or `--format jsonl`. With JSON/JSONL `--full-output`, failures use an `ok: false`
2874
- error envelope. Other formats retain stderr-only failures. Interruptions retain
2875
- exit codes `130` and `143` without a result.
2646
+ With `--json` or `--format jsonl`, authentication and execution failures return
2647
+ `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
2648
+ `--full-output`, these failures use an `ok: false` error envelope. If a saved
2649
+ selection exceeds one request, the CLI sends the failure message only to the
2650
+ structured output. With `--token-count`, `--token-limit`, or `--token-offset`,
2651
+ stderr also carries the diagnostic so it remains available alongside a count
2652
+ or a partial result. Other formats report failures on stderr. Interruptions
2653
+ retain exit codes `130` and `143` without a result.
2876
2654
 
2877
2655
  ## Command discovery and integrations
2878
2656
 
2879
2657
  Use `--llms` for the command manifest, `scan --schema --format json` for its
2880
2658
  schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
2881
- `--format toon|json|yaml|jsonl` and `--full-output`.
2659
+ `--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
2660
+ `--filter-output`, `--token-limit`, and `--token-offset` options accept either
2661
+ `--option value` or `--option=value`.
2882
2662
 
2883
2663
  `skills add` syncs generated CLI command guidance; it does not install the full
2884
2664
  Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing