@openai/codex-security 0.6.0 → 0.8.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 (308) hide show
  1. package/README.md +76 -39
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  4. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  6. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  9. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  11. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  12. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  13. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  23. package/_bundled_plugin/references/access-advisory.md +11 -0
  24. package/_bundled_plugin/references/core-scan.md +30 -77
  25. package/_bundled_plugin/references/final-report.md +50 -184
  26. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  27. package/_bundled_plugin/references/scan-contract.md +12 -12
  28. package/_bundled_plugin/references/scan-prologue.md +1 -1
  29. package/_bundled_plugin/references/scan-runtime.md +1 -5
  30. package/_bundled_plugin/references/threat-model.md +33 -41
  31. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  32. package/_bundled_plugin/schemas/scan-manifest.schema.json +37 -11
  33. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  34. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  35. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  36. package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
  37. package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
  38. package/_bundled_plugin/scripts/report_projection.py +49 -17
  39. package/_bundled_plugin/scripts/review_state.py +68 -0
  40. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  41. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  43. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
  44. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  45. package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
  46. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  47. package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
  48. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  49. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  50. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  51. package/_bundled_plugin/scripts/workbench_db.py +55 -171
  52. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  53. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  54. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  55. package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
  56. package/_bundled_plugin/scripts/workbench_scan_history.py +77 -7
  57. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  58. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  59. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  60. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  61. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  62. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  63. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  64. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  65. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  66. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  67. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  68. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  69. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  70. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  71. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  72. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  73. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  74. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -24
  75. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  76. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  77. package/_bundled_plugin/skills/security-scan/SKILL.md +29 -17
  78. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  79. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  80. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  81. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  82. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  83. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  84. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  85. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  86. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  87. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  88. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  89. package/dist/api.d.ts +5 -3
  90. package/dist/api.d.ts.map +1 -1
  91. package/dist/api.js +359 -53
  92. package/dist/api.js.map +1 -1
  93. package/dist/auth.d.ts.map +1 -1
  94. package/dist/auth.js +4 -1
  95. package/dist/auth.js.map +1 -1
  96. package/dist/cli.d.ts +2 -2
  97. package/dist/cli.d.ts.map +1 -1
  98. package/dist/cli.js +696 -430
  99. package/dist/cli.js.map +1 -1
  100. package/dist/cloud-publish.d.ts.map +1 -1
  101. package/dist/cloud-publish.js +2 -23
  102. package/dist/cloud-publish.js.map +1 -1
  103. package/dist/component-scan.d.ts +8 -2
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +2 -0
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/contract.d.ts +5 -2
  108. package/dist/contract.d.ts.map +1 -1
  109. package/dist/contract.js +93 -45
  110. package/dist/contract.js.map +1 -1
  111. package/dist/cost.d.ts +18 -0
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +107 -12
  114. package/dist/cost.js.map +1 -1
  115. package/dist/coverage-presentation.d.ts +6 -0
  116. package/dist/coverage-presentation.d.ts.map +1 -0
  117. package/dist/coverage-presentation.js +34 -0
  118. package/dist/coverage-presentation.js.map +1 -0
  119. package/dist/custom-publish.js +2 -2
  120. package/dist/custom-publish.js.map +1 -1
  121. package/dist/custom-validation-prompt.js +5 -5
  122. package/dist/custom-validation-prompt.js.map +1 -1
  123. package/dist/custom-validation.d.ts.map +1 -1
  124. package/dist/custom-validation.js +47 -19
  125. package/dist/custom-validation.js.map +1 -1
  126. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  127. package/dist/deduplication/checkpointed-review.js +3 -1
  128. package/dist/deduplication/checkpointed-review.js.map +1 -1
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +2 -2
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  133. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  134. package/dist/deduplication/deduplication-prompts.js +3 -0
  135. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  136. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  137. package/dist/deduplication/records-protocol.js +21 -1
  138. package/dist/deduplication/records-protocol.js.map +1 -1
  139. package/dist/deduplication/scan.d.ts.map +1 -1
  140. package/dist/deduplication/scan.js +9 -7
  141. package/dist/deduplication/scan.js.map +1 -1
  142. package/dist/endor-findings.d.ts +4 -3
  143. package/dist/endor-findings.d.ts.map +1 -1
  144. package/dist/endor-findings.js +16 -11
  145. package/dist/endor-findings.js.map +1 -1
  146. package/dist/external-findings-import.d.ts.map +1 -1
  147. package/dist/external-findings-import.js +13 -5
  148. package/dist/external-findings-import.js.map +1 -1
  149. package/dist/external-findings-local.d.ts +1 -0
  150. package/dist/external-findings-local.d.ts.map +1 -1
  151. package/dist/external-findings-local.js +14 -3
  152. package/dist/external-findings-local.js.map +1 -1
  153. package/dist/external-findings-publish.d.ts +2 -1
  154. package/dist/external-findings-publish.d.ts.map +1 -1
  155. package/dist/external-findings-publish.js +64 -28
  156. package/dist/external-findings-publish.js.map +1 -1
  157. package/dist/external-findings-read.d.ts +12 -1
  158. package/dist/external-findings-read.d.ts.map +1 -1
  159. package/dist/external-findings-read.js +25 -6
  160. package/dist/external-findings-read.js.map +1 -1
  161. package/dist/external-findings.d.ts +2 -0
  162. package/dist/external-findings.d.ts.map +1 -1
  163. package/dist/external-findings.js.map +1 -1
  164. package/dist/external-import-contract.d.ts +7 -1
  165. package/dist/external-import-contract.d.ts.map +1 -1
  166. package/dist/external-import-contract.js +63 -31
  167. package/dist/external-import-contract.js.map +1 -1
  168. package/dist/external-imports-feature.d.ts +6 -0
  169. package/dist/external-imports-feature.d.ts.map +1 -0
  170. package/dist/external-imports-feature.js +51 -0
  171. package/dist/external-imports-feature.js.map +1 -0
  172. package/dist/finding-workflow.d.ts +24 -5
  173. package/dist/finding-workflow.d.ts.map +1 -1
  174. package/dist/finding-workflow.js +24 -9
  175. package/dist/finding-workflow.js.map +1 -1
  176. package/dist/github-advisories.d.ts.map +1 -1
  177. package/dist/github-advisories.js +3 -1
  178. package/dist/github-advisories.js.map +1 -1
  179. package/dist/github-findings.d.ts +4 -3
  180. package/dist/github-findings.d.ts.map +1 -1
  181. package/dist/github-findings.js +16 -14
  182. package/dist/github-findings.js.map +1 -1
  183. package/dist/host-protocol.d.ts +1 -1
  184. package/dist/host-protocol.d.ts.map +1 -1
  185. package/dist/host-protocol.js +2 -2
  186. package/dist/host-protocol.js.map +1 -1
  187. package/dist/hosted-remediation.d.ts.map +1 -1
  188. package/dist/hosted-remediation.js +19 -2
  189. package/dist/hosted-remediation.js.map +1 -1
  190. package/dist/hosted-scan.d.ts +1 -1
  191. package/dist/hosted-scan.d.ts.map +1 -1
  192. package/dist/hosted-scan.js +0 -6
  193. package/dist/hosted-scan.js.map +1 -1
  194. package/dist/import-scan.js +17 -17
  195. package/dist/import-scan.js.map +1 -1
  196. package/dist/index.d.ts +4 -3
  197. package/dist/index.d.ts.map +1 -1
  198. package/dist/index.js +2 -1
  199. package/dist/index.js.map +1 -1
  200. package/dist/knowledge-base.d.ts +1 -0
  201. package/dist/knowledge-base.d.ts.map +1 -1
  202. package/dist/knowledge-base.js +20 -8
  203. package/dist/knowledge-base.js.map +1 -1
  204. package/dist/mock-scan.d.ts +1 -2
  205. package/dist/mock-scan.d.ts.map +1 -1
  206. package/dist/mock-scan.js +12 -17
  207. package/dist/mock-scan.js.map +1 -1
  208. package/dist/models.d.ts +10 -1
  209. package/dist/models.d.ts.map +1 -1
  210. package/dist/models.js.map +1 -1
  211. package/dist/multiscan.d.ts.map +1 -1
  212. package/dist/multiscan.js +1 -6
  213. package/dist/multiscan.js.map +1 -1
  214. package/dist/native-json-findings.d.ts +30 -0
  215. package/dist/native-json-findings.d.ts.map +1 -0
  216. package/dist/native-json-findings.js +114 -0
  217. package/dist/native-json-findings.js.map +1 -0
  218. package/dist/opengrep-findings.d.ts +10 -0
  219. package/dist/opengrep-findings.d.ts.map +1 -0
  220. package/dist/opengrep-findings.js +198 -0
  221. package/dist/opengrep-findings.js.map +1 -0
  222. package/dist/owner-evidence.d.ts +2 -0
  223. package/dist/owner-evidence.d.ts.map +1 -1
  224. package/dist/owner-evidence.js +2 -1
  225. package/dist/owner-evidence.js.map +1 -1
  226. package/dist/patch-tui.d.ts.map +1 -1
  227. package/dist/patch-tui.js +2 -0
  228. package/dist/patch-tui.js.map +1 -1
  229. package/dist/publication.js +1 -2
  230. package/dist/publication.js.map +1 -1
  231. package/dist/publish.d.ts +2 -0
  232. package/dist/publish.d.ts.map +1 -1
  233. package/dist/publish.js +1 -1
  234. package/dist/publish.js.map +1 -1
  235. package/dist/record.d.ts +1 -0
  236. package/dist/record.d.ts.map +1 -1
  237. package/dist/record.js +10 -0
  238. package/dist/record.js.map +1 -1
  239. package/dist/remediation.d.ts +1 -25
  240. package/dist/remediation.d.ts.map +1 -1
  241. package/dist/remediation.js +3 -24
  242. package/dist/remediation.js.map +1 -1
  243. package/dist/result.d.ts +5 -3
  244. package/dist/result.d.ts.map +1 -1
  245. package/dist/result.js +9 -6
  246. package/dist/result.js.map +1 -1
  247. package/dist/runtime.d.ts.map +1 -1
  248. package/dist/runtime.js +7 -7
  249. package/dist/runtime.js.map +1 -1
  250. package/dist/scan-dashboard.d.ts +5 -3
  251. package/dist/scan-dashboard.d.ts.map +1 -1
  252. package/dist/scan-dashboard.js +79 -26
  253. package/dist/scan-dashboard.js.map +1 -1
  254. package/dist/scan-history-renderer.d.ts.map +1 -1
  255. package/dist/scan-history-renderer.js +9 -3
  256. package/dist/scan-history-renderer.js.map +1 -1
  257. package/dist/scan-owner-suggestions.d.ts +1 -1
  258. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  259. package/dist/scan-owner-suggestions.js +4 -4
  260. package/dist/scan-owner-suggestions.js.map +1 -1
  261. package/dist/scan-usage-display.d.ts +8 -0
  262. package/dist/scan-usage-display.d.ts.map +1 -0
  263. package/dist/scan-usage-display.js +46 -0
  264. package/dist/scan-usage-display.js.map +1 -0
  265. package/dist/scanner-import.d.ts +1 -1
  266. package/dist/scanner-import.d.ts.map +1 -1
  267. package/dist/scanner-import.js +7 -3
  268. package/dist/scanner-import.js.map +1 -1
  269. package/dist/security-policy.d.ts.map +1 -1
  270. package/dist/security-policy.js +17 -22
  271. package/dist/security-policy.js.map +1 -1
  272. package/dist/semgrep-findings.d.ts +4 -3
  273. package/dist/semgrep-findings.d.ts.map +1 -1
  274. package/dist/semgrep-findings.js +22 -89
  275. package/dist/semgrep-findings.js.map +1 -1
  276. package/dist/skill-authentication.d.ts +18 -0
  277. package/dist/skill-authentication.d.ts.map +1 -0
  278. package/dist/skill-authentication.js +82 -0
  279. package/dist/skill-authentication.js.map +1 -0
  280. package/dist/snyk-findings.d.ts +5 -4
  281. package/dist/snyk-findings.d.ts.map +1 -1
  282. package/dist/snyk-findings.js +18 -17
  283. package/dist/snyk-findings.js.map +1 -1
  284. package/dist/suggest-owners.d.ts +4 -1
  285. package/dist/suggest-owners.d.ts.map +1 -1
  286. package/dist/suggest-owners.js +53 -21
  287. package/dist/suggest-owners.js.map +1 -1
  288. package/dist/targets.d.ts.map +1 -1
  289. package/dist/targets.js +4 -1
  290. package/dist/targets.js.map +1 -1
  291. package/dist/wiz-csv.d.ts +2 -1
  292. package/dist/wiz-csv.d.ts.map +1 -1
  293. package/dist/wiz-csv.js +3 -3
  294. package/dist/wiz-csv.js.map +1 -1
  295. package/dist/wiz-findings.d.ts +2 -1
  296. package/dist/wiz-findings.d.ts.map +1 -1
  297. package/dist/wiz-findings.js +27 -23
  298. package/dist/wiz-findings.js.map +1 -1
  299. package/docs/classify-severity-records.md +3 -4
  300. package/docs/cli.md +171 -41
  301. package/docs/dedupe-records.md +15 -1
  302. package/docs/findings-service.md +119 -118
  303. package/docs/hosted-remediation.md +19 -17
  304. package/docs/hosted-scans.md +37 -11
  305. package/package.json +9 -9
  306. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  307. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  308. 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:
