@openai/codex-security 0.2.0 → 0.3.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 (463) hide show
  1. package/README.md +437 -2692
  2. package/_bundled_plugin/.app.json +5 -1
  3. package/_bundled_plugin/.codex-plugin/plugin.json +9 -5
  4. package/_bundled_plugin/.mcp.json +2 -0
  5. package/_bundled_plugin/examples/completed-scan/coverage.json +0 -1
  6. package/_bundled_plugin/examples/completed-scan/report.md +28 -26
  7. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
  8. package/_bundled_plugin/mcp/helpers.mjs +1 -0
  9. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +6 -213
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +563 -0
  20. package/_bundled_plugin/mcp/server.mjs +1 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  23. package/_bundled_plugin/preflight/capability-profiles.toml +0 -13
  24. package/_bundled_plugin/references/artifact-storage.md +2 -2
  25. package/_bundled_plugin/references/config-preflight.md +0 -4
  26. package/_bundled_plugin/references/core-scan.md +21 -9
  27. package/_bundled_plugin/references/final-report.md +10 -12
  28. package/_bundled_plugin/references/finding-detail-fields.md +90 -80
  29. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  30. package/_bundled_plugin/references/scan-artifacts.md +1 -2
  31. package/_bundled_plugin/references/scan-contract.md +9 -4
  32. package/_bundled_plugin/references/scan-prologue.md +12 -0
  33. package/_bundled_plugin/references/security-guidance.md +2 -2
  34. package/_bundled_plugin/references/standalone-validation.md +11 -0
  35. package/_bundled_plugin/references/threat-model.md +1 -1
  36. package/_bundled_plugin/schemas/coverage.schema.json +1 -47
  37. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +2 -24
  38. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +49 -25
  39. package/_bundled_plugin/schemas/findings.schema.json +71 -192
  40. package/_bundled_plugin/schemas/scan-manifest.schema.json +18 -45
  41. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +91 -83
  42. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +35 -64
  43. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +5 -2
  44. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +6 -55
  45. package/_bundled_plugin/schemas/tools/review-items.schema.json +2 -38
  46. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +169 -294
  47. package/_bundled_plugin/scripts/codex_profile.mjs +239 -0
  48. package/_bundled_plugin/scripts/codex_session.mjs +53 -0
  49. package/_bundled_plugin/scripts/config_preflight.py +26 -62
  50. package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
  51. package/_bundled_plugin/scripts/deep_scan_workbench.py +129 -150
  52. package/_bundled_plugin/scripts/finalize_scan_contract.py +315 -232
  53. package/_bundled_plugin/scripts/finding_preview.py +39 -9
  54. package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -77
  55. package/_bundled_plugin/scripts/generate_rank_input.py +99 -829
  56. package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -10
  57. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
  58. package/_bundled_plugin/scripts/rank_preview.py +42 -918
  59. package/_bundled_plugin/scripts/report_projection.py +117 -172
  60. package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
  61. package/_bundled_plugin/scripts/threat_model_projection.py +4 -7
  62. package/_bundled_plugin/scripts/validate_scan_contract.py +4 -34
  63. package/_bundled_plugin/scripts/validate_tracking_source.py +3 -13
  64. package/_bundled_plugin/scripts/windows_scan_local_files.py +48 -3
  65. package/_bundled_plugin/scripts/workbench/handoff.py +25 -50
  66. package/_bundled_plugin/scripts/workbench/runtime_toml.py +22 -0
  67. package/_bundled_plugin/scripts/workbench/storage.py +10 -6
  68. package/_bundled_plugin/scripts/workbench_cli.py +94 -179
  69. package/_bundled_plugin/scripts/workbench_db.py +427 -463
  70. package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
  71. package/_bundled_plugin/scripts/workbench_finding_index.py +19 -1
  72. package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
  73. package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +27 -14
  75. package/_bundled_plugin/scripts/workbench_progress.py +14 -58
  76. package/_bundled_plugin/scripts/workbench_publication.py +33 -57
  77. package/_bundled_plugin/scripts/workbench_remediation.py +12 -0
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +172 -49
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +105 -41
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +23 -34
  82. package/_bundled_plugin/scripts/workbench_schema.py +37 -1151
  83. package/_bundled_plugin/scripts/workbench_source_excerpt.py +11 -1
  84. package/_bundled_plugin/scripts/workbench_target.py +430 -142
  85. package/_bundled_plugin/scripts/workbench_validation.py +16 -27
  86. package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
  87. package/_bundled_plugin/shared/workbench-migrations.json +397 -0
  88. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
  89. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
  90. package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
  91. package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +3 -3
  93. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  94. package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
  95. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
  96. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
  97. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  98. package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
  99. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  100. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +1 -1
  101. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +13 -1
  102. package/_bundled_plugin/skills/threat-model/SKILL.md +1 -1
  103. package/_bundled_plugin/skills/track-findings/SKILL.md +46 -178
  104. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  105. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
  106. package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
  107. package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
  108. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
  110. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
  111. package/bin/codex-security.mjs +9 -2
  112. package/dist/api.d.ts +60 -10
  113. package/dist/api.d.ts.map +1 -1
  114. package/dist/api.js +803 -380
  115. package/dist/api.js.map +1 -1
  116. package/dist/artifact-export.d.ts +1 -1
  117. package/dist/artifact-export.d.ts.map +1 -1
  118. package/dist/artifact-export.js +28 -13
  119. package/dist/artifact-export.js.map +1 -1
  120. package/dist/auth.d.ts +2 -6
  121. package/dist/auth.d.ts.map +1 -1
  122. package/dist/auth.js +19 -9
  123. package/dist/auth.js.map +1 -1
  124. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  125. package/dist/bulk-scan-discovery.js +1 -0
  126. package/dist/bulk-scan-discovery.js.map +1 -1
  127. package/dist/classify-severity.d.ts +26 -9
  128. package/dist/classify-severity.d.ts.map +1 -1
  129. package/dist/classify-severity.js +13 -30
  130. package/dist/classify-severity.js.map +1 -1
  131. package/dist/cli-help.d.ts.map +1 -1
  132. package/dist/cli-help.js +17 -13
  133. package/dist/cli-help.js.map +1 -1
  134. package/dist/cli-signals.d.ts +8 -0
  135. package/dist/cli-signals.d.ts.map +1 -0
  136. package/dist/cli-signals.js +28 -0
  137. package/dist/cli-signals.js.map +1 -0
  138. package/dist/cli.d.ts +4 -3
  139. package/dist/cli.d.ts.map +1 -1
  140. package/dist/cli.js +1087 -900
  141. package/dist/cli.js.map +1 -1
  142. package/dist/cloud-publish.d.ts.map +1 -1
  143. package/dist/cloud-publish.js +10 -9
  144. package/dist/cloud-publish.js.map +1 -1
  145. package/dist/codeowners.d.ts +19 -0
  146. package/dist/codeowners.d.ts.map +1 -0
  147. package/dist/codeowners.js +138 -0
  148. package/dist/codeowners.js.map +1 -0
  149. package/dist/codex-sdk-environment.d.ts +1 -0
  150. package/dist/codex-sdk-environment.d.ts.map +1 -1
  151. package/dist/codex-sdk-environment.js +40 -2
  152. package/dist/codex-sdk-environment.js.map +1 -1
  153. package/dist/component-plan.d.ts +2 -5
  154. package/dist/component-plan.d.ts.map +1 -1
  155. package/dist/component-plan.js +38 -30
  156. package/dist/component-plan.js.map +1 -1
  157. package/dist/component-scan.d.ts +6 -5
  158. package/dist/component-scan.d.ts.map +1 -1
  159. package/dist/component-scan.js +23 -35
  160. package/dist/component-scan.js.map +1 -1
  161. package/dist/config.d.ts.map +1 -1
  162. package/dist/config.js +64 -74
  163. package/dist/config.js.map +1 -1
  164. package/dist/contract.d.ts +15 -3
  165. package/dist/contract.d.ts.map +1 -1
  166. package/dist/contract.js +87 -252
  167. package/dist/contract.js.map +1 -1
  168. package/dist/cost-model.d.ts +13 -6
  169. package/dist/cost-model.d.ts.map +1 -1
  170. package/dist/cost-model.js +14 -4
  171. package/dist/cost-model.js.map +1 -1
  172. package/dist/cost.d.ts +10 -2
  173. package/dist/cost.d.ts.map +1 -1
  174. package/dist/cost.js +102 -104
  175. package/dist/cost.js.map +1 -1
  176. package/dist/custom-validation-prompt.d.ts.map +1 -1
  177. package/dist/custom-validation-prompt.js +6 -5
  178. package/dist/custom-validation-prompt.js.map +1 -1
  179. package/dist/custom-validation.d.ts +1 -2
  180. package/dist/custom-validation.d.ts.map +1 -1
  181. package/dist/custom-validation.js +9 -3
  182. package/dist/custom-validation.js.map +1 -1
  183. package/dist/deduplication/checkpointed-review.d.ts +4 -2
  184. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  185. package/dist/deduplication/checkpointed-review.js +23 -9
  186. package/dist/deduplication/checkpointed-review.js.map +1 -1
  187. package/dist/deduplication/codex-review.d.ts +7 -1
  188. package/dist/deduplication/codex-review.d.ts.map +1 -1
  189. package/dist/deduplication/codex-review.js +126 -17
  190. package/dist/deduplication/codex-review.js.map +1 -1
  191. package/dist/deduplication/deduplication-prompts.d.ts +5 -2
  192. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  193. package/dist/deduplication/deduplication-prompts.js +18 -4
  194. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  195. package/dist/deduplication/deduplication-reviewer.d.ts +26 -4
  196. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  197. package/dist/deduplication/deduplication-reviewer.js +57 -47
  198. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  199. package/dist/deduplication/deduplication.d.ts.map +1 -1
  200. package/dist/deduplication/deduplication.js +19 -51
  201. package/dist/deduplication/deduplication.js.map +1 -1
  202. package/dist/deduplication/diagnostics.d.ts +17 -0
  203. package/dist/deduplication/diagnostics.d.ts.map +1 -0
  204. package/dist/deduplication/diagnostics.js +5 -0
  205. package/dist/deduplication/diagnostics.js.map +1 -0
  206. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  207. package/dist/deduplication/finding-schema.js +7 -1
  208. package/dist/deduplication/finding-schema.js.map +1 -1
  209. package/dist/deduplication/local.d.ts +31 -0
  210. package/dist/deduplication/local.d.ts.map +1 -0
  211. package/dist/deduplication/local.js +166 -0
  212. package/dist/deduplication/local.js.map +1 -0
  213. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  214. package/dist/deduplication/records-protocol.js +11 -24
  215. package/dist/deduplication/records-protocol.js.map +1 -1
  216. package/dist/deduplication/records.d.ts +186 -11
  217. package/dist/deduplication/records.d.ts.map +1 -1
  218. package/dist/deduplication/records.js +10 -18
  219. package/dist/deduplication/records.js.map +1 -1
  220. package/dist/deduplication/scan.d.ts +9 -3
  221. package/dist/deduplication/scan.d.ts.map +1 -1
  222. package/dist/deduplication/scan.js +158 -39
  223. package/dist/deduplication/scan.js.map +1 -1
  224. package/dist/deep-config.d.ts +2 -1
  225. package/dist/deep-config.d.ts.map +1 -1
  226. package/dist/deep-config.js +4 -4
  227. package/dist/deep-config.js.map +1 -1
  228. package/dist/deep-progress.d.ts +2 -0
  229. package/dist/deep-progress.d.ts.map +1 -1
  230. package/dist/deep-progress.js +13 -10
  231. package/dist/deep-progress.js.map +1 -1
  232. package/dist/deep-scan.d.ts +20 -0
  233. package/dist/deep-scan.d.ts.map +1 -0
  234. package/dist/deep-scan.js +113 -0
  235. package/dist/deep-scan.js.map +1 -0
  236. package/dist/errors.d.ts +2 -0
  237. package/dist/errors.d.ts.map +1 -1
  238. package/dist/errors.js +2 -0
  239. package/dist/errors.js.map +1 -1
  240. package/dist/feedback.d.ts.map +1 -1
  241. package/dist/feedback.js +53 -21
  242. package/dist/feedback.js.map +1 -1
  243. package/dist/finding-catalogue.d.ts.map +1 -1
  244. package/dist/finding-catalogue.js +4 -8
  245. package/dist/finding-catalogue.js.map +1 -1
  246. package/dist/finding-normalization.d.ts +5 -0
  247. package/dist/finding-normalization.d.ts.map +1 -0
  248. package/dist/finding-normalization.js +120 -0
  249. package/dist/finding-normalization.js.map +1 -0
  250. package/dist/finding-retrieval.d.ts +9 -0
  251. package/dist/finding-retrieval.d.ts.map +1 -1
  252. package/dist/finding-retrieval.js.map +1 -1
  253. package/dist/finding-workflow.d.ts +13 -8
  254. package/dist/finding-workflow.d.ts.map +1 -1
  255. package/dist/finding-workflow.js +14 -6
  256. package/dist/finding-workflow.js.map +1 -1
  257. package/dist/findings-client.d.ts +2 -1
  258. package/dist/findings-client.d.ts.map +1 -1
  259. package/dist/findings-client.js +36 -9
  260. package/dist/findings-client.js.map +1 -1
  261. package/dist/findings-errors.d.ts +16 -0
  262. package/dist/findings-errors.d.ts.map +1 -0
  263. package/dist/findings-errors.js +24 -0
  264. package/dist/findings-errors.js.map +1 -0
  265. package/dist/findings-import.d.ts +1 -1
  266. package/dist/findings-import.d.ts.map +1 -1
  267. package/dist/findings-import.js +12 -30
  268. package/dist/findings-import.js.map +1 -1
  269. package/dist/github.d.ts.map +1 -1
  270. package/dist/github.js +7 -1
  271. package/dist/github.js.map +1 -1
  272. package/dist/import-scan.d.ts.map +1 -1
  273. package/dist/import-scan.js +48 -38
  274. package/dist/import-scan.js.map +1 -1
  275. package/dist/index.d.ts +8 -4
  276. package/dist/index.d.ts.map +1 -1
  277. package/dist/index.js +1 -1
  278. package/dist/index.js.map +1 -1
  279. package/dist/knowledge-base.d.ts +7 -1
  280. package/dist/knowledge-base.d.ts.map +1 -1
  281. package/dist/knowledge-base.js +114 -46
  282. package/dist/knowledge-base.js.map +1 -1
  283. package/dist/linear.d.ts.map +1 -1
  284. package/dist/linear.js +2 -7
  285. package/dist/linear.js.map +1 -1
  286. package/dist/mock-scan.d.ts.map +1 -1
  287. package/dist/mock-scan.js +0 -1
  288. package/dist/mock-scan.js.map +1 -1
  289. package/dist/models.d.ts +0 -2
  290. package/dist/models.d.ts.map +1 -1
  291. package/dist/models.js.map +1 -1
  292. package/dist/multiscan.d.ts +9 -3
  293. package/dist/multiscan.d.ts.map +1 -1
  294. package/dist/multiscan.js +193 -126
  295. package/dist/multiscan.js.map +1 -1
  296. package/dist/owner-evidence.d.ts +10 -2
  297. package/dist/owner-evidence.d.ts.map +1 -1
  298. package/dist/owner-evidence.js +67 -8
  299. package/dist/owner-evidence.js.map +1 -1
  300. package/dist/patch-tui.d.ts.map +1 -1
  301. package/dist/patch-tui.js +3 -2
  302. package/dist/patch-tui.js.map +1 -1
  303. package/dist/project-config.js +3 -3
  304. package/dist/project-config.js.map +1 -1
  305. package/dist/provider-profile.d.ts +21 -0
  306. package/dist/provider-profile.d.ts.map +1 -0
  307. package/dist/provider-profile.js +133 -0
  308. package/dist/provider-profile.js.map +1 -0
  309. package/dist/publication-events.d.ts +6 -8
  310. package/dist/publication-events.d.ts.map +1 -1
  311. package/dist/publication-events.js +25 -50
  312. package/dist/publication-events.js.map +1 -1
  313. package/dist/publication-store.d.ts.map +1 -1
  314. package/dist/publication-store.js +40 -64
  315. package/dist/publication-store.js.map +1 -1
  316. package/dist/publication.d.ts +1 -2
  317. package/dist/publication.d.ts.map +1 -1
  318. package/dist/publication.js +2 -8
  319. package/dist/publication.js.map +1 -1
  320. package/dist/publish.d.ts +1 -5
  321. package/dist/publish.d.ts.map +1 -1
  322. package/dist/publish.js +109 -160
  323. package/dist/publish.js.map +1 -1
  324. package/dist/request-metadata.d.ts +9 -0
  325. package/dist/request-metadata.d.ts.map +1 -0
  326. package/dist/request-metadata.js +13 -0
  327. package/dist/request-metadata.js.map +1 -0
  328. package/dist/runtime.d.ts +15 -4
  329. package/dist/runtime.d.ts.map +1 -1
  330. package/dist/runtime.js +430 -138
  331. package/dist/runtime.js.map +1 -1
  332. package/dist/saved-scan-bootstrap.d.ts +14 -0
  333. package/dist/saved-scan-bootstrap.d.ts.map +1 -0
  334. package/dist/saved-scan-bootstrap.js +261 -0
  335. package/dist/saved-scan-bootstrap.js.map +1 -0
  336. package/dist/saved-scan.d.ts +1 -1
  337. package/dist/saved-scan.d.ts.map +1 -1
  338. package/dist/saved-scan.js +6 -12
  339. package/dist/saved-scan.js.map +1 -1
  340. package/dist/scan-activity.js +11 -8
  341. package/dist/scan-activity.js.map +1 -1
  342. package/dist/scan-comparison.d.ts +28 -15
  343. package/dist/scan-comparison.d.ts.map +1 -1
  344. package/dist/scan-comparison.js +276 -281
  345. package/dist/scan-comparison.js.map +1 -1
  346. package/dist/scan-dashboard.d.ts +3 -0
  347. package/dist/scan-dashboard.d.ts.map +1 -1
  348. package/dist/scan-dashboard.js +345 -77
  349. package/dist/scan-dashboard.js.map +1 -1
  350. package/dist/scan-history-renderer.d.ts.map +1 -1
  351. package/dist/scan-history-renderer.js +54 -13
  352. package/dist/scan-history-renderer.js.map +1 -1
  353. package/dist/scan-inputs.d.ts +6 -0
  354. package/dist/scan-inputs.d.ts.map +1 -0
  355. package/dist/scan-inputs.js +71 -0
  356. package/dist/scan-inputs.js.map +1 -0
  357. package/dist/scan-logs.d.ts +2 -3
  358. package/dist/scan-logs.d.ts.map +1 -1
  359. package/dist/scan-logs.js +12 -6
  360. package/dist/scan-logs.js.map +1 -1
  361. package/dist/scan-sessions.d.ts +4 -0
  362. package/dist/scan-sessions.d.ts.map +1 -1
  363. package/dist/scan-sessions.js +17 -0
  364. package/dist/scan-sessions.js.map +1 -1
  365. package/dist/scan-skill-paths.d.ts +8 -0
  366. package/dist/scan-skill-paths.d.ts.map +1 -0
  367. package/dist/scan-skill-paths.js +47 -0
  368. package/dist/scan-skill-paths.js.map +1 -0
  369. package/dist/security-policy-cli.d.ts.map +1 -1
  370. package/dist/security-policy-cli.js +7 -27
  371. package/dist/security-policy-cli.js.map +1 -1
  372. package/dist/security-policy.d.ts +9 -5
  373. package/dist/security-policy.d.ts.map +1 -1
  374. package/dist/security-policy.js +33 -14
  375. package/dist/security-policy.js.map +1 -1
  376. package/dist/server/api.d.ts +0 -1
  377. package/dist/server/api.d.ts.map +1 -1
  378. package/dist/server/api.js +0 -1
  379. package/dist/server/api.js.map +1 -1
  380. package/dist/server/embeddings.d.ts +3 -1
  381. package/dist/server/embeddings.d.ts.map +1 -1
  382. package/dist/server/embeddings.js +10 -3
  383. package/dist/server/embeddings.js.map +1 -1
  384. package/dist/server/errors.d.ts +5 -2
  385. package/dist/server/errors.d.ts.map +1 -1
  386. package/dist/server/errors.js +7 -0
  387. package/dist/server/errors.js.map +1 -1
  388. package/dist/server/sqlite-store.d.ts +0 -2
  389. package/dist/server/sqlite-store.d.ts.map +1 -1
  390. package/dist/server/sqlite-store.js +54 -44
  391. package/dist/server/sqlite-store.js.map +1 -1
  392. package/dist/server/storage.d.ts +0 -2
  393. package/dist/server/storage.d.ts.map +1 -1
  394. package/dist/server/storage.js.map +1 -1
  395. package/dist/severity-store.js +19 -24
  396. package/dist/severity-store.js.map +1 -1
  397. package/dist/standalone-validation-prompt.d.ts +2 -0
  398. package/dist/standalone-validation-prompt.d.ts.map +1 -0
  399. package/dist/standalone-validation-prompt.js +10 -0
  400. package/dist/standalone-validation-prompt.js.map +1 -0
  401. package/dist/suggest-owners.d.ts +4 -2
  402. package/dist/suggest-owners.d.ts.map +1 -1
  403. package/dist/suggest-owners.js +11 -5
  404. package/dist/suggest-owners.js.map +1 -1
  405. package/dist/targets.d.ts +11 -0
  406. package/dist/targets.d.ts.map +1 -1
  407. package/dist/targets.js +106 -47
  408. package/dist/targets.js.map +1 -1
  409. package/dist/trusted-executable.d.ts +2 -2
  410. package/dist/trusted-executable.d.ts.map +1 -1
  411. package/dist/trusted-executable.js +8 -6
  412. package/dist/trusted-executable.js.map +1 -1
  413. package/dist/value.js +7 -0
  414. package/dist/value.js.map +1 -1
  415. package/dist/version.js.map +1 -1
  416. package/dist/workbench-arguments.d.ts +3 -0
  417. package/dist/workbench-arguments.d.ts.map +1 -0
  418. package/dist/workbench-arguments.js +15 -0
  419. package/dist/workbench-arguments.js.map +1 -0
  420. package/dist/worker-progress.d.ts +1 -0
  421. package/dist/worker-progress.d.ts.map +1 -1
  422. package/dist/worker-progress.js +27 -12
  423. package/dist/worker-progress.js.map +1 -1
  424. package/docs/cli.md +1778 -0
  425. package/docs/findings-service.md +402 -0
  426. package/package.json +18 -19
  427. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
  428. package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
  429. package/_bundled_plugin/scripts/workbench_findings.py +0 -221
  430. package/_bundled_plugin/scripts/workbench_severity.py +0 -122
  431. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
  432. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
  433. package/dist/server/dashboard/app.css +0 -2
  434. package/dist/server/dashboard/app.js +0 -66
  435. package/dist/server/dashboard/index.html +0 -18
  436. package/dist/server/dashboard-types.d.ts +0 -48
  437. package/dist/server/dashboard-types.d.ts.map +0 -1
  438. package/dist/server/dashboard-types.js +0 -2
  439. package/dist/server/dashboard-types.js.map +0 -1
  440. package/dist/server/dashboard.d.ts +0 -6
  441. package/dist/server/dashboard.d.ts.map +0 -1
  442. package/dist/server/dashboard.js +0 -59
  443. package/dist/server/dashboard.js.map +0 -1
  444. package/dist/server/index.d.ts +0 -2
  445. package/dist/server/index.d.ts.map +0 -1
  446. package/dist/server/index.js +0 -6
  447. package/dist/server/index.js.map +0 -1
  448. package/dist/server/routes.d.ts +0 -7
  449. package/dist/server/routes.d.ts.map +0 -1
  450. package/dist/server/routes.js +0 -98
  451. package/dist/server/routes.js.map +0 -1
  452. package/dist/server/serve.d.ts +0 -2
  453. package/dist/server/serve.d.ts.map +0 -1
  454. package/dist/server/serve.js +0 -28
  455. package/dist/server/serve.js.map +0 -1
  456. package/dist/server/server.d.ts +0 -10
  457. package/dist/server/server.d.ts.map +0 -1
  458. package/dist/server/server.js +0 -16
  459. package/dist/server/server.js.map +0 -1
  460. package/dist/server/validation.d.ts +0 -17
  461. package/dist/server/validation.d.ts.map +0 -1
  462. package/dist/server/validation.js +0 -53
  463. package/dist/server/validation.js.map +0 -1
