@openai/codex-security 0.8.2 → 0.8.3

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 (375) hide show
  1. package/README.md +43 -61
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  14. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +46 -12
  15. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  16. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  17. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  18. package/_bundled_plugin/references/artifact-storage.md +1 -1
  19. package/_bundled_plugin/references/core-scan.md +14 -5
  20. package/_bundled_plugin/references/default-severity-rubric.md +28 -0
  21. package/_bundled_plugin/references/finding-detail-fields.md +1 -0
  22. package/_bundled_plugin/references/threat-model.md +1 -0
  23. package/_bundled_plugin/scripts/deep_scan_workbench.py +23 -112
  24. package/_bundled_plugin/scripts/finalize_scan_contract.py +167 -153
  25. package/_bundled_plugin/scripts/finding_preview.py +5 -29
  26. package/_bundled_plugin/scripts/posix_scan_local_files.py +187 -0
  27. package/_bundled_plugin/scripts/report_projection.py +87 -136
  28. package/_bundled_plugin/scripts/validate_scan_contract.py +2 -6
  29. package/_bundled_plugin/scripts/windows_scan_local_files.py +212 -55
  30. package/_bundled_plugin/scripts/workbench/retained_coverage.py +8 -24
  31. package/_bundled_plugin/scripts/workbench/saved_coverage.py +143 -231
  32. package/_bundled_plugin/scripts/workbench_cli.py +102 -13
  33. package/_bundled_plugin/scripts/workbench_constants.py +9 -0
  34. package/_bundled_plugin/scripts/workbench_db.py +186 -360
  35. package/_bundled_plugin/scripts/workbench_finding_workflows.py +86 -4
  36. package/_bundled_plugin/scripts/workbench_native_indexes.py +17 -21
  37. package/_bundled_plugin/scripts/workbench_remediation.py +495 -11
  38. package/_bundled_plugin/scripts/workbench_scan_history.py +22 -25
  39. package/_bundled_plugin/scripts/workbench_scan_start.py +1 -1
  40. package/_bundled_plugin/scripts/workbench_scan_usage.py +25 -52
  41. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  42. package/_bundled_plugin/scripts/workbench_setup.py +239 -0
  43. package/_bundled_plugin/scripts/workbench_source_scopes.py +15 -23
  44. package/_bundled_plugin/scripts/workbench_target.py +213 -20
  45. package/_bundled_plugin/scripts/workbench_validation.py +1 -9
  46. package/_bundled_plugin/shared/workbench-history-repairs.json +7 -0
  47. package/_bundled_plugin/shared/workbench-migrations.json +19 -0
  48. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  49. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  50. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  51. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  52. package/_bundled_plugin/skills/cloud-findings/SKILL.md +2 -0
  53. package/_bundled_plugin/skills/fix-finding/SKILL.md +18 -1
  54. package/_bundled_plugin/skills/publish-findings/SKILL.md +64 -35
  55. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +2 -21
  56. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +14 -8
  57. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  58. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  59. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -4
  60. package/dist/api.d.ts +6 -1
  61. package/dist/api.d.ts.map +1 -1
  62. package/dist/api.js +411 -160
  63. package/dist/api.js.map +1 -1
  64. package/dist/auth.js +6 -1
  65. package/dist/auth.js.map +1 -1
  66. package/dist/blackduck-findings.d.ts +8 -0
  67. package/dist/blackduck-findings.d.ts.map +1 -0
  68. package/dist/blackduck-findings.js +305 -0
  69. package/dist/blackduck-findings.js.map +1 -0
  70. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  71. package/dist/bulk-scan-discovery.js +51 -36
  72. package/dist/bulk-scan-discovery.js.map +1 -1
  73. package/dist/classify-severity-records.d.ts +5 -0
  74. package/dist/classify-severity-records.d.ts.map +1 -1
  75. package/dist/classify-severity-records.js +6 -8
  76. package/dist/classify-severity-records.js.map +1 -1
  77. package/dist/classify-severity.d.ts +4 -1
  78. package/dist/classify-severity.d.ts.map +1 -1
  79. package/dist/classify-severity.js +28 -9
  80. package/dist/classify-severity.js.map +1 -1
  81. package/dist/cli.d.ts +3 -0
  82. package/dist/cli.d.ts.map +1 -1
  83. package/dist/cli.js +608 -258
  84. package/dist/cli.js.map +1 -1
  85. package/dist/codex-prompt.d.ts +2 -0
  86. package/dist/codex-prompt.d.ts.map +1 -1
  87. package/dist/codex-prompt.js +6 -0
  88. package/dist/codex-prompt.js.map +1 -1
  89. package/dist/component-scan.d.ts.map +1 -1
  90. package/dist/component-scan.js +6 -5
  91. package/dist/component-scan.js.map +1 -1
  92. package/dist/config.d.ts +2 -1
  93. package/dist/config.d.ts.map +1 -1
  94. package/dist/config.js +162 -40
  95. package/dist/config.js.map +1 -1
  96. package/dist/continuum-findings.d.ts +7 -0
  97. package/dist/continuum-findings.d.ts.map +1 -0
  98. package/dist/continuum-findings.js +157 -0
  99. package/dist/continuum-findings.js.map +1 -0
  100. package/dist/contract-values.d.ts +28 -0
  101. package/dist/contract-values.d.ts.map +1 -0
  102. package/dist/contract-values.js +75 -0
  103. package/dist/contract-values.js.map +1 -0
  104. package/dist/contract.d.ts +2 -20
  105. package/dist/contract.d.ts.map +1 -1
  106. package/dist/contract.js +58 -669
  107. package/dist/contract.js.map +1 -1
  108. package/dist/cost-model.d.ts.map +1 -1
  109. package/dist/cost-model.js +1 -4
  110. package/dist/cost-model.js.map +1 -1
  111. package/dist/cost.d.ts +19 -1
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +2120 -39
  114. package/dist/cost.js.map +1 -1
  115. package/dist/custom-validation-prompt.d.ts +1 -1
  116. package/dist/custom-validation-prompt.d.ts.map +1 -1
  117. package/dist/custom-validation-prompt.js +5 -0
  118. package/dist/custom-validation-prompt.js.map +1 -1
  119. package/dist/custom-validation.d.ts +2 -0
  120. package/dist/custom-validation.d.ts.map +1 -1
  121. package/dist/custom-validation.js +4 -0
  122. package/dist/custom-validation.js.map +1 -1
  123. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  124. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  125. package/dist/deduplication/deduplication-prompts.js +2 -2
  126. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  127. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  128. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  129. package/dist/deduplication/deduplication-reviewer.js +11 -4
  130. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  131. package/dist/deduplication/deduplication.js.map +1 -1
  132. package/dist/deduplication/finding-schema.d.ts +19 -1
  133. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  134. package/dist/deduplication/finding-schema.js +25 -0
  135. package/dist/deduplication/finding-schema.js.map +1 -1
  136. package/dist/deduplication/local.d.ts.map +1 -1
  137. package/dist/deduplication/local.js +3 -8
  138. package/dist/deduplication/local.js.map +1 -1
  139. package/dist/deduplication/records.d.ts +8 -2
  140. package/dist/deduplication/records.d.ts.map +1 -1
  141. package/dist/deduplication/records.js +36 -8
  142. package/dist/deduplication/records.js.map +1 -1
  143. package/dist/deep-scan.d.ts +11 -0
  144. package/dist/deep-scan.d.ts.map +1 -1
  145. package/dist/deep-scan.js +235 -4
  146. package/dist/deep-scan.js.map +1 -1
  147. package/dist/default-severity-rubric.d.ts +1 -2
  148. package/dist/default-severity-rubric.d.ts.map +1 -1
  149. package/dist/default-severity-rubric.js +2 -66
  150. package/dist/default-severity-rubric.js.map +1 -1
  151. package/dist/endor-findings.d.ts.map +1 -1
  152. package/dist/endor-findings.js +7 -37
  153. package/dist/endor-findings.js.map +1 -1
  154. package/dist/errors.js +1 -1
  155. package/dist/errors.js.map +1 -1
  156. package/dist/external-findings-import.d.ts.map +1 -1
  157. package/dist/external-findings-import.js +5 -11
  158. package/dist/external-findings-import.js.map +1 -1
  159. package/dist/external-findings-local.d.ts +9 -0
  160. package/dist/external-findings-local.d.ts.map +1 -1
  161. package/dist/external-findings-local.js +325 -179
  162. package/dist/external-findings-local.js.map +1 -1
  163. package/dist/external-findings-publish.d.ts +12 -0
  164. package/dist/external-findings-publish.d.ts.map +1 -1
  165. package/dist/external-findings-publish.js +1202 -214
  166. package/dist/external-findings-publish.js.map +1 -1
  167. package/dist/external-findings-read.d.ts +8 -0
  168. package/dist/external-findings-read.d.ts.map +1 -1
  169. package/dist/external-findings-read.js +65 -54
  170. package/dist/external-findings-read.js.map +1 -1
  171. package/dist/external-findings.d.ts +2 -0
  172. package/dist/external-findings.d.ts.map +1 -1
  173. package/dist/external-findings.js +111 -0
  174. package/dist/external-findings.js.map +1 -1
  175. package/dist/external-import-contract.d.ts +29 -1
  176. package/dist/external-import-contract.d.ts.map +1 -1
  177. package/dist/external-import-contract.js +314 -44
  178. package/dist/external-import-contract.js.map +1 -1
  179. package/dist/external-import-models.d.ts +1 -1
  180. package/dist/external-import-models.d.ts.map +1 -1
  181. package/dist/external-import-models.js.map +1 -1
  182. package/dist/finding-normalization.d.ts +1 -1
  183. package/dist/finding-normalization.d.ts.map +1 -1
  184. package/dist/finding-normalization.js +46 -11
  185. package/dist/finding-normalization.js.map +1 -1
  186. package/dist/finding-retrieval.d.ts +3 -3
  187. package/dist/finding-retrieval.d.ts.map +1 -1
  188. package/dist/finding-retrieval.js.map +1 -1
  189. package/dist/finding-workflow.d.ts +6 -1
  190. package/dist/finding-workflow.d.ts.map +1 -1
  191. package/dist/finding-workflow.js +2 -2
  192. package/dist/finding-workflow.js.map +1 -1
  193. package/dist/git-remote.d.ts +4 -0
  194. package/dist/git-remote.d.ts.map +1 -1
  195. package/dist/git-remote.js +20 -0
  196. package/dist/git-remote.js.map +1 -1
  197. package/dist/github-advisories.d.ts +3 -12
  198. package/dist/github-advisories.d.ts.map +1 -1
  199. package/dist/github-advisories.js +9 -29
  200. package/dist/github-advisories.js.map +1 -1
  201. package/dist/github-dependabot-findings.d.ts.map +1 -1
  202. package/dist/github-dependabot-findings.js +7 -16
  203. package/dist/github-dependabot-findings.js.map +1 -1
  204. package/dist/github-findings.d.ts.map +1 -1
  205. package/dist/github-findings.js +344 -56
  206. package/dist/github-findings.js.map +1 -1
  207. package/dist/github.d.ts +17 -7
  208. package/dist/github.d.ts.map +1 -1
  209. package/dist/github.js +43 -30
  210. package/dist/github.js.map +1 -1
  211. package/dist/host-protocol.d.ts +2 -2
  212. package/dist/host-protocol.d.ts.map +1 -1
  213. package/dist/host-protocol.js.map +1 -1
  214. package/dist/host-records-protocol.d.ts +10 -11
  215. package/dist/host-records-protocol.d.ts.map +1 -1
  216. package/dist/host-records-protocol.js +69 -9
  217. package/dist/host-records-protocol.js.map +1 -1
  218. package/dist/hosted-scan.d.ts +15 -0
  219. package/dist/hosted-scan.d.ts.map +1 -1
  220. package/dist/hosted-scan.js +55 -33
  221. package/dist/hosted-scan.js.map +1 -1
  222. package/dist/index.d.ts +7 -0
  223. package/dist/index.d.ts.map +1 -1
  224. package/dist/index.js +6 -0
  225. package/dist/index.js.map +1 -1
  226. package/dist/inspector-findings.d.ts.map +1 -1
  227. package/dist/inspector-findings.js +13 -18
  228. package/dist/inspector-findings.js.map +1 -1
  229. package/dist/knowledge-base.js +18 -5
  230. package/dist/knowledge-base.js.map +1 -1
  231. package/dist/local-git-metadata.d.ts +5 -0
  232. package/dist/local-git-metadata.d.ts.map +1 -0
  233. package/dist/local-git-metadata.js +131 -0
  234. package/dist/local-git-metadata.js.map +1 -0
  235. package/dist/multiscan.d.ts.map +1 -1
  236. package/dist/multiscan.js +22 -12
  237. package/dist/multiscan.js.map +1 -1
  238. package/dist/opengrep-findings.d.ts.map +1 -1
  239. package/dist/opengrep-findings.js +34 -20
  240. package/dist/opengrep-findings.js.map +1 -1
  241. package/dist/patch-tui.d.ts.map +1 -1
  242. package/dist/patch-tui.js +90 -35
  243. package/dist/patch-tui.js.map +1 -1
  244. package/dist/private-finding-import.d.ts +246 -0
  245. package/dist/private-finding-import.d.ts.map +1 -0
  246. package/dist/private-finding-import.js +387 -0
  247. package/dist/private-finding-import.js.map +1 -0
  248. package/dist/project-config.d.ts.map +1 -1
  249. package/dist/project-config.js +2 -2
  250. package/dist/project-config.js.map +1 -1
  251. package/dist/provider-profile.d.ts +10 -2
  252. package/dist/provider-profile.d.ts.map +1 -1
  253. package/dist/provider-profile.js +72 -10
  254. package/dist/provider-profile.js.map +1 -1
  255. package/dist/publication.js +7 -1
  256. package/dist/publication.js.map +1 -1
  257. package/dist/reader-selection.d.ts +13 -0
  258. package/dist/reader-selection.d.ts.map +1 -0
  259. package/dist/reader-selection.js +81 -0
  260. package/dist/reader-selection.js.map +1 -0
  261. package/dist/record.d.ts +6 -1
  262. package/dist/record.d.ts.map +1 -1
  263. package/dist/record.js +53 -2
  264. package/dist/record.js.map +1 -1
  265. package/dist/remediation.d.ts +5 -0
  266. package/dist/remediation.d.ts.map +1 -1
  267. package/dist/remediation.js +30 -0
  268. package/dist/remediation.js.map +1 -1
  269. package/dist/result.d.ts +2 -0
  270. package/dist/result.d.ts.map +1 -1
  271. package/dist/result.js +3 -1
  272. package/dist/result.js.map +1 -1
  273. package/dist/runtime.d.ts +2 -1
  274. package/dist/runtime.d.ts.map +1 -1
  275. package/dist/runtime.js +95 -52
  276. package/dist/runtime.js.map +1 -1
  277. package/dist/scan-activity.js +40 -17
  278. package/dist/scan-activity.js.map +1 -1
  279. package/dist/scan-comparison.d.ts +1 -1
  280. package/dist/scan-comparison.d.ts.map +1 -1
  281. package/dist/scan-comparison.js +11 -13
  282. package/dist/scan-comparison.js.map +1 -1
  283. package/dist/scan-dashboard.d.ts +1 -0
  284. package/dist/scan-dashboard.d.ts.map +1 -1
  285. package/dist/scan-dashboard.js +16 -37
  286. package/dist/scan-dashboard.js.map +1 -1
  287. package/dist/scan-executor.d.ts +2 -0
  288. package/dist/scan-executor.d.ts.map +1 -1
  289. package/dist/scan-executor.js.map +1 -1
  290. package/dist/scan-history-renderer.d.ts.map +1 -1
  291. package/dist/scan-history-renderer.js +22 -9
  292. package/dist/scan-history-renderer.js.map +1 -1
  293. package/dist/scan-logs.d.ts.map +1 -1
  294. package/dist/scan-logs.js +5 -5
  295. package/dist/scan-logs.js.map +1 -1
  296. package/dist/scanner-import.d.ts +46 -6
  297. package/dist/scanner-import.d.ts.map +1 -1
  298. package/dist/scanner-import.js +208 -42
  299. package/dist/scanner-import.js.map +1 -1
  300. package/dist/scanner-repository-url.d.ts +14 -0
  301. package/dist/scanner-repository-url.d.ts.map +1 -0
  302. package/dist/scanner-repository-url.js +67 -0
  303. package/dist/scanner-repository-url.js.map +1 -0
  304. package/dist/semgrep-findings.d.ts.map +1 -1
  305. package/dist/semgrep-findings.js +20 -48
  306. package/dist/semgrep-findings.js.map +1 -1
  307. package/dist/semgrep-platform-findings.d.ts +12 -0
  308. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  309. package/dist/semgrep-platform-findings.js +198 -0
  310. package/dist/semgrep-platform-findings.js.map +1 -0
  311. package/dist/severity-rubric.d.ts +20 -0
  312. package/dist/severity-rubric.d.ts.map +1 -0
  313. package/dist/severity-rubric.js +73 -0
  314. package/dist/severity-rubric.js.map +1 -0
  315. package/dist/severity-store.js +15 -5
  316. package/dist/severity-store.js.map +1 -1
  317. package/dist/snyk-findings.d.ts.map +1 -1
  318. package/dist/snyk-findings.js +21 -20
  319. package/dist/snyk-findings.js.map +1 -1
  320. package/dist/sonar-collector.d.ts +16 -0
  321. package/dist/sonar-collector.d.ts.map +1 -0
  322. package/dist/sonar-collector.js +383 -0
  323. package/dist/sonar-collector.js.map +1 -0
  324. package/dist/sonar-findings.d.ts +49 -0
  325. package/dist/sonar-findings.d.ts.map +1 -0
  326. package/dist/sonar-findings.js +288 -0
  327. package/dist/sonar-findings.js.map +1 -0
  328. package/dist/sonar-import.d.ts +111 -0
  329. package/dist/sonar-import.d.ts.map +1 -0
  330. package/dist/sonar-import.js +279 -0
  331. package/dist/sonar-import.js.map +1 -0
  332. package/dist/suggest-owners.d.ts.map +1 -1
  333. package/dist/suggest-owners.js +2 -1
  334. package/dist/suggest-owners.js.map +1 -1
  335. package/dist/targets.d.ts +3 -0
  336. package/dist/targets.d.ts.map +1 -1
  337. package/dist/targets.js +18 -12
  338. package/dist/targets.js.map +1 -1
  339. package/dist/terminal-columns.d.ts +4 -0
  340. package/dist/terminal-columns.d.ts.map +1 -0
  341. package/dist/terminal-columns.js +19 -0
  342. package/dist/terminal-columns.js.map +1 -0
  343. package/dist/validation-records.d.ts +0 -3
  344. package/dist/validation-records.d.ts.map +1 -1
  345. package/dist/validation-records.js +0 -16
  346. package/dist/validation-records.js.map +1 -1
  347. package/dist/veracode-findings.d.ts +7 -0
  348. package/dist/veracode-findings.d.ts.map +1 -0
  349. package/dist/veracode-findings.js +371 -0
  350. package/dist/veracode-findings.js.map +1 -0
  351. package/dist/windows-path.d.ts.map +1 -1
  352. package/dist/windows-path.js +1 -0
  353. package/dist/windows-path.js.map +1 -1
  354. package/dist/wiz-csv.d.ts +2 -2
  355. package/dist/wiz-csv.d.ts.map +1 -1
  356. package/dist/wiz-csv.js +1 -3
  357. package/dist/wiz-csv.js.map +1 -1
  358. package/dist/wiz-findings.d.ts +10 -2
  359. package/dist/wiz-findings.d.ts.map +1 -1
  360. package/dist/wiz-findings.js +88 -49
  361. package/dist/wiz-findings.js.map +1 -1
  362. package/docs/classify-severity-records.md +1 -1
  363. package/docs/cli.md +310 -477
  364. package/docs/dedupe-records.md +10 -0
  365. package/docs/findings-service.md +21 -8
  366. package/docs/hosted-scans.md +16 -1
  367. package/package.json +8 -9
  368. package/schemas/external-findings.schema.json +12 -1
  369. package/schemas/hosted-scan-v2.fixture.json +16 -1
  370. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  371. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  372. package/dist/deduplication/records-protocol.d.ts +0 -4
  373. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  374. package/dist/deduplication/records-protocol.js +0 -49
  375. package/dist/deduplication/records-protocol.js.map +0 -1