@@ -404,6 +426,11 @@ codex-security scan . --owner-suggestions
404
426
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
405
427
  ```
406
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
+
407
434
  Whole-codebase and path scans also accept ordinary directories, including SVN
408
435
  working copies. Their source inventories exclude `.git` and `.svn` metadata.
409
436
 
@@ -412,12 +439,20 @@ changes. Both require Git. Deep scans support whole repositories and path scopes
412
439
  Working-tree snapshots include untracked nested Git repositories. Initialized submodules must
413
440
  be clean and at the commit recorded by the parent.
414
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
+
415
447
  `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
416
448
  committed Git scan, using the same checkout, model, and reasoning effort. Owner
417
449
  errors leave the base scan completed. The JSON result includes
418
450
  `ownerSuggestionsPath` or `ownerSuggestionsError`; the sealed findings and
419
451
  manifest stay unchanged. This option is unsupported for working-tree and
420
- directory snapshots, and is skipped with a warning when `--max-cost` is set.
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.
421
456
 
422
457
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
423
458
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
@@ -471,7 +506,7 @@ or JSONL output produce:
471
506
  With `--full-output`, the error appears under `error` in an `ok: false` envelope.
472
507
  If the scan target changed, the error explains that the results no longer
473
508
  represent the current checkout. Retained sealed results remain available under