package/docs/cli.md ADDED
@@ -0,0 +1,1778 @@
1
+ # CLI and workflows
2
+
3
+ The global installation provides both `codex-security` and its short alias `cs`.
4
+ They accept the same arguments and options. The examples below use
5
+ `codex-security`; you can also use `cs` or, without a global installation,
6
+ `npx @openai/codex-security`. See the [installation guide](../README.md#install).
7
+
8
+ ```bash
9
+ codex-security --help
10
+ codex-security scan --help
11
+ codex-security --version
12
+ codex-security info --json
13
+ ```
14
+
15
+ `--help` lists commands by task; `<command> --help` lists its options.
16
+ `info --json` reports package, plugin, runtime, and model details.
17
+ `scans` and `findings` default to their `list` subcommands.
18
+
19
+ ## Authentication
20
+
21
+ Sign in with ChatGPT, or supply an API key for CI:
22
+
23
+ ```bash
24
+ codex-security login
25
+ codex-security scan .
26
+
27
+ # Save an API key from the environment.
28
+ printenv OPENAI_API_KEY | codex-security login --with-api-key
29
+ ```
30
+
31
+ `OPENAI_API_KEY` and `CODEX_API_KEY` also work without saving a login.
32
+ Environment keys apply to the current command; only `login --with-api-key`
33
+ saves them. `login --with-access-token` accepts a Codex access token on stdin.
34
+ Access-token environment variables are not scan API keys.
35
+
36
+ On remote or headless machines, use `login --device-auth` if your workspace
37
+ allows it. If device auth is disabled, use SSH forwarding below.
38
+
39
+ On Windows, set a key in PowerShell:
40
+
41
+ ```powershell
42
+ $env:OPENAI_API_KEY = "<your-api-key>"
43
+ codex-security scan C:\code\repository
44
+ ```
45
+
46
+ ### Remote login with SSH forwarding
47
+
48
+ On your local machine, open a tunnel to the remote host:
49
+
50
+ ```bash
51
+ ssh -L 1455:localhost:1455 user@remote-host
52
+ ```
53
+
54
+ Run `codex-security login` in that SSH session and open its sign-in URL in
55
+ your local browser. Keep SSH connected until login finishes.
56
+
57
+ ### OpenAI credentials
58
+
59
+ Interactive scans ask which credentials to use when both ChatGPT and an
60
+ environment API key are available. Noninteractive commands prefer
61
+ `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials. Choose explicitly
62
+ with `--auth`:
63
+
64
+ ```bash
65
+ codex-security scan . --auth chatgpt
66
+ codex-security scan . --auth api-key
67
+ codex-security patch OCCURRENCE_ID --auth chatgpt
68
+ codex-security verify-fix OCCURRENCE_ID --auth api-key
69
+ ```
70
+
71
+ `--auth chatgpt` ignores environment API keys. `--auth api-key` requires a key.
72
+ The default is `auto`. Scans, validation, patching, and fix verification share
73
+ the stored login. Patch follow-up assessments and `scan --patch` retain the
74
+ chosen authentication. Environment keys do not replace the saved login.
75
+ The SDK uses `auth` on `run()`, `validate()`, and `preflight()`.
76
+
77
+ Stored OpenAI credentials live in
78
+ `$CODEX_SECURITY_STATE_DIR/codex-home`, or
79
+ `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this private home
80
+ outside the target and every enclosing Git worktree. It also serves providers
81
+ with `requires_openai_auth = true`.
82
+
83
+ Codex carries credential-storage, forced-login, and workspace settings from the
84
+ ambient configuration into this home. Managed-device policies still apply;
85
+ workspace-managed policies may require ChatGPT credentials even with an API key.
86
+ Without an overriding environment API key, scans and status checks import
87
+ existing file-based Codex credentials when this home is empty. Import errors make
88
+ `login status` exit with code 2 and SDK `account()` reject its promise. Logout
89
+ disables imports until you log in again. Status imports and logout share the
90
+ credential-home lock so a concurrent status check cannot restore credentials
91
+ after logout completes.
92
+
93
+ Scans and status checks expand a home-relative `CODEX_HOME` using the caller's
94
+ `HOME` or `USERPROFILE` environment setting.
95
+
96
+ If credentials cannot refresh, run `login status`. Retry if the sign-in recently
97
+ changed; otherwise run `logout`, then `login`.
98
+ Some cybersecurity requests and protected findings require
99
+ [Trusted Access for Cyber](https://chatgpt.com/cyber).
100
+
101
+ ### Daybreak Blue with an API key
102
+
103
+ The [Responses API defaults](https://developers.openai.com/api/docs/guides/daybreak#understand-defaults-when-omitted)
104
+ can apply Daybreak Blue to compatible mainline models when the API organization
105
+ and project have access. An omitted `access_programs.cyber` field does not by
106
+ itself mean that Daybreak treatment is disabled.
107
+
108
+ Choose a compatible model available to your project and select Daybreak Blue
109
+ explicitly:
110
+
111
+ ```bash
112
+ codex-security scan /path/to/repository \
113
+ --auth api-key --model "<model>" --cyber-access-program daybreak_blue
114
+ ```
115
+
116
+ In the SDK, select your model through `codexOverrides.model` and pass
117
+ `auth: "api-key"` and `cyberAccessProgram: "daybreak_blue"` in the scan options.
118
+ Use `--mode deep` in the CLI or `mode: "deep"` in SDK scan options for Deep Scan.
119
+ The selection reaches discovery and reducer workers, including resumed workers. See [Select a Cyber access program](#select-a-cyber-access-program)
120
+ for configuration precedence and the API-key feature setting.
121
+
122
+ The previously documented `gpt-daybreak-blue-latest` alias is
123
+ [deprecated](https://developers.openai.com/api/docs/models/gpt-daybreak-blue-latest).
124
+ Use a current model available to your project. `access_programs.cyber` is a
125
+ Responses API field; use the supported selector instead of passing it as a
126
+ `--codex` configuration key.
127
+
128
+ ### Select a Cyber access program
129
+
130
+ For the built-in OpenAI provider, choose `standard`, `daybreak_blue`, or
131
+ `daybreak_red`:
132
+
133
+ ```bash
134
+ codex-security scan . --auth api-key --cyber-access-program daybreak_blue
135
+ ```
136
+
137
+ ```ts
138
+ await security.run("/path/to/repository", {
139
+ auth: "api-key",
140
+ cyberAccessProgram: "daybreak_blue",
141
+ });
142
+ ```
143
+
144
+ `scan-components` accepts the same flag. Project files use
145
+ `scan.cyber_access_program`, including for bulk scans. Explicit CLI or SDK values
146
+ override the file; omission preserves Codex defaults. `standard` explicitly
147
+ selects the standard program.
148
+
149
+ The selection applies to workers, resumed scans, planning, matching, and scan
150
+ follow-ups. Recipes retain it for resume and rerun. API-key selection enables
151
+ Codex's experimental Cyber support unless native configuration explicitly disables
152
+ `features.api_key_cyber_access_programs`. A selection does not grant entitlement;
153
+ explicit disables and access denials remain errors.
154
+
155
+ ### Native command authentication and other providers
156
+
157
+ SDK callers can select a native command provider through
158
+ `codexOverrides.model_providers.<id>.auth` and `model_provider`, including a
159
+ selected profile. Codex runs the credential helper and renews its token. Scans,
160
+ comparisons, and deduplication preserve that selection. Relative helper paths and
161
+ `auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews
162
+ also honor the selected command provider in that home's `config.toml`.
163
+
164
+ For other providers, set their key and select a model the provider supports:
165
+
166
+ ```bash
167
+ export OPENROUTER_API_KEY="<your-openrouter-api-key>"
168
+ codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
169
+
170
+ export FIREWORKS_API_KEY="<your-fireworks-api-key>"
171
+ codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
172
+ ```
173
+
174
+ ### Amazon Bedrock
175
+
176
+ Use AWS credentials and a region with access to the exact Bedrock model ID:
177
+
178
+ ```bash
179
+ export AWS_PROFILE="security-scan"
180
+ export AWS_REGION="us-east-2"
181
+ codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna
182
+ ```
183
+
184
+ Run credential setup and the scan in the same shell or job. Bedrock scanning
185
+ uses AWS authentication, including in Deep Scan workers; it does not need an
186
+ OpenAI API key or separate CLI login. Publishing to Cloud requires separate
187
+ ChatGPT credentials. `info` and `--dry-run` do not verify AWS access.
188
+
189
+ See the [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
190
+ for credential alternatives, restricted-model access, cost estimates, and
191
+ reasoning-summary configuration.
192
+
193
+ ## Generate a security policy
194
+
195
+ Use `policy` to draft or update `SECURITY.md` before a scan. The policy describes
196
+ the project's security boundaries and what should count as a finding. This step
197
+ is optional: you can scan with an existing policy or without one.
198
+
199
+ From the repository root, run:
200
+
201
+ ```bash
202
+ codex-security policy .
203
+ ```
204
+
205
+ The command saves a draft outside the repository and leaves existing files
206
+ unchanged. In a terminal, it asks about facts the source cannot establish and
207
+ shows the proposed diff.
208
+
209
+ 1. Read the saved `SECURITY.md`, diff, and **Review notes**. Edit the draft as
210
+ needed. Preserve reporting instructions and confirm exclusions, accepted
211
+ risks, and severity decisions with the project owner.
212
+ 2. If you choose to use the draft, copy only the reviewed `SECURITY.md` to the
213
+ displayed **Policy target**. Keep the supporting documents outside the
214
+ repository.
215
+ 3. Run `codex-security scan .`. The scan reads the policy from the repository.
216
+
217
+ If you reject the draft, skip the copy and scan with your existing policy or
218
+ without one. If the command reports that `SECURITY.md` is already up to date, no
219
+ copy is needed; review any notes and continue to the scan.
220
+
221
+ You can leave answers blank during generation. Keep unresolved decisions
222
+ explicit in any policy you adopt, or scan without adopting the draft while you
223
+ resolve them. Regenerate if relevant source or neighboring policies changed
224
+ during generation.
225
+
226
+ ### Existing policies and components
227
+
228
+ If your existing root or component `SECURITY.md` already describes the relevant
229
+ security boundaries, scan with it directly. To propose an update, use `policy .`
230
+ for the root policy or select a component:
231
+
232
+ ```bash
233
+ codex-security policy . --path services/api
234
+ ```
235
+
236
+ This drafts `services/api/SECURITY.md`, whether or not that file already exists.
237
+ The repository defaults to the current directory. A component inherits policies
238
+ from its Git root, with the closest policy taking precedence. Inherited policies
239
+ may refer to ancestor `SECURITY.md` files or the checkout's `.github/SECURITY.md`
240
+ and `docs/SECURITY.md`; they cannot widen the component's scope.
241
+
242
+ A `.github/SECURITY.md` or `docs/SECURITY.md` often describes how to report
243
+ vulnerabilities. Keep those instructions: these files do not automatically
244
+ provide repository-wide scan guidance. Use a root `SECURITY.md` for that guidance,
245
+ or a component `SECURITY.md` for guidance specific to that directory. Before
246
+ replacing the policy target, check whether either reporting file links to it;
247
+ the replacement can affect their guidance too.
248
+
249
+ ### Generation options and saved files
250
+
251
+ Generation describes the system, builds a threat model, then drafts the policy.
252
+ Add context with `--knowledge-base`:
253
+
254
+ ```bash
255
+ codex-security policy . --knowledge-base architecture.md
256
+ ```
257
+
258
+ | Invocation | Result |
259
+ | ---------------------------- | -------------------------------------------------------- |
260
+ | `policy . --headless --json` | Generate without prompts; return paths and review notes. |
261
+ | `policy . --format md` | Generate and write the draft to stdout. |
262
+ | `policy . --dry-run --json` | Check local inputs without calling Codex. |
263
+
264
+ `--headless` leaves unanswered questions in the review notes. By default, files
265
+ go in the Codex Security state directory. To choose a location, use an empty
266
+ directory outside every enclosing checkout and its Git metadata:
267
+
268
+ ```bash
269
+ codex-security policy . --path services/api --headless \
270
+ --output-dir /path/outside/repository/api-policy --json
271
+ ```
272
+
273
+ | Artifact | Contents |
274
+ | ---------------------- | ----------------------------------------------- |
275
+ | `SECURITY.md` | Policy draft. |
276
+ | `threatmodel.md` | Threat model with source references. |
277
+ | `project-spec.md` | System description and security boundaries. |
278
+ | `previous-SECURITY.md` | Original policy used for the diff. |
279
+ | `policy-draft.json` | Target, hashes, stage status, and review notes. |
280
+
281
+ Keep supporting documents private until reviewed for disclosure. If governing
282
+ policies change during generation, the documents remain for inspection but no
283
+ completed-draft manifest is written. A preview failure reports saved paths.
284
+
285
+ `--max-cost` applies to the whole generation. Progress goes to stderr;
286
+ `--json` includes status and estimated cost. `--full-output` reports failures
287
+ with `ok: false`. If a stage cannot inspect required evidence, generation stops
288
+ and keeps completed documents. Fix the problem and retry in a new directory.
289
+
290
+ ### Source access and restrictions
291
+
292
+ The command uses scan authentication and read-only access to the selected source.
293
+ It denies Git metadata and sibling-component access, disables network, web, apps,
294
+ and MCP, and uses only Codex's core shell environment. Knowledge-base text stays
295
+ in private review artifacts during generation and is removed afterward.
296
+
297
+ Targets and links stay within the checkout and outside Git metadata. Linked
298
+ worktrees and initialized submodules use their own roots. For a separate Git
299
+ directory, set `core.worktree` to the checkout's absolute path; use
300
+ `git worktree repair` for moved linked worktrees.
301
+
302
+ Generation currently fails on Unix directories with non-UTF-8 names. On macOS,
303
+ the bundled runtime does not fully enforce write restrictions under `/tmp`
304
+ (including `/private/tmp`); keep source and artifacts elsewhere when read-only
305
+ enforcement is required. See the
306
+ [upstream sandbox issue](https://github.com/openai/codex/issues/32395).
307
+
308
+ ### Generate a policy from TypeScript
309
+
310
+ ```ts
311
+ import { CodexSecurity } from "@openai/codex-security";
312
+
313
+ const security = new CodexSecurity();
314
+ try {
315
+ const draft = await security.generatePolicy("/path/to/repository", {
316
+ path: "services/api",
317
+ knowledgeBasePaths: ["/path/to/architecture.md"],
318
+ onStage: (stage) => console.error(stage),
319
+ });
320
+ console.log(await security.previewPolicy(draft));
321
+ // Review the saved policy at draft.draftPath before installing it.
322
+ } finally {
323
+ await security.close();
324
+ }
325
+ ```
326
+
327
+ `preflightPolicy()` checks local inputs. `previewPolicy()` previews the supplied
328
+ in-memory draft and escapes terminal controls; editing its saved file does not
329
+ change that object. `securityPolicyDiff()` returns a raw diff for files and other
330
+ non-terminal uses, with an optional Python interpreter.
331
+
332
+ `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
333
+ `maxCostUsd`, `signal`, and progress/cost callbacks. `answerQuestions` receives
334
+ groups of up to three owner questions and a cancellation signal. Without the
335
+ callback, questions remain unresolved.
336
+
337
+ ## Scan options and output
338
+
339
+ ```bash
340
+ codex-security scan .
341
+ codex-security scan . --path src --path tests
342
+ codex-security scan . --diff origin/main --json
343
+ codex-security scan . --working-tree
344
+ codex-security scan . --output-dir /path/outside/repository/results --dry-run
345
+ ```
346
+
347
+ `--diff` scans committed changes; `--working-tree` scans staged and unstaged
348
+ changes. Deep scans support whole repositories and path scopes. Working-tree
349
+ snapshots include untracked nested Git repositories. Initialized submodules must
350
+ be clean and at the commit recorded by the parent.
351
+
352
+ Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
353
+ SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
354
+ explicit unsupported binary files are rejected. Bulk scans share this context
355
+ with every repository.
356
+
357
+ Output directories must be empty and outside the scanned directory and enclosing
358
+ Git worktree. On macOS/Linux, existing directories must be private (`chmod 700`).
359
+ `--archive-existing` moves earlier output to
360
+ `<output-dir>.previous-<timestamp>-<id>`; `--dry-run` previews the move.
361
+ SARIF, when produced, is saved at `<scan-dir>/exports/results.sarif`.
362
+
363
+ Completed scans exit with `0` by default. Configure `--fail-on-severity high`
364
+ to return `1` for high or critical findings. Scope exclusions, skipped files, and follow-up notes
365
+ do not fail a scan or bypass the findings threshold. Execution, target-integrity,
366
+ and required-output failures exit with `2`.
367
+
368
+ New reports omit `coverage.completeness`. Use `manifest.scan.status` and the
369
+ command exit code to distinguish execution failures from findings-policy violations.
370
+ Legacy completeness values affect neither.
371
+ Bulk and component summaries report completed and failed scans without an
372
+ `incomplete` count. Component matching errors have status `failed`.
373
+
374
+ New drafts use the current finding schema: `codeEvidence`, `rootCause`,
375
+ `attackPath.dataflow`, and `evidenceRefs`. Source snippets belong in
376
+ `codeEvidence`; `rootCause.evidenceRefs` links to them. Legacy aliases and
377
+ malformed optional fields are rejected before completion rather than repaired.
378
+ This applies to model-authored files, worker results, custom validation, and new
379
+ imports. Existing sealed reports remain readable and exportable without
380
+ rewriting their contents. Older unfinished drafts must be updated to the current
381
+ schema or completed with their original CLI/plugin version.
382
+
383
+ `scan`, `scans rerun`, and `scans resume` execution failures with `--json`, JSON,
384
+ or JSONL output produce:
385
+
386
+ ```json
387
+ { "status": "failed", "code": "SCAN_FAILED", "message": "..." }
388
+ ```
389
+
390
+ With `--full-output`, the error appears under `error` in an `ok: false` envelope.
391
+ If the scan target changed, the error explains that the results no longer
392
+ represent the current checkout. Retained sealed results remain available under
393
+ `data`, including their manifest, findings, coverage, scan directory, and report
394
+ path. Unsealed or invalid artifacts are not included. This also applies to
395
+ `scans rerun` and `scans resume`.
396
+ For `scans rerun` and `scans resume`, `--filter-output` applies to retained `data`;
397
+ selecting an unavailable field can return `null` or omit `data`.
398
+
399
+ Saved-scan setup failures use the same output shape with
400
+ `SCAN_REPLAY_UNAVAILABLE` for `scans rerun` (including when no completed scan is
401
+ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an imported
402
+ scan uses `SCAN_IMPORT_FAILED` if the import fails. Other output formats retain
403
+ stderr-only failures, including when `--full-output` is selected.
404
+
405
+ Diagnostics stay on stderr. Each command's `--schema --format json` describes
406
+ its successful output and failure codes.
407
+ See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
408
+
409
+ ### Project files
410
+
411
+ ```bash
412
+ codex-security init
413
+ codex-security scan . -c codex-security.yaml --dry-run --json
414
+ codex-security info -c codex-security.yaml --json
415
+ ```
416
+
417
+ Select a YAML or JSON file with `-c`, or set `CODEX_SECURITY_PROJECT_CONFIG`.
418
+ Explicit `-c` wins. Without either, no file is discovered. `scan`, `bulk-scan`,
419
+ `scan-components`, and `info` accept project files. SDK calls and saved reruns
420
+ do not load them automatically.
421
+
422
+ Treat the selected file as trusted operator configuration: native settings can
423
+ start MCP processes and choose model-service destinations. Keep CI scanner
424
+ configuration outside the untrusted checkout being assessed.
425
+
426
+ See [Project configuration](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
427
+ for settings, precedence, paths, schemas, and SDK loading. File paths resolve
428
+ from the config directory; scope paths resolve from the repository.
429
+
430
+ ### Import findings as a saved scan
431
+
432
+ ```bash
433
+ codex-security scan import --csv /path/to/findings.csv
434
+ codex-security scan import --json /path/to/findings.json --format json
435
+ codex-security scan import --csv /path/to/findings.csv --dry-run
436
+ ```
437
+
438
+ Supply exactly one input. CSV follows the
439
+ [findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
440
+ JSON accepts a complete `codex-security.findings` document or
441
+ `{ "findings": [...] }` matching the findings schema. For this command, `--json`
442
+ selects the input file; use `--format json` for JSON output. The input must be a
443
+ regular file with no symlinks or directory junctions in its path.
444
+
445
+ Each import creates a completed scan in local history, retains the input under
446
+ `artifacts/import/`, and preserves each occurrence, including duplicates.
447
+ Original identifiers live in `extensions.import`; referenced writeup paths are
448
+ metadata only. Completion means import finished; no security analysis occurred.
449
+ Import needs no model calls or authentication. `--dry-run` validates without
450
+ saving; `--output-dir` and `--archive-existing` control output. `scans rerun`
451
+ reimports the retained input.
452
+
453
+ ### Generate mock scan results
454
+
455
+ ```bash
456
+ codex-security scan /path/to/repository --mock
457
+ ```
458
+
459
+ The SDK equivalent is `security.run(repository, { mock: true })`. Mock scans
460
+ save synthetic results through the normal reporting and history flow without
461
+ model calls or authentication. Each contains 12 findings: eight stable across
462
+ runs, four with new identities, and two duplicate pairs for testing deduplication.
463
+ Paths and snippets are fictional; repository files remain unchanged.
464
+
465
+ Use a separate `CODEX_SECURITY_STATE_DIR` for disposable data. Output, exports,
466
+ archiving, and severity thresholds work normally. Reruns preserve mock mode.
467
+ Separate matching or deduplication commands still make their usual model calls.
468
+
469
+ Mock mode supports Standard repository, path, and diff scans. It cannot combine
470
+ with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan prompts.
471
+ Scan prompts and knowledge bases do not change the fixtures.
472
+
473
+ ### Attribute scans to end users
474
+
475
+ Pass a stable hashed ID when scanning on behalf of users:
476
+
477
+ ```bash
478
+ codex-security scan . --auth api-key --safety-identifier hashed-user-id
479
+ ```
480
+
481
+ ```ts
482
+ await security.run("/path/to/repository", {
483
+ auth: "api-key",
484
+ safetyIdentifier: hashedUserId,
485
+ });
486
+ ```
487
+
488
+ Use 1–64 characters, with no NUL or personal data such as email addresses.
489
+ The ID applies to workers, retries, and follow-ups. Supply it again for reruns.
490
+
491
+ The bundled runtime does not yet support native `--safety-identifier`; select a
492
+ compatible build with `CODEX_CLI_PATH` and a plugin that forwards it to workers.
493
+ The SDK checks the format, not runtime/plugin compatibility. Older versions may
494
+ omit the ID.
495
+
496
+ ### Scan project components
497
+
498
+ `scan --path` runs one scan over selected paths. `scan-components` runs a separate
499
+ scan for each component:
500
+
501
+ ```bash
502
+ codex-security scan-components /path/to/project \
503
+ --component apps/api --component apps/web --component packages/shared \
504
+ --workers 4 --output-dir /path/outside/project/results
505
+ ```
506
+
507
+ Use `-c FILE` to share scan settings, including Deep mode, context, cost limits,
508
+ and severity policy. Component plans override the file's scope. Use `--auto` to
509
+ propose a split, then review the saved plan:
510
+
511
+ ```bash
512
+ codex-security scan-components . --auto --plan-only \
513
+ --output-dir /path/outside/project/plan
514
+ codex-security scan-components . \
515
+ --components-file /path/outside/project/plan/components.json \
516
+ --output-dir /path/outside/project/results
517
+ ```
518
+
519
+ Plans use repository-relative paths:
520
+
521
+ ```json
522
+ {
523
+ "components": [
524
+ { "name": "API", "paths": ["apps/api", "packages/auth"] },
525
+ { "name": "Web", "paths": ["apps/web"] }
526
+ ]
527
+ }
528
+ ```
529
+
530
+ Automatic planning respects Git ignore rules and includes omitted inventory
531
+ files in `Other files` components. Large inventories require multiple planning
532
+ calls and may produce more components. Planning leaves source unchanged.
533
+
534
+ Each component saves artifacts under `component-N/`. Combined `findings.json`
535
+ groups high-confidence root-cause matches, keeping original IDs and the highest
536
+ severity. Uncertain matches stay separate. `summary.json` records component execution and
537
+ matching status; `report.md` links to component reports. Export or publish each
538
+ individual scan folder.
539
+
540
+ Failures do not stop other components. Failed scans or
541
+ failed matching return `2`; severity-policy violations return `1`. Retry with
542
+ `--components-file retry-components.json` and a new empty output directory.
543
+ The retry report covers only those components.
544
+
545
+ `--max-cost` applies per component, excluding planning and matching. `--model`
546
+ and `--effort` also apply to matching; `--auth` applies throughout. Planning and
547
+ matching reject ambient command providers that conflict with explicit ChatGPT
548
+ or API-key auth. SDK-selected command providers retain their authentication.
549
+
550
+ From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
551
+ Use `auto: true`, `planOnly: true`, and `scanOptions.auth` for the corresponding
552
+ planning and authentication choices.
553
+
554
+ ### Configure deep scans
555
+
556
+ ```ts
557
+ await security.run("/path/to/repository", {
558
+ mode: "deep",
559
+ workers: 2,
560
+ subagents: 0,
561
+ stopAfterNoNew: 3,
562
+ stopAfterConsecutiveErrors: 2,
563
+ maxDiscoveryRuns: 10,
564
+ maxTimeHours: 1.5,
565
+ });
566
+ ```
567
+
568
+ For `scan --mode deep`, `--workers` controls discovery concurrency and
569
+ `--subagents` controls subagents per worker. `--stop-after-no-new`,
570
+ `--max-discovery-runs`, and `--max-time-hours` stop discovery by novelty, count,
571
+ or duration. At the deadline, discovery stops; the scan then combines and returns
572
+ completed findings.
573
+
574
+ Use project-file `scan.deep` settings or legacy
575
+ `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
576
+ that `subagents` can be zero. Time accepts positive fractional hours up to 96.
577
+ `stopAfterConsecutiveErrors` is an SDK/project-file setting, with no CLI flag.
578
+ `--codex` does not configure deep-scan settings. See
579
+ [Deep settings and limits](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md#deep-settings-and-limits).
580
+
581
+ `bulk-scan --workers` controls concurrent repositories; `scan --workers` controls
582
+ workers within one Deep Scan. New recipes save all resolved deep settings so
583
+ resume and rerun do not depend on later changes to legacy defaults.
584
+
585
+ ### Runtime configuration and worker limits
586
+
587
+ Scans use an isolated Codex configuration. The default model and effort are
588
+ `gpt-5.6-sol` and `xhigh`. Multi-agent v2 allows nine concurrent threads: the
589
+ parent and up to eight delegated workers. That limit is separate from Deep Scan
590
+ and bulk worker counts.
591
+
592
+ ```bash
593
+ codex-security scan . --model gpt-6.1-sol --effort high \
594
+ --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
595
+ ```
596
+
597
+ Model IDs and `--effort` values pass through to Codex unchanged, including values
598
+ such as `minimal`, `none`, and `high`. Supported combinations depend on the model,
599
+ provider, Codex version, and credentials. Codex and provider errors are reported
600
+ without substituting another model or effort.
601
+ The flags also work with bulk/component scans, policy, validation, patching,
602
+ verification, owner suggestions, severity classification, and scan matching.
603
+ Matching and severity classification default to Codex's configured model and
604
+ `medium` effort. `dedupe` has separate default screening and review models;
605
+ the host's Codex model and effort settings override those defaults for both
606
+ stages.
607
+
608
+ `codex-security dedupe --scan SCAN_ID --json` prepares embeddings and deduplicates
609
+ directly in local SQLite. An optional `--findings-url URL` selects an existing
610
+ findings service instead. Local mode needs an embedding API key for missing or
611
+ stale vectors and a model provider for fresh reviews; it does not publish to
612
+ Cloud. See [deduplication](findings-service.md#deduplicate-a-scan) for scope,
613
+ credentials, and workflow resume behavior.
614
+
615
+ For `dedupe --scan latest`, matching across worktrees or clones requires a Git
616
+ executable outside all saved scan targets. If a historical target includes the
617
+ available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
618
+ explicit saved scan ID. Exact-path `latest` lookup still works without Git.
619
+
620
+ Repeat `--codex KEY=VALUE` for supported native settings. Quote strings as TOML:
621
+ `--codex 'model_reasoning_effort="high"'`. Repeated or conflicting keys are
622
+ rejected, including a `--model` or `--effort` flag plus its native equivalent.
623
+ Choose plugins with `--plugin-path`; native plugin and marketplace overrides are
624
+ rejected. New and resumed Deep Scans require the current plugin's direct engine,
625
+ worker provider snapshot, and isolated worker configuration capabilities. Update
626
+ older custom plugins or omit `--plugin-path` to use the bundled plugin. The SDK
627
+ no longer adapts direct `node ./mcp/server.mjs` entrypoints; use the current shell
628
+ or Windows MCP launcher. Saved reports remain readable.
629
+ Multi-agent v2 must remain enabled; `agents.max_threads` is unsupported.
630
+
631
+ `validate`, `patch`, and `verify-fix` limit native overrides to `model`,
632
+ `model_reasoning_effort`, `model_provider`, `model_providers`, and
633
+ `analytics.enabled`. For a custom provider:
634
+
635
+ ```bash
636
+ codex-security patch "Security issue" --model gateway-model \
637
+ --codex 'model_provider="gateway"' \
638
+ --codex 'model_providers.gateway.name="Gateway"' \
639
+ --codex 'model_providers.gateway.base_url="https://gateway.example.test/v1"' \
640
+ --codex 'model_providers.gateway.wire_api="responses"' \
641
+ --codex 'model_providers.gateway.env_key="GATEWAY_API_KEY"'
642
+ ```
643
+
644
+ Set the provider's key environment variable before running. Patching and
645
+ verification preserve unspecified provider settings from Codex configuration.
646
+ With `auto` or `api-key`, the provider's `env_key` takes precedence over OpenAI
647
+ account authentication. Explicit `--auth chatgpt` selects stored account auth,
648
+ omits the provider key, and clears any configured experimental bearer token for
649
+ that command. Model, effort, and provider choices carry into patch-risk assessment.
650
+
651
+ Model requests include Codex Security attribution in `responses_api_metadata`:
652
+ `codex_security_surface` (`cli` or `sdk`), `codex_security_command`,
653
+ `codex_security_package_version`, and `codex_security_plugin_version` when the
654
+ selected plugin declares a version. These fields identify the workflow and
655
+ versions producing a model request; they do not record command starts,
656
+ completions, or failures.
657
+
658
+ Disable Codex usage analytics and built-in metrics with
659
+ `--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
660
+ patch-risk assessment, and Deep Scan discovery and reducer workers, including
661
+ resumed workers. Deep Scan workers also preserve the scan's request metadata.
662
+ Model-request attribution metadata remains attached when analytics are disabled.
663
+ The setting does not control configured OpenTelemetry exporters, integrations,
664
+ authentication, or CLI update checks. Validation uses isolated configuration;
665
+ patching and verification preserve ambient project trust.
666
+
667
+ For filesystem and approval behavior, see the
668
+ [local security model](../README.md#local-security-model).
669
+
670
+ ### Environment variables
671
+
672
+ | Variable | Effect |
673
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
674
+ | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; the first takes precedence. |
675
+ | `CODEX_SECURITY_STATE_DIR` | Private history, database, and default artifacts. |
676
+ | `CODEX_SECURITY_PROJECT_CONFIG` | Selected project file; `-c` overrides it. |
677
+ | `CODEX_HOME` | Ambient Codex home; default `~/.codex`. |
678
+ | `CODEX_CLI_PATH` | Codex executable for login, setup, scans, and workers. |
679
+ | `PYTHON` | Python interpreter unless an explicit option overrides it. |
680
+ | `CODEX_SECURITY_LOG_LEVEL` | CLI diagnostics; `debug` enables verbose output. |
681
+ | `LOG_LEVEL` | Fallback if `CODEX_SECURITY_LOG_LEVEL` is unset or blank. |
682
+ | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default publication destination. |
683
+ | `CODEX_SECURITY_LINEAR_API_KEY` | Linear personal API key. |
684
+ | `CODEX_SECURITY_EMBEDDINGS_URL` | Local dedupe and findings service embeddings endpoint. |
685
+ | `GH_HOST` | GitHub Enterprise host for bulk discovery. |
686
+ | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Disable interactive update notices. |
687
+ | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update registry, in precedence order. |
688
+ | `CI` | Disable interactive update notices. |
689
+ | `NO_COLOR`, `TERM` | Disable colored history when `NO_COLOR` is defined or `TERM=dumb`. |
690
+
691
+ Custom Codex executables need thread source attribution for `exec` and
692
+ `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
693
+ command shims such as `codex.cmd` fall back to the bundled executable.
694
+
695
+ Python lookup: `--python` on commands that expose interpreter selection or SDK
696
+ `pythonPath`, then
697
+ `PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
698
+ works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
699
+
700
+ ### Troubleshooting
701
+
702
+ Use `--verbose` or `CODEX_SECURITY_LOG_LEVEL=debug` for lifecycle, configuration,
703
+ retry, and worker diagnostics on stderr. Diagnostic text is preserved in output,
704
+ saved failures, receipts, and patch-risk summaries. Review it for sensitive
705
+ information before sharing; upstream Codex output may already be redacted.
706
+
707
+ Keep state and reports when recovering authentication or locking problems.
708
+ Finish older-version operations before upgrading. Never remove
709
+ `.codex-security-scan.sqlite3` during an operation. Stop all operations using the
710
+ credential home before manually removing an old `.codex-security-scan.lock`.
711
+
712
+ On Windows, an older sandboxed run can leave invalid ACLs on a credential-home
713
+ ancestor. Preserve that state, then select a new private `CODEX_SECURITY_STATE_DIR`
714
+ outside the old state and repository. Sign in again if needed; the new directory
715
+ has separate scan history.
716
+
717
+ ### Progress and cost
718
+
719
+ Interactive scans show full-screen progress. CI, redirected output, `--headless`,
720
+ and `--verbose` use plain status lines. Results go to stdout; progress and
721
+ diagnostics go to stderr. Press `d` in the dashboard for details, then `a` for
722
+ all sources, `m` for the main scan, or `1`–`9` for a worker.
723
+
724
+ Token totals include input plus output; cache reads and writes are subsets of
725
+ input. Missing cache-write usage makes the uncached/cache-write breakdown
726
+ unavailable. The CLI cannot recover missing information already recorded as zero
727
+ by the runtime.
728
+
729
+ Cost displays use [standard API prices](https://developers.openai.com/api/docs/pricing)
730
+ and show a short/long-context range. They estimate model usage, excluding other
731
+ tiers, fees, surcharges, and account-specific pricing. They do not measure ChatGPT
732
+ subscription allowance. Models without known prices have no estimate.
733
+
734
+ JSON, history, and bulk receipts include `cost.estimatedUsdRange` (`min`, `max`,
735
+ and `context: "unknown"`). A null maximum means no upper estimate is available.
736
+ `cost.pricing` records source, verification date, tier, and rates. Older results
737
+ keep their legacy estimates. `cost.estimatedUsd` is the short-context baseline
738
+ used for spending limits; use the range for reporting. Missing cache-write usage
739
+ is recorded by `cacheWriteInputTokensReported: false`.
740
+
741
+ `--max-cost USD` stops the scan and workers after estimated cost exceeds the
742
+ limit; in-flight requests can finish above it. Bulk limits apply per repository
743
+ attempt. Post-scan prompts run after cost tracking and are outside this limit.
744
+ Automatic history matching gets at most one extra call with a limit; if more
745
+ work is needed, the scan is preserved and you can run `scans match --all`.
746
+
747
+ When Deep discovery has finished at a cost stop, the scan returns a sealed
748
+ report and lists unvalidated candidates as follow-up work. Reaching a configured
749
+ limit with a valid finalized report returns `0` by default, or `1` if findings
750
+ meet a configured failure threshold.
751
+
752
+ When Codex reports an exhausted usage limit, Deep Scan cancels active workers
753
+ and stops retrying or launching replacements. Completed worker artifacts are retained.
754
+
755
+ At 80% of a single interactive scan's limit, the dashboard offers a higher total
756
+ budget. Enter a larger total, or leave it blank/press Escape to keep the limit.
757
+ Work continues while you decide; the old limit remains active until saved.
758
+ CI, JSON/JSONL, headless, and verbose scans do not offer increases.
759
+
760
+ SDK callers can use `onBudgetApproaching({ maxCostUsd, cost, signal })`, returning
761
+ a larger total or `undefined`. It runs once per limit without blocking the scan.
762
+ Late responses after cancellation/completion are ignored; invalid increases or
763
+ save failures keep the existing limit. `onCost(cost, maxCostUsd)` reports changes.
764
+
765
+ ## Review one system across repositories
766
+
767
+ Use a single directory/path scan when an application spans repositories and you
768
+ want Codex to follow relationships between their source files. Put the checkouts
769
+ under one parent directory; that parent does not need to be a Git repository.
770
+ Select the relevant paths beneath it and supply the shared architecture and
771
+ reporting instructions explicitly:
772
+
773
+ ```text
774
+ workspace/
775
+ ├── application/
776
+ │ ├── api/ # Git checkout
777
+ │ ├── web/ # Git checkout
778
+ │ └── shared/ # Git checkout
779
+ ├── context/
780
+ │ ├── architecture.md
781
+ │ └── scan-instructions.md
782
+ └── results/
783
+ ```
784
+
785
+ From `workspace/`, run:
786
+
787
+ ```bash
788
+ codex-security scan ./application \
789
+ --mode deep \
790
+ --path api/src --path web/src --path shared/src \
791
+ --knowledge-base ./context/architecture.md \
792
+ --scan-prompt-file ./context/scan-instructions.md \
793
+ --output-dir ./results/system-review
794
+ ```
795
+
796
+ Scope paths are relative to `application/`. Context and output paths in this
797
+ example are relative to the working directory. Keep results outside the scanned
798
+ directory and any enclosing Git worktree. You do not need to add `AGENTS.md` or
799
+ `SECURITY.md` to each checkout to pass these documents.
800
+
801
+ Include both sides of a boundary you want reviewed, such as an API caller and
802
+ its authorization implementation. Architecture documents can explain deployment
803
+ facts and trust boundaries, but cannot replace missing source evidence. Identify
804
+ excluded or unavailable services in the context so their dependencies remain
805
+ explicit coverage limitations. Distinguish source that supports an investigation
806
+ from locations where you want findings reported.
807
+
808
+ Record each checkout's commit and local changes before scanning, and keep the
809
+ checkouts unchanged while a scan or resume is active. A non-Git parent is recorded
810
+ as one directory snapshot, rather than one pinned revision per child repository.
811
+ Use the saved scan ID when inspecting results and logs:
812
+
813
+ ```bash
814
+ codex-security scans show SCAN_ID
815
+ codex-security scans logs SCAN_ID
816
+ ```
817
+
818
+ See [scan history and reruns](#scan-history-and-reruns) for the distinction between
819
+ continuing an interrupted scan and starting a new run. Neither approach proves
820
+ that every possible cross-service path was reviewed; inspect the reported
821
+ coverage and unresolved questions alongside findings.
822
+
823
+ ## Bulk scans
824
+
825
+ Bulk scans run independent repository reviews in one resumable campaign. Shared
826
+ knowledge-base documents give each review application context; they do not make
827
+ the campaign a joint source review across repositories. For that workflow, use
828
+ [one system scan](#review-one-system-across-repositories).
829
+
830
+ Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
831
+ selection. It lists repositories pushed in the last 90 days, excluding forks
832
+ and archives, asks for output, and saves the selection as `repositories.csv`.
833
+ Private checkouts use your GitHub CLI login.
834
+
835
+ For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
836
+ Optional `scope`, `mode`, and `prompt` customize each row:
837
+
838
+ ```csv
839
+ id,repository,revision,scope,mode,prompt
840
+ service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Review authentication and authorization.
841
+ ```
842
+
843
+ ```bash
844
+ codex-security bulk-scan repositories.csv \
845
+ --output-dir /path/outside/repositories/results --workers 4
846
+ ```
847
+
848
+ Bulk scans use clean shallow checkouts and support repository/path scopes.
849
+ Configured diff or working-tree scopes are rejected unless every affected row
850
+ overrides them with a path scope. `--output-dir` requires CSV input.
851
+
852
+ Use `-c FILE` for shared settings; CSV mode/scope override file values.
853
+ `--scan-prompt-file` adds shared instructions before each row's prompt.
854
+ `--post-scan-prompt-file` runs a follow-up even after failure, but not after
855
+ cancellation or a cost stop.
856
+
857
+ Concurrency defaults to four repositories. `--max-attempts` defaults to one
858
+ attempt per pending repository per invocation. Repeating the command continues
859
+ the campaign, skips completed results, and starts pending attempts. Occupied
860
+ attempt directories stop that repository and suggest `--recover`.
861
+ Changes to project configuration, extracted knowledge-base text, staged document
862
+ filenames, direct Codex overrides, or explicit `--plugin-path`/`--python` selections
863
+ require a new output directory. Version 1 manifests also require a new directory
864
+ because their original knowledge inputs and direct overrides cannot be verified.
865
+ Worker and retry counts can change when resuming.
866
+
867
+ ### Recovering failed or interrupted bulk scans
868
+
869
+ Use the original CSV, output directory, and options:
870
+
871
+ ```bash
872
+ codex-security bulk-scan repositories.csv \
873
+ --output-dir /path/outside/repositories/results --recover
874
+ ```
875
+
876
+ Recovery requires a matching campaign manifest. It skips completed results
877
+ (including saved results with legacy coverage notes) and repositories never started. For each latest
878
+ failed or interrupted attempt:
879
+
880
+ - A sealed scan is recorded in `results.jsonl` without scanning again.
881
+ - An eligible running Deep Scan resumes its original session, keeping its ID,
882
+ workers, artifacts, settings, and accumulated cost.
883
+ - An unavailable, failed, or canceled scan starts a new attempt at the pinned
884
+ revision, preserving old artifacts and checkouts.
885
+
886
+ New attempts use `recovery-checkouts/<id>/attempt-<n>`. Recovery defaults to four
887
+ workers and one recovery/new attempt per repository. A resume connection failure
888
+ stops only that repository for this invocation. Failed recovery checkouts remain;
889
+ fresh completed checkouts are removed after recording their result.
890
+
891
+ Same-scan resume needs the original checkout, session logs, and state directory.
892
+ Recovery cannot reconstruct deleted checkpoints or fix execution failures.
893
+ New attempts incur new costs. Remaining execution failures return `2`;
894
+ completed severity-policy violations return `1` without retrying the scan.
895
+
896
+ ## Custom validation
897
+
898
+ Replace the final validation step of a Standard or diff scan with a prompt:
899
+
900
+ ```bash
901
+ codex-security scan . --validation-prompt-file validation.md
902
+ ```
903
+
904
+ ```ts
905
+ const result = await security.run(repository, {
906
+ validationPrompt:
907
+ "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",
908
+ });
909
+ ```
910
+
911
+ Source review still runs; discovery workers do not receive this prompt. Include
912
+ setup, authorized targets, required evidence, and cleanup. Use environment
913
+ variables for credentials. Deep scans reject custom validation; scans with no
914
+ candidates skip it. The SDK also accepts `validationPromptFile`.
915
+
916
+ The model must return a `CustomValidationResult` with one entry per candidate:
917
+
918
+ ```json
919
+ {
920
+ "status": "complete",
921
+ "reason": null,
922
+ "validations": [
923
+ {
924
+ "candidateId": "candidate-1",
925
+ "validation": {
926
+ "disposition": "reportable",
927
+ "method": "integration test",
928
+ "confidence": "high",
929
+ "confidence_rationale": "The test reproduced the reported behavior.",
930
+ "rubric": "Check the protected operation.",
931
+ "evidence": ["The unauthorized request succeeded."],
932
+ "counterevidence_or_proof_gap": "",
933
+ "remaining_uncertainty": "",
934
+ "artifact_paths": []
935
+ },
936
+ "severity": null,
937
+ "impact": null
938
+ }
939
+ ]
940
+ }
941
+ ```
942
+
943
+ Dispositions are `reportable`, `suppressed`, `not_applicable`, or `deferred`.
944
+ Set severity/impact to `{ "level": "medium", "rationale": "..." }` to revise
945
+ them, or null to retain them. Identity and source locations stay unchanged.
946
+
947
+ Candidates and results remain under `artifacts/custom-validation/`. Setup
948
+ failure or incomplete/invalid output fails the scan. Deferred candidates remain
949
+ follow-up notes and do not fail the scan. An incompatible plugin stops the scan.
950
+ Supply the validation prompt again when rerunning.
951
+
952
+ ## Publish findings to Cloud
953
+
954
+ Preview selected completed scans before uploading:
955
+
956
+ ```bash
957
+ codex-security publish scan --to cloud --dry-run --json
958
+ codex-security publish scan --scan SCAN_ID_A --scan SCAN_ID_B \
959
+ --to cloud --dry-run --json
960
+ ```
961
+
962
+ The interactive picker starts with nothing selected; press Space to select and
963
+ Enter to submit. Find IDs with `scans list --json`. Select by full ID, unique
964
+ prefix of at least eight characters, or `latest` for the current repository.
965
+ Local sealed artifacts are required. Dry runs need no login or network access.
966
+
967
+ Uploads require ChatGPT credentials saved to a file. Set
968
+ `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.
969
+ Cloud publication rejects automatic/keyring storage even when `auth.json` exists,
970
+ because that file may be stale or belong to another account.
971
+
972
+ Use a positional scan directory or repeated `--scan-dir PATH` for artifacts
973
+ outside history. Each must contain one completed sealed scan, not a bulk-run
974
+ directory or `results.jsonl`. Do not mix directories with `--scan`.
975
+ Cloud also accepts exported CSV:
976
+
977
+ ```bash
978
+ codex-security publish scan --to cloud --csv /path/outside/repository/findings.csv
979
+ ```
980
+
981
+ CSV cannot combine with scan selectors. Use the
982
+ [CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)
983
+ or `export --export-format csv` output.
984
+
985
+ One scan returns a receipt directly. Multiple scans return `results`, `failed`,
986
+ and `notAttempted` arrays. Uploads run sequentially and continue after individual
987
+ failures, returning `2` if any fail. Cancellation returns results so far with
988
+ `130` (Ctrl-C) or `143` (SIGTERM), unless every upload was already confirmed.
989
+
990
+ Save receipts: Cloud does not store them in local history. IDs are Cloud finding
991
+ IDs in request order. Uploads are not retried automatically. A missing receipt
992
+ can still mean the upload succeeded; check Cloud before retrying and do not
993
+ resend a confirmed upload.
994
+
995
+ ## Publish completed scans to Linear
996
+
997
+ ```bash
998
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID
999
+ ```
1000
+
1001
+ Select one completed scan by ID, prefix, `latest`, or directory; omit the selector
1002
+ for the picker. Live publication and `--skip-existing` require local history.
1003
+ A directory-only dry run does not.
1004
+
1005
+ `--linear-project PROJECT_ID` (`--project`) selects a project. Flags override
1006
+ `CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
1007
+ previews titles offline; `--json` returns structured output.
1008
+
1009
+ Sign in to Codex and connect Linear, or set `CODEX_SECURITY_LINEAR_API_KEY` to
1010
+ use its API directly. Direct API publication leaves issues unassigned unless
1011
+ `--linear-assignee` gives a user ID or email. Prefer the environment variable
1012
+ over `--linear-api-key`, which exposes the key in shell history/process listings.
1013
+ Keys are omitted from saved results; diagnostic messages remain unchanged.
1014
+
1015
+ ```bash
1016
+ codex-security publish check /path/to/completed-scan \
1017
+ --to linear --linear-team TEAM_ID --json
1018
+ ```
1019
+
1020
+ `publish check` verifies artifacts and recorded publications. With an API key,
1021
+ it also checks authentication and destination access. It does not test issue
1022
+ creation; connected-app access is reported as `not-checked`.
1023
+
1024
+ Each finding becomes an issue with severity, source, evidence, and remediation.
1025
+ Choose a destination authorized to receive that content. Local history records
1026
+ successful issue IDs separately from sealed artifacts.
1027
+
1028
+ Republishing creates duplicates unless `--skip-existing` finds a recorded success
1029
+ for that occurrence, team, and project. It does not check remote issues or cover
1030
+ unrecorded/concurrent publication. After interruption, inspect the handoff,
1031
+ evidence, and destination before retrying.
1032
+
1033
+ ```ts
1034
+ import { publishScan } from "@openai/codex-security";
1035
+
1036
+ const publication = await publishScan("/path/to/completed-scan", {
1037
+ destination: "linear",
1038
+ teamId: "TEAM_ID",
1039
+ skipExisting: true,
1040
+ });
1041
+ console.log(publication.scanId, publication.created.length);
1042
+ ```
1043
+
1044
+ Options also include `projectId`, `linearApiKey`, and `assigneeId` (ID or email).
1045
+ `checkScanPublication()` takes the same destination options for a read-only check.
1046
+
1047
+ ## Classify finding severity
1048
+
1049
+ Apply a rubric to completed findings without repeating discovery:
1050
+
1051
+ ```bash
1052
+ codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
1053
+ codex-security classify-severity --scan-dir /path/to/completed-scan --json
1054
+ ```
1055
+
1056
+ Use exactly one of `--scan` (ID, prefix, or `latest`) and `--scan-dir`.
1057
+ Omitting `--rubric` inherits original severity without model calls. Rubrics and
1058
+ repeatable `--knowledge-base` context accept text, PDF, DOCX, and directories.
1059
+ Each finding is classified in a separate read-only turn using its report and
1060
+ supplied context, without tools or source inspection. `--model` and `--effort`
1061
+ override Codex's configured model and the default medium effort.
1062
+
1063
+ Assessments contain `decision` (`assessed` or `excluded`), normalized `level`,
1064
+ the original `rubricLabel`, rationale, confidence, and a `reviewTrigger` for
1065
+ missing facts that could change the result. Exclusions have a null level.
1066
+ Finding/occurrence IDs and input hashes bind each assessment to its evidence.
1067
+
1068
+ Successful assessments checkpoint immediately in local SQLite. Retries reuse
1069
+ matching evidence, rubric, and context hashes; failed/canceled runs keep completed
1070
+ work. Use `--reprocess` to replace assessments, including when changing only model
1071
+ or effort. A successful run also writes `severity-classification.json`, but
1072
+ publication reads the database. Original findings and sealed artifacts remain
1073
+ unchanged.
1074
+
1075
+ Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
1076
+ `uniqueFindingIds` can represent findings from another scan; replace an outside-scan
1077
+ representative with a member of its `duplicateGroups` entry from this scan.
1078
+ Linear publication defaults to saved classification selection, omits exclusions,
1079
+ and uses assessed severity for title and priority. Descriptions retain original
1080
+ severity and add the classification rationale. Publication rejects incomplete or
1081
+ stale assessments. It never reclassifies or rereads the rubric at publication time.
1082
+
1083
+ ```bash
1084
+ codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
1085
+ --finding-id FINDING_ID
1086
+ codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
1087
+ ```
1088
+
1089
+ Linear publication also accepts `--finding-id`. If a classification exists, every
1090
+ selected finding needs an assessment. Existing tickets are not changed;
1091
+ `--skip-existing` preserves recorded tickets and human priority edits.
1092
+
1093
+ ```ts
1094
+ import {
1095
+ classifySeverity,
1096
+ classifyScanSeverity,
1097
+ classifyScanDirectorySeverity,
1098
+ publishScan,
1099
+ type FindingsDocument,
1100
+ } from "@openai/codex-security";
1101
+ import { readFile } from "node:fs/promises";
1102
+ import { join } from "node:path";
1103
+
1104
+ // Assess supplied reports in memory.
1105
+ const classification = await classifySeverity(findings, {
1106
+ rubricPath: "/path/to/policy.md",
1107
+ knowledgeBasePaths: ["/path/to/context.md"],
1108
+ });
1109
+
1110
+ // Save assessments for a scan ID or sealed directory.
1111
+ await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
1112
+ const scanFindings = (
1113
+ JSON.parse(
1114
+ await readFile(join(scanDirectory, "findings.json"), "utf8"),
1115
+ ) as FindingsDocument
1116
+ ).findings;
1117
+ const scanFindingIds = new Set(
1118
+ scanFindings.map((finding) => finding.findingId),
1119
+ );
1120
+ // dedupeResult was produced by deduplicating this same scan.
1121
+ const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
1122
+ if (scanFindingIds.has(representative)) return representative;
1123
+ return dedupeResult.duplicateGroups
1124
+ .find((group) => group.includes(representative))!
1125
+ .find((member) => scanFindingIds.has(member))!;
1126
+ });
1127
+ await classifyScanDirectorySeverity(scanDirectory, {
1128
+ rubricPath: "/path/to/policy.md",
1129
+ findingIds: selectedIds,
1130
+ });
1131
+
1132
+ // Or supply an in-memory assessment directly to publication.
1133
+ await publishScan(scanDirectory, {
1134
+ destination: "linear",
1135
+ teamId: "TEAM_ID",
1136
+ classification,
1137
+ findingIds: classification.assessments.map(({ findingId }) => findingId),
1138
+ dryRun: true,
1139
+ });
1140
+ ```
1141
+
1142
+ `classifySeverity()` accepts `findingId`, `title`, `summary`, and available
1143
+ evidence/metadata. Imported reports may lack severity or occurrence IDs; missing
1144
+ severity requires a rubric. Scan wrappers persist checkpoints (including for
1145
+ external directories), accept `reprocess: true`, and treat `findingIds: []` as an
1146
+ empty selection. Use the same `CODEX_SECURITY_STATE_DIR` for classification and
1147
+ publication. Older JSON-only assessments need reclassification once. All
1148
+ classification methods accept `signal`; keep human overrides in your workflow.
1149
+
1150
+ ## Suggest finding owners
1151
+
1152
+ ```bash
1153
+ codex-security suggest-owners findings.json --source-root /path/to/repo --json > owners.json
1154
+ ```
1155
+
1156
+ Input is a findings document or `{ "findings": [...] }`. The source root
1157
+ defaults to the current directory. The command reads committed `HEAD`, relevant
1158
+ source, CODEOWNERS, blame, and history; it does not read uncommitted source or assign tickets.
1159
+ Finding location paths are relative to the Git worktree root, including when
1160
+ `--source-root` points to a subdirectory. A location for `src/handler.ts` keeps
1161
+ that prefix; a location of `handler.ts` refers to the root file. Rebase imported
1162
+ subdirectory-relative locations to repository-relative paths before suggesting
1163
+ owners.
1164
+
1165
+ Linked worktrees and bound separate Git directories are supported; borrowed
1166
+ external object stores such as `git clone --shared` are rejected.
1167
+
1168
+ CODEOWNERS declarations take priority over Git history, following
1169
+ [GitHub's CODEOWNERS rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
1170
+ The last matching rule wins, and the command returns its first declared owner.
1171
+ Git history is the fallback when no declared owner applies.
1172
+
1173
+ Results preserve IDs and report `identified`, `abstained`, or `error`. Identified
1174
+ owners include a declared GitHub user, team, or email, or an observed Git
1175
+ name/email, with a reason and checked citations.
1176
+ Git identities do not establish current employment or tracker accounts; match
1177
+ accounts before assigning. Use a checkout matching the findings.
1178
+
1179
+ An owner can be a Git name/email identity, a GitHub user or team handle,
1180
+ an email-only identity, or `null`. Example JSON excerpt:
1181
+
1182
+ ```json
1183
+ {
1184
+ "schemaVersion": 2,
1185
+ "results": [
1186
+ {
1187
+ "owner": {
1188
+ "kind": "group",
1189
+ "provider": "github",
1190
+ "handle": "example/maintainers"
1191
+ }
1192
+ }
1193
+ ]
1194
+ }
1195
+ ```
1196
+
1197
+ The command uses scan-default model/effort; override with `--model` and `--effort`.
1198
+ The model receives collected evidence with tools/network disabled. Exit `0`
1199
+ includes abstentions; `2` means invalid input or a failed recommendation, while
1200
+ retaining other results. Cancellation uses `130` or `143`.
1201
+
1202
+ ```ts
1203
+ import { suggestOwners } from "@openai/codex-security";
1204
+
1205
+ const owners = await suggestOwners("/path/to/repo", result.findings.findings, {
1206
+ reasoningEffort: "high",
1207
+ });
1208
+ for (const { owner } of owners.results) {
1209
+ if (owner === null) continue;
1210
+ console.log("handle" in owner ? owner.handle : owner.email);
1211
+ }
1212
+ ```
1213
+
1214
+ SDK inputs can include `sourceRevision`. If it differs from `HEAD`, the collector
1215
+ ignores stale line ranges and reports the mismatch. Reports remain separate from
1216
+ scan artifacts and record the analyzed revision and limitations.
1217
+
1218
+ ## Feedback
1219
+
1220
+ ```bash
1221
+ codex-security feedback --reason "The scan stopped before it finished"
1222
+ codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
1223
+ ```
1224
+
1225
+ Share the returned ID with support. Without a selector, `feedback` uses the most
1226
+ recently started scan in the current repository, including failed/active scans,
1227
+ or sends a general report if none exist. Reports include your description,
1228
+ versions, and selected scan/session IDs. `--json` returns structured output.
1229
+
1230
+ Logs are off by default. `--include-logs` sends Codex diagnostics and saved scan/
1231
+ worker activity, potentially including source, prompts, findings, and tool output.
1232
+ Include only logs you can share with OpenAI. `feedback.enabled = false` disables
1233
+ the service.
1234
+
1235
+ For Desktop-plugin scans, run on the machine where the scan ran with the same
1236
+ Codex home and state directory. The command searches active/archived sessions and
1237
+ recorded worker descendants. Standard scans in an existing Codex conversation
1238
+ attach only their owner's session. Unrecorded earlier retry sessions may be absent.
1239
+
1240
+ ## Scan history and reruns
1241
+
1242
+ Commands default to the current repository. IDs accept unique prefixes of at
1243
+ least eight characters.
1244
+
1245
+ | Command | Purpose |
1246
+ | ----------------------------------------------------- | ---------------------------------------------------------- |
1247
+ | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
1248
+ | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
1249
+ | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
1250
+ | `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |
1251
+ | `scans rerun [SCAN_ID]` | Repeat on the current checkout. |
1252
+ | `scans match BEFORE AFTER` | Link findings with the same root cause. |
1253
+ | `scans match --all` | Match completed scans across worktrees/clones. |
1254
+ | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
1255
+ | `findings list [REPOSITORY]` | List open findings. |
1256
+ | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
1257
+
1258
+ Without an ID, `scans show` selects the latest completed scan, while `scans logs`
1259
+ selects the latest scan of any status. After a successful scan followed by a
1260
+ failed or active scan, these defaults refer to different runs. Human output
1261
+ identifies the selected run, labels its saved update time, and gives matching
1262
+ commands with its full scan ID:
1263
+
1264
+ ```bash
1265
+ codex-security scans show SCAN_ID
1266
+ codex-security scans logs SCAN_ID
1267
+ ```
1268
+
1269
+ Completion summaries include that ID and the saved results directory. Failure
1270
+ summaries include the same navigation when the current run was registered, plus
1271
+ the last observed phase when available. A failure before registration has no
1272
+ scan ID. The handoff uses that run's registration receipt without querying scan
1273
+ history. Inspect its saved status before choosing resume or rerun, and supply
1274
+ the original custom prompt files for reruns. Structured history and log output
1275
+ and command selection defaults are unchanged.
1276
+
1277
+ Recipes save settings and authentication choice, not credentials. Reruns use the
1278
+ current checkout/context files and do not reload project files. Supply replacement
1279
+ scan and custom-validation prompts when the original used them:
1280
+
1281
+ ```bash
1282
+ codex-security scans rerun SCAN_ID --scan-prompt-file instructions.md
1283
+ ```
1284
+
1285
+ A rerun creates a new scan. When the original has saved input identities, the
1286
+ rerun reports changes to the scan instructions or knowledge base. `scans show`
1287
+ includes the saved scope, runtime and Deep Scan settings, instruction digest,
1288
+ and knowledge snapshot/document digests. JSON includes these identities under
1289
+ `recipe.scanInputs`. The instruction digest covers the exact UTF-8 prompt text;
1290
+ document digests cover the extracted text workers receive. These identities
1291
+ describe supplied inputs, not proof that a model read or followed every passage.
1292
+
1293
+ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
1294
+ `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. Keep it private,
1295
+ writable, and outside the target repository. Session logs may contain sensitive
1296
+ data even though scan recipes do not store credentials.
1297
+
1298
+ Codex may compress saved session logs to `.jsonl.zst`. Reading those logs requires
1299
+ Node.js 22.15.0+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14,
1300
+ compressed sessions are unavailable to `scans logs`, feedback attachments, and
1301
+ `scans resume`. Upgrade Node.js to read or resume these sessions. Plain `.jsonl`
1302
+ logs work on all supported runtimes.
1303
+
1304
+ ### Resuming an interrupted Deep Scan
1305
+
1306
+ ```bash
1307
+ codex-security scans list --scan-root /path/to/security-scans
1308
+ codex-security scans resume SCAN_ID
1309
+ ```
1310
+
1311
+ The scan must still be `running`, with its original checkout, output directory,
1312
+ and Codex session in the same state directory. Checkout identity, revision, and
1313
+ contents must match. Completed, failed, and canceled scans need a rerun instead.
1314
+
1315
+ Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
1316
+ settings/instructions. Knowledge-bearing scans save their extracted documents in
1317
+ the private `.scan-knowledge.json` continuation file beside the scan artifacts.
1318
+ Resume verifies and uses that snapshot even if the original files changed or were
1319
+ deleted. Preserve it with the scan directory; canonical reports do not embed its
1320
+ document text. Old individual scans without a saved knowledge snapshot require a
1321
+ new scan when they used a knowledge base. Old scans without a knowledge base and
1322
+ bulk campaigns with an already-bound snapshot retain their existing resume path.
1323
+ New records save the authentication mode, explicit safety
1324
+ identifier, and post-scan prompt; older records cannot reconstruct missing values.
1325
+ A failed connection leaves the scan available for another resume attempt.
1326
+ Compatible scans can resume after plugin updates; sealed results keep their
1327
+ original producer version. Unsupported artifacts are rejected without rewriting them.
1328
+
1329
+ For bulk scans, use [bulk recovery](#recovering-failed-or-interrupted-bulk-scans)
1330
+ to update campaign receipts. Individual resume does not update `results.jsonl`.
1331
+
1332
+ ### Matching saved scans
1333
+
1334
+ Matching uses sealed artifacts and cached decisions unless `--force` is supplied.
1335
+ Comparisons classify findings as new, persisting, reopened, not observed, resolved,
1336
+ or unknown. An absent finding in the later scope is not observed; absence alone
1337
+ does not verify remediation. A finding is resolved only after it was explicitly
1338
+ closed as already fixed. Excluded paths and uncertain matches remain unknown.
1339
+ One comparison ID is compared with the latest completed scan.
1340
+
1341
+ ```bash
1342
+ codex-security scans match --all --force --model gpt-6.1-sol --effort high
1343
+ ```
1344
+
1345
+ Only high-confidence root-cause matches are grouped. Uncertain and related
1346
+ findings remain separate. Rebuilding retains stable identities, triage, and
1347
+ sealed artifacts; interruption preserves completed comparisons. Model/effort
1348
+ changes alone do not invalidate cached decisions.
1349
+
1350
+ ```ts
1351
+ import { readFile } from "node:fs/promises";
1352
+ import {
1353
+ matchScanFindings,
1354
+ type FindingsDocument,
1355
+ } from "@openai/codex-security";
1356
+
1357
+ const before = JSON.parse(
1358
+ await readFile("/path/to/earlier-scan/findings.json", "utf8"),
1359
+ ) as FindingsDocument;
1360
+ const after = JSON.parse(
1361
+ await readFile("/path/to/later-scan/findings.json", "utf8"),
1362
+ ) as FindingsDocument;
1363
+
1364
+ const comparison = await matchScanFindings(
1365
+ { before: before.findings, after: after.findings },
1366
+ { workingDirectory: "/path/to/repository" },
1367
+ );
1368
+ console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
1369
+ ```
1370
+
1371
+ This SDK method does not save a workbench comparison. `knownFindingGroups` can
1372
+ reuse confirmed stable `findingId` groups; results identify original occurrence
1373
+ IDs. Options include model, reasoning effort, `signal`, and `onProgress`.
1374
+ Progress callback failures do not stop matching.
1375
+
1376
+ ## Exports and CI
1377
+
1378
+ `export` reads saved results without Codex or credentials. It defaults to the
1379
+ current repository's latest completed scan. Choose either a positional result
1380
+ directory or `--scan ID`. Findings require sealed results and support
1381
+ `--export-format csv|json|sarif` (default SARIF). `--source-root PATH` adds SARIF
1382
+ source-line fingerprints.
1383
+
1384
+ ```bash
1385
+ codex-security export --scan SCAN_ID --export-format json --output findings.json
1386
+ codex-security export --artifact threat-model --output docs/threatmodel.md
1387
+ codex-security export /path/to/policy-results --artifact threat-model --output -
1388
+ ```
1389
+
1390
+ Threat-model exports use Markdown and default to `./threatmodel.md`. Standard,
1391
+ Deep, Diff, and policy workflows retain models when available; component/bulk
1392
+ runs save one per child. Explicit results may expose a model before completion
1393
+ or after later failure. Missing models return an error rather than generating
1394
+ or substituting one. Historical models in sealed scans need a matching manifest
1395
+ digest.
1396
+
1397
+ `--output -` emits only artifact content, with diagnostics on stderr. Markdown
1398
+ and CSV stdout cannot combine with JSON command output. Exporting into a checkout
1399
+ does not make the model scan input; pass it with `--knowledge-base`.
1400
+
1401
+ `ScanResult.threatModel` and `threatModelPath` expose the retained model and
1402
+ document, or null. Export still works if the document could not be written.
1403
+
1404
+ ```ts
1405
+ import { exportArtifact } from "@openai/codex-security";
1406
+
1407
+ const exported = await exportArtifact({
1408
+ source: { directory: "/path/to/scan-results" }, // Or { scanId: "SCAN_ID" }.
1409
+ artifact: "threat-model",
1410
+ output: "/path/to/threatmodel.md",
1411
+ });
1412
+ console.log(exported.path, exported.provenance);
1413
+ ```
1414
+
1415
+ Use `artifact: "findings"` with `format: "csv" | "json" | "sarif"` for findings.
1416
+ `output: "-"` streams stdout and returns null path/provenance. `pythonPath`
1417
+ selects an interpreter; `signal` cancels.
1418
+
1419
+ JSON preserves sealed findings. CSV marks them open, omits local triage state,
1420
+ and retains distinct occurrence IDs. It escapes spreadsheet-formula prefixes and
1421
+ leading apostrophes; import removes the escape. Use JSON to recover ambiguous
1422
+ apostrophes from older CSV exports.
1423
+
1424
+ For CI, place output outside the checkout and set a severity threshold:
1425
+
1426
+ ```bash
1427
+ SCAN_ROOT="$(mktemp -d)"
1428
+ codex-security scan . --diff origin/main \
1429
+ --output-dir "$SCAN_ROOT/results" --json --fail-on-severity high \
1430
+ > "$SCAN_ROOT/findings.json"
1431
+ ```
1432
+
1433
+ | Exit code | Meaning |
1434
+ | ------------- | ------------------------------------------------------------------------ |
1435
+ | `0` | Complete report-only scan or passing severity policy. |
1436
+ | `1` | Severity policy violation. |
1437
+ | `2` | Invalid input, runtime error, target change, or required-output failure. |
1438
+ | `130` / `143` | Interrupt / termination. |
1439
+
1440
+ JSON scans have no interactive controls. `validate`, `login`, and `logout` reject
1441
+ `--json`. Use `validate --output-schema FILE` for a schema-checked JSON assessment.
1442
+ For GitHub Actions setup, see the
1443
+ [Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md)
1444
+ or the [Bedrock workflow](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md).
1445
+
1446
+ ### Local pre-commit checks
1447
+
1448
+ `install-hook` checks staged and unstaged changes, blocking the commit on scan
1449
+ failure or findings at/above its threshold (`high` by default). Use required CI
1450
+ for enforcement; local hooks are optional.
1451
+
1452
+ Install the CLI outside the target repository and run that copy directly. `npx`
1453
+ can select a repository-local package. Before installation, inspect:
1454
+
1455
+ ```bash
1456
+ git -C /path/to/repository rev-parse --git-path hooks/pre-commit
1457
+ ```
1458
+
1459
+ Resolve relative output against the repository. Leave custom, linked, shared, or
1460
+ unverified hooks/directories alone; contact their owner or use CI. If the directory
1461
+ belongs only to this repository and no hook exists, run from outside the checkout:
1462
+
1463
+ ```bash
1464
+ codex-security install-hook /path/to/repository
1465
+ ```
1466
+
1467
+ To migrate an existing generated hook, verify it is a regular file used only by
1468
+ this repository and contains only the generated command. Preserve its severity.
1469
+ The installer can update older `npx` hooks when the severity matches. New hooks
1470
+ record absolute Node/CLI paths. If those change, back up and remove the verified
1471
+ generated hook, then reinstall with the same threshold. Restore the backup if
1472
+ installation fails. The installer respects `core.hooksPath`.
1473
+
1474
+ ## Import alerts from the CLI
1475
+
1476
+ ```bash
1477
+ codex-security import github example/repository --format json > /path/outside/repository/alerts.json
1478
+ codex-security import github example/repository --github-alert 12 --github-alert 18 --format json
1479
+ codex-security validate /path/outside/repository/alerts.json
1480
+ ```
1481
+
1482
+ Run validation from the matching local repository. Import defaults to open alerts
1483
+ on the default branch. Use `--github-state open|closed|dismissed|fixed|all` or
1484
+ `--github-ref REF` to filter. Exact alert numbers ignore state and reject a
1485
+ nondefault state.
1486
+
1487
+ Import is read-only and returns an array. Save validation inputs without output
1488
+ filters or token limits. It includes third-party SARIF uploads, does not start
1489
+ Codex, and does not check out code. Each record contains `source`, `repository`,
1490
+ `number`, `url`, and the full upstream `alert`.
1491
+
1492
+ For a disposition per alert, import and validate through the SDK:
1493
+
1494
+ ```ts
1495
+ import {
1496
+ CodexSecurity,
1497
+ importGitHubCodeScanningAlerts,
1498
+ } from "@openai/codex-security";
1499
+
1500
+ const findings = await importGitHubCodeScanningAlerts({
1501
+ repository: "example/repository",
1502
+ alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
1503
+ githubToken: process.env["GH_TOKEN"],
1504
+ });
1505
+
1506
+ const security = new CodexSecurity();
1507
+ try {
1508
+ for (const finding of findings) {
1509
+ const result = await security.validate({
1510
+ repositoryPath: "/path/to/repository",
1511
+ finding,
1512
+ });
1513
+ console.log(finding.url, result.disposition, result.outputDir);
1514
+ }
1515
+ } finally {
1516
+ await security.close();
1517
+ }
1518
+ ```
1519
+
1520
+ SDK options include `state` (default `"open"`), `ref`, and `signal`.
1521
+ Supply `githubToken` or use `gh auth token` credentials, including GitHub CLI
1522
+ token environment variables. `githubHost` defaults to `GH_HOST` or `github.com`.
1523
+ The token needs code-scanning read access; access failures reject the import.
1524
+
1525
+ ## Validate and patch findings
1526
+
1527
+ `validate` assesses candidates from local source evidence without building the
1528
+ target, executing application code, running tests or PoCs, or contacting services.
1529
+ It uses a read-only sandbox. Standard, Deep, and diff scans retain their existing
1530
+ validation, and `patch` still fixes and verifies findings. Both commands accept files
1531
+ or literal text and work in the current directory. Saved finding/occurrence IDs
1532
+ select their original repository for patching.
1533
+
1534
+ ```bash
1535
+ codex-security validate "Possible SQL injection" --effort high
1536
+ codex-security validate findings.json --knowledge-base ./context --context "Check the tenant boundary."
1537
+ codex-security validate findings.json --context-file context.md --output-schema result.schema.json > assessment.json
1538
+ codex-security patch OCCURRENCE_ID
1539
+ codex-security patch --scan SCAN_ID --severity high --json
1540
+ codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
1541
+ ```
1542
+
1543
+ Context inputs are optional and can be combined:
1544
+
1545
+ - `--context TEXT` adds inline security context or reviewer feedback.
1546
+ - `--context-file PATH` reads a single UTF-8 file.
1547
+ - Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
1548
+ document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
1549
+ are searched recursively; binary files, symlinks, and Git metadata are skipped.
1550
+
1551
+ Inline and file context are included in the prompt. Knowledge-base documents are
1552
+ prepared in a temporary directory for Codex to read during the assessment, then
1553
+ removed. Context is separate from findings and checked against source evidence;
1554
+ feedback alone does not dismiss a finding.
1555
+
1556
+ By default, `validate` prints a readable assessment without JSON-schema checking.
1557
+ `--output-schema PATH` supplies the schema to Codex **before generation** using
1558
+ native structured output. The CLI also checks the completed JSON before writing
1559
+ stdout; it does not convert a prose assessment into JSON afterward. Invalid JSON
1560
+ or a schema mismatch fails with exit code 2 and no assessment on stdout.
1561
+
1562
+ Use a self-contained schema in the subset supported by the selected Codex model
1563
+ and provider. The local checker uses JSON Schema 2020-12, but accepting a schema
1564
+ locally does not guarantee provider support. Keep the schema small and use it only
1565
+ when the caller needs structured results. It checks the result's shape, not whether
1566
+ the security conclusion is correct. Relative paths resolve from the current directory.
1567
+
1568
+ The validator no longer writes reports. Save the assessment by redirecting stdout:
1569
+ `codex-security validate findings.json > assessment.md`. For runtime proof, run a
1570
+ separate reproduction step. Missing facts are reported as proof gaps; a finding
1571
+ supported by source evidence does not require runtime reproduction.
1572
+
1573
+ ### Structured validation example
1574
+
1575
+ Save two synthetic candidates as `findings.json`:
1576
+
1577
+ ```json
1578
+ [
1579
+ {
1580
+ "id": "candidate-1",
1581
+ "title": "Missing tenant filter",
1582
+ "location": "src/invoices.ts:24"
1583
+ },
1584
+ {
1585
+ "id": "candidate-2",
1586
+ "title": "Anonymous access",
1587
+ "location": "src/routes.ts:18"
1588
+ }
1589
+ ]
1590
+ ```
1591
+
1592
+ Save this minimal schema as `result.schema.json`. Each `report` contains the
1593
+ assessment's source evidence, counterevidence, confidence, context used, and proof
1594
+ gaps; callers can instead define separate fields for those details.
1595
+
1596
+ ```json
1597
+ {
1598
+ "type": "object",
1599
+ "additionalProperties": false,
1600
+ "required": ["assessments"],
1601
+ "properties": {
1602
+ "assessments": {
1603
+ "type": "array",
1604
+ "items": {
1605
+ "type": "object",
1606
+ "additionalProperties": false,
1607
+ "required": ["id", "disposition", "report"],
1608
+ "properties": {
1609
+ "id": { "type": "string" },
1610
+ "disposition": {
1611
+ "type": "string",
1612
+ "enum": ["reportable", "suppressed", "not_applicable", "deferred"]
1613
+ },
1614
+ "report": { "type": "string" }
1615
+ }
1616
+ }
1617
+ }
1618
+ }
1619
+ }
1620
+ ```
1621
+
1622
+ Run from the repository directory:
1623
+
1624
+ ```bash
1625
+ codex-security validate findings.json --output-schema result.schema.json > assessment.json
1626
+ ```
1627
+
1628
+ An illustrative result is below. Actual decisions depend on the repository;
1629
+ this example assumes a tenant filter exists but deployment routing is unavailable.
1630
+ Both candidate IDs remain in the output, including the unresolved claim.
1631
+
1632
+ ```json
1633
+ {
1634
+ "assessments": [
1635
+ {
1636
+ "id": "candidate-1",
1637
+ "disposition": "suppressed",
1638
+ "report": "Missing tenant filter: src/invoices.ts:24 filters by the authenticated tenant, defeating the claimed cross-tenant read. Static confidence: high. No material proof gap for this claim. No additional context supplied; no runtime checks performed."
1639
+ },
1640
+ {
1641
+ "id": "candidate-2",
1642
+ "disposition": "deferred",
1643
+ "report": "Anonymous access: src/routes.ts:18 has no local authentication guard. An upstream gateway may provide one, but its routing configuration was not supplied. Proof gap: whether unauthenticated traffic can reach this route. Static confidence: low. No additional context supplied; no runtime checks performed."
1644
+ }
1645
+ ]
1646
+ }
1647
+ ```
1648
+
1649
+ ### Patch existing findings
1650
+
1651
+ `--scan latest` uses the current repository's latest completed scan. Patching
1652
+ supports JSON for saved findings, literal text, and files. Each finding gets a
1653
+ saved Codex desktop task. `--model` and `--effort` control the model.
1654
+
1655
+ `--validation-prompt-file PATH` supplies setup, authorized targets, expected
1656
+ results, and cleanup for dynamic validation. It works with saved findings,
1657
+ text/files, and Linear inputs. Paths resolve from the invocation directory, even
1658
+ when the finding belongs to another repository. The file must be nonempty and
1659
+ regular, is read before patching, and cannot combine with `--resume-pr`.
1660
+
1661
+ `--assess-patch-risk` runs an advisory assessment after patching. Human-readable
1662
+ output prints its report; saved-finding JSON includes `patchRisk.report`.
1663
+ With `--create-pr`, the draft description includes the concise Markdown summary.
1664
+ The assessment does not change the patch or merge state.
1665
+
1666
+ Patching first checks that its sandbox can start. Failure reports
1667
+ `SANDBOX_UNAVAILABLE`; no file changes from the task reports `NO_PATCH_APPLIED`.
1668
+ Results list `applied`, `filesChanged`, and `files`, excluding preexisting edits.
1669
+ File changes alone do not prove a fix; saved findings require a verified result.
1670
+
1671
+ For a controlled container providing its own isolation:
1672
+
1673
+ ```bash
1674
+ codex-security patch "Security issue" --external-sandbox --json
1675
+ ```
1676
+
1677
+ This explicit option disables Codex filesystem/network enforcement for the patch
1678
+ task. The container must provide it. There is no automatic fallback; optional
1679
+ patch-risk assessment still uses its read-only sandbox.
1680
+
1681
+ `scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
1682
+ `high` selects high and critical findings. Interactive users can select findings
1683
+ and add instructions. Patch results are `verified`, `no_change`, `blocked`, or
1684
+ `failed`. Verified/already-fixed findings no longer fail the severity threshold.
1685
+
1686
+ ### Create or resume a draft pull request
1687
+
1688
+ `--create-pr` commits generated patch files and opens a draft GitHub PR with `gh`
1689
+ or a GitLab merge request with `glab`. Authenticate the appropriate CLI first.
1690
+ The `origin` push URL selects GitLab.com, including SSH and subgroup projects.
1691
+ For self-hosted GitLab, set `GITLAB_HOST` to that host and authenticate with
1692
+ `glab auth login --hostname HOST`. `GITLAB_URI` and `GL_HOST` are fallback aliases.
1693
+ GitLab merge requests stay within the origin project; a fork merge request with
1694
+ the same branch name is not reused. GitLab descriptions display the report in a
1695
+ blockquote so report text cannot execute quick actions. The report contents,
1696
+ including code, HTML, and math, retain their original text.
1697
+
1698
+ ```bash
1699
+ GITLAB_HOST=gitlab.example.com codex-security patch --scan SCAN_ID --create-pr
1700
+ ```
1701
+
1702
+ Both providers return `pullRequest: { branch, url }`. Supplied-issue patching
1703
+ requires a clean tree. If publication fails, run the printed
1704
+ `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
1705
+ commit and refuses changed branches. Retain the GitLab host setting on resume.
1706
+
1707
+ ### Patch Linear issues
1708
+
1709
+ Repeat `--linear-issue ISSUE` (ID or URL), or select `--linear-project "PROJECT"`
1710
+ with optional native JSON `--linear-filter`. Completed/canceled issues are
1711
+ excluded unless the filter sets `state`.
1712
+
1713
+ Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or
1714
+ `LINEAR_ACCESS_TOKEN` for OAuth. Prefer environment variables over
1715
+ `--linear-api-key`. Intake is read-only, includes comments, and keeps Linear
1716
+ credentials out of the patch subprocess. URLs must match the selected workspace.
1717
+
1718
+ ## Verify fixes
1719
+
1720
+ `verify-fix` checks fixes in a read-only sandbox. It accepts descriptions, saved
1721
+ finding IDs, `--scan`, and the Linear issue/project selectors above. Explicitly
1722
+ filter for completed Linear issues to check a finished backlog.
1723
+
1724
+ Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
1725
+ `--json` returns structured output. Exit codes are `0` when all findings are
1726
+ fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
1727
+
1728
+ ## Command discovery and integrations
1729
+
1730
+ Use `--llms` for the command manifest, `scan --schema --format json` for its
1731
+ schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
1732
+ `--format toon|json|yaml|jsonl` and `--full-output`.
1733
+
1734
+ `skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
1735
+ MCP exposes only read-only `info`, because the transport cannot cancel scans.
1736
+
1737
+ For local findings storage, deduplication, and custom endpoints, see the
1738
+ [findings guide](findings-service.md).
1739
+
1740
+ ## Containerized bulk scans
1741
+
1742
+ Create `repositories.csv` as described under [Bulk scans](#bulk-scans), then run
1743
+ from the repository root with the published image:
1744
+
1745
+ ```bash
1746
+ mkdir -p results state
1747
+ chmod 700 results state
1748
+ export CODEX_SECURITY_USER="$(id -u):$(id -g)"
1749
+ export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest
1750
+ docker compose pull codex-security
1751
+ docker compose run --rm codex-security login --device-auth
1752
+ docker compose run --rm codex-security
1753
+ ```
1754
+
1755
+ Use device login only if your workspace permits it. For unattended scans, set
1756
+ `OPENAI_API_KEY` or `CODEX_API_KEY`. Results go to `results/`; login stays in
1757
+ `state/`. Private GitHub checkouts use `GH_TOKEN` or `GITHUB_TOKEN`; Enterprise
1758
+ uses `CODEX_SECURITY_GIT_HOST`. The container requires CSV input.
1759
+
1760
+ Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,
1761
+ `CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and
1762
+ `CODEX_SECURITY_STATE` for its image, user, seccomp policy, and mounts.
1763
+
1764
+ Codex requires Bubblewrap for filesystem-restricted Linux execution. On Ubuntu
1765
+ hosts that restrict unprivileged user namespaces, an administrator must install
1766
+ the AppArmor profile and use the Compose override:
1767
+
1768
+ ```bash
1769
+ sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
1770
+ sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
1771
+ docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
1772
+ ```
1773
+
1774
+ The override enables nested namespaces while keeping the nonroot user, dropped
1775
+ capabilities, no-new-privileges, and seccomp policy. Hosts that permit nested user
1776
+ namespaces do not need it. The legacy Landlock fallback is unsupported.
1777
+ See the [Docker guide](https://github.com/openai/codex-security/blob/main/docker/README.md)
1778
+ for deployment and source-build instructions.