@openai/codex-security 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/README.md +151 -36
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  5. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  6. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/access-advisory.md +11 -0
  17. package/_bundled_plugin/references/core-scan.md +30 -77
  18. package/_bundled_plugin/references/final-report.md +45 -189
  19. package/_bundled_plugin/references/scan-contract.md +2 -0
  20. package/_bundled_plugin/references/scan-prologue.md +1 -1
  21. package/_bundled_plugin/references/scan-runtime.md +1 -5
  22. package/_bundled_plugin/references/threat-model.md +33 -41
  23. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  24. package/_bundled_plugin/schemas/scan-manifest.schema.json +1 -0
  25. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  26. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  27. package/_bundled_plugin/scripts/deep_scan_workbench.py +145 -85
  28. package/_bundled_plugin/scripts/finalize_scan_contract.py +189 -57
  29. package/_bundled_plugin/scripts/report_projection.py +44 -15
  30. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  31. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  32. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3218 -0
  33. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  34. package/_bundled_plugin/scripts/workbench/saved_coverage.py +644 -1
  35. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  36. package/_bundled_plugin/scripts/workbench/saved_sources.py +712 -0
  37. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  38. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  39. package/_bundled_plugin/scripts/workbench_db.py +51 -22
  40. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  41. package/_bundled_plugin/scripts/workbench_finding_workflows.py +53 -9
  42. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +641 -2387
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +72 -7
  45. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  47. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  48. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +44 -0
  51. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  52. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  53. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  54. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  56. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  57. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  58. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  59. package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -30
  60. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  61. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  62. package/_bundled_plugin/skills/publish-findings/SKILL.md +134 -0
  63. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +6 -0
  64. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  65. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  66. package/_bundled_plugin/skills/security-scan/SKILL.md +28 -16
  67. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  68. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  69. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  70. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  71. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  72. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  73. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  74. package/_bundled_plugin/skills/verify-fix/SKILL.md +8 -4
  75. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  76. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  77. package/dist/api.d.ts +8 -3
  78. package/dist/api.d.ts.map +1 -1
  79. package/dist/api.js +414 -72
  80. package/dist/api.js.map +1 -1
  81. package/dist/auth.d.ts.map +1 -1
  82. package/dist/auth.js +4 -1
  83. package/dist/auth.js.map +1 -1
  84. package/dist/classify-severity-records.d.ts +5 -2
  85. package/dist/classify-severity-records.d.ts.map +1 -1
  86. package/dist/classify-severity-records.js +40 -34
  87. package/dist/classify-severity-records.js.map +1 -1
  88. package/dist/classify-severity.d.ts +5 -1
  89. package/dist/classify-severity.d.ts.map +1 -1
  90. package/dist/classify-severity.js +20 -30
  91. package/dist/classify-severity.js.map +1 -1
  92. package/dist/cli-help.d.ts.map +1 -1
  93. package/dist/cli-help.js +1 -0
  94. package/dist/cli-help.js.map +1 -1
  95. package/dist/cli.d.ts +9 -2
  96. package/dist/cli.d.ts.map +1 -1
  97. package/dist/cli.js +802 -149
  98. package/dist/cli.js.map +1 -1
  99. package/dist/cloud-endpoint.d.ts +6 -0
  100. package/dist/cloud-endpoint.d.ts.map +1 -0
  101. package/dist/cloud-endpoint.js +51 -0
  102. package/dist/cloud-endpoint.js.map +1 -0
  103. package/dist/cloud-publish.d.ts.map +1 -1
  104. package/dist/cloud-publish.js +7 -5
  105. package/dist/cloud-publish.js.map +1 -1
  106. package/dist/component-scan.d.ts +8 -2
  107. package/dist/component-scan.d.ts.map +1 -1
  108. package/dist/component-scan.js +2 -0
  109. package/dist/component-scan.js.map +1 -1
  110. package/dist/contract.d.ts +2 -0
  111. package/dist/contract.d.ts.map +1 -1
  112. package/dist/contract.js +67 -33
  113. package/dist/contract.js.map +1 -1
  114. package/dist/cost.d.ts +18 -0
  115. package/dist/cost.d.ts.map +1 -1
  116. package/dist/cost.js +107 -12
  117. package/dist/cost.js.map +1 -1
  118. package/dist/coverage-presentation.d.ts +6 -0
  119. package/dist/coverage-presentation.d.ts.map +1 -0
  120. package/dist/coverage-presentation.js +34 -0
  121. package/dist/coverage-presentation.js.map +1 -0
  122. package/dist/custom-validation-prompt.js +3 -3
  123. package/dist/custom-validation-prompt.js.map +1 -1
  124. package/dist/custom-validation.d.ts.map +1 -1
  125. package/dist/custom-validation.js +30 -4
  126. package/dist/custom-validation.js.map +1 -1
  127. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  128. package/dist/deduplication/checkpointed-review.js +3 -1
  129. package/dist/deduplication/checkpointed-review.js.map +1 -1
  130. package/dist/deduplication/scan.d.ts.map +1 -1
  131. package/dist/deduplication/scan.js +7 -5
  132. package/dist/deduplication/scan.js.map +1 -1
  133. package/dist/default-severity-rubric.d.ts +3 -0
  134. package/dist/default-severity-rubric.d.ts.map +1 -0
  135. package/dist/default-severity-rubric.js +67 -0
  136. package/dist/default-severity-rubric.js.map +1 -0
  137. package/dist/endor-findings.d.ts +8 -0
  138. package/dist/endor-findings.d.ts.map +1 -0
  139. package/dist/endor-findings.js +238 -0
  140. package/dist/endor-findings.js.map +1 -0
  141. package/dist/external-findings-import.d.ts +5 -0
  142. package/dist/external-findings-import.d.ts.map +1 -0
  143. package/dist/external-findings-import.js +46 -0
  144. package/dist/external-findings-import.js.map +1 -0
  145. package/dist/external-findings-local.d.ts +63 -0
  146. package/dist/external-findings-local.d.ts.map +1 -0
  147. package/dist/external-findings-local.js +344 -0
  148. package/dist/external-findings-local.js.map +1 -0
  149. package/dist/external-findings-publish.d.ts +73 -0
  150. package/dist/external-findings-publish.d.ts.map +1 -0
  151. package/dist/external-findings-publish.js +721 -0
  152. package/dist/external-findings-publish.js.map +1 -0
  153. package/dist/external-findings-read.d.ts +16 -0
  154. package/dist/external-findings-read.d.ts.map +1 -0
  155. package/dist/external-findings-read.js +97 -0
  156. package/dist/external-findings-read.js.map +1 -0
  157. package/dist/external-findings.d.ts +21 -0
  158. package/dist/external-findings.d.ts.map +1 -0
  159. package/dist/external-findings.js +2 -0
  160. package/dist/external-findings.js.map +1 -0
  161. package/dist/external-import-contract.d.ts +15 -0
  162. package/dist/external-import-contract.d.ts.map +1 -0
  163. package/dist/external-import-contract.js +262 -0
  164. package/dist/external-import-contract.js.map +1 -0
  165. package/dist/external-import-models.d.ts +362 -0
  166. package/dist/external-import-models.d.ts.map +1 -0
  167. package/dist/external-import-models.js +3 -0
  168. package/dist/external-import-models.js.map +1 -0
  169. package/dist/external-imports-feature.d.ts +6 -0
  170. package/dist/external-imports-feature.d.ts.map +1 -0
  171. package/dist/external-imports-feature.js +51 -0
  172. package/dist/external-imports-feature.js.map +1 -0
  173. package/dist/finding-workflow.d.ts +23 -6
  174. package/dist/finding-workflow.d.ts.map +1 -1
  175. package/dist/finding-workflow.js +23 -10
  176. package/dist/finding-workflow.js.map +1 -1
  177. package/dist/github-advisories.d.ts +386 -0
  178. package/dist/github-advisories.d.ts.map +1 -0
  179. package/dist/github-advisories.js +133 -0
  180. package/dist/github-advisories.js.map +1 -0
  181. package/dist/github-findings.d.ts +11 -0
  182. package/dist/github-findings.d.ts.map +1 -0
  183. package/dist/github-findings.js +258 -0
  184. package/dist/github-findings.js.map +1 -0
  185. package/dist/hosted-remediation-protocol.d.ts +2 -1
  186. package/dist/hosted-remediation-protocol.d.ts.map +1 -1
  187. package/dist/hosted-remediation-protocol.js +17 -11
  188. package/dist/hosted-remediation-protocol.js.map +1 -1
  189. package/dist/hosted-remediation.d.ts +4 -0
  190. package/dist/hosted-remediation.d.ts.map +1 -1
  191. package/dist/hosted-remediation.js +22 -3
  192. package/dist/hosted-remediation.js.map +1 -1
  193. package/dist/hosted-scan.d.ts +16 -0
  194. package/dist/hosted-scan.d.ts.map +1 -1
  195. package/dist/hosted-scan.js +9 -2
  196. package/dist/hosted-scan.js.map +1 -1
  197. package/dist/import-scan.js +1 -1
  198. package/dist/import-scan.js.map +1 -1
  199. package/dist/index.d.ts +16 -3
  200. package/dist/index.d.ts.map +1 -1
  201. package/dist/index.js +9 -1
  202. package/dist/index.js.map +1 -1
  203. package/dist/knowledge-base.d.ts +1 -0
  204. package/dist/knowledge-base.d.ts.map +1 -1
  205. package/dist/knowledge-base.js +17 -8
  206. package/dist/knowledge-base.js.map +1 -1
  207. package/dist/models.d.ts +1 -0
  208. package/dist/models.d.ts.map +1 -1
  209. package/dist/models.js.map +1 -1
  210. package/dist/owner-evidence.d.ts +2 -0
  211. package/dist/owner-evidence.d.ts.map +1 -1
  212. package/dist/owner-evidence.js +2 -1
  213. package/dist/owner-evidence.js.map +1 -1
  214. package/dist/project-config-schema.d.ts +2 -0
  215. package/dist/project-config-schema.d.ts.map +1 -1
  216. package/dist/project-config-schema.js +1 -0
  217. package/dist/project-config-schema.js.map +1 -1
  218. package/dist/project-config.d.ts +1 -0
  219. package/dist/project-config.d.ts.map +1 -1
  220. package/dist/project-config.js +2 -0
  221. package/dist/project-config.js.map +1 -1
  222. package/dist/publish.d.ts +2 -0
  223. package/dist/publish.d.ts.map +1 -1
  224. package/dist/publish.js +1 -1
  225. package/dist/publish.js.map +1 -1
  226. package/dist/remediation.d.ts +7 -25
  227. package/dist/remediation.d.ts.map +1 -1
  228. package/dist/remediation.js +18 -28
  229. package/dist/remediation.js.map +1 -1
  230. package/dist/result.d.ts +4 -0
  231. package/dist/result.d.ts.map +1 -1
  232. package/dist/result.js +10 -0
  233. package/dist/result.js.map +1 -1
  234. package/dist/runtime.d.ts +1 -0
  235. package/dist/runtime.d.ts.map +1 -1
  236. package/dist/runtime.js +10 -8
  237. package/dist/runtime.js.map +1 -1
  238. package/dist/scan-dashboard.d.ts +5 -3
  239. package/dist/scan-dashboard.d.ts.map +1 -1
  240. package/dist/scan-dashboard.js +79 -26
  241. package/dist/scan-dashboard.js.map +1 -1
  242. package/dist/scan-history-renderer.d.ts.map +1 -1
  243. package/dist/scan-history-renderer.js +8 -2
  244. package/dist/scan-history-renderer.js.map +1 -1
  245. package/dist/scan-owner-suggestions.d.ts +8 -0
  246. package/dist/scan-owner-suggestions.d.ts.map +1 -0
  247. package/dist/scan-owner-suggestions.js +33 -0
  248. package/dist/scan-owner-suggestions.js.map +1 -0
  249. package/dist/scan-settings.d.ts +1 -0
  250. package/dist/scan-settings.d.ts.map +1 -1
  251. package/dist/scan-settings.js +4 -0
  252. package/dist/scan-settings.js.map +1 -1
  253. package/dist/scan-usage-display.d.ts +8 -0
  254. package/dist/scan-usage-display.d.ts.map +1 -0
  255. package/dist/scan-usage-display.js +46 -0
  256. package/dist/scan-usage-display.js.map +1 -0
  257. package/dist/scanner-import.d.ts +20 -0
  258. package/dist/scanner-import.d.ts.map +1 -0
  259. package/dist/scanner-import.js +208 -0
  260. package/dist/scanner-import.js.map +1 -0
  261. package/dist/security-policy-diff.d.ts +2 -0
  262. package/dist/security-policy-diff.d.ts.map +1 -0
  263. package/dist/security-policy-diff.js +197 -0
  264. package/dist/security-policy-diff.js.map +1 -0
  265. package/dist/security-policy.d.ts +7 -3
  266. package/dist/security-policy.d.ts.map +1 -1
  267. package/dist/security-policy.js +11 -76
  268. package/dist/security-policy.js.map +1 -1
  269. package/dist/semgrep-findings.d.ts +10 -0
  270. package/dist/semgrep-findings.d.ts.map +1 -0
  271. package/dist/semgrep-findings.js +293 -0
  272. package/dist/semgrep-findings.js.map +1 -0
  273. package/dist/severity-review.d.ts +3 -0
  274. package/dist/severity-review.d.ts.map +1 -1
  275. package/dist/severity-review.js +19 -0
  276. package/dist/severity-review.js.map +1 -1
  277. package/dist/severity-store.js +7 -2
  278. package/dist/severity-store.js.map +1 -1
  279. package/dist/skill-authentication.d.ts +18 -0
  280. package/dist/skill-authentication.d.ts.map +1 -0
  281. package/dist/skill-authentication.js +82 -0
  282. package/dist/skill-authentication.js.map +1 -0
  283. package/dist/snyk-findings.d.ts +10 -0
  284. package/dist/snyk-findings.d.ts.map +1 -0
  285. package/dist/snyk-findings.js +350 -0
  286. package/dist/snyk-findings.js.map +1 -0
  287. package/dist/suggest-owners.d.ts +4 -1
  288. package/dist/suggest-owners.d.ts.map +1 -1
  289. package/dist/suggest-owners.js +53 -21
  290. package/dist/suggest-owners.js.map +1 -1
  291. package/dist/targets.d.ts +2 -2
  292. package/dist/targets.d.ts.map +1 -1
  293. package/dist/targets.js +16 -3
  294. package/dist/targets.js.map +1 -1
  295. package/dist/wiz-csv.d.ts +9 -0
  296. package/dist/wiz-csv.d.ts.map +1 -0
  297. package/dist/wiz-csv.js +116 -0
  298. package/dist/wiz-csv.js.map +1 -0
  299. package/dist/wiz-findings.d.ts +5 -0
  300. package/dist/wiz-findings.d.ts.map +1 -0
  301. package/dist/wiz-findings.js +464 -0
  302. package/dist/wiz-findings.js.map +1 -0
  303. package/docs/classify-severity-records.md +30 -13
  304. package/docs/cli.md +835 -47
  305. package/docs/findings-service.md +119 -118
  306. package/docs/hosted-remediation.md +43 -24
  307. package/docs/hosted-scans.md +38 -0
  308. package/package.json +11 -9
  309. package/schemas/external-findings.schema.json +1421 -0
  310. package/schemas/project-config.schema.json +4 -0
  311. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  312. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  313. package/_bundled_plugin/scripts/rank_preview.py +0 -129