474
- `data`, including their manifest, findings, coverage, scan directory, and report
509
+ `data`, including their manifest, findings, review summary, scan directory, and report
475
510
  path. Unsealed or invalid artifacts are not included. This also applies to
476
511
  `scans rerun` and `scans resume`.
477
512
  For `scans rerun` and `scans resume`, `--filter-output` applies to retained `data`;
@@ -487,6 +522,38 @@ Diagnostics stay on stderr. Each command's `--schema --format json` describes
487
522
  its successful output and failure codes.
488
523
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
489
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
+
490
557
  ### Understand scan scope and follow-up work
491
558
 
492
559
  A completed scan means the requested workflow finished. It does not mean every
@@ -739,16 +806,9 @@ not to planning, result matching, or the total campaign.
739
806
 
740
807
  ### Configure deep scans
741
808
 
742
- ```ts
743
- await security.run("/path/to/repository", {
744
- mode: "deep",
745
- workers: 2,
746
- subagents: 0,
747
- stopAfterNoNew: 3,
748
- stopAfterConsecutiveErrors: 2,
749
- maxDiscoveryRuns: 10,
750
- maxTimeMinutes: 90,
751
- });
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
752
812
  ```
753
813
 
754
814
  For `scan --mode deep`, `--workers` controls discovery concurrency and