package/docs/cli.md CHANGED
@@ -32,6 +32,7 @@ without running security analysis.
32
32
  - [Review one system across repositories](#review-one-system-across-repositories)
33
33
  or [run independent bulk scans](#bulk-scans).
34
34
  - [Import vendor findings locally](#import-vendor-findings-locally),
35
+ [import Sonar issues selected in Codex](#import-sonarqube-cloud-issues),
35
36
  [save findings as a scan](#import-findings-as-a-saved-scan), or
36
37
  [retrieve GitHub alerts](#import-alerts-from-the-cli).
37
38
  - [Inspect saved scans and rerun them](#scan-history-and-reruns),
@@ -169,7 +170,8 @@ and project have access. An omitted `access_programs.cyber` field does not by
169
170
  itself mean that Daybreak treatment is disabled.
170
171
 
171
172
  Choose a compatible model available to your project and select Daybreak Blue
172
- explicitly:
173
+ explicitly. If you use `--max-cost` or the SDK's `maxCostUsd`, choose a model
174
+ with built-in pricing so the scan can enforce the limit.
173
175
 
174
176
  ```bash
175
177
  codex-security scan /path/to/repository \
@@ -182,11 +184,8 @@ Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan
182
184
  The selection reaches discovery and reducer workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
183
185
  for configuration precedence and the API-key feature setting.
184
186
 
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.
187
+ `access_programs.cyber` is a Responses API field. Use `--cyber-access-program`
188
+ instead of passing it as a `--codex` configuration key.
190
189
 
191
190
  ### Select a Cyber access program
192
191
 
@@ -644,6 +643,9 @@ Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
644
643
  `scan-components`, and `info` accept project files. SDK calls and saved reruns
645
644
  do not load them automatically.
646
645
 
646
+ JSON project files and component plans (`--components-file`) accept UTF-8 with
647
+ or without a leading byte-order mark.
648
+
647
649
  Treat the selected file as trusted operator configuration: native settings can
648
650
  start MCP processes and choose model-service destinations. Keep CI scanner
649
651
  configuration outside the untrusted checkout being assessed.
@@ -782,6 +784,28 @@ Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
782
784
  planning and authentication choices. Custom `createSecurity` clients receive
783
785
  absolute targets; saved plans and component receipts retain relative paths.
784
786
 
787
+ ### Choose a severity rubric
788
+
789
+ Standalone Standard and Deep scans grade findings with the bundled rubric by
790
+ default. Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the
791
+ current default from Statsig once when starting a scan. If that lookup fails,
792
+ the scan uses the bundled rubric.
793
+
794
+ ```bash
795
+ CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1 codex-security scan .
796
+ codex-security scan . --mode deep --rubric ./severity.md
797
+ ```
798
+
799
+ An explicit Markdown file takes precedence and skips the lookup, even when
800
+ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
801
+ `markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
802
+ Markdown. A supplied snapshot takes precedence over a file.
803
+
804
+ The scan saves the rubric text in its local launch recipe. Retrying a Standard
805
+ scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
806
+ with a saved rubric reuses that copy even if the remote default or file changes.
807
+ Older scans without a saved rubric continue to resume using their existing workflow.
808
+
785
809
  ### Set investigation time
786
810
 
787
811
  ```bash
@@ -877,6 +901,24 @@ explicit saved scan ID. Exact-path `latest` lookup still works without Git.
877
901
  Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:
878
902
  `--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are
879
903
  rejected, including a `--model` or `--effort` flag plus its native equivalent.
904
+
905
+ To select a Codex file profile, put its settings in
906
+ `$CODEX_HOME/review.config.toml` (or `~/.codex/review.config.toml` when
907
+ `CODEX_HOME` is unset), then run:
908
+
909
+ ```bash
910
+ npx @openai/codex-security scan . --codex 'profile="review"'
911
+ ```
912
+
913
+ In the SDK, set `codexOverrides: { profile: "review" }`. In a project config,
914
+ set `codex.profile: review`. The profile file uses top-level Codex TOML keys.
915
+ Its settings override scanner defaults. Explicit scan settings take precedence.
916
+ Relative file paths, including `model_instructions_file`, resolve from the
917
+ profile directory. Saved launches retain the profile name and reload its settings.
918
+ Include custom provider definitions in the file so the scan
919
+ can use them from its isolated Codex home. An absent file contributes no
920
+ settings. Existing inline `profiles` tables still work.
921
+
880
922
  Choose plugins with `--plugin-path`; native plugin and marketplace overrides are
881
923
  rejected. New and resumed Deep Scans require the current plugin's direct engine,
882
924
  worker provider snapshot, and isolated worker configuration capabilities. Update
@@ -983,6 +1025,15 @@ Finish older-version operations before upgrading. Never remove
983
1025
  `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
984
1026
  credential home before manually removing an old `.codex-security-scan.lock`.
985
1027
 
1028
+ If credential-home preparation fails, the error includes the underlying
1029
+ filesystem diagnostic. For permission or read-only filesystem errors, check
1030
+ the reported path or set `CODEX_SECURITY_STATE_DIR` to a private, writable
1031
+ directory outside the repository. A new state directory has separate history
1032
+ and does not migrate existing credentials or reports.
1033
+
1034
+ Sandbox startup errors include the native diagnostic followed by a command to
1035
+ reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
1036
+
986
1037
  On Windows, credential-home checks require trusted ownership and permissions
987
1038
  through every ancestor, including the volume root. Codex Security can repair
988
1039
  the credential home and its descendants; it does not change ancestor ownership
@@ -1202,6 +1253,11 @@ failed or interrupted attempt:
1202
1253
  - An unavailable, failed, or canceled scan starts a new attempt at the pinned
1203
1254
  revision, preserving old artifacts and checkouts.
1204
1255
 
1256
+ If a nonempty committed line in `results.jsonl` contains invalid JSON or lacks
1257
+ a string task ID, the command reports its line number and leaves the ledger untouched.
1258
+ Restore a complete ledger backup that includes every committed attempt, or start
1259
+ a separate campaign in a new `--output-dir`.
1260
+
1205
1261
  New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
1206
1262
  workers and one recovery/new attempt per repository. A resume connection failure
1207
1263
  stops only that repository for this invocation. Failed recovery checkouts remain;
@@ -1270,304 +1326,169 @@ Supply the validation prompt again when rerunning.
1270
1326
 
1271
1327
  ## Import vendor findings locally
1272
1328
 
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.
1274
-
1275
- External finding imports are disabled by default. Opt in for the current shell:
1276
-
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):
1314
-
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
1319
- ```
1320
-
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.
1326
-
1327
- Read the saved evidence with:
1328
-
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.
1329
+ Choose an input in the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
1330
+ Each guide shows how to preview its input for a local repository. Follow the [shared procedure](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
1331
+ to confirm the import and read the resulting records.
1332
+
1333
+ Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` to enable `publish findings`,
1334
+ `findings imported`, `import sonar`, and `import github-advisories`. Only `1`
1335
+ enables these commands in help and schemas. The SDK's corresponding operations
1336
+ require the flag in their effective environment. Pure normalizers, file readers,
1337
+ and the existing `import github` alert collector remain available independently.
1338
+ Disabling the flag retains saved records.
1339
+
1340
+ For `publish findings`, `--to` is required. With `--to local`, `--repository`
1341
+ takes a checkout path. The reader detects the file format, and `--format json`
1342
+ selects the output format. A local preview writes no findings and needs no Cloud
1343
+ login, network connection, or model call.
1344
+
1345
+ Local readback uses `findings imported [PATH]`. The path defaults to the current
1346
+ directory. Each imported record starts as `not_assessed`. Unknown revisions and
1347
+ locations stay unknown. Repository-scoped sources are checked against comparable
1348
+ configured Git remotes as described in the provider guide. Reimporting the same
1349
+ source key and finding ID reports created, updated, or unchanged records.
1350
+ Records omitted from the new selection stay stored. An import with exclusions
1351
+ exits with status 1. Local imports can retain evidence that exceeds Cloud's per-finding limits.
1352
+
1353
+ For completed scans exported in the Codex Security JSON or CSV format, use
1354
+ [scan import](#import-findings-as-a-saved-scan).
1361
1355
 
1362
1356
  ## Import Endor Labs findings
1363
1357
 
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:
1367
-
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.
1358
+ Use `--provider endor` for one Endor project and context. The
1359
+ [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1360
+ SARIF compatibility, and the local preview.
1400
1361
 
1401
1362
  ## Publish findings to Cloud
1402
1363
 
1364
+ Use the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) to prepare a supported input
1365
+ and follow the [shared publication steps](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify)
1366
+ to preview and confirm it. The following settings and result fields apply to
1367
+ scanner publication across providers.
1368
+
1369
+ ### Preview and publish
1370
+
1371
+ With `--to cloud`, `--repository` accepts a connected GitHub or GitHub Enterprise
1372
+ repository URL or Cloud repository ID. A unique URL and its ID resolve to the
1373
+ same destination and saved submission. Use the ID if several connectors share
1374
+ the URL. Use a file-backed ChatGPT login for the selected Cloud
1375
+ account. If you use your regular Codex login, set `cli_auth_credentials_store = "file"`
1376
+ in Codex `config.toml` and sign in again. API-key-only and keyring-only logins
1377
+ cannot publish. The destination needs an authorized environment. It can receive
1378
+ scanner findings before its first native scan.
1379
+
1380
+ Cloud preview reads current source versions and lists the account, endpoint,
1381
+ repository, and environments. Existing source records keep their environment.
1382
+ New records use the repository's current authorized default. The terminal
1383
+ summarizes severities, shows up to five finding IDs and titles, and identifies
1384
+ the evidence file and exclusions. Inspect the full preview with `--dry-run --format json`.
1385
+ The interactive confirmation defaults to No and identifies skipped records.
1386
+ Without a terminal, uploading requires `--yes`.
1387
+
1388
+ ### Configure an alternate Cloud deployment
1389
+
1390
+ Set `CODEX_SECURITY_CLOUD_BASE_URL` to the deployment's API root, such as
1391
+ `https://cloud.example.test/backend-api/aardvark`. Use a login issued by that
1392
+ deployment. Remote API roots require HTTPS. Loopback development also accepts
1393
+ HTTP on `localhost`, `127.0.0.0/8`, or `::1`. An empty or invalid setting
1394
+ stops preparation before authentication or network requests. Leaving it unset
1395
+ selects production. For testing, use an isolated `CODEX_SECURITY_STATE_DIR`.
1396
+
1397
+ For a separately hosted Cloud UI, set `CODEX_SECURITY_CLOUD_WEB_URL` to the
1398
+ full app URL. The preview and result can then supply a repository-specific
1399
+ `cloudUrl`. With a custom API and no web URL, the CLI prints navigation
1400
+ instructions. API requests always use the API root. The older
1401
+ `CODEX_SECURITY_CLOUD_PUBLISH_URL` setting applies only to native scan publishing.
1402
+
1403
+ ### Resume interrupted imports
1404
+
1405
+ The publisher saves request IDs and bodies privately in the configured state
1406
+ directory before uploading batches of up to 100 findings within Cloud payload
1407
+ limits. After a lost response, use the same input, destination, account, API
1408
+ endpoint, and state directory to resume. Deployments have separate checkpoints
1409
+ even if their account and repository IDs match. Check `cloudApiUrl` for the API
1410
+ endpoint and `savedSubmission` for the checkpoint. A repository reset retires
1411
+ the old request and requires a fresh preview and approval.
1412
+ [Retry a Cloud submission](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/schema-guide.md#retry-a-cloud-submission)
1413
+
1414
+ ### Results and exit codes
1415
+
1416
+ | Status | Exit code | Meaning |
1417
+ | ------------- | --------- | ----------------------------------------------------------------------- |
1418
+ | `complete` | 0 | All selected records were acknowledged and read back. |
1419
+ | `partial` | 1 | Some records were excluded locally or rejected by Cloud. |
1420
+ | `interrupted` | 2 | Upload, verification, or receipt persistence stopped after preparation. |
1421
+ | `failed` | 2 | Preparation failed before upload. |
1422
+
1423
+ With `--format json` or `--format jsonl`, add `--full-output` for an envelope.
1424
+ Failed and interrupted imports set `ok` to `false` and `error.code` to
1425
+ `IMPORT_FAILED`. Available results, receipts, and counts remain under `data`.
1426
+ Other formats reject `--full-output` before reading the file or contacting
1427
+ Cloud. Ctrl-C and SIGTERM retain exit codes 130 and 143.
1428
+
1429
+ `verified` and `unacknowledged` are counts. Each receipt item identifies a
1430
+ request item by `client_id`. Each entry in `failures` identifies the vendor
1431
+ record by `source_finding_id`. A lost response can leave accepted records
1432
+ unacknowledged. Review `error` before retrying, and check `excluded` for local
1433
+ input errors. Counts include previously acknowledged batches in the same
1434
+ saved submission.
1435
+
1436
+ Progress goes to stderr and JSON results to stdout. Lookups and readback use up
1437
+ to four concurrent requests. Uploads are sequential. Saved receipts and
1438
+ readback verify source-record identity and evidence. Codex assessment and
1439
+ visibility in the shared Cloud Findings view are separate. `cloudUrl`, when
1440
+ available, links to the destination repository in Cloud.
1441
+
1403
1442
  ### Import Snyk Open Source findings
1404
1443
 
1405
- Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
1406
- SBOM results and platform backlog ingestion are outside this adapter.
1407
-
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.
1412
-
1413
- The same saved bundle supports [local import](#import-vendor-findings-locally)
1414
- without a Cloud login:
1415
-
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
- ```
1421
-
1422
- Or preview publication to a connected Cloud repository:
1423
-
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.
1444
+ Use `--provider snyk` for Open Source SCA vulnerabilities. Native CLI JSON, plugin
1445
+ exports, and Open Source SARIF can produce different occurrence IDs. Use a
1446
+ separate source key for each format. See the [Snyk guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for
1447
+ collection and preview commands.
1464
1448
 
1465
1449
  ### Import Wiz findings
1466
1450
 
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.
1451
+ The [Wiz guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/wiz.md) shows how to preview saved package vulnerabilities,
1452
+ SAST findings, repository secrets, or IaC findings. The format reference below
1453
+ describes the fields to preserve when preparing those exports.
1454
+
1455
+ #### Review the Cloud destination
1456
+
1457
+ The preview shows which Cloud destination will receive the selected records.
1458
+ When the deployment advertises private import for the scanner, the CLI puts a
1459
+ report in the signed-in account’s **private findings inbox**. The preview
1460
+ identifies its format and byte count. For complete Endor findings and Wiz
1461
+ vulnerability JSON exports, the CLI sends the original bytes when Cloud
1462
+ advertises the format and every record matches the reviewed selection. Other
1463
+ selections and in-memory collectors use `security.findings.v1`. The CLI
1464
+ attaches the selected repository and connector as a suggested assessment
1465
+ target. Review the selection, exclusions, source key and destination before
1466
+ confirming.
1467
+
1468
+ The job receipt contains the file and job identifiers and record counts. To
1469
+ share a finding, open it in Cloud, assess it against a pinned repository
1470
+ revision, and explicitly publish a reportable assessment. An import can
1471
+ finish with record errors. Check the error and unprocessed counts in the
1472
+ receipt.
1473
+
1474
+ Repeat the same command to recover an interrupted private import. The CLI
1475
+ checks the report digest, reuses its saved request IDs, and reads an accepted
1476
+ job even when new uploads are disabled. Resetting the inbox requires a new
1477
+ preview and confirmation. Deployments and scanners using the repository
1478
+ publisher continue to show the repository destination and per-finding receipts.
1479
+ An in-flight repository publication resumes on its original protocol.
1474
1480
 
1475
1481
  #### Select findings and a destination
1476
1482
 
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:
1483
+ Acquire selected findings through an authorized Wiz connection and save the
1484
+ complete native response. The publisher reads the saved file. MCP summaries,
1485
+ Wiz Issues, and local Wiz CLI scan results may have different shapes. Verify
1486
+ the selected response against the format for its finding family. Acquisition
1487
+ against a live Wiz tenant requires separate qualification.
1548
1488
 
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.
1489
+ For saved reports, use the detailed repository package vulnerability export
1490
+ shown in the Wiz guide. Raw Event on Code & Build Scans contains scan
1491
+ metadata. For other CSV exports, see [Convert CSV reports](#convert-csv-reports).
1571
1492
 
1572
1493
  #### Package vulnerability inputs
1573
1494
 
@@ -1579,6 +1500,10 @@ A response that advertises another page is rejected. Complete the requested page
1579
1500
  or save only the explicitly selected records; retain the named collection for
1580
1501
  SAST, repository secrets, and IaC.
1581
1502
 
1503
+ For native package records, include `id`, `name`, `detailedName`,
1504
+ `vulnerableAsset.id`, and `vendorSeverity` or `severity`. Retain any available
1505
+ package, image, and repository metadata.
1506
+
1582
1507
  The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
1583
1508
  `CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
1584
1509
  this profile; other Wiz report types use different fields.
@@ -1727,56 +1652,6 @@ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1727
1652
  integer range is rejected; export those values as strings to preserve them
1728
1653
  exactly. Invalid records appear in `excluded` with their source ID and reason.
1729
1654
 
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.
1779
-
1780
1655
  ### Publish completed scans
1781
1656
 
1782
1657
  Preview selected completed scans before uploading:
@@ -1892,12 +1767,19 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
1892
1767
  report snapshots and delegates model execution to the host.
1893
1768
 
1894
1769
  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).
1770
+ 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
1771
  It evaluates attacker access, boundary crossing, additional harm, and evidence for
1897
1772
  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.
1773
+ from severity; missing proof alone does not justify a downgrade.
1774
+
1775
+ Set `CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1` to fetch the current default
1776
+ from Statsig once per reclassification. Only the exact value `1` enables the
1777
+ request. It sends the config name without findings or account identifiers.
1778
+ If the request fails, times out, or returns an invalid rubric, the built-in
1779
+ rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
1780
+ uses your policy for every review. Rubrics and repeatable `--knowledge-base`
1781
+ context accept text, PDF, DOCX, and directories.
1782
+
1901
1783
  Each finding is classified three times by default. `--runs N` accepts
1902
1784
  an integer from 1 through 10; SDK options use `classificationRuns` with the same
1903
1785
  default and bounds. Each review runs in an independent read-only turn using the
@@ -1918,6 +1800,12 @@ the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
1918
1800
  missing facts that could change the result. Exclusions have a null level.
1919
1801
  Finding/occurrence IDs and input hashes bind each assessment to its evidence.
1920
1802
 
1803
+ For a single rubric document, the classification result reports the SHA-256 of
1804
+ the exact UTF-8 text supplied to the reviewer in `rubricSha256`. For multiple
1805
+ documents it reports the digest of the ordered text collection. A bundled or
1806
+ remote default also records its `rubricRevision`. Older saved results retain
1807
+ their original digest and may omit the revision.
1808
+
1921
1809
  Successful assessments checkpoint immediately in local SQLite. Retries reuse
1922
1810
  matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
1923
1811
  work. Default-rubric assessments use `source: "rubric"` and a content hash; former
@@ -2001,7 +1889,7 @@ await publishScan(scanDirectory, {
2001
1889
 
2002
1890
  `classifySeverity()` accepts `findingId`, `title`, `summary`, and available
2003
1891
  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.
1892
+ `rubricPath` uses the selected default policy even when a scanner severity is present.
2005
1893
  Scan wrappers persist checkpoints (including for
2006
1894
  external directories), accept `reprocess: true`, and treat `findingIds: []` as an
2007
1895
  empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
@@ -2310,7 +2198,8 @@ marks shortened text. Other template columns keep their original values.
2310
2198
 
2311
2199
  The output defaults to `servicenow-avit.csv`. Upload the completed file in the
2312
2200
  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).
2201
+ application. If the submission result is unclear, check its status and log notes
2202
+ 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
2203
 
2315
2204
  ### Export a threat model
2316
2205
 
@@ -2429,72 +2318,32 @@ record absolute Node/CLI paths. If those change, back up and remove the verified
2429
2318
  generated hook, then reinstall with the same threshold. Restore the backup if
2430
2319
  installation fails. The installer respects `core.hooksPath`.
2431
2320
 
2432
- ## Import GitHub findings locally or to Cloud
2321
+ ## Import SonarQube Cloud issues
2433
2322
 
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.
2323
+ The [SonarQube Cloud guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/sonar.md) covers live collection, repository
2324
+ binding, saved issue-search pages, and replay. Unlike a saved-file
2325
+ `publish findings` preview, `import sonar --dry-run` writes a private capture
2326
+ and returns its path. Confirm with the capture from the preview for the intended
2327
+ destination. A Cloud confirmation imports the selected issues locally and
2328
+ publishes them to Cloud. Use `--full-output` with `--format json` or
2329
+ `--format jsonl` for a structured success or error envelope.
2448
2330
 
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:
2331
+ ## Import GitHub findings locally or to Cloud
2457
2332
 
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.
2333
+ Choose the [code scanning](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-code-scanning.md),
2334
+ [Dependabot](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md), or
2335
+ [GitHub Security Advisories](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md) guide to acquire
2336
+ and preview findings. All three use `--provider github`. Keep a separate source
2337
+ key for each family. Saving locally or publishing to Cloud requires the
2338
+ [external-import opt-in](#import-vendor-findings-locally).
2339
+
2340
+ The code-scanning and advisory CLI collectors use `gh` to authenticate for
2341
+ `GH_HOST` (default `github.com`). A GitHub
2342
+ plugin connection can select alerts but does not sign the CLI in.
2343
+ Collection retains the selected ref's instance. Branches keep separate
2344
+ evidence. An alert-wide dismissal takes precedence over the selected instance's
2345
+ open or fixed state. Missing security severity stays `unknown`. See
2346
+ [code-scanning access requirements](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository).
2498
2347
 
2499
2348
  The SDK offers the same preview and publication boundary for Cloud:
2500
2349
 
@@ -2509,7 +2358,7 @@ const alerts = await importGitHubCodeScanningAlerts({
2509
2358
  repository: "example/project",
2510
2359
  });
2511
2360
  const prepared = await prepareNormalizedExternalPublication(
2512
- normalizeGitHubCodeScanningAlerts(alerts),
2361
+ normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
2513
2362
  {
2514
2363
  provider: "github",
2515
2364
  repository: "https://github.com/example/project",
@@ -2521,73 +2370,37 @@ console.log(prepared.preview);
2521
2370
  const receipt = await prepared.publish();
2522
2371
  ```
2523
2372
 
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 })`.
2373
+ For local storage, call `normalizeGitHubCodeScanningAlerts(alerts, "local")` on
2374
+ the original alerts to retain evidence that exceeds Cloud limits. Pass the result
2375
+ to `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
2376
+ its preview, and call `import()`. Alternatively, pass the saved alert file directly
2377
+ to `prepareLocalExternalImport()`. Read records with `listLocalExternalFindings({ repository })`.
2528
2378
 
2529
2379
  ### Import GHSA advisories separately
2530
2380
 
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.
2381
+ See the [GitHub Security Advisories guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-security-advisories.md)
2382
+ to save repository advisories or selected global database records and preview
2383
+ them for the chosen destination. Advisories report affected ranges and
2384
+ available fixes. Verify installed dependencies and applicability in the
2385
+ destination repository separately.
2386
+
2387
+ Repository lists default to published advisories. When selecting exact IDs, omit
2388
+ `--github-state`. Selecting a repository advisory by its GHSA ID can return a
2389
+ draft if you have access.
2390
+ Global collection requires one or more explicit IDs.
2391
+ Acquisition failure yields no partial selection. Access to private or
2392
+ unpublished repository advisories requires the repository advisory read
2393
+ permission and access to the record. See
2394
+ [GitHub repository advisory permissions](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories).
2395
+
2396
+ In the SDK, collect the advisories with `importGitHubAdvisories()`. For Cloud,
2397
+ pass `normalizeGitHubAdvisories(advisories, "cloud")` to
2398
+ `prepareNormalizedExternalPublication()`. For local storage, pass
2399
+ `normalizeGitHubAdvisories(advisories, "local")` to `prepareNormalizedLocalImport()`.
2588
2400
  `importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
2589
2401
  `{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
2590
2402
  records. Both forms require `repository: "OWNER/REPO"` as source or target context.
2403
+ Supply `githubHost` and `githubToken` to override the GitHub CLI login and host.
2591
2404
 
2592
2405
  ## Import alerts from the CLI
2593
2406
 
@@ -2618,6 +2431,7 @@ import {
2618
2431
  const findings = await importGitHubCodeScanningAlerts({
2619
2432
  repository: "example/repository",
2620
2433
  alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
2434
+ githubHost: "github.com",
2621
2435
  githubToken: process.env["GH_TOKEN"],
2622
2436
  });
2623
2437
 
@@ -2636,8 +2450,9 @@ try {
2636
2450
  ```
2637
2451
 
2638
2452
  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`.
2453
+ Without `gh`, pass a `githubToken` issued for the selected `githubHost`.
2454
+ If you omit the token, the SDK asks the GitHub CLI for credentials, including
2455
+ its supported token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
2641
2456
  The token needs code-scanning read access; access failures reject the import.
2642
2457
 
2643
2458
  ## Validate and patch findings
@@ -2684,6 +2499,9 @@ native structured output. The CLI also checks the completed JSON before writing
2684
2499
  stdout; it does not convert a prose assessment into JSON afterward. Invalid JSON
2685
2500
  or a schema mismatch fails with exit code 2 and no assessment on stdout.
2686
2501
 
2502
+ Save the output schema as UTF-8 without a byte-order mark so both the CLI and
2503
+ Codex can read it.
2504
+
2687
2505
  Use a self-contained schema in the subset supported by the selected Codex model
2688
2506
  and provider. The local checker uses JSON Schema 2020-12, but accepting a schema
2689
2507
  locally does not guarantee provider support. Keep the schema small and use it only
@@ -2862,17 +2680,32 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
2862
2680
  finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
2863
2681
  filter for completed Linear issues to check a finished backlog.
2864
2682
 
2683
+ The CLI selects findings from the workbench and loads their evidence from the
2684
+ saved scan artifacts. It measures the verification request with that evidence
2685
+ included. Large selections use multiple requests without splitting or further
2686
+ truncating any selected finding. The CLI prints verdicts in selection order
2687
+ after every request returns valid results. For these selections the CLI omits
2688
+ per-event progress and update notices so stderr cannot delay the verdicts.
2689
+
2690
+ If one finding exceeds the input limit on its own, verification stops before
2691
+ the first request. The error reports its occurrence ID and required request
2692
+ size. To verify another open occurrence from that scan, run
2693
+ `codex-security verify-fix --scan SCAN_ID OCCURRENCE_ID`.
2694
+
2865
2695
  `--verification-mode static` selects source-only assessment, as described above
2866
2696
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2867
2697
 
2868
2698
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2869
2699
  `--json` returns structured output. Exit codes are `0` when all findings are
2870
2700
  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.
2701
+ With `--json` or `--format jsonl`, authentication and execution failures return
2702
+ `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
2703
+ `--full-output`, these failures use an `ok: false` error envelope. If a saved
2704
+ selection exceeds one request, the CLI sends the failure message only to the
2705
+ structured output. With `--token-count`, `--token-limit`, or `--token-offset`,
2706
+ stderr also carries the diagnostic so it remains available alongside a count
2707
+ or a partial result. Other formats report failures on stderr. Interruptions
2708
+ retain exit codes `130` and `143` without a result.
2876
2709
 
2877
2710
  ## Command discovery and integrations
2878
2711