package/docs/cli.md CHANGED
@@ -23,6 +23,28 @@ findings file in local scan history, use
23
23
  GitHub import returns upstream alerts for validation; file import saves findings
24
24
  without running security analysis.
25
25
 
26
+ ## Find a workflow
27
+
28
+ - [Sign in or configure a provider](#authentication).
29
+ - [Scan a repository or selected paths](#scan-options-and-output),
30
+ [configure a Deep Scan](#configure-deep-scans), or
31
+ [save project settings](#project-files).
32
+ - [Review one system across repositories](#review-one-system-across-repositories)
33
+ or [run independent bulk scans](#bulk-scans).
34
+ - [Import vendor findings locally](#import-vendor-findings-locally),
35
+ [save findings as a scan](#import-findings-as-a-saved-scan), or
36
+ [retrieve GitHub alerts](#import-alerts-from-the-cli).
37
+ - [Inspect saved scans and rerun them](#scan-history-and-reruns),
38
+ [classify severity](#classify-finding-severity), or
39
+ [suggest owners](#suggest-finding-owners).
40
+ - [Validate and patch findings](#validate-and-patch-findings) or
41
+ [verify an existing fix](#verify-fixes).
42
+ - [Publish to Cloud](#publish-findings-to-cloud) or
43
+ [Linear](#publish-completed-scans-to-linear), or [export results](#exports-and-ci).
44
+ - [Draft a security policy](#generate-a-security-policy).
45
+ - [Use a hosted executor](#hosted-standard-scan) or
46
+ [run bulk scans in containers](#containerized-bulk-scans).
47
+
26
48
  ## Authentication
27
49
 
28
50
  Sign in with ChatGPT, or supply an API key for CI:
@@ -377,7 +399,16 @@ try {
377
399
  `preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
378
400
  in-memory draft and escapes terminal controls; editing its saved file does not
379
401
  change that object. `securityPolicyDiff()` returns a raw diff for files and other
380
- non-terminal uses, with an optional Python interpreter.
402
+ non-terminal uses. Both preview methods compute the diff in Node without
403
+ discovering or launching Python; `pythonPath` and `PYTHON` do not affect previews.
404
+
405
+ The optional second argument to `securityPolicyDiff(draft, python, signal)` is
406
+ deprecated. Interpreter paths, including paths returned by a resolver callback,
407
+ no longer select an executable or get validated. For compatibility, an explicitly
408
+ supplied resolver is still awaited when the draft changes, and any error it throws
409
+ propagates. Omit that argument for new code, or pass `undefined` when supplying a
410
+ cancellation signal. Source freshness is checked before and after computing the
411
+ diff.
381
412
 
382
413
  `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
383
414
  `maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
@@ -391,9 +422,15 @@ codex-security scan .
391
422
  codex-security scan . --path src --path tests
392
423
  codex-security scan . --diff origin/main --json
393
424
  codex-security scan . --working-tree
425
+ codex-security scan . --owner-suggestions
394
426
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
395
427
  ```
396
428
 
429
+ `--path` selects files or directories. The scan summary and saved scan details
430
+ show requested paths and exclusions. `coverage.deferred` records unfinished
431
+ requested work separately from optional `coverage.openQuestions` follow-up.
432
+ Human-readable output quotes ambiguous paths, while JSON retains their original strings.
433
+
397
434
  Whole-codebase and path scans also accept ordinary directories, including SVN
398
435
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
399
436
 
@@ -402,6 +439,21 @@ changes. Both require Git. Deep scans support whole repositories and path scopes
402
439
  Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
403
440
  be clean and at the commit recorded by the parent.
404
441
 
442
+ Committed-diff scans require a clean, full checkout at the requested head
443
+ revision, including when using `--validate`. A different checkout revision or
444
+ local changes are rejected before scanning; check out the requested head and
445
+ commit or stash local changes before retrying.
446
+
447
+ `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
448
+ committed Git scan, using the same checkout, model, and reasoning effort. Owner
449
+ errors leave the base scan completed. The JSON result includes
450
+ `ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
451
+ manifest stay unchanged. This option is unsupported for working-tree and
452
+ directory snapshots. It works with `--max-cost`: hints are recorded within the
453
+ existing scan execution and budget, and the report is finalized without another
454
+ model call. Missing hints abstain; invalid hints produce per-finding owner errors.
455
+ Use the separate `suggest-owners` command for explicit owner-only jobs.
456
+
405
457
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
406
458
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
407
459
  explicit unsupported binary files are rejected. Bulk scans share this context
@@ -470,6 +522,38 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
470
522
  its successful output and failure codes.
471
523
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
472
524
 
525
+ ### Follow-up finding validation
526
+
527
+ Scans already validate findings against local source. Add `--validate` to run
528
+ the existing standalone validation workflow for each reported finding after
529
+ the scan, using the same selected Cyber access program. Validation has read-only
530
+ filesystem access with network and web search disabled. Each assessment uses a
531
+ separate evidence directory; the combined report is saved as
532
+ `<scan-dir>/validation.md`, or a uniquely suffixed report
533
+ if that path already exists. Each completed assessment is saved immediately;
534
+ failed or interrupted runs retain the partial report. JSON scan output includes
535
+ the execution status, completed assessment count, and report path. Completion means the assessments finished,
536
+ not that every finding was confirmed. A scan with no findings needs no second
537
+ pass.
538
+
539
+ With `--workflow-id`, retries reuse completed assessments for unchanged findings,
540
+ source, validation settings, and saved evidence. Missing or changed evidence
541
+ causes validation to run again, as do older assessments without recorded evidence
542
+ fingerprints. By default, regeneration uses a new evidence directory. An explicit
543
+ SDK validation `outputDir` reuses an assessment only when it points to the same
544
+ evidence directory. A different destination starts a new assessment. The requested
545
+ directory must be empty when regenerating; existing files are never overwritten.
546
+ When `--knowledge-base` is supplied, the scan and all follow-up assessments use
547
+ one captured copy of those documents. A workflow retry must use the same document
548
+ contents. Use a new workflow ID if they changed or if the workflow was created
549
+ before document snapshots were bound to follow-up validation.
550
+
551
+ The report is supplemental: its assessments are not applied to the saved
552
+ findings or the `--fail-on-severity` decision. Validation failures exit with
553
+ `2` while retaining the completed scan. The additional model calls are not
554
+ cost-tracked, so `--validate` cannot be combined with `--max-cost` (including a
555
+ configured scan cost limit), `--dry-run`, or `--mock`.
556
+
473
557
  ### Understand scan scope and follow-up work
474
558
 
475
559
  A completed scan means the requested workflow finished. It does not mean every
@@ -590,6 +674,9 @@ Import needs no model calls or authentication. `--dry-run` validates without
590
674
  saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
591
675
  reimports the retained input.
592
676
 
677
+ For vendor exports, use [local vendor import](#import-vendor-findings-locally)
678
+ instead. That flow retains unassessed source evidence without creating a scan.
679
+
593
680
  ### Generate mock scan results
594
681
 
595
682
  ```bash
@@ -719,16 +806,9 @@ not to planning, result matching, or the total campaign.
719
806
 
720
807
  ### Configure deep scans
721
808
 
722
- ```ts
723
- await security.run("/path/to/repository", {
724
- mode: "deep",
725
- workers: 2,
726
- subagents: 0,
727
- stopAfterNoNew: 3,
728
- stopAfterConsecutiveErrors: 2,
729
- maxDiscoveryRuns: 10,
730
- maxTimeMinutes: 90,
731
- });
809
+ ```bash
810
+ codex-security scan . --mode deep --workers 2 --subagents 0 \
811
+ --stop-after-no-new 3 --max-discovery-runs 10 --max-time 90
732
812
  ```
733
813
 
734
814
  For `scan --mode deep`, `--workers` controls discovery concurrency and
@@ -737,11 +817,13 @@ For `scan --mode deep`, `--workers` controls discovery concurrency and
737
817
  or duration. At the deadline, discovery stops; the scan then combines and returns
738
818
  completed findings.
739
819
 
820
+ For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
821
+
740
822
  Use project-file `scan.deep` settings or legacy
741
823
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
742
824
  that `subagents` can be zero. Discovery time accepts positive fractional minutes;
743
- its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
744
- advisory allowance, this existing Deep discovery limit is enforced. Resuming a
825
+ its default and maximum are 5760 minutes (96 hours). Unlike Standard's
826
+ advisory allowance, the Deep discovery limit is enforced. Resuming a
745
827
  Deep scan keeps its original deadline; rerunning starts a new scan.
746
828
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
747
829
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
@@ -857,24 +939,27 @@ For filesystem and approval behavior, see the
857
939
 
858
940
  ### Environment variables
859
941
 
860
- | Variable | Effect |
861
- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
862
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
863
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
864
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
865
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
866
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
867
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
868
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
869
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
870
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
871
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
872
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
873
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
874
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
875
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
876
- | `CI` | Disable interactive update notices. |
877
- | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
942
+ | Variable | Effect |
943
+ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
944
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
945
+ | `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS` | Set to `1` to enable vendor finding imports, imported-findings readback, and GitHub advisory acquisition; disabled otherwise. |
946
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
947
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
948
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
949
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
950
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
951
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
952
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
953
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
954
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
955
+ | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
956
+ | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
957
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
958
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
959
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
960
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
961
+ | `CI` | Disable interactive update notices. |
962
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
878
963
 
879
964
  Custom Codex executables need thread source attribution for `exec` and
880
965
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -939,6 +1024,14 @@ work could not be measured, including in-flight turns or missing earlier attempt
939
1024
  The parent can continue after report completion, so final CLI tokens can exceed
940
1025
  the saved measurement window.
941
1026
 
1027
+ During a scan, progress shows when Codex reported the displayed token and cost
1028
+ totals, in UTC. If the report has no timestamp, progress says so.
1029
+ In-flight requests may add tokens and cost after that time. When Codex supplies
1030
+ account allowance, progress shows the percentage used in each reported window
1031
+ and the time of that reading. On a short terminal, resize the window or press
1032
+ `d` to scroll through the full readings in Details. With ChatGPT authentication,
1033
+ progress also says when Codex has yet to report allowance.
1034
+
942
1035
  `usage.accountRateLimits` saves the latest observed account-wide readings with
943
1036
  their own timestamps, window durations, and reset times. These are historical
944
1037
  observations, not a live allowance check or scan-only consumption. Empty readings
@@ -1173,8 +1266,502 @@ failure or incomplete/invalid output fails the scan. Deferred candidates remain
1173
1266
  follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
1174
1267
  Supply the validation prompt again when rerunning.
1175
1268
 
1269
+ ## Import vendor findings locally
1270
+
1271
+ External finding imports are disabled by default. Opt in for the current shell:
1272
+
1273
+ ```bash
1274
+ export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
1275
+ ```
1276
+
1277
+ In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
1278
+ Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
1279
+ and `import github-advisories` are absent from command help and schemas and cannot
1280
+ run. The SDK's external publication, local import/readback, and advisory
1281
+ acquisition APIs require the same flag in their effective environment. An explicit
1282
+ `dependencies.environment` is used instead of the process environment. Pure
1283
+ normalizers and file readers remain available as library utilities.
1284
+
1285
+ This flag does not affect `publish scan`, `publish check`, `scan import`, or the
1286
+ existing `import github` alert collector. Disabling it retains previously imported
1287
+ records; enable it again to read them with `findings imported`.
1288
+
1289
+ Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
1290
+ reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
1291
+ inputs only for providers and report profiles that support them. A JSON API
1292
+ summary is not automatically a supported report; follow the provider's acquisition
1293
+ instructions and retain the original records. The readers detect supported input
1294
+ formats; `--format json` selects command output, not the input format.
1295
+
1296
+ Keep the acquisition format consistent across imports. Depending on the provider,
1297
+ switching formats can create separate records for the same vulnerability or
1298
+ replace a richer evidence snapshot with less detail. The importer does not merge
1299
+ evidence or deduplicate equivalent vulnerabilities across different source IDs.
1300
+
1301
+ Use the same vendor input and parser as Cloud publication, selecting a local
1302
+ repository path instead of a Cloud repository ID or URL. Supported inputs include
1303
+ Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
1304
+ [Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
1305
+ [Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
1306
+ and [saved GitHub alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
1307
+
1308
+ ```bash
1309
+ codex-security publish findings selected-wiz.json \
1310
+ --to local --repository ./project --provider wiz \
1311
+ --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1312
+ ```
1313
+
1314
+ Review the normalized evidence, repository, source namespace, and exclusions.
1315
+ Run the same command without `--dry-run` to confirm interactively, or add `--yes`
1316
+ after reviewing the preview. `--to` is required; there is no default destination.
1317
+ Local import uses the workbench SQLite database and requires no Cloud login,
1318
+ network connection, or model call. `--dry-run` does not write findings.
1319
+
1320
+ Read the saved evidence with:
1321
+
1322
+ ```bash
1323
+ codex-security findings imported ./project --format json
1324
+ ```
1325
+
1326
+ The repository argument defaults to the current directory. Local imports are
1327
+ separate from the assessed findings shown by `findings list`: they remain
1328
+ `not_assessed`, retain the original vendor evidence, and do not create a completed
1329
+ scan or automatically validate or patch findings. Missing revisions, locations,
1330
+ and assessment fields stay unknown. When the source includes a repository URL and the local checkout has configured
1331
+ Git remotes, the URL must match one of those remotes; the importer does not
1332
+ substitute the checkout's current commit for an unknown scanner revision.
1333
+
1334
+ Repeated imports update the same record by repository, provider, source key, and
1335
+ source finding ID. The result reports created, updated, and unchanged counts.
1336
+ Keep the source key stable across exports. Records omitted from a later selection
1337
+ remain stored; omission does not resolve or delete a finding. Excluded records
1338
+ are reported, and an import with exclusions exits with status 1. The same
1339
+ supported vendor formats and evidence requirements apply locally and in Cloud.
1340
+
1341
+ `scan import --json` and `scan import --csv` remain separate commands for importing
1342
+ Codex Security's findings schema as a saved scan; they do not accept vendor
1343
+ exports.
1344
+
1345
+ ## Import Endor Labs findings
1346
+
1347
+ For local or Cloud import, prefer complete native Finding JSON from authenticated
1348
+ `endorctl`, scoped to one project and context. Omit `--field-mask` and use
1349
+ `--list-all` to finish pagination:
1350
+
1351
+ ```sh
1352
+ endorctl api list --resource Finding --namespace "YOUR_NAMESPACE" \
1353
+ --filter 'context.type==CONTEXT_TYPE_MAIN and spec.project_uuid=="PROJECT_UUID"' \
1354
+ --list-all --output-type json > endor-findings.json
1355
+ codex-security publish findings endor-findings.json --to local \
1356
+ --provider endor --repository ./project \
1357
+ --source-key "YOUR_NAMESPACE/PROJECT_UUID/main" --dry-run
1358
+ ```
1359
+
1360
+ Replace the example namespace, project UUID and local repository with your selection.
1361
+ Review the preview, remove `--dry-run` to confirm, then read the stored evidence
1362
+ with `codex-security findings imported ./project --format json`. To publish to
1363
+ Cloud instead, use `--to cloud --repository "CLOUD_REPOSITORY_ID"` with the same
1364
+ file, provider and source key. The official
1365
+ [Endor Labs Agent Kit for Codex](https://github.com/endorlabs/ai-plugins/tree/main/plugins/codex/endor-labs-agent-kit)
1366
+ can help with setup and investigation, but summaries, counts and field-masked
1367
+ results do not replace complete Finding objects. `endorctl` reads the Endor API;
1368
+ the importer reads the saved export without maintaining an API connection or
1369
+ writing changes back to Endor.
1370
+
1371
+ Native JSON retains severity, package and advisory data, primary SAST/AI SAST
1372
+ locations and the scanned commit. Existing self-contained endorctl SARIF 2.1.0
1373
+ reports are a lossy compatibility format, retaining finding links and UUIDs;
1374
+ unavailable severity and revisions stay unknown. Both formats use the Endor UUID
1375
+ within the selected repository and stable source key as identity. Importing SARIF
1376
+ after native JSON for that UUID updates the same record by replacing its evidence
1377
+ snapshot, not merging it. Native detail absent from SARIF is removed from the
1378
+ snapshot. Use native JSON consistently for ongoing imports.
1379
+
1380
+ Local and Cloud records remain unassessed source evidence. Local imports use the
1381
+ SQLite readback described above; Cloud imports use the login, preview,
1382
+ confirmation and retry flow below.
1383
+
1176
1384
  ## Publish findings to Cloud
1177
1385
 
1386
+ ### Import Snyk Open Source findings
1387
+
1388
+ Import **Open Source SCA vulnerabilities only**. Licenses, Code, Container, IaC,
1389
+ SBOM results and platform backlog ingestion are outside this adapter.
1390
+
1391
+ Use the [official Snyk Codex plugin](https://github.com/snyk/studio-recipes/tree/main/plugins/codex)
1392
+ with its `snyk-findings-export` skill to collect SCA findings from the repository's
1393
+ Git root. It runs a fresh local scan and writes a `snyk-findings-export/v1` bundle;
1394
+ it does not retrieve existing platform project findings.
1395
+
1396
+ The same saved bundle supports [local import](#import-vendor-findings-locally)
1397
+ without a Cloud login:
1398
+
1399
+ ```sh
1400
+ codex-security publish findings snyk-findings.json --to local \
1401
+ --provider snyk --repository ./project \
1402
+ --source-key github.com/example/project/main/root/plugin-sca --dry-run
1403
+ ```
1404
+
1405
+ Or preview publication to a connected Cloud repository:
1406
+
1407
+ ```sh
1408
+ codex-security publish findings snyk-findings.json --to cloud \
1409
+ --provider snyk --repository https://github.com/example/project \
1410
+ --source-key github.com/example/project/main/root/plugin-sca --dry-run
1411
+ ```
1412
+
1413
+ Check the collection's scan outcomes and limitations. Only Open Source SCA
1414
+ vulnerabilities are imported; other products and licenses are explicit exclusions.
1415
+ The importer retains the selected finding, native MCP record and collection
1416
+ context. MCP may shorten descriptions and omit dependency paths. Plugin paths
1417
+ remain in original evidence because v1 lacks their offset from the Git root.
1418
+
1419
+ For automation, prefer native JSON from
1420
+ `snyk test --file=package.json --json-file-output=snyk.json`. Exit 1 means findings;
1421
+ stop on other nonzero exits before importing. The existing `--provider snyk`
1422
+ autodetects a single project object or an `--all-projects` array; any project error
1423
+ stops the import. Use default ungrouped output, without `--group-issues`.
1424
+ Native JSON preserves individual dependency paths and remediation fields. Its
1425
+ paths remain original evidence because it does not establish their Git-root offset.
1426
+
1427
+ Open Source SARIF from `snyk test --sarif-file-output=snyk.sarif` remains supported
1428
+ for compatibility. Its target-relative manifest paths and synthetic line numbers
1429
+ remain original evidence, without being projected as repository locations or
1430
+ package manifest paths. All three formats accept either destination. Use a consistent
1431
+ format and stable source key per repository, branch and scan target, for example
1432
+ `github.com/example/project/main/root/native-sca` for native JSON. Their source
1433
+ identities differ: use separate keys when switching acquisition formats. Imports
1434
+ do not deduplicate across formats or remove earlier imported records.
1435
+
1436
+ Known repository claims must
1437
+ match the selected Cloud repository or, when available, a configured local Git
1438
+ remote. Unknown repository context still requires selecting the correct target;
1439
+ the importer does not infer provenance from the current checkout.
1440
+
1441
+ Remove `--dry-run` from the selected command to review and confirm the import, or
1442
+ use `--yes` after reviewing the preview. Read local records with
1443
+ `codex-security findings imported ./project --format json`. Imported source
1444
+ evidence is not a Codex assessment. No Snyk-side triage state is changed. See the
1445
+ [Snyk import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) for format limits and
1446
+ acquisition details.
1447
+
1448
+ ### Import Wiz findings
1449
+
1450
+ Import selected Wiz package vulnerabilities, SAST findings, repository secrets,
1451
+ and IaC findings without creating a scan. Imported records retain vendor evidence
1452
+ and remain **not assessed by Codex**, including when Wiz marks them resolved or
1453
+ reports an AI verdict. Workload secrets, cloud configuration findings, and external
1454
+ network findings are not supported by this repository importer. Cloud destinations
1455
+ currently support connected GitHub and GitHub Enterprise repositories, including
1456
+ custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
1457
+
1458
+ #### Select findings and a destination
1459
+
1460
+ Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
1461
+ connection to acquire findings and save the supported native JSON. A configured
1462
+ plugin may provide that connection; an official Codex plugin is not a prerequisite.
1463
+ The publisher reads the saved records. It does not fetch from Wiz or require a
1464
+ manual website download. The acquisition path still needs validation against
1465
+ actual responses from an authorized Wiz tenant; local parser checks do not
1466
+ establish that qualification.
1467
+
1468
+ Inspect the connection's actual response before importing it. MCP summaries,
1469
+ Wiz Issues, and local Wiz CLI scan results are not automatically compatible with
1470
+ this finding mapper. Keep the original occurrence IDs and evidence; use the
1471
+ named collections below when the response contains repository findings.
1472
+
1473
+ Before the first import:
1474
+
1475
+ 1. Select an existing repository in Codex Security Cloud and copy its URL or
1476
+ Cloud repository ID. The repository needs an
1477
+ authorized environment, but does not need a completed native scan.
1478
+ 2. Read the selected records through the authorized connection and save their
1479
+ JSON. For **package vulnerabilities**, include `id`, `name`, `detailedName`,
1480
+ `vendorSeverity` (or `severity`), and `vulnerableAsset.id`; retain available
1481
+ package, image, and source metadata. For SAST, repository secrets, and IaC,
1482
+ retain the named API collections and repository metadata described below.
1483
+ Complete the selected pages before importing; a summary or unfinished page
1484
+ is not a complete finding selection.
1485
+ 3. Choose a stable source key such as `TENANT_ID/vulnerability-finding`. Reuse it
1486
+ for that Wiz tenant and finding class across exports. Do not create a new key
1487
+ for each project filter or import; that creates different source identities.
1488
+ 4. Check the ChatGPT account used by your existing file-backed Codex Security
1489
+ login. API-key-only and keyring-only logins are not supported for Cloud
1490
+ publication. See the credential-storage instructions below.
1491
+
1492
+ Prefer the supported native JSON. Existing package-vulnerability CSV reports are
1493
+ accepted as a compatibility input. **CSV support covers repository package
1494
+ vulnerabilities (SCA) only; it does not add SAST, cloud posture (CSPM), or complete
1495
+ Wiz code-to-cloud coverage.** The named JSON readers described below handle their
1496
+ respective finding families separately.
1497
+
1498
+ When a UI report is needed, retain the repository and finding filters in Wiz
1499
+ **Vulnerability Findings**, choose **Save as → Report**, select **Repository
1500
+ Branch**, **JSON** or **CSV**, and **Detailed** columns, then download the completed
1501
+ report. CSV must use the columns described below and a comma delimiter. Plain and
1502
+ gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
1503
+ filename extension. **Raw Event** on Code & Build Scans contains scan metadata
1504
+ rather than findings.
1505
+
1506
+ #### Configure an alternate Cloud deployment
1507
+
1508
+ For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
1509
+ API root before previewing or uploading, for example
1510
+ `https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
1511
+ HTTP is accepted only for loopback development (`localhost`, `127.0.0.0/8`, or
1512
+ `::1`). Use a login issued by that deployment and an isolated
1513
+ `CODEX_SECURITY_STATE_DIR` for testing. The endpoint
1514
+ does not change your login or sign you into another deployment. An invalid or
1515
+ empty configured URL stops the import before authentication or network requests.
1516
+ With the variable unset, the existing production endpoint remains the default.
1517
+ The older `CODEX_SECURITY_CLOUD_PUBLISH_URL` overrides only the final native scan
1518
+ publication endpoint; it does not route vendor imports.
1519
+
1520
+ If that deployment serves its UI separately, set `CODEX_SECURITY_CLOUD_WEB_URL`
1521
+ to the full Cloud app URL shown in the browser. The import handoff supplies both
1522
+ deployment settings. The preview and result include a repository-specific
1523
+ `cloudUrl`, and terminal completion prints the link. This setting only controls
1524
+ the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
1525
+ For custom API destinations without a configured app URL, completion retains
1526
+ the manual navigation guidance rather than guessing a UI host or port.
1527
+
1528
+ #### Preview and publish
1529
+
1530
+ Preview the selection and destination:
1531
+
1532
+ ```bash
1533
+ codex-security publish findings selected-wiz.json \
1534
+ --to cloud --repository https://github.com/example/project --provider wiz \
1535
+ --source-key TENANT_ID/vulnerability-finding --dry-run --format json
1536
+ ```
1537
+
1538
+ `--repository` accepts the repository's URL or ID. Both resolve to the same Cloud
1539
+ destination and resume the same saved submission. This command reads the
1540
+ authorized destination and current source versions during
1541
+ preview. It uses the same saved ChatGPT file login as scan publication. The Cloud
1542
+ repository needs an existing environment; no native scan is required. Review the
1543
+ Cloud API endpoint, account, repository, environments, findings, and exclusions,
1544
+ then rerun without
1545
+ `--dry-run`. The default terminal prompt is No; `--yes` confirms a previously
1546
+ reviewed input for scripts or the plugin. Without a terminal or `--yes`, no upload
1547
+ occurs. Existing source findings keep their Cloud environment; new findings use
1548
+ the repository’s current authorized default. Preview shows the environments that
1549
+ will receive the selected findings. The terminal preview summarizes severities,
1550
+ shows up to five finding IDs and titles, and identifies the evidence file and
1551
+ exclusions. `--dry-run --format json` retains all normalized findings and complete
1552
+ evidence for inspection. A prompt explicitly includes any records that will be
1553
+ skipped.
1554
+
1555
+ #### Package vulnerability inputs
1556
+
1557
+ Native package input can be a Wiz JSON vulnerability report, a vulnerability
1558
+ finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1559
+ with one package record per line. The repository package-vulnerability CSV
1560
+ profile below is also supported. Plain and gzip-compressed files are accepted.
1561
+ A response that advertises another page is rejected. Complete the requested pages
1562
+ or save only the explicitly selected records; retain the named collection for
1563
+ SAST, repository secrets, and IaC.
1564
+
1565
+ The CSV mapper requires `ID`, `Name`, `DetailedName`, `AssetID`, `WizURL`,
1566
+ `CloudPlatform`, and `CloudProviderURL`. Check the actual report headers against
1567
+ this profile; other Wiz report types use different fields.
1568
+ For repository imports, `CloudPlatform` must identify GitHub and
1569
+ `CloudProviderURL` must identify a repository branch. The repository URL must
1570
+ match the selected Cloud repository or, for local import, one of the checkout's
1571
+ Git remotes when configured. This also applies when the parsed findings are saved and
1572
+ read again as normalized JSONL. Other resource types are excluded.
1573
+
1574
+ CSV imports use `ID` as the occurrence identity and retain every parsed field,
1575
+ including unknown columns and quoted multiline values, in `source_data.row`.
1576
+ Severity comes from `Severity`, then `VendorSeverity`, then `CVSSSeverity`.
1577
+ Vendor resolution status stays in the original evidence. The importer does not
1578
+ derive a branch or revision from a tree URL, or treat last-detected time as a
1579
+ record-update timestamp. Duplicate headers, damaged CSV rows, invalid UTF-8,
1580
+ and duplicate occurrence IDs among otherwise importable records stop the import.
1581
+ Review any excluded records in the preview before publishing.
1582
+
1583
+ Normalized JSONL is also accepted:
1584
+
1585
+ ```json
1586
+ {
1587
+ "source_finding_id": "vendor-finding-42",
1588
+ "evidence": {
1589
+ "title": "Vulnerable example package",
1590
+ "severity": "high",
1591
+ "source_data": { "id": "vendor-finding-42" }
1592
+ }
1593
+ }
1594
+ ```
1595
+
1596
+ Use Wiz's finding `id` (`ID` in CSV), not a CVE, as identity. Keep the source key stable across
1597
+ exports; a selected project filter does not change the vendor namespace. Confirm
1598
+ that the selected assets or builds map to this repository. The raw Wiz adapter
1599
+ retains each record in `source_data`, uses reported severity, and leaves unknown
1600
+ branch/revision empty. Repository-branch findings retain their repository-relative
1601
+ file paths; container and other workload paths remain vendor evidence rather than
1602
+ source-code locations. It does not
1603
+ fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1604
+ Findings from external network scans are excluded from this package vulnerability
1605
+ mapping.
1606
+
1607
+ #### SAST, repository secrets, and IaC inputs
1608
+
1609
+ For SAST, repository secrets, and IaC, save the documented JSON API collection:
1610
+
1611
+ | Finding family | Collection | Raw occurrence identity |
1612
+ | ------------------ | ---------------------------- | ----------------------- |
1613
+ | SAST | `data.sastFindings.nodes` | `sast:<id>` |
1614
+ | Repository secrets | `data.secretInstances.nodes` | `secret:<id>` |
1615
+ | IaC | `data.iacFindings.nodes` | `iac:<id>` |
1616
+
1617
+ The collection identifies the mapping. Bare arrays of these raw findings are
1618
+ excluded because their overlapping fields do not identify a family. An export
1619
+ may contain multiple named collections. GraphQL errors and unfinished pages stop
1620
+ the import. Secret resources must have `type: "REPOSITORY_BRANCH"`; a workload's
1621
+ relationship to source code does not make it a repository secret.
1622
+
1623
+ Each new finding needs a verified source repository URL. Supply `repository.url`
1624
+ in the finding's repository metadata, or include the matching repository inventory
1625
+ in `data.versionControlResources.nodes`. For secrets, repository metadata is under
1626
+ `resource.typedProperties.repository`. The importer joins the inventory's
1627
+ `repository.id` to that source ID and uses `repository.url`; inventory node IDs,
1628
+ `providerID`, names, and Wiz UUIDs are not Cloud repository IDs. A supplied URL
1629
+ must agree with the inventory and with the selected Cloud repository before any
1630
+ finding is uploaded. Keep each inventory node's `platform` field: `GITHUB`
1631
+ establishes case-insensitive repository matching on custom GitHub Enterprise
1632
+ hosts. Fresh imports preserve the reported branch name literally. Duplicate
1633
+ entries for one repository ID must agree on their platform and repository URL.
1634
+ For example, this synthetic selection supplies the inventory alongside its SAST
1635
+ collection:
1636
+
1637
+ ```json
1638
+ {
1639
+ "data": {
1640
+ "sastFindings": {
1641
+ "nodes": [
1642
+ {
1643
+ "id": "finding-42",
1644
+ "name": "Untrusted query construction",
1645
+ "severity": "HIGH",
1646
+ "repository": { "id": "source-repository-1" },
1647
+ "filePath": "src/query.ts",
1648
+ "startLine": 10,
1649
+ "endLine": 12
1650
+ }
1651
+ ]
1652
+ },
1653
+ "versionControlResources": {
1654
+ "nodes": [
1655
+ {
1656
+ "repository": {
1657
+ "id": "source-repository-1",
1658
+ "url": "https://github.com/example/project"
1659
+ }
1660
+ }
1661
+ ]
1662
+ }
1663
+ }
1664
+ }
1665
+ ```
1666
+
1667
+ #### Preserved evidence
1668
+
1669
+ The adapters preserve each selected raw node exactly in `source_data`. Typed
1670
+ `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1671
+ and family-specific evidence:
1672
+
1673
+ | Family | Evidence retained in typed fields |
1674
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1675
+ | SAST | CWE IDs, first location's end line and snippet, scanner origin and verdict, remediation instructions |
1676
+ | Repository secrets | Detector rule, type, confidence, vendor validation status, encryption/management flags, introduced commit when supplied |
1677
+ | IaC | Rule IDs and name, first location's range and matched content, platform, expected/actual content, separate file link, remediation instructions |
1678
+
1679
+ Vendor status and verdict remain separate from Codex assessment. A secret's
1680
+ introduced commit is not its scanned revision. Missing source revisions and scan
1681
+ IDs stay unknown. A logical IaC resource is retained in the original record and
1682
+ does not establish that it is deployed. Precise original timestamps remain in
1683
+ `source_data`; only an explicit record-update timestamp maps to the whole-second
1684
+ `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1685
+ timestamps.
1686
+
1687
+ #### Convert CSV reports
1688
+
1689
+ Native SAST and secret report downloads can be CSV, including gzip-compressed
1690
+ CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1691
+ for its actual column headers into normalized JSONL, preserving each original row
1692
+ in `source_data`. Set `details.kind` and `details.repository.url` explicitly after
1693
+ verifying the source repository. Use the same prefixed occurrence ID shown above
1694
+ so API and report imports update the same finding; normalized IDs are accepted
1695
+ exactly as supplied. Never substitute a rule ID, CWE, title, token, or file path
1696
+ for a vendor occurrence ID. Missing IDs or severity must be corrected at the
1697
+ source rather than invented.
1698
+
1699
+ For repository-secret reports, select `path` and `lineNumber` for source
1700
+ navigation, detector fields under `rule`, and `vcsDetails.initialCommitHash` only
1701
+ as the introduced commit. The standard secret metadata API does not supply a
1702
+ path or line. For IaC reports, explicitly select `filePath`, `startLine`, `endLine`,
1703
+ `rule.id`, `rule.shortId`, `expectedContent`, `foundContent`, `matchContent`, and
1704
+ repository/branch metadata. Preserve the original fields; source locations must
1705
+ be repository-relative, and an end line requires a start line. Keep credential
1706
+ values out of the metadata selection; the importer does not retrieve or test
1707
+ credentials or apply remediation instructions.
1708
+
1709
+ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1710
+ integer range is rejected; export those values as strings to preserve them
1711
+ exactly. Invalid records appear in `excluded` with their source ID and reason.
1712
+
1713
+ #### Resume interrupted imports
1714
+
1715
+ Requests contain at most 100 findings and respect the Cloud payload limits.
1716
+ Before uploading, the publisher saves request IDs and bodies privately under
1717
+ the configured Codex Security state directory. After an uncertain response,
1718
+ repeat the same command with unchanged input and Cloud API endpoint to resume those
1719
+ requests. Different deployments have separate saved submissions, including when
1720
+ their account and repository IDs match. The preview and result include
1721
+ `cloudApiUrl` so scripts can verify which API received the findings; this is an
1722
+ API endpoint, not a link to the Cloud UI. A reset
1723
+ retires the old request without republishing; review and explicitly approve a
1724
+ fresh invocation.
1725
+
1726
+ #### Results and exit codes
1727
+
1728
+ Results distinguish completion from partial or interrupted work:
1729
+
1730
+ | Status | Exit code | Meaning |
1731
+ | ------------- | --------- | -------------------------------------------------------------------------------------------------- |
1732
+ | `complete` | 0 | All selected records were acknowledged and their source records read back. |
1733
+ | `partial` | 1 | The import finished, but some records were excluded locally or rejected by Cloud. |
1734
+ | `interrupted` | 2 | Upload, verification, or receipt persistence stopped; acknowledged work is included in the result. |
1735
+ | `failed` | 2 | Preparation failed before uploading; structured output includes the error. |
1736
+
1737
+ For finding imports, `--full-output` requires `--format json` or `--format jsonl`.
1738
+ Failed and interrupted imports set the envelope's `ok` to `false`, with
1739
+ `error.code: "IMPORT_FAILED"`, while retaining available results, receipts, and
1740
+ counts under `data`. Other full-output format combinations are rejected before
1741
+ reading the input or contacting Cloud; omit `--full-output` to use those formats.
1742
+
1743
+ Ctrl-C and SIGTERM retain exit codes 130 and 143. Interrupted JSON output preserves
1744
+ `receipts`, `counts`, `failures` with vendor source IDs, `excluded`, `verified`, and
1745
+ `unacknowledged`. A lost response can mean unacknowledged findings were accepted;
1746
+ resume the saved submission rather than treating them as never uploaded. When
1747
+ available, `savedSubmission` identifies the checkpoint to resume by repeating the
1748
+ same command. Review `error` before retrying; a repository reset retires the old
1749
+ submission and requires fresh approval. Correct local exclusions or final source
1750
+ conflicts before preparing a new submission.
1751
+
1752
+ Counts are cumulative for the saved submission: a resumed result includes
1753
+ batches acknowledged by earlier invocations, not just the latest upload attempt.
1754
+
1755
+ Terminal progress reports preparation, acknowledged uploads, and verification
1756
+ on stderr; JSON results stay on stdout. Lookups and readback use at most four
1757
+ concurrent requests, while uploads remain sequential. Successful receipts are
1758
+ saved locally. Verification reads the imported source records and checks their
1759
+ identities and evidence against the receipts. This does not establish a Codex
1760
+ assessment or visibility in the shared Cloud Findings view.
1761
+ When available, `cloudUrl` links to the destination repository in Cloud.
1762
+
1763
+ ### Publish completed scans
1764
+
1178
1765
  Preview selected completed scans before uploading:
1179
1766
 
1180
1767
  ```bash
@@ -1283,16 +1870,31 @@ codex-security classify-severity --scan latest --rubric /path/to/policy.md --jso
1283
1870
  codex-security classify-severity --scan-dir /path/to/completed-scan --json
1284
1871
  ```
1285
1872
 
1286
- For repository-free canonical records, use `classify-severity --records` alone.
1873
+ For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
1287
1874
  The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1288
1875
  report snapshots and delegates model execution to the host.
1289
1876
 
1290
1877
  For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1291
- Omitting `--rubric` inherits original severity without model calls. Rubrics and
1292
- repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
1293
- Each finding is classified in a separate read-only turn using its report and
1294
- supplied context, without tools or source inspection. `--model` and `--effort`
1295
- override Codex's configured model and the default medium effort.
1878
+ Omitting `--rubric` runs classification with the [built-in severity rubric](https://github.com/openai/codex-security/blob/main/sdk/typescript/src/default-severity-rubric.ts).
1879
+ It evaluates attacker access, boundary crossing, additional harm, and evidence for
1880
+ Critical, High, Medium, Low, and Informational findings. Confidence remains separate
1881
+ from severity; missing proof alone does not justify a downgrade. An explicit
1882
+ `--rubric` replaces the default policy completely. Rubrics and repeatable
1883
+ `--knowledge-base` context accept text, PDF, DOCX, and directories.
1884
+ Each finding is classified three times by default. `--runs N` accepts
1885
+ an integer from 1 through 10; SDK options use `classificationRuns` with the same
1886
+ default and bounds. Each review runs in an independent read-only turn using the
1887
+ same report, rubric, and supplied context, without tools or source inspection.
1888
+ The most common normalized severity wins; the highest among tied top counts wins
1889
+ (`critical` > `high` > `medium` > `low` > `informational`). Exclusion is a separate
1890
+ vote: exclusions can win by count, but lose ties to assessed severities. The first answer matching the winner supplies its label, rationale,
1891
+ confidence, and review trigger. All requested reviews must succeed; failures or invalid
1892
+ answers fail that finding without saving a partial vote. This uses the requested number of model
1893
+ calls per uncached finding (three by default), including when no custom rubric is supplied, and
1894
+ requires the same Codex authentication and model access as custom classification.
1895
+ Codex retains usage for each independent turn. There is no fallback to scanner
1896
+ severity if classification fails.
1897
+ `--model` and `--effort` override Codex's configured model and the default medium effort.
1296
1898
 
1297
1899
  Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
1298
1900
  the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
@@ -1300,10 +1902,17 @@ missing facts that could change the result. Exclusions have a null level.
1300
1902
  Finding/occurrence IDs and input hashes bind each assessment to its evidence.
1301
1903
 
1302
1904
  Successful assessments checkpoint immediately in local SQLite. Retries reuse
1303
- matching evidence, rubric, and context hashes; failed/canceled runs keep completed
1304
- work. Use `--reprocess` to replace assessments, including when changing only model
1305
- or effort. A successful run also writes `severity-classification.json`, but
1306
- publication reads the database. Original findings and sealed artifacts remain
1905
+ matching evidence, rubric, context hashes, and classification run count; failed/canceled runs keep completed
1906
+ work. Default-rubric assessments use `source: "rubric"` and a content hash; former
1907
+ no-rubric inherited assessments have no rubric hash and are automatically
1908
+ reclassified on the next classification run. Changes to the bundled policy or
1909
+ switching between default and custom policies also invalidate matching checkpoints.
1910
+ The result and checkpoint record `classificationRuns`; changing the count, or
1911
+ reusing an older checkpoint with no recorded count, triggers fresh classification.
1912
+ Older results remain readable; publication does not silently run a model.
1913
+ Use `--reprocess` to replace assessments, including when changing only model
1914
+ or effort. A successful
1915
+ run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
1307
1916
  unchanged.
1308
1917
 
1309
1918
  Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
@@ -1374,8 +1983,9 @@ await publishScan(scanDirectory, {
1374
1983
  ```
1375
1984
 
1376
1985
  `classifySeverity()` accepts `findingId`, `title`, `summary`, and available
1377
- evidence/metadata. Imported reports may lack severity or occurrence IDs; missing
1378
- severity requires a rubric. Scan wrappers persist checkpoints (including for
1986
+ evidence/metadata. Imported reports may lack severity or occurrence IDs; omitting
1987
+ `rubricPath` uses the built-in policy even when a scanner severity is present.
1988
+ Scan wrappers persist checkpoints (including for
1379
1989
  external directories), accept `reprocess: true`, and treat `findingIds: []` as an
1380
1990
  empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
1381
1991
  publication. Older JSON-only assessments need reclassification once. All
@@ -1487,6 +2097,7 @@ least eight characters.
1487
2097
  | `scans match --all` | Match completed scans across worktrees/clones. |
1488
2098
  | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
1489
2099
  | `findings list [REPOSITORY]` | List open findings. |
2100
+ | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
1490
2101
  | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
1491
2102
 
1492
2103
  Without an ID, `scans show` selects the latest completed scan, while `scans logs`
@@ -1772,6 +2383,163 @@ record absolute Node/CLI paths. If those change, back up and remove the verified
1772
2383
  generated hook, then reinstall with the same threshold. Restore the backup if
1773
2384
  installation fails. The installer respects `core.hooksPath`.
1774
2385
 
2386
+ ## Import GitHub findings locally or to Cloud
2387
+
2388
+ Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
2389
+ The existing alert collector remains available without it.
2390
+
2391
+ Acquire code-scanning findings with the existing `import github` collector and
2392
+ save its complete JSON output. In Codex, the official
2393
+ [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
2394
+ can help select the repository, alert numbers and ref through GitHub's MCP
2395
+ server; pass that selection to the collector. This integration reads
2396
+ code-scanning alerts and GHSA advisories. It does not import Dependabot or
2397
+ secret-scanning alerts or write back to GitHub. Preview local storage with a
2398
+ repository path:
2399
+
2400
+ ```bash
2401
+ codex-security import github example/project --format json > /path/outside/repository/alerts.json
2402
+ codex-security publish findings /path/outside/repository/alerts.json \
2403
+ --to local --provider github --repository ./project \
2404
+ --source-key github.com/example/project/code-scanning --dry-run --format json
2405
+ ```
2406
+
2407
+ Or preview publication to a connected Cloud repository:
2408
+
2409
+ ```bash
2410
+ codex-security publish findings /path/outside/repository/alerts.json \
2411
+ --to cloud --provider github --repository https://github.com/example/project \
2412
+ --source-key github.com/example/project/code-scanning --dry-run --format json
2413
+ ```
2414
+
2415
+ The importer fetches every page, retrieves alert details, and retains the selected
2416
+ ref's instance. It writes the saved input for publication; no website download or
2417
+ hand-written JSON mapping is needed. Use `--github-alert NUMBER` repeatedly for
2418
+ selected alerts or `--github-ref REF` for another ref. Defaults are open alerts on
2419
+ the default branch. MCP list calls are paginated separately, and raw MCP/API
2420
+ responses are not the saved import format accepted by `--provider github`.
2421
+
2422
+ The importer uses GitHub CLI authentication (`gh auth login`) and `GH_HOST`;
2423
+ the plugin's connection does not sign in `gh`. Reading alerts requires
2424
+ [code-scanning access](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository):
2425
+ **Code scanning alerts: read** for a fine-grained token, or `security_events` for
2426
+ a classic token (`public_repo` is sufficient for public repositories). The source
2427
+ repository must have code scanning available. For Cloud publication, the
2428
+ destination must be connected in the selected Cloud account. For local import,
2429
+ the source repository must match a configured Git remote when remotes are
2430
+ available; no Cloud login is required to store the acquired evidence.
2431
+
2432
+ Review the destination, source, exclusions and evidence in the preview. Repeat the
2433
+ selected command without `--dry-run` and confirm it, or add `--yes` for a
2434
+ previously reviewed input. Local persistence and readback follow the
2435
+ [local import flow](#import-vendor-findings-locally); use
2436
+ `codex-security findings imported ./project --format json` to read the records.
2437
+ Cloud authentication, batching, saved receipts, partial results and
2438
+ interrupted-upload recovery follow the [publication flow](#import-wiz-findings).
2439
+ JSON, JSONL and gzip are supported. Save complete import output without field or
2440
+ token filters or `--full-output`.
2441
+
2442
+ Use a stable source key for the GitHub host, repository and finding family.
2443
+ Code-scanning identities include the selected ref, so branches retain separate
2444
+ evidence. The original alert, rule, scanner, location, revision and source state
2445
+ remain attached. An alert-wide dismissal takes precedence over the selected
2446
+ instance's open/fixed state. Missing security severity stays `unknown`;
2447
+ SARIF error/warning/note levels are not vulnerability ratings. Imported evidence
2448
+ remains unassessed by Codex.
2449
+
2450
+ The SDK offers the same preview and publication boundary for Cloud:
2451
+
2452
+ ```ts
2453
+ import {
2454
+ importGitHubCodeScanningAlerts,
2455
+ normalizeGitHubCodeScanningAlerts,
2456
+ prepareNormalizedExternalPublication,
2457
+ } from "@openai/codex-security";
2458
+
2459
+ const alerts = await importGitHubCodeScanningAlerts({
2460
+ repository: "example/project",
2461
+ });
2462
+ const prepared = await prepareNormalizedExternalPublication(
2463
+ normalizeGitHubCodeScanningAlerts(alerts),
2464
+ {
2465
+ provider: "github",
2466
+ repository: "https://github.com/example/project",
2467
+ sourceKey: "github.com/example/project/code-scanning",
2468
+ },
2469
+ );
2470
+ console.log(prepared.preview);
2471
+ // After reviewing the preview:
2472
+ const receipt = await prepared.publish();
2473
+ ```
2474
+
2475
+ For local storage, pass the same normalized evidence to
2476
+ `prepareNormalizedLocalImport()` with `repository: "/path/to/project"`, inspect
2477
+ its preview, and call `import()`. `prepareLocalExternalImport()` accepts the saved
2478
+ import file directly. Read records with `listLocalExternalFindings({ repository })`.
2479
+
2480
+ ### Import GHSA advisories separately
2481
+
2482
+ Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
2483
+
2484
+ **Importing a GHSA advisory does not establish an installed dependency or
2485
+ applicability to the destination repository.** Repository advisories are
2486
+ disclosures maintained by a repository; global advisories describe affected
2487
+ software in GitHub's public advisory database. Both are evidence for
2488
+ investigation, not Dependabot alerts. Check the repository’s dependency versions
2489
+ and applicability separately.
2490
+
2491
+ ```bash
2492
+ # Read only published advisories for this repository.
2493
+ codex-security import github-advisories example/project --format json > /path/outside/repository/advisories.json
2494
+
2495
+ # Select individual public database records without enumerating the database.
2496
+ codex-security import github-advisories example/project \
2497
+ --github-advisory-source global --github-advisory GHSA-2345-6789-cfgh \
2498
+ --format json > /path/outside/repository/advisories.json
2499
+
2500
+ codex-security publish findings /path/outside/repository/advisories.json \
2501
+ --to cloud --provider github --repository https://github.com/example/project \
2502
+ --source-key github.com/example/project/security-advisories --dry-run --format json
2503
+ ```
2504
+
2505
+ For local storage, use the same advisory file, provider and source key with
2506
+ `--to local --repository ./project`. Follow the [local import flow](#import-vendor-findings-locally)
2507
+ to review, confirm and read the stored evidence.
2508
+
2509
+ `--github-advisory-source` defaults to `repository`. Repeat `--github-advisory`
2510
+ to select exact IDs from that API, regardless of advisory state. Repository
2511
+ lists default to `--github-state published`; `draft`, `triage`, and `closed`
2512
+ require explicit selection. A nondefault state cannot be combined with exact
2513
+ IDs. Global selection requires at least one ID and never lists the advisory
2514
+ database. Both readers use `GH_HOST` and GitHub CLI authentication by default;
2515
+ the SDK also accepts `githubHost` and `githubToken`. Private or unpublished
2516
+ [repository advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories)
2517
+ require **Repository security advisories: read**, or the classic `repo` or
2518
+ `repository_advisories:read` scope, plus access to the advisory. Public records
2519
+ need no additional advisory permission.
2520
+
2521
+ Review the saved evidence before local import or Cloud publication, including any
2522
+ selected private advisories. Acquisition failure returns no partial selection.
2523
+ Both destinations report invalid records as exclusions. Cloud publication retains
2524
+ acknowledged receipts if a later batch or readback fails.
2525
+
2526
+ Advisory evidence retains GHSA/CVE IDs, affected version ranges, available
2527
+ patched versions, source status and original JSON. It does not infer an installed
2528
+ version or source location. Global advisories omit a source repository; the
2529
+ explicit local or Cloud destination binds the import for investigation. Repository
2530
+ advisories retain their source repository and check it against the Cloud target
2531
+ or configured local Git remotes when available. Withdrawal remains vendor
2532
+ state, and all imported evidence remains not assessed by Codex. Use a separate
2533
+ source key from code-scanning alerts; shared advisory IDs do not combine source
2534
+ records from different providers.
2535
+
2536
+ In the SDK, call `importGitHubAdvisories()` and `normalizeGitHubAdvisories()`
2537
+ with `prepareNormalizedExternalPublication()` for Cloud or
2538
+ `prepareNormalizedLocalImport()` for local storage as described above.
2539
+ `importGitHubAdvisories()` defaults to `{ source: "repository", state: "published" }`; use
2540
+ `{ source: "global", advisoryIds: ["GHSA-2345-6789-cfgh"] }` for selected database
2541
+ records. Both forms require `repository: "OWNER/REPO"` as source or target context.
2542
+
1775
2543
  ## Import alerts from the CLI
1776
2544
 
1777
2545
  ```bash
@@ -1968,6 +2736,18 @@ text/files, and Linear inputs. Paths resolve from the invocation directory, even
1968
2736
  when the finding belongs to another repository. The file must be nonempty and
1969
2737
  regular, is read before patching, and cannot combine with `--resume-pr`.
1970
2738
 
2739
+ Use `--verification-mode static` to assess a patch from source and diff evidence
2740
+ without installing dependencies or running builds, tests, reproducers, or the
2741
+ application. Validation instructions become questions for that source review.
2742
+ The default is `standard`, which retains the existing verification checks.
2743
+ Static results identify the evidence and state that runtime checks were not
2744
+ performed; material proof gaps can still block verification.
2745
+
2746
+ ```bash
2747
+ codex-security patch finding.md --verification-mode static
2748
+ codex-security verify-fix finding.md --verification-mode static
2749
+ ```
2750
+
1971
2751
  `--assess-patch-risk` runs an advisory assessment after patching. Human-readable
1972
2752
  output prints its report; saved-finding JSON includes `patchRisk.report`.
1973
2753
  With `--create-pr`, the draft description includes the concise Markdown summary.
@@ -2031,9 +2811,17 @@ credentials out of the patch subprocess. URLs must match the selected workspace.
2031
2811
  finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
2032
2812
  filter for completed Linear issues to check a finished backlog.
2033
2813
 
2814
+ `--verification-mode static` selects source-only assessment, as described above
2815
+ for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2816
+
2034
2817
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2035
2818
  `--json` returns structured output. Exit codes are `0` when all findings are
2036
2819
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2820
+ Authentication and execution failures print diagnostics on stderr and return
2821
+ `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message` with `--json`
2822
+ or `--format jsonl`. With JSON/JSONL `--full-output`, failures use an `ok: false`
2823
+ error envelope. Other formats retain stderr-only failures. Interruptions retain
2824
+ exit codes `130` and `143` without a result.
2037
2825
 
2038
2826
  ## Command discovery and integrations
2039
2827
 
@@ -2050,6 +2838,10 @@ scan, triage, patch, and verification workflows, see the
2050
2838
  For local findings storage, deduplication, and custom endpoints, see the
2051
2839
  [findings guide](findings-service.md).
2052
2840
 
2841
+ ### Hosted Standard scan
2842
+
2843
+ `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.
2844
+
2053
2845
  ## Containerized bulk scans
2054
2846
 
2055
2847
  Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
@@ -2089,7 +2881,3 @@ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested us
2089
2881
  namespaces do not need it. The legacy Landlock fallback is unsupported.
2090
2882
  See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
2091
2883
  for deployment and source-build instructions.
2092
-
2093
- ### Hosted Standard scan
2094
-
2095
- `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.