@@ -757,11 +817,13 @@ For `scan --mode deep`, `--workers` controls discovery concurrency and
757
817
  or duration. At the deadline, discovery stops; the scan then combines and returns
758
818
  completed findings.
759
819
 
820
+ For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
821
+
760
822
  Use project-file `scan.deep` settings or legacy
761
823
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
762
824
  that `subagents` can be zero. Discovery time accepts positive fractional minutes;
763
- its default and maximum remain 5760 minutes (96 hours). Unlike Standard's
764
- 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
765
827
  Deep scan keeps its original deadline; rerunning starts a new scan.
766
828
  `--max-time-hours`, SDK `maxTimeHours`, project `scan.deep.max_time_hours`, and
767
829
  legacy TOML `deep_scan.max_time_hours` remain deprecated Deep-only aliases in
@@ -877,26 +939,27 @@ For filesystem and approval behavior, see the
877
939
 
878
940
  ### Environment variables
879
941
 
880
- | Variable | Effect |
881
- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
882
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
883
- | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
884
- | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
885
- | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
886
- | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
887
- | `PYTHON` | Python interpreter unless an explicit option overrides it. |
888
- | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
889
- | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
890
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
891
- | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
892
- | `CODEX_SECURITY_CLOUD_BASE_URL` | Cloud API root for discovery, imports, and scan publication. Defaults to `https://chatgpt.com/backend-api/aardvark`. |
893
- | `CODEX_SECURITY_CLOUD_WEB_URL` | Cloud app URL for repository links when an alternate deployment serves its UI separately. |
894
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
895
- | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
896
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
897
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
898
- | `CI` | Disable interactive update notices. |
899
- | `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`. |
900
963
 
901
964
  Custom Codex executables need thread source attribution for `exec` and
902
965
  `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
@@ -961,6 +1024,14 @@ work could not be measured, including in-flight turns or missing earlier attempt
961
1024
  The parent can continue after report completion, so final CLI tokens can exceed
962
1025
  the saved measurement window.
963
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
+
964
1035
  `usage.accountRateLimits` saves the latest observed account-wide readings with
965
1036
  their own timestamps, window durations, and reset times. These are historical
966
1037
  observations, not a live allowance check or scan-only consumption. Empty readings
@@ -1197,6 +1268,26 @@ Supply the validation prompt again when rerunning.
1197
1268
 
1198
1269
  ## Import vendor findings locally
1199
1270
 
1271
+ 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.
1272
+
1273
+ External finding imports are disabled by default. Opt in for the current shell:
1274
+
1275
+ ```bash
1276
+ export CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1
1277
+ ```
1278
+
1279
+ In PowerShell, use `$env:CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS = '1'`.
1280
+ Only `1` enables the feature. Without it, `publish findings`, `findings imported`,
1281
+ and `import github-advisories` are absent from command help and schemas and cannot
1282
+ run. The SDK's external publication, local import/readback, and advisory
1283
+ acquisition APIs require the same flag in their effective environment. An explicit
1284
+ `dependencies.environment` is used instead of the process environment. Pure
1285
+ normalizers and file readers remain available as library utilities.
1286
+
1287
+ This flag does not affect `publish scan`, `publish check`, `scan import`, or the
1288
+ existing `import github` alert collector. Disabling it retains previously imported
1289
+ records; enable it again to read them with `findings imported`.
1290
+
1200
1291
  Prefer the provider's supported native JSON from its CLI, plugin, or API. Native
1201
1292
  reports can retain details omitted by SARIF. Use SARIF or CSV as compatibility
1202
1293
  inputs only for providers and report profiles that support them. A JSON API
@@ -1214,6 +1305,7 @@ repository path instead of a Cloud repository ID or URL. Supported inputs includ
1214
1305
  Wiz findings, [Snyk Open Source JSON and SARIF](#import-snyk-open-source-findings),
1215
1306
  [Endor Labs Finding JSON and SARIF](#import-endor-labs-findings),
1216
1307
  [Semgrep Code JSON and SARIF](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md),
1308
+ [OpenGrep native JSON](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md),
1217
1309
  and [saved GitHub alerts and GHSA advisories](#import-github-findings-locally-or-to-cloud):
1218
1310
 
1219
1311
  ```bash
@@ -1246,8 +1338,18 @@ Repeated imports update the same record by repository, provider, source key, and
1246
1338
  source finding ID. The result reports created, updated, and unchanged counts.
1247
1339
  Keep the source key stable across exports. Records omitted from a later selection
1248
1340
  remain stored; omission does not resolve or delete a finding. Excluded records
1249
- are reported, and an import with exclusions exits with status 1. The same
1250
- supported vendor formats and evidence requirements apply locally and in Cloud.
1341
+ are reported, and an import with exclusions exits with status 1. Both destinations
1342
+ read the same vendor formats; Cloud's field, size and nesting limits do not apply
1343
+ to local file imports.
1344
+
1345
+ For OpenGrep, use `--provider opengrep` and supply `--source-repository-url`.
1346
+ The reader supports native JSON and gzip for both destinations. It uses the
1347
+ existing `semgrep` source-provider contract while retaining `OpenGrep` as the
1348
+ scanner origin; keep a stable OpenGrep-specific source key. Review report
1349
+ diagnostics as well as findings: import completion does not establish scan
1350
+ coverage. The [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md)
1351
+ covers evidence identity, empty reports, and assessing an imported finding with
1352
+ the existing SDK validator.
1251
1353
 
1252
1354
  `scan import --json` and `scan import --csv` remain separate commands for importing
1253
1355
  Codex Security's findings schema as a saved scan; they do not accept vendor
@@ -1366,6 +1468,8 @@ network findings are not supported by this repository importer. Cloud destinatio
1366
1468
  currently support connected GitHub and GitHub Enterprise repositories, including
1367
1469
  custom Enterprise hostnames. Named Wiz exports do not add other VCS destinations.
1368
1470
 
1471
+ #### Select findings and a destination
1472
+
1369
1473
  Use an authorized [Wiz MCP](https://www.wiz.io/blog/introducing-wiz-mcp) or Wiz API
1370
1474
  connection to acquire findings and save the supported native JSON. A configured
1371
1475
  plugin may provide that connection; an official Codex plugin is not a prerequisite.
@@ -1412,6 +1516,8 @@ gzip-compressed JSON or CSV are accepted; gzip is detected regardless of the
1412
1516
  filename extension. **Raw Event** on Code & Build Scans contains scan metadata
1413
1517
  rather than findings.
1414
1518
 
1519
+ #### Configure an alternate Cloud deployment
1520
+
1415
1521
  For an alternate Cloud deployment, set `CODEX_SECURITY_CLOUD_BASE_URL` to its
1416
1522
  API root before previewing or uploading, for example
1417
1523
  `https://cloud.example.test/backend-api/aardvark`. Remote APIs require HTTPS;
@@ -1432,6 +1538,8 @@ the return link; all API requests still use `CODEX_SECURITY_CLOUD_BASE_URL`.
1432
1538
  For custom API destinations without a configured app URL, completion retains
1433
1539
  the manual navigation guidance rather than guessing a UI host or port.
1434
1540
 
1541
+ #### Preview and publish
1542
+
1435
1543
  Preview the selection and destination:
1436
1544
 
1437
1545
  ```bash
@@ -1457,6 +1565,8 @@ exclusions. `--dry-run --format json` retains all normalized findings and comple
1457
1565
  evidence for inspection. A prompt explicitly includes any records that will be
1458
1566
  skipped.
1459
1567
 
1568
+ #### Package vulnerability inputs
1569
+
1460
1570
  Native package input can be a Wiz JSON vulnerability report, a vulnerability
1461
1571
  finding, an array, a complete `data.vulnerabilityFindings.nodes` response, or JSONL
1462
1572
  with one package record per line. The repository package-vulnerability CSV
@@ -1507,6 +1617,8 @@ fetch from Wiz, assess findings, or change vendor or Cloud triage decisions.
1507
1617
  Findings from external network scans are excluded from this package vulnerability
1508
1618
  mapping.
1509
1619
 
1620
+ #### SAST, repository secrets, and IaC inputs
1621
+
1510
1622
  For SAST, repository secrets, and IaC, save the documented JSON API collection:
1511
1623
 
1512
1624
  | Finding family | Collection | Raw occurrence identity |
@@ -1565,6 +1677,8 @@ collection:
1565
1677
  }
1566
1678
  ```
1567
1679
 
1680
+ #### Preserved evidence
1681
+
1568
1682
  The adapters preserve each selected raw node exactly in `source_data`. Typed
1569
1683
  `evidence.details` carries `kind`, verified `repository`, vendor `source_status`,
1570
1684
  and family-specific evidence:
@@ -1583,6 +1697,8 @@ does not establish that it is deployed. Precise original timestamps remain in
1583
1697
  `source_updated_at` field. SAST creation time and IaC last-seen time are not update
1584
1698
  timestamps.
1585
1699
 
1700
+ #### Convert CSV reports
1701
+
1586
1702
  Native SAST and secret report downloads can be CSV, including gzip-compressed
1587
1703
  CSV. Those CSV profiles are not parsed directly. Convert a selected report with a reviewed mapping
1588
1704
  for its actual column headers into normalized JSONL, preserving each original row
@@ -1607,6 +1723,8 @@ Inputs must be valid UTF-8. Integer-valued evidence outside JavaScript's safe
1607
1723
  integer range is rejected; export those values as strings to preserve them
1608
1724
  exactly. Invalid records appear in `excluded` with their source ID and reason.
1609
1725
 
1726
+ #### Resume interrupted imports
1727
+
1610
1728
  Requests contain at most 100 findings and respect the Cloud payload limits.
1611
1729
  Before uploading, the publisher saves request IDs and bodies privately under
1612
1730
  the configured Codex Security state directory. After an uncertain response,
@@ -1618,6 +1736,8 @@ API endpoint, not a link to the Cloud UI. A reset
1618
1736
  retires the old request without republishing; review and explicitly approve a
1619
1737
  fresh invocation.
1620
1738
 
1739
+ #### Results and exit codes
1740
+
1621
1741
  Results distinguish completion from partial or interrupted work:
1622
1742
 
1623
1743
  | Status | Exit code | Meaning |
@@ -1768,7 +1888,7 @@ The [records protocol](classify-severity-records.md) accepts immutable Markdown
1768
1888
  report snapshots and delegates model execution to the host.
1769
1889
 
1770
1890
  For saved findings, use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1771
- Omitting `--rubric` runs classification with the [built-in severity rubric](../src/default-severity-rubric.ts).
1891
+ 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).
1772
1892
  It evaluates attacker access, boundary crossing, additional harm, and evidence for
1773
1893
  Critical, High, Medium, Low, and Informational findings. Confidence remains separate
1774
1894
  from severity; missing proof alone does not justify a downgrade. An explicit
@@ -2278,6 +2398,9 @@ installation fails. The installer respects `core.hooksPath`.
2278
2398
 
2279
2399
  ## Import GitHub findings locally or to Cloud
2280
2400
 
2401
+ Local and Cloud ingestion require the [external-import opt-in](#import-vendor-findings-locally).
2402
+ The existing alert collector remains available without it.
2403
+
2281
2404
  Acquire code-scanning findings with the existing `import github` collector and
2282
2405
  save its complete JSON output. In Codex, the official
2283
2406
  [GitHub Codex plugin](https://github.com/openai/plugins/tree/main/plugins/github)
@@ -2369,6 +2492,8 @@ import file directly. Read records with `listLocalExternalFindings({ repository
2369
2492
 
2370
2493
  ### Import GHSA advisories separately
2371
2494
 
2495
+ Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1` before using this command or its SDK API.
2496
+
2372
2497
  **Importing a GHSA advisory does not establish an installed dependency or
2373
2498
  applicability to the destination repository.** Repository advisories are
2374
2499
  disclosures maintained by a repository; global advisories describe affected
@@ -2705,6 +2830,11 @@ for `patch`. Omit it or use `--verification-mode standard` for the default check
2705
2830
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2706
2831
  `--json` returns structured output. Exit codes are `0` when all findings are
2707
2832
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2833
+ Authentication and execution failures print diagnostics on stderr and return
2834
+ `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message` with `--json`
2835
+ or `--format jsonl`. With JSON/JSONL `--full-output`, failures use an `ok: false`
2836
+ error envelope. Other formats retain stderr-only failures. Interruptions retain
2837
+ exit codes `130` and `143` without a result.
2708
2838
 
2709
2839
  ## Command discovery and integrations
2710
2840
 
@@ -2721,6 +2851,10 @@ scan, triage, patch, and verification workflows, see the
2721
2851
  For local findings storage, deduplication, and custom endpoints, see the
2722
2852
  [findings guide](findings-service.md).
2723
2853
 
2854
+ ### Hosted Standard scan
2855
+
2856
+ `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.
2857
+
2724
2858
  ## Containerized bulk scans
2725
2859
 
2726
2860
  Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
@@ -2760,7 +2894,3 @@ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested us
2760
2894
  namespaces do not need it. The legacy Landlock fallback is unsupported.
2761
2895
  See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
2762
2896
  for deployment and source-build instructions.
2763
-
2764
- ### Hosted Standard scan
2765
-
2766
- `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.
@@ -190,7 +190,7 @@ For failure or an inconclusive review, send an explicit error:
190
190
  }
191
191
  ```
192
192
 
193
- The CLI never resubmits a review, including after this error. Invalid model
193
+ A host error ends the review without another submission. Invalid model
194
194
  answers, missing decisions, and host errors make the whole batch unresolved;
195
195
  previous successful reviews in that run do not become persistence decisions.
196
196
  The existing algorithm treats a validated `DISTINCT` as a nonmatch, when
@@ -203,6 +203,20 @@ severity-based representative selection are reused. No local review checkpoints
203
203
  are read or written in records mode. Local saved-scan execution retains its
204
204
  existing tool-submission validation and workflow checkpoints.
205
205
 
206
+ ### Continuing a review
207
+
208
+ A `review.run` request with `supportsContinuation: true` can receive the result
209
+ `{"status":"missing_submission"}`. Send this only after verifying that the
210
+ original turn completed without a pending decision or blocker. Keep that
211
+ review session open. The CLI then sends one `review.continue` request with a
212
+ fresh JSON-RPC ID and `params: {requestId, prompt}`. The request ID in the
213
+ parameters identifies the original review. Submit the prompt in the same
214
+ session and reply on the new JSON-RPC ID. The correction omits
215
+ `supportsContinuation`, so the host releases the session after that turn. A second missing submission ends
216
+ the review as unresolved. A pending tool call uses the original turn and
217
+ requires no correction. An uncertain outcome or explicit blocker follows the
218
+ existing error path. Hosts without continuation support can ignore the field.
219
+
206
220
  ## Final response and persistence
207
221
 
208
222
  ```json