@openai/codex-security 0.1.31 → 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 (514) hide show
  1. package/README.md +442 -2434
  2. package/_bundled_plugin/.app.json +5 -1
  3. package/_bundled_plugin/.codex-plugin/plugin.json +9 -5
  4. package/_bundled_plugin/.mcp.json +3 -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 +7 -214
  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 +5 -5
  25. package/_bundled_plugin/references/config-preflight.md +1 -5
  26. package/_bundled_plugin/references/core-scan.md +34 -10
  27. package/_bundled_plugin/references/final-report.md +13 -13
  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 +3 -4
  31. package/_bundled_plugin/references/scan-contract.md +11 -6
  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 +2 -2
  36. package/_bundled_plugin/schemas/coverage.schema.json +23 -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 +83 -95
  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 +245 -356
  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 +29 -69
  50. package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
  51. package/_bundled_plugin/scripts/deep_scan_workbench.py +208 -363
  52. package/_bundled_plugin/scripts/filesystem_identity.py +1 -5
  53. package/_bundled_plugin/scripts/finalize_scan_contract.py +733 -375
  54. package/_bundled_plugin/scripts/finding_preview.py +81 -91
  55. package/_bundled_plugin/scripts/generate_in_scope_files.py +48 -102
  56. package/_bundled_plugin/scripts/generate_rank_input.py +117 -888
  57. package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -6
  58. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
  59. package/_bundled_plugin/scripts/rank_preview.py +43 -902
  60. package/_bundled_plugin/scripts/report_projection.py +143 -219
  61. package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
  62. package/_bundled_plugin/scripts/threat_model_projection.py +161 -0
  63. package/_bundled_plugin/scripts/validate_scan_contract.py +4 -34
  64. package/_bundled_plugin/scripts/validate_tracking_source.py +3 -13
  65. package/_bundled_plugin/scripts/windows_scan_local_files.py +59 -9
  66. package/_bundled_plugin/scripts/workbench/handoff.py +25 -50
  67. package/_bundled_plugin/scripts/workbench/runtime_toml.py +22 -0
  68. package/_bundled_plugin/scripts/workbench/storage.py +21 -6
  69. package/_bundled_plugin/scripts/workbench_cli.py +99 -190
  70. package/_bundled_plugin/scripts/workbench_constants.py +6 -14
  71. package/_bundled_plugin/scripts/workbench_db.py +524 -672
  72. package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
  73. package/_bundled_plugin/scripts/workbench_finding_index.py +20 -7
  74. package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
  75. package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
  76. package/_bundled_plugin/scripts/workbench_native_indexes.py +28 -18
  77. package/_bundled_plugin/scripts/workbench_progress.py +26 -92
  78. package/_bundled_plugin/scripts/workbench_publication.py +77 -116
  79. package/_bundled_plugin/scripts/workbench_remediation.py +14 -20
  80. package/_bundled_plugin/scripts/workbench_saved_results.py +1402 -263
  81. package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
  82. package/_bundled_plugin/scripts/workbench_scan_start.py +109 -52
  83. package/_bundled_plugin/scripts/workbench_scan_usage.py +30 -49
  84. package/_bundled_plugin/scripts/workbench_schema.py +71 -1370
  85. package/_bundled_plugin/scripts/workbench_source_excerpt.py +16 -7
  86. package/_bundled_plugin/scripts/workbench_target.py +526 -150
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1 -5
  88. package/_bundled_plugin/scripts/workbench_validation.py +19 -44
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
  90. package/_bundled_plugin/shared/workbench-migrations.json +397 -0
  91. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
  92. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
  93. package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
  94. package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
  95. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +6 -6
  96. package/_bundled_plugin/skills/deep-security-scan/agents/openai.yaml +1 -1
  97. package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
  98. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
  99. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
  100. package/_bundled_plugin/skills/security-diff-scan/agents/openai.yaml +1 -1
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +1 -1
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  104. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +13 -1
  105. package/_bundled_plugin/skills/threat-model/SKILL.md +2 -2
  106. package/_bundled_plugin/skills/track-findings/SKILL.md +46 -178
  107. package/_bundled_plugin/skills/track-findings/agents/openai.yaml +1 -1
  108. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
  109. package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
  110. package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
  111. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
  112. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
  113. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
  114. package/bin/codex-security.mjs +9 -2
  115. package/dist/api.d.ts +63 -15
  116. package/dist/api.d.ts.map +1 -1
  117. package/dist/api.js +970 -553
  118. package/dist/api.js.map +1 -1
  119. package/dist/artifact-export.d.ts +70 -0
  120. package/dist/artifact-export.d.ts.map +1 -0
  121. package/dist/artifact-export.js +292 -0
  122. package/dist/artifact-export.js.map +1 -0
  123. package/dist/auth.d.ts +2 -6
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +27 -12
  126. package/dist/auth.js.map +1 -1
  127. package/dist/bulk-scan-discovery.d.ts +1 -0
  128. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  129. package/dist/bulk-scan-discovery.js +9 -9
  130. package/dist/bulk-scan-discovery.js.map +1 -1
  131. package/dist/classify-scan-severity.d.ts.map +1 -1
  132. package/dist/classify-scan-severity.js +2 -5
  133. package/dist/classify-scan-severity.js.map +1 -1
  134. package/dist/classify-severity.d.ts +28 -17
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +16 -35
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli-help.d.ts +3 -0
  139. package/dist/cli-help.d.ts.map +1 -0
  140. package/dist/cli-help.js +285 -0
  141. package/dist/cli-help.js.map +1 -0
  142. package/dist/cli-signals.d.ts +8 -0
  143. package/dist/cli-signals.d.ts.map +1 -0
  144. package/dist/cli-signals.js +28 -0
  145. package/dist/cli-signals.js.map +1 -0
  146. package/dist/cli.d.ts +22 -24
  147. package/dist/cli.d.ts.map +1 -1
  148. package/dist/cli.js +1660 -1556
  149. package/dist/cli.js.map +1 -1
  150. package/dist/cloud-publish.d.ts.map +1 -1
  151. package/dist/cloud-publish.js +11 -17
  152. package/dist/cloud-publish.js.map +1 -1
  153. package/dist/codeowners.d.ts +19 -0
  154. package/dist/codeowners.d.ts.map +1 -0
  155. package/dist/codeowners.js +138 -0
  156. package/dist/codeowners.js.map +1 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +1 -2
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/codex-sdk-environment.d.ts +3 -0
  161. package/dist/codex-sdk-environment.d.ts.map +1 -0
  162. package/dist/codex-sdk-environment.js +68 -0
  163. package/dist/codex-sdk-environment.js.map +1 -0
  164. package/dist/component-plan.d.ts +2 -5
  165. package/dist/component-plan.d.ts.map +1 -1
  166. package/dist/component-plan.js +38 -34
  167. package/dist/component-plan.js.map +1 -1
  168. package/dist/component-scan.d.ts +7 -5
  169. package/dist/component-scan.d.ts.map +1 -1
  170. package/dist/component-scan.js +54 -44
  171. package/dist/component-scan.js.map +1 -1
  172. package/dist/config.d.ts.map +1 -1
  173. package/dist/config.js +93 -104
  174. package/dist/config.js.map +1 -1
  175. package/dist/contract.d.ts +15 -2
  176. package/dist/contract.d.ts.map +1 -1
  177. package/dist/contract.js +124 -348
  178. package/dist/contract.js.map +1 -1
  179. package/dist/cost-model.d.ts +13 -6
  180. package/dist/cost-model.d.ts.map +1 -1
  181. package/dist/cost-model.js +75 -34
  182. package/dist/cost-model.js.map +1 -1
  183. package/dist/cost.d.ts +10 -2
  184. package/dist/cost.d.ts.map +1 -1
  185. package/dist/cost.js +116 -134
  186. package/dist/cost.js.map +1 -1
  187. package/dist/custom-validation-prompt.d.ts.map +1 -1
  188. package/dist/custom-validation-prompt.js +7 -6
  189. package/dist/custom-validation-prompt.js.map +1 -1
  190. package/dist/custom-validation.d.ts +1 -2
  191. package/dist/custom-validation.d.ts.map +1 -1
  192. package/dist/custom-validation.js +23 -16
  193. package/dist/custom-validation.js.map +1 -1
  194. package/dist/deduplication/checkpointed-review.d.ts +4 -2
  195. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  196. package/dist/deduplication/checkpointed-review.js +33 -20
  197. package/dist/deduplication/checkpointed-review.js.map +1 -1
  198. package/dist/deduplication/codex-review.d.ts +9 -1
  199. package/dist/deduplication/codex-review.d.ts.map +1 -1
  200. package/dist/deduplication/codex-review.js +129 -20
  201. package/dist/deduplication/codex-review.js.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.d.ts +5 -2
  203. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  204. package/dist/deduplication/deduplication-prompts.js +18 -4
  205. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.d.ts +26 -4
  207. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  208. package/dist/deduplication/deduplication-reviewer.js +59 -47
  209. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  210. package/dist/deduplication/deduplication.d.ts.map +1 -1
  211. package/dist/deduplication/deduplication.js +59 -113
  212. package/dist/deduplication/deduplication.js.map +1 -1
  213. package/dist/deduplication/diagnostics.d.ts +17 -0
  214. package/dist/deduplication/diagnostics.d.ts.map +1 -0
  215. package/dist/deduplication/diagnostics.js +5 -0
  216. package/dist/deduplication/diagnostics.js.map +1 -0
  217. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  218. package/dist/deduplication/finding-schema.js +7 -1
  219. package/dist/deduplication/finding-schema.js.map +1 -1
  220. package/dist/deduplication/local.d.ts +31 -0
  221. package/dist/deduplication/local.d.ts.map +1 -0
  222. package/dist/deduplication/local.js +166 -0
  223. package/dist/deduplication/local.js.map +1 -0
  224. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  225. package/dist/deduplication/records-protocol.js +12 -28
  226. package/dist/deduplication/records-protocol.js.map +1 -1
  227. package/dist/deduplication/records.d.ts +188 -12
  228. package/dist/deduplication/records.d.ts.map +1 -1
  229. package/dist/deduplication/records.js +34 -24
  230. package/dist/deduplication/records.js.map +1 -1
  231. package/dist/deduplication/review.d.ts +7 -0
  232. package/dist/deduplication/review.d.ts.map +1 -1
  233. package/dist/deduplication/review.js.map +1 -1
  234. package/dist/deduplication/scan.d.ts +9 -3
  235. package/dist/deduplication/scan.d.ts.map +1 -1
  236. package/dist/deduplication/scan.js +159 -44
  237. package/dist/deduplication/scan.js.map +1 -1
  238. package/dist/deep-config.d.ts +2 -1
  239. package/dist/deep-config.d.ts.map +1 -1
  240. package/dist/deep-config.js +7 -23
  241. package/dist/deep-config.js.map +1 -1
  242. package/dist/deep-progress.d.ts +2 -1
  243. package/dist/deep-progress.d.ts.map +1 -1
  244. package/dist/deep-progress.js +32 -47
  245. package/dist/deep-progress.js.map +1 -1
  246. package/dist/deep-scan.d.ts +20 -0
  247. package/dist/deep-scan.d.ts.map +1 -0
  248. package/dist/deep-scan.js +113 -0
  249. package/dist/deep-scan.js.map +1 -0
  250. package/dist/errors.d.ts +5 -2
  251. package/dist/errors.d.ts.map +1 -1
  252. package/dist/errors.js +7 -7
  253. package/dist/errors.js.map +1 -1
  254. package/dist/feedback.d.ts.map +1 -1
  255. package/dist/feedback.js +53 -21
  256. package/dist/feedback.js.map +1 -1
  257. package/dist/finding-catalogue.d.ts.map +1 -1
  258. package/dist/finding-catalogue.js +26 -30
  259. package/dist/finding-catalogue.js.map +1 -1
  260. package/dist/finding-normalization.d.ts +5 -0
  261. package/dist/finding-normalization.d.ts.map +1 -0
  262. package/dist/finding-normalization.js +120 -0
  263. package/dist/finding-normalization.js.map +1 -0
  264. package/dist/finding-retrieval.d.ts +9 -0
  265. package/dist/finding-retrieval.d.ts.map +1 -1
  266. package/dist/finding-retrieval.js.map +1 -1
  267. package/dist/finding-workflow.d.ts +13 -8
  268. package/dist/finding-workflow.d.ts.map +1 -1
  269. package/dist/finding-workflow.js +18 -13
  270. package/dist/finding-workflow.js.map +1 -1
  271. package/dist/findings-client.d.ts +2 -1
  272. package/dist/findings-client.d.ts.map +1 -1
  273. package/dist/findings-client.js +36 -9
  274. package/dist/findings-client.js.map +1 -1
  275. package/dist/findings-errors.d.ts +16 -0
  276. package/dist/findings-errors.d.ts.map +1 -0
  277. package/dist/findings-errors.js +24 -0
  278. package/dist/findings-errors.js.map +1 -0
  279. package/dist/findings-import.d.ts +1 -1
  280. package/dist/findings-import.d.ts.map +1 -1
  281. package/dist/findings-import.js +16 -44
  282. package/dist/findings-import.js.map +1 -1
  283. package/dist/github.d.ts.map +1 -1
  284. package/dist/github.js +9 -4
  285. package/dist/github.js.map +1 -1
  286. package/dist/import-scan.d.ts.map +1 -1
  287. package/dist/import-scan.js +49 -39
  288. package/dist/import-scan.js.map +1 -1
  289. package/dist/index.d.ts +11 -5
  290. package/dist/index.d.ts.map +1 -1
  291. package/dist/index.js +2 -1
  292. package/dist/index.js.map +1 -1
  293. package/dist/knowledge-base.d.ts +7 -1
  294. package/dist/knowledge-base.d.ts.map +1 -1
  295. package/dist/knowledge-base.js +115 -47
  296. package/dist/knowledge-base.js.map +1 -1
  297. package/dist/linear.d.ts.map +1 -1
  298. package/dist/linear.js +4 -10
  299. package/dist/linear.js.map +1 -1
  300. package/dist/mock-scan.d.ts.map +1 -1
  301. package/dist/mock-scan.js +0 -1
  302. package/dist/mock-scan.js.map +1 -1
  303. package/dist/models.d.ts +24 -2
  304. package/dist/models.d.ts.map +1 -1
  305. package/dist/models.js.map +1 -1
  306. package/dist/multiscan.d.ts +9 -3
  307. package/dist/multiscan.d.ts.map +1 -1
  308. package/dist/multiscan.js +225 -153
  309. package/dist/multiscan.js.map +1 -1
  310. package/dist/owner-evidence.d.ts +10 -2
  311. package/dist/owner-evidence.d.ts.map +1 -1
  312. package/dist/owner-evidence.js +69 -14
  313. package/dist/owner-evidence.js.map +1 -1
  314. package/dist/patch-tui.d.ts.map +1 -1
  315. package/dist/patch-tui.js +5 -6
  316. package/dist/patch-tui.js.map +1 -1
  317. package/dist/project-config-schema.d.ts +10 -0
  318. package/dist/project-config-schema.d.ts.map +1 -1
  319. package/dist/project-config-schema.js +1 -0
  320. package/dist/project-config-schema.js.map +1 -1
  321. package/dist/project-config.d.ts +1 -0
  322. package/dist/project-config.d.ts.map +1 -1
  323. package/dist/project-config.js +5 -3
  324. package/dist/project-config.js.map +1 -1
  325. package/dist/prompt-files.d.ts +0 -1
  326. package/dist/prompt-files.d.ts.map +1 -1
  327. package/dist/prompt-files.js +2 -4
  328. package/dist/prompt-files.js.map +1 -1
  329. package/dist/provider-profile.d.ts +21 -0
  330. package/dist/provider-profile.d.ts.map +1 -0
  331. package/dist/provider-profile.js +133 -0
  332. package/dist/provider-profile.js.map +1 -0
  333. package/dist/publication-events.d.ts +6 -8
  334. package/dist/publication-events.d.ts.map +1 -1
  335. package/dist/publication-events.js +40 -79
  336. package/dist/publication-events.js.map +1 -1
  337. package/dist/publication-store.d.ts.map +1 -1
  338. package/dist/publication-store.js +48 -76
  339. package/dist/publication-store.js.map +1 -1
  340. package/dist/publication.d.ts +1 -2
  341. package/dist/publication.d.ts.map +1 -1
  342. package/dist/publication.js +7 -16
  343. package/dist/publication.js.map +1 -1
  344. package/dist/publish.d.ts +1 -5
  345. package/dist/publish.d.ts.map +1 -1
  346. package/dist/publish.js +138 -199
  347. package/dist/publish.js.map +1 -1
  348. package/dist/record.d.ts +2 -0
  349. package/dist/record.d.ts.map +1 -0
  350. package/dist/record.js +4 -0
  351. package/dist/record.js.map +1 -0
  352. package/dist/request-metadata.d.ts +9 -0
  353. package/dist/request-metadata.d.ts.map +1 -0
  354. package/dist/request-metadata.js +13 -0
  355. package/dist/request-metadata.js.map +1 -0
  356. package/dist/result.d.ts +4 -1
  357. package/dist/result.d.ts.map +1 -1
  358. package/dist/result.js +7 -0
  359. package/dist/result.js.map +1 -1
  360. package/dist/runtime.d.ts +25 -17
  361. package/dist/runtime.d.ts.map +1 -1
  362. package/dist/runtime.js +619 -255
  363. package/dist/runtime.js.map +1 -1
  364. package/dist/saved-scan-bootstrap.d.ts +14 -0
  365. package/dist/saved-scan-bootstrap.d.ts.map +1 -0
  366. package/dist/saved-scan-bootstrap.js +261 -0
  367. package/dist/saved-scan-bootstrap.js.map +1 -0
  368. package/dist/saved-scan.d.ts +1 -1
  369. package/dist/saved-scan.d.ts.map +1 -1
  370. package/dist/saved-scan.js +16 -32
  371. package/dist/saved-scan.js.map +1 -1
  372. package/dist/scan-activity.d.ts.map +1 -1
  373. package/dist/scan-activity.js +19 -30
  374. package/dist/scan-activity.js.map +1 -1
  375. package/dist/scan-comparison.d.ts +31 -18
  376. package/dist/scan-comparison.d.ts.map +1 -1
  377. package/dist/scan-comparison.js +307 -347
  378. package/dist/scan-comparison.js.map +1 -1
  379. package/dist/scan-dashboard.d.ts +3 -1
  380. package/dist/scan-dashboard.d.ts.map +1 -1
  381. package/dist/scan-dashboard.js +351 -92
  382. package/dist/scan-dashboard.js.map +1 -1
  383. package/dist/scan-history-renderer.d.ts.map +1 -1
  384. package/dist/scan-history-renderer.js +55 -15
  385. package/dist/scan-history-renderer.js.map +1 -1
  386. package/dist/scan-inputs.d.ts +6 -0
  387. package/dist/scan-inputs.d.ts.map +1 -0
  388. package/dist/scan-inputs.js +71 -0
  389. package/dist/scan-inputs.js.map +1 -0
  390. package/dist/scan-logs.d.ts +2 -3
  391. package/dist/scan-logs.d.ts.map +1 -1
  392. package/dist/scan-logs.js +14 -12
  393. package/dist/scan-logs.js.map +1 -1
  394. package/dist/scan-sessions.d.ts +4 -0
  395. package/dist/scan-sessions.d.ts.map +1 -1
  396. package/dist/scan-sessions.js +18 -3
  397. package/dist/scan-sessions.js.map +1 -1
  398. package/dist/scan-settings.d.ts +5 -0
  399. package/dist/scan-settings.d.ts.map +1 -1
  400. package/dist/scan-settings.js +4 -0
  401. package/dist/scan-settings.js.map +1 -1
  402. package/dist/scan-skill-paths.d.ts +8 -0
  403. package/dist/scan-skill-paths.d.ts.map +1 -0
  404. package/dist/scan-skill-paths.js +47 -0
  405. package/dist/scan-skill-paths.js.map +1 -0
  406. package/dist/security-policy-cli.d.ts.map +1 -1
  407. package/dist/security-policy-cli.js +15 -33
  408. package/dist/security-policy-cli.js.map +1 -1
  409. package/dist/security-policy.d.ts +17 -9
  410. package/dist/security-policy.d.ts.map +1 -1
  411. package/dist/security-policy.js +131 -98
  412. package/dist/security-policy.js.map +1 -1
  413. package/dist/server/api.d.ts +0 -1
  414. package/dist/server/api.d.ts.map +1 -1
  415. package/dist/server/api.js +0 -1
  416. package/dist/server/api.js.map +1 -1
  417. package/dist/server/embeddings.d.ts +3 -1
  418. package/dist/server/embeddings.d.ts.map +1 -1
  419. package/dist/server/embeddings.js +11 -3
  420. package/dist/server/embeddings.js.map +1 -1
  421. package/dist/server/errors.d.ts +5 -2
  422. package/dist/server/errors.d.ts.map +1 -1
  423. package/dist/server/errors.js +7 -0
  424. package/dist/server/errors.js.map +1 -1
  425. package/dist/server/sqlite-store.d.ts +0 -2
  426. package/dist/server/sqlite-store.d.ts.map +1 -1
  427. package/dist/server/sqlite-store.js +55 -55
  428. package/dist/server/sqlite-store.js.map +1 -1
  429. package/dist/server/storage.d.ts +0 -2
  430. package/dist/server/storage.d.ts.map +1 -1
  431. package/dist/server/storage.js.map +1 -1
  432. package/dist/severity-store.js +20 -32
  433. package/dist/severity-store.js.map +1 -1
  434. package/dist/standalone-validation-prompt.d.ts +2 -0
  435. package/dist/standalone-validation-prompt.d.ts.map +1 -0
  436. package/dist/standalone-validation-prompt.js +10 -0
  437. package/dist/standalone-validation-prompt.js.map +1 -0
  438. package/dist/suggest-owners.d.ts +6 -5
  439. package/dist/suggest-owners.d.ts.map +1 -1
  440. package/dist/suggest-owners.js +15 -10
  441. package/dist/suggest-owners.js.map +1 -1
  442. package/dist/targets.d.ts +12 -0
  443. package/dist/targets.d.ts.map +1 -1
  444. package/dist/targets.js +124 -62
  445. package/dist/targets.js.map +1 -1
  446. package/dist/trusted-executable.d.ts +6 -1
  447. package/dist/trusted-executable.d.ts.map +1 -1
  448. package/dist/trusted-executable.js +28 -9
  449. package/dist/trusted-executable.js.map +1 -1
  450. package/dist/value.d.ts +2 -0
  451. package/dist/value.d.ts.map +1 -0
  452. package/dist/value.js +27 -0
  453. package/dist/value.js.map +1 -0
  454. package/dist/version.d.ts.map +1 -1
  455. package/dist/version.js +3 -6
  456. package/dist/version.js.map +1 -1
  457. package/dist/windows-path.d.ts.map +1 -1
  458. package/dist/windows-path.js +1 -2
  459. package/dist/windows-path.js.map +1 -1
  460. package/dist/workbench-arguments.d.ts +3 -0
  461. package/dist/workbench-arguments.d.ts.map +1 -0
  462. package/dist/workbench-arguments.js +15 -0
  463. package/dist/workbench-arguments.js.map +1 -0
  464. package/dist/worker-progress.d.ts +2 -0
  465. package/dist/worker-progress.d.ts.map +1 -1
  466. package/dist/worker-progress.js +40 -46
  467. package/dist/worker-progress.js.map +1 -1
  468. package/docs/cli.md +1778 -0
  469. package/docs/dedupe-records.md +24 -0
  470. package/docs/findings-service.md +402 -0
  471. package/package.json +23 -23
  472. package/schemas/project-config.schema.json +5 -0
  473. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
  474. package/_bundled_plugin/scripts/normalize_candidates.py +0 -338
  475. package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
  476. package/_bundled_plugin/scripts/workbench_findings.py +0 -221
  477. package/_bundled_plugin/scripts/workbench_severity.py +0 -119
  478. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
  479. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
  480. package/dist/server/dashboard/app.css +0 -2
  481. package/dist/server/dashboard/app.js +0 -66
  482. package/dist/server/dashboard/index.html +0 -18
  483. package/dist/server/dashboard-types.d.ts +0 -48
  484. package/dist/server/dashboard-types.d.ts.map +0 -1
  485. package/dist/server/dashboard-types.js +0 -2
  486. package/dist/server/dashboard-types.js.map +0 -1
  487. package/dist/server/dashboard.d.ts +0 -6
  488. package/dist/server/dashboard.d.ts.map +0 -1
  489. package/dist/server/dashboard.js +0 -59
  490. package/dist/server/dashboard.js.map +0 -1
  491. package/dist/server/findings-service.d.ts +0 -20
  492. package/dist/server/findings-service.d.ts.map +0 -1
  493. package/dist/server/findings-service.js +0 -31
  494. package/dist/server/findings-service.js.map +0 -1
  495. package/dist/server/index.d.ts +0 -2
  496. package/dist/server/index.d.ts.map +0 -1
  497. package/dist/server/index.js +0 -6
  498. package/dist/server/index.js.map +0 -1
  499. package/dist/server/routes.d.ts +0 -6
  500. package/dist/server/routes.d.ts.map +0 -1
  501. package/dist/server/routes.js +0 -86
  502. package/dist/server/routes.js.map +0 -1
  503. package/dist/server/serve.d.ts +0 -2
  504. package/dist/server/serve.d.ts.map +0 -1
  505. package/dist/server/serve.js +0 -28
  506. package/dist/server/serve.js.map +0 -1
  507. package/dist/server/server.d.ts +0 -10
  508. package/dist/server/server.d.ts.map +0 -1
  509. package/dist/server/server.js +0 -17
  510. package/dist/server/server.js.map +0 -1
  511. package/dist/server/validation.d.ts +0 -17
  512. package/dist/server/validation.d.ts.map +0 -1
  513. package/dist/server/validation.js +0 -53
  514. package/dist/server/validation.js.map +0 -1
package/README.md CHANGED
@@ -1,2635 +1,643 @@
1
1
  # `@openai/codex-security`
2
2
 
3
- Run Codex Security scans from TypeScript or the command line. This ESM-only
4
- package includes TypeScript declarations and the Codex runtime.
3
+ Run Codex Security from TypeScript or the command line to find, validate, and fix
4
+ security vulnerabilities in your code. The package includes the Codex runtime,
5
+ security plugin, and TypeScript declarations. It uses ES modules.
6
+
7
+ - Scan repositories, selected paths, or Git changes. Deep scans run parallel
8
+ discovery workers on repositories and selected paths.
9
+ - Validate findings, generate patches, and verify existing fixes.
10
+ - Draft security policies and retain threat models.
11
+ - Review saved findings, identify duplicates, classify severity, and suggest owners.
12
+ - Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
13
+ findings to Linear or a findings service.
14
+ - Automate scans across repositories and project components.
15
+
16
+ See the [CLI reference](docs/cli.md),
17
+ [findings guide](docs/findings-service.md), or
18
+ [online documentation](https://learn.chatgpt.com/docs/security) for setup and examples.
5
19
 
6
20
  Before version `1.0.0`, minor releases may change the public API.
7
21
 
8
22
  ## Install
9
23
 
10
- ```bash
11
- npm install @openai/codex-security
12
- npx @openai/codex-security --version
13
- ```
14
-
15
- Use Node.js 22.13.0+ (22.x), 24.x, or 26.x on macOS, Linux, or Windows.
16
- Policy drafting, scans, exports, scan history, and saved findings also need Python 3.10+
17
- (plus `tomli` on Python 3.10).
18
-
19
- ## Run a scan from TypeScript
20
-
21
- Sign in with `npx @openai/codex-security login` or set `OPENAI_API_KEY` or
22
- `CODEX_API_KEY`, then scan a repository you own or have permission to assess:
23
-
24
- ```ts
25
- import { CodexSecurity } from "@openai/codex-security";
26
-
27
- const security = new CodexSecurity();
24
+ Supported runtimes:
28
25
 
29
- try {
30
- const result = await security.run("/path/to/repository", {
31
- outputDir: "/path/outside/repository/results",
32
- });
26
+ - Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.
27
+ - Python 3.10+ for scans, policy generation, exports, scan history, and saved
28
+ findings. Python 3.10 also needs `tomli`.
33
29
 
34
- console.log(result.reportPath);
35
- console.log(result.findings.findings.length);
36
- } finally {
37
- await security.close();
38
- }
39
- ```
30
+ Reading compressed Codex session logs (`.jsonl.zst`) requires Node.js 22.15.0+
31
+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14, compressed sessions
32
+ are unavailable when reading saved activity or attaching scan logs to feedback, and
33
+ scans whose original session is compressed cannot resume. Plain `.jsonl` logs
34
+ work on all supported runtimes.
40
35
 
41
- `result.findings` contains this scan's findings; `repositoryFindings` also
42
- includes earlier open findings when available. Matching earlier findings can
43
- make extra model calls; see [Progress and cost](#progress-and-cost).
36
+ `LocalPluginBootstrapError` identifies local plugin setup failures and extends
37
+ `PluginBootstrapError`, so existing catches keep working. Knowledge-base
38
+ preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
44
39
 
45
- Keep results outside the repository and restrict access: reports can contain
46
- source code, vulnerability details, and reproduction steps.
40
+ ### Install the CLI
47
41
 
48
- ### Validate an existing finding
42
+ Install the CLI globally:
49
43
 
50
- ```ts
51
- const security = new CodexSecurity();
52
- try {
53
- const result = await security.validate({
54
- repositoryPath: "/path/to/repository",
55
- finding: {
56
- title: "Possible SQL injection",
57
- location: "src/query.ts:42",
58
- },
59
- outputDir: "/path/outside/repository/validation",
60
- });
61
- console.log(result.disposition);
62
- console.log(result.report);
63
- } finally {
64
- await security.close();
65
- }
66
- ```
67
-
68
- Pass literal text or a JSON-serializable object as `finding`, not a file path.
69
- Validation uses the client's settings and credentials without changing
70
- repository files or adding a scan to history.
71
-
72
- To disable Codex usage analytics and built-in metrics, create the client with
73
- `new CodexSecurity({ codexOverrides: { analytics: { enabled: false } } })`.
74
- This setting also applies to scans run by the same client.
75
-
76
- Results include `disposition` (`reportable`, `suppressed`, `not_applicable`,
77
- or `deferred`), a Markdown `report`, `threadId`, and evidence `outputDir`.
78
- `reportable` may rely on static analysis; `deferred` means insufficient evidence.
79
- Failed, incomplete, or malformed responses reject the promise.
80
-
81
- `outputDir` must be empty and outside the Git worktree; it defaults to
82
- `validations/` under the state directory. Pass `auth` to select credentials
83
- or `signal` to cancel.
84
-
85
- ### Import GitHub code scanning alerts
86
-
87
- Import alerts, including third-party SARIF uploads, and validate them against
88
- the matching local checkout:
89
-
90
- ```ts
91
- import {
92
- CodexSecurity,
93
- importGitHubCodeScanningAlerts,
94
- } from "@openai/codex-security";
95
-
96
- const findings = await importGitHubCodeScanningAlerts({
97
- repository: "example/repository",
98
- alertNumbers: [12, 18], // Omit to list all open alerts on the default branch.
99
- githubToken: process.env["GH_TOKEN"],
100
- });
101
-
102
- const security = new CodexSecurity();
103
- try {
104
- for (const finding of findings) {
105
- const result = await security.validate({
106
- repositoryPath: "/path/to/repository",
107
- finding,
108
- });
109
- console.log(finding.url, result.disposition, result.outputDir);
110
- }
111
- } finally {
112
- await security.close();
113
- }
44
+ ```bash
45
+ npm install --global @openai/codex-security
46
+ cs --version
114
47
  ```
115
48
 
116
- Each result contains `source`, `repository`, `number`, `url`, and the full
117
- upstream `alert`. Import is read-only and does not start Codex or check out code.
118
-
119
- Without `alertNumbers`, `state` filters alerts and defaults to `"open"`.
120
- It also accepts `"closed"`, `"dismissed"`, `"fixed"`, and `"all"`. Exact alert
121
- numbers ignore state and reject a nondefault `state`. Use `ref` for another
122
- branch or pull-request reference.
123
-
124
- Supply `githubToken` or use your `gh auth token` credentials, including GitHub
125
- CLI token environment variables. `githubHost` defaults to `GH_HOST` or
126
- `github.com`. The token needs read access to code scanning alerts; access
127
- failures reject the import. Pass `signal` to cancel.
128
-
129
- ### SDK configuration and scan options
130
-
131
- Constructor options:
132
-
133
- | Option | Description |
134
- | ---------------- | ----------------------------------------------------------------------- |
135
- | `pluginPath` | Plugin directory or ZIP; defaults to the bundled plugin. |
136
- | `pythonPath` | Python interpreter; overrides `PYTHON`. |
137
- | `codexOverrides` | Supported settings to deep-merge into the isolated Codex configuration. |
138
-
139
- Options for `security.run(repository, options)` and
140
- `security.preflight(repository, options)`:
141
-
142
- | Option | Description |
143
- | ------------------------------------------- | ----------------------------------------------------------------------------------- |
144
- | `auth` | Credential source: `"auto"`, `"chatgpt"`, or `"api-key"`. |
145
- | `safetyIdentifier` | Stable hashed end-user ID for model requests; requires API-key authentication. |
146
- | `target` | Repository, repository-relative paths, committed diff, or working-tree diff. |
147
- | `mode` | `"standard"` or `"deep"`; deep mode supports repositories and paths. |
148
- | `knowledgeBasePaths` | Architecture documents, security policies, threat models, or directories. |
149
- | `scanPrompt` / `scanPromptFile` | Additional scan instructions as text or a local file. |
150
- | `validationPrompt` / `validationPromptFile` | Custom validation instructions as text or a local file; not Deep. |
151
- | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions as text or a local file. |
152
- | `outputDir` | Artifact directory outside the enclosing Git worktree. |
153
- | `archiveExisting` | Archive existing results in `outputDir` before scanning. |
154
- | `maxCostUsd` | Stop when estimated model cost exceeds this positive USD amount. |
155
- | `stopAfterConsecutiveErrors` | Stop deep discovery after this many consecutive errors (default: 3). |
156
- | `maxTimeHours` | Deep-scan discovery limit in hours: greater than zero, up to 96. |
157
- | `failureSeverity` | Severity threshold recorded in the recipe; the SDK caller decides how to handle it. |
158
- | `parentScanId` | Parent scan ID for a rerun. |
159
- | `expectedPluginVersion` | Required original plugin version when replaying a scan. |
160
- | `signal` | `AbortSignal` to cancel a scan. |
161
-
162
- Follow scans with `onWorkerStatus` and `onReconnect`. `onSessionEvent` receives
163
- saved events with thread IDs and worker numbers. Deep scans can additionally use
164
- `onDeepProgress` for durable independent-review counts: `completed`, `active`,
165
- and `maximum`. The maximum is a configured cap, not a percentage denominator.
166
- `ScanOptions` lists all callbacks.
49
+ `cs` is a short alias for `codex-security`; both commands run the same CLI.
50
+ The installation creates both commands in npm's global executable directory,
51
+ which must be on your `PATH`. If `cs` already resolves to another tool, use
52
+ `codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
53
+ `npx @openai/codex-security` without a global installation.
167
54
 
168
- `preflight` and CLI `--dry-run` check local inputs without starting Codex or
169
- using the network. They don't authenticate, verify model access, resolve Python,
170
- inspect the plugin, or run scan-lifecycle callbacks. Dry runs print effective settings.
171
- Deep preflight includes all six resolved deep settings and their origins in
172
- `deepScanSources`. Applicable legacy deep configuration is validated during
173
- preflight rather than after runtime startup.
55
+ Continue with the [CLI walkthrough](#cli). To run without a global installation,
56
+ replace `cs` in the CLI examples with `npx @openai/codex-security`.
174
57
 
175
- `ScanSettings` is the shared settings type. `ScanOptions` adds callbacks,
176
- cancellation, workflow, and runtime controls. Load the same project file used by
177
- `scan -c` through the SDK:
58
+ ### Install the TypeScript SDK
178
59
 
179
- ```ts
180
- import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
60
+ Install the package locally in your TypeScript project:
181
61
 
182
- const { config, options } = await loadProjectConfig("codex-security.yaml");
183
- await using security = new CodexSecurity(config);
184
- const result = await security.run(repository, options);
185
- if (
186
- options.failureSeverity !== undefined &&
187
- result.hasFindingsAtOrAbove(options.failureSeverity)
188
- ) {
189
- process.exitCode = 1;
190
- }
62
+ ```bash
63
+ npm install @openai/codex-security
191
64
  ```
192
65
 
193
- `resolveProjectConfig(input, directory?)` accepts a typed `ProjectConfigInput`
194
- object with the same `snake_case` keys as YAML/JSON and returns the same `{ config,
195
- options }` pair and an immutable `sources` map. Resolved context, prompt, and output
196
- paths have the `AbsolutePath` type. `loadProjectConfig(file, directory?)` resolves the selected file
197
- from `directory`, which defaults to the current directory; paths inside the file
198
- are relative to that file. Object paths are relative to the supplied directory.
199
- Scope paths remain relative to the selected repository. Neither helper starts a
200
- scan, reads prompt contents, or discovers another configuration file. `preflight`
201
- and `run` apply the existing local checks and remaining legacy deep defaults.
202
- Project-file keys follow Codex's configuration convention; SDK options keep their
203
- existing `camelCase` names, and CLI flags keep `kebab-case`.
204
-
205
- Override resolved SDK options with `{ ...options, maxCostUsd: 5 }`, or add
206
- callbacks there. Direct SDK prompt-file paths use the current directory; inline
207
- text takes precedence over its matching file. Files use the same regular-file
208
- protections as the CLI. The SDK records `failureSeverity` without throwing or
209
- changing process status. `hasFindingsAtOrAbove()` uses the CLI's severity ordering
210
- and leaves the findings unchanged.
211
-
212
66
  ## Authentication
213
67
 
214
68
  Sign in with ChatGPT:
215
69
 
216
70
  ```bash
217
- npx @openai/codex-security login
218
- npx @openai/codex-security scan .
71
+ cs login
219
72
  ```
220
73
 
221
- Use device authentication on remote or headless machines:
74
+ If you installed only the SDK locally, sign in from your project directory:
222
75
 
223
76
  ```bash
224
- npx @openai/codex-security login --device-auth
77
+ npx @openai/codex-security login
225
78
  ```
226
79
 
227
- For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY`. To save a key, pass it on stdin:
80
+ In the following CLI examples, replace `cs` with `npx @openai/codex-security`
81
+ when using a local SDK installation, including the API-key login example below.
82
+
83
+ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.
84
+ These keys apply to the current command without replacing your saved login.
85
+ To save an API key instead, pass it on stdin:
228
86
 
229
87
  ```bash
230
- printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
88
+ printenv OPENAI_API_KEY | cs login --with-api-key
231
89
  ```
232
90
 
233
- Environment API keys apply to the current command; only `login --with-api-key`
234
- saves them. Pass Codex access tokens on stdin to `login --with-access-token`.
235
- Access-token environment variables are not scan API keys.
236
-
237
- SDK callers can select native command authentication through
238
- `codexOverrides.model_providers.<id>.auth` and `model_provider` (including a
239
- selected `profile`). Scans, comparisons, and deduplication reviews preserve
240
- that selection without requiring an API key or replacing it with a stored
241
- login. Codex executes the helper and renews its token. Helper paths and relative
242
- `auth.cwd` values resolve from the supplied `CODEX_HOME` (default `~/.codex`),
243
- not the source checkout; an absolute `auth.cwd` is preserved. Comparisons and
244
- reviews also honor the selected command provider in that home's `config.toml`.
245
- Configuration is passed to Codex for validation, including profile support.
91
+ SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,
92
+ prefers `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
93
+ Use `"chatgpt"` to ignore environment API keys. The CLI uses the same `--auth`
94
+ values and prompts in an interactive terminal when both credential types are available.
246
95
 
247
- For other inference providers:
96
+ Some cybersecurity requests and protected findings require
97
+ [Trusted Access for Cyber](https://chatgpt.com/cyber) approval. See the
98
+ [authentication reference](docs/cli.md#authentication) for providers, stored
99
+ credentials, and Cyber access program selection.
248
100
 
249
- ```bash
250
- export OPENROUTER_API_KEY="<your-openrouter-api-key>"
251
- npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5
101
+ ### Remote login with SSH forwarding
252
102
 
253
- export FIREWORKS_API_KEY="<your-fireworks-api-key>"
254
- npx @openai/codex-security scan . --provider fireworks --model accounts/fireworks/models/qwen3-235b-a22b
103
+ On a remote or headless machine, try `login --device-auth` if your workspace
104
+ allows it. Otherwise, open an SSH tunnel from your local machine:
255
105
 
256
- export AWS_BEARER_TOKEN_BEDROCK="<your-bedrock-api-key>"
257
- export AWS_REGION="us-east-2"
258
- npx @openai/codex-security scan . --provider amazon-bedrock --model openai.gpt-5.6-luna
106
+ ```bash
107
+ ssh -L 1455:localhost:1455 user@remote-host
259
108
  ```
260
109
 
261
- Bedrock also accepts AWS access keys, profiles, web identity, container
262
- credentials, and the default AWS credential chain. Set `AWS_REGION` and choose
263
- a Bedrock model with `--model`; OpenAI models such as `openai.gpt-5.6-luna`
264
- support `--max-cost`.
265
-
266
- Bedrock scans, including Deep Scan workers, default to
267
- `model_reasoning_summary = "none"` because some Bedrock models reject
268
- `reasoning.summary`. This leaves reasoning effort unchanged. Explicit summary
269
- settings in `--codex` overrides or the selected Codex profile take precedence.
270
- For standard scans on older CLI versions, append
271
- `--codex 'model_reasoning_summary="none"'` to your scan command if Bedrock
272
- reports that `reasoning.summary` is unsupported. Deep scans require a CLI
273
- version that forwards this setting to workers.
274
-
275
- On Windows, set the API key in PowerShell:
276
-
277
- ```powershell
278
- $env:OPENAI_API_KEY = "<your-api-key>"
279
- npx @openai/codex-security scan C:\code\repository
280
- ```
110
+ Run `cs login` in that SSH session, then open its sign-in
111
+ URL in your local browser. Keep SSH connected until login finishes.
281
112
 
282
- Login, logout, scans, validation, patching, and fix verification share a private
283
- credential home for stored OpenAI credentials, including custom providers with
284
- `requires_openai_auth = true`:
285
- `$CODEX_SECURITY_STATE_DIR/codex-home`, or
286
- `$CODEX_HOME/state/plugins/codex-security/codex-home`. Keep this credential
287
- home outside the target directory and every enclosing Git worktree, including
288
- when running a command from a subdirectory. Codex carries
289
- `cli_auth_credentials_store`, `forced_login_method`, and
290
- `forced_chatgpt_workspace_id` from the ambient configuration into this home,
291
- including removing settings that are no longer present in the ambient configuration.
292
- Each command carries its selected provider into this home. Patching and fix
293
- verification also synchronize the ambient home's project-trust decisions and
294
- project-root markers, preserving which project configuration Codex loads.
295
- They hold the credential-home lock until the app-server thread is ready,
296
- then release it before model execution.
297
- Managed-device policies still apply. If this home has no credentials, it imports
298
- an existing file-based Codex sign-in. Logout disables
299
- imports until you log in again.
300
-
301
- Finish operations using older versions before upgrading. Runtime preparation
302
- holds the credential-home lock through pauses; exit or crash releases it.
303
- Compatibility heartbeats protect active locks from older heartbeat-only
304
- clients, but those clients can replace a paused client's lock.
305
-
306
- Keep `.codex-security-scan.sqlite3` between operations; never remove it during
307
- an operation. PID reuse can make old PID-only locks appear active and block
308
- recovery. Stop all operations using this home before removing an old
309
- `.codex-security-scan.lock` directory manually.
310
-
311
- If ChatGPT credentials cannot be refreshed, run `login status`. Retry if the
312
- sign-in recently changed; otherwise run `logout`, then `login`.
313
-
314
- Interactive scans ask whether to use ChatGPT or an environment API key when
315
- both are available. The choice applies to that scan. Noninteractive scans,
316
- including CI, JSON output, and dry runs, prefer the API key. Choose with `--auth`:
113
+ ### Amazon Bedrock
317
114
 
318
- ```bash
319
- npx @openai/codex-security scan . --auth chatgpt
320
- npx @openai/codex-security scan . --auth api-key
321
- ```
115
+ Bedrock scans use AWS credentials and model access. They do not require
116
+ `codex-security login` or an OpenAI API key. See the
117
+ [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
118
+ for setup, model selection, and verification.
322
119
 
323
- `--auth` also works with `validate`, `patch`, and `verify-fix`. These commands
324
- use the same stored login as `scan`, including a sign-in created with
325
- `codex-security login --device-auth`:
120
+ ## Read existing Cloud findings
326
121
 
327
- ```bash
328
- npx @openai/codex-security patch OCCURRENCE_ID --auth chatgpt
329
- npx @openai/codex-security verify-fix OCCURRENCE_ID --auth api-key
330
- ```
122
+ The Security plugin includes `$cloud-findings` for accounts where Codex Security
123
+ Cloud is available. Install the plugin through your configured Codex marketplace,
124
+ sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
125
+ the intended account and workspace. Installation alone does not authenticate the
126
+ connection. Local scans do not require Cloud, and an API key used for scanning
127
+ does not replace the Cloud connection.
331
128
 
332
- `--auth chatgpt` ignores environment API keys. `--auth api-key` requires
333
- `OPENAI_API_KEY` or `CODEX_API_KEY`. The default is `--auth auto`; noninteractive
334
- commands prefer `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
335
- Patch follow-up assessment uses the same selection, and `scan --patch` keeps
336
- the scan's choice. Environment API keys do not replace the saved login.
337
- The SDK uses the same `auth` option on `run`, `validate`, and `preflight`.
338
- Codex may still need ChatGPT credentials to load workspace-managed policies
339
- when using an API key.
340
-
341
- Some cybersecurity requests and protected findings require Trusted Access for
342
- Cyber approval. Apply or check your access at
343
- [chatgpt.com/cyber](https://chatgpt.com/cyber).
344
-
345
- ## Generate a security policy
346
-
347
- `policy` drafts `SECURITY.md` guidance for future scans. It does not run a
348
- vulnerability scan, change application settings, or install the draft in the
349
- checkout. It uses the scan runtime and authentication, requesting read-only
350
- access to the selected repository or component and required tools. Network access,
351
- web search, apps, and MCP servers are disabled. Drafts stay outside the checkout.
352
- The host resolves inherited guidance once and includes each checked descendant
353
- policy separately. Descendant policy links must stay within the selected component.
354
- Inherited and reporting-policy links may also resolve to ancestor `SECURITY.md`
355
- files or the checkout's `.github/SECURITY.md` and `docs/SECURITY.md`.
356
- The model cannot read sibling components or Git metadata. Policy turns deny
357
- access to the resolved Git metadata and markers, including those inside the
358
- selected source tree, nested bare repositories, and associated alternate object
359
- stores.
360
- Policy shell tools inherit only Codex's core environment; custom shell environment
361
- settings, login shells, and shell snapshots are disabled for these turns.
362
- Knowledge-base text stays with the private review artifacts during generation
363
- and is removed afterward.
364
-
365
- Known limitation: policy preflight and generation currently fail on Unix
366
- directories with non-UTF-8 names.
367
-
368
- On macOS, the pinned Codex runtime does not fully enforce write restrictions
369
- under `/tmp` (including `/private/tmp`). Keep the repository and artifacts outside
370
- that tree when read-only enforcement is required. See the
371
- [upstream sandbox limitation](https://github.com/openai/codex/issues/32395).
129
+ In Codex desktop or the interactive Codex CLI, ask:
372
130
 
373
- ```bash
374
- npx @openai/codex-security policy .
375
- npx @openai/codex-security policy . --path services/api
376
- npx @openai/codex-security policy . --knowledge-base architecture.md --model gpt-5.6-terra --effort high
377
- npx @openai/codex-security policy . --dry-run --json
378
- ```
131
+ > Use $cloud-findings to list findings for example/security-demo in my selected
132
+ > workspace. Inspect the highest-severity finding and its report, and show its
133
+ > recorded assignee, patch links, verification results, and latest scan status.
134
+ > Do not change anything.
379
135
 
380
- The repository defaults to the current directory. `--path` selects a component,
381
- which inherits policies from its Git root, with the closest policy taking
382
- precedence. Linked worktrees and initialized submodules use their own roots.
383
- Targets and policy links must stay in the selected checkout, outside Git
384
- metadata; ancestor links cannot widen a component policy's scope.
385
-
386
- For an intentional separate Git directory, set `core.worktree` to the checkout's
387
- absolute path. Use `git worktree repair` for moved linked worktrees.
388
-
389
- Generation uses three Codex stages: describe the system, build a threat model,
390
- then draft the policy. The first two documents support review; they are not
391
- additional approval steps or policies to install.
392
- In a terminal, it asks about facts the source cannot establish and shows the
393
- exact diff. If both ChatGPT and API-key credentials are available, it asks which
394
- to use; `--auth chatgpt` or `--auth api-key` selects one explicitly.
395
-
396
- | Invocation | Calls Codex? | Result |
397
- | ---------------------------- | ------------ | ----------------------------------------------------------------------- |
398
- | `policy .` | Yes | Ask owner questions, save documents, and preview the draft. |
399
- | `policy . --headless --json` | Yes | Save documents without prompts and return their paths and review notes. |
400
- | `policy . --format md` | Yes | Generate a draft and write its Markdown to stdout. |
401
- | `policy . --dry-run --json` | No | Check local inputs and show the resolved target and settings. |
402
-
403
- None of these commands installs `SECURITY.md` in the repository. Output formats
404
- change presentation; they do not turn generation into a saved-draft read.
405
-
406
- ### Review the draft
407
-
408
- Review the saved `SECURITY.md` before copying it to the reported target. Check
409
- links from `.github/SECURITY.md` or `docs/SECURITY.md`: copying can change their
410
- guidance too. Preserve reporting instructions and obtain owner approval for
411
- exclusions, accepted risks, and severity decisions. Later scans read this policy.
412
-
413
- Generation and preview check for changes to the selected or inherited policies.
414
- If governing guidance changes during generation, completed documents remain for
415
- inspection, but no completed-draft manifest is written. Other source files are not
416
- frozen; regenerate if relevant source or neighboring policies change.
417
- A failed terminal preview reports a warning and the saved draft paths. Explicit
418
- output formats return the draft directly without running a diff preview.
419
-
420
- Use `--headless` or an explicit output format to skip questions. Unanswered
421
- questions remain in the review notes. Drafts default to the Codex Security state
422
- directory; `--output-dir` selects an empty directory outside every enclosing
423
- Git checkout and its Git metadata.
136
+ After completing connection setup, the same host connection can be used by
137
+ `codex exec`:
424
138
 
425
139
  ```bash
426
- npx @openai/codex-security policy . --path services/api \
427
- --headless --output-dir /path/outside/repository/api-policy --json
140
+ codex exec --ephemeral --json -s read-only 'Use $codex-security:cloud-findings to read findings and the latest scan status for example/security-demo in my selected workspace. Inspect one finding and its report. If the workspace or repository is ambiguous, explain the required selection and stop. Do not change anything.'
428
141
  ```
429
142
 
430
- The artifact directory contains:
143
+ Noninteractive execution needs an existing authenticated connection; it cannot
144
+ complete first-time sign-in. If authentication expires, the app is unavailable,
145
+ or workspace policy denies access, complete the reported setup action before
146
+ retrying. Those failures do not mean the repository has no findings.
431
147
 
432
- | File | Purpose |
433
- | ---------------------- | --------------------------------------------------------- |
434
- | `SECURITY.md` | Editable policy draft. |
435
- | `THREAT_MODEL.md` | Detailed threat model with source references. |
436
- | `project-spec.md` | System description and security boundaries. |
437
- | `previous-SECURITY.md` | Original policy used for the diff. |
438
- | `policy-draft.json` | Target, policy hashes, revision, model, and review notes. |
148
+ Assignment, issue validation, patch checks, periodic fix checks, and finding
149
+ lifecycle status are separate records. Some finding sources do not provide all
150
+ of them. The read workflow reports missing data and incomplete evidence pages,
151
+ and does not describe failed or unfinished scans as clean.
439
152
 
440
- Keep supporting documents private until reviewed for disclosure. A generated
441
- threat scenario is neither owner approval nor a confirmed vulnerability.
442
-
443
- `--format md` writes the draft to stdout. `--json` returns paths, review notes,
444
- status, and estimated cost. Global filters and token options work with these
445
- formats. Progress goes to stderr. `--full-output` reports failures with
446
- `ok: false`. `--max-cost` applies to the whole generation. If a stage cannot
447
- inspect required source evidence, generation stops and preserves completed
448
- documents. Fix the reported problem and use a new output directory to retry.
153
+ ## Run a scan from TypeScript
449
154
 
450
- ### Generate a policy from TypeScript
155
+ Scan a repository you own or have permission to assess:
451
156
 
452
157
  ```ts
453
158
  import { CodexSecurity } from "@openai/codex-security";
454
159
 
455
160
  const security = new CodexSecurity();
161
+
456
162
  try {
457
- const draft = await security.generatePolicy("/path/to/repository", {
458
- path: "services/api",
459
- knowledgeBasePaths: ["/path/to/architecture.md"],
460
- onStage: (stage) => console.error(stage),
461
- });
163
+ const result = await security.run("/path/to/repository");
164
+
165
+ console.log(result.reportPath);
166
+ console.log(result.findings.findings);
462
167
 
463
- console.log(await security.previewPolicy(draft));
464
- // Open draft.draftPath in an editor to review the saved policy.
168
+ if (result.hasFindingsAtOrAbove("high")) {
169
+ process.exitCode = 1;
170
+ }
465
171
  } finally {
466
172
  await security.close();
467
173
  }
468
174
  ```
469
175
 
470
- `preflightPolicy()` checks local inputs without starting Codex.
471
- `previewPolicy()` previews the supplied in-memory draft, uses the client's Python
472
- setting, and makes terminal control characters visible. Editing the saved file
473
- does not change that object. The standalone `securityPolicyDiff()` returns a raw diff
474
- for files or other non-terminal uses; pass an interpreter explicitly if needed.
475
- `generatePolicy()` accepts `auth`, `path`, `knowledgeBasePaths`, `outputDir`,
476
- `maxCostUsd`, `signal`, and progress and cost callbacks. An optional
477
- `answerQuestions` callback receives each group of up to three owner questions
478
- and a cancellation signal. Without it, the questions remain unresolved.
479
-
480
- ## CLI
176
+ Omitting `outputDir` saves results in the private Codex Security state directory.
177
+ To choose another location, use a new or empty directory outside the scanned
178
+ repository and its enclosing Git worktree. On macOS and Linux, an existing output
179
+ directory must be private to you (`chmod 700`).
481
180
 
482
- ```bash
483
- npx @openai/codex-security policy . --path services/api
484
- npx @openai/codex-security scan .
485
- npx @openai/codex-security scan /path/to/repository --path src --path tests
486
- npx @openai/codex-security scan /path/to/repository --diff origin/main --json
487
- npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/results
488
- npx @openai/codex-security scan /path/to/repository --dry-run
489
- ```
181
+ ### Read results
490
182
 
491
- Use `scan --help` for options, `--version` for the installed version, and
492
- `info --json` for package, plugin, runtime, and model details. `--dry-run`
493
- runs local preflight checks. `info -c FILE --json` inspects resolved configuration
494
- and its sources without a repository or runtime.
183
+ | Result | Contents |
184
+ | --------------------------------- | ---------------------------------------------------------------- |
185
+ | `findings.findings` | Findings from this scan. |
186
+ | `reportPath` | Path to the Markdown report. |
187
+ | `coverage` | What the scan assessed and any coverage gaps. |
188
+ | `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
189
+ | `sarifPath` | SARIF export path, or `null`. |
190
+ | `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
191
+ | `cost` | Estimated model usage cost, or `null` when unavailable. |
495
192
 
496
- ### Project files
193
+ Review coverage alongside findings. A report with no findings does not establish
194
+ that the repository is secure. Reports and logs can contain source code,
195
+ vulnerability details, and credentials; review them before sharing.
497
196
 
498
- Use `scan -c FILE` / `scan --config FILE` to load reusable scan settings:
499
-
500
- ```bash
501
- codex-security scan . -c codex-security.yaml --dry-run --json
502
- codex-security scan . -c codex-security.json --model gpt-5.6-terra
503
- codex-security init
504
- codex-security info -c codex-security.yaml --json
505
- ```
506
-
507
- Select one `.yaml`, `.yml`, or `.json` file. `scan`, `bulk-scan`, `scan-components`,
508
- and `info` accept `-c`. They also accept an operator-set
509
- `CODEX_SECURITY_PROJECT_CONFIG`; an explicit `-c` wins. Without either, no file is
510
- loaded or discovered. The repository still comes from the command's target
511
- selection. SDK `run()` and saved reruns do not load project files automatically.
512
-
513
- The selected file is trusted like CLI options and SDK `codexOverrides`. Native
514
- settings can start configured MCP server processes and select model-service destinations. Do not
515
- select configuration controlled by an untrusted repository or pull request; keep
516
- CI scanner configuration outside the checkout being assessed.
517
-
518
- `init [file]` writes `codex-security.yaml` by default and never overwrites an
519
- existing file. YAML starters show defaults as comments; JSON starters contain the
520
- editor schema hint, relative to the chosen file and the invocation directory's
521
- local package installation. `info` reports effective model details and native key sources
522
- without dumping raw native values.
523
-
524
- ```yaml
525
- # yaml-language-server: $schema=./node_modules/@openai/codex-security/schemas/project-config.schema.json
526
- scan:
527
- mode: standard
528
- scope:
529
- paths: [src]
530
- codex:
531
- model: gpt-5.6-sol
532
- model_reasoning_effort: xhigh
533
- policy:
534
- fail_on_severity: high
535
- ```
536
-
537
- All settings are optional; `{}` uses the existing defaults. JSON files can use a
538
- root `$schema` string pointing to the same packaged schema. Schema hints are for
539
- editors; the CLI uses its bundled validator without fetching URLs, coercing values,
540
- or dropping unknown keys. Native `codex` settings retain their existing checks and
541
- profile semantics. CLI `scan --schema --json` describes command arguments.
542
-
543
- Settings use built-in defaults, applicable legacy deep defaults, the file, then
544
- explicit CLI values. Lists and scope variants are replaced. `--head` can refine
545
- a file diff and `--base` a file working-tree scope. A selected native profile can
546
- still override root model/effort values. Existing native alias-conflict checks
547
- and the behavior of `--provider openai` are unchanged.
548
-
549
- File context, instruction, validation, and output paths resolve from the file's
550
- directory. CLI file paths resolve from the invocation directory; scope paths
551
- resolve from the repository. The file cannot select a different repository or
552
- enable automatic patching/publication. The loader does not evaluate code,
553
- interpolate environment values, include remote files, or merge multiple files.
554
-
555
- Dry-run output adds `projectConfig.path` and `projectConfig.sources`, selected
556
- prompt paths, and the finding policy without dumping raw native configuration.
557
- Missing or invalid selected files exit `2`. Help, version, and command schema
558
- output do not load project files. Existing scan and finding-policy exit codes
559
- remain unchanged.
197
+ The SDK does not set your process's exit status. Use `hasFindingsAtOrAbove()`
198
+ as in the example to enforce a severity threshold.
560
199
 
561
200
  ### Scan options and output
562
201
 
563
- `--path` scopes a scan to one or more paths, `--diff` scans committed changes,
564
- and `--working-tree` scans staged and unstaged changes. Deep scans support
565
- repository and path targets.
566
-
567
- Bulk scans use clean, shallow checkouts and support repository or path scopes.
568
- They reject configured diff or working-tree scopes before starting unless each
569
- affected CSV row supplies its own path scope.
570
-
571
- Working-tree snapshots include files from untracked nested Git repositories.
572
- Initialized submodules must be clean and checked out at the commit recorded by
573
- the parent repository.
574
-
575
- Repeat `--knowledge-base PATH` for UTF-8 text files with any extension (including
576
- JSON and SARIF), PDF, or Word (`.docx`) files. Directories are searched recursively,
577
- skipping other binary files. Explicitly supplied unsupported binary files are rejected.
578
- Bulk scans share these documents with every repository.
579
-
580
- Use an empty output directory outside the scanned directory and enclosing Git
581
- worktree. On macOS/Linux, existing directories must be private to you
582
- (`chmod 700`). `--archive-existing` moves previous results to
583
- `<output-dir>.previous-<timestamp>-<id>`; add `--dry-run` to preview the move.
584
- SARIF output, when produced, is at `<scan-dir>/exports/results.sarif`.
585
-
586
- Scans are report-only by default. Set `--fail-on-severity high` to exit with
587
- `1` if a completed scan finds high or critical issues. Incomplete scans exit
588
- with `2`, writing available results to stdout and a coverage warning to stderr.
589
-
590
- For machine-readable scan output (`--format json` or `--format jsonl`), a scan
591
- execution failure writes one structured object to stdout:
592
-
593
- ```json
594
- {
595
- "status": "failed",
596
- "code": "SCAN_FAILED",
597
- "message": "..."
598
- }
599
- ```
600
-
601
- With `--full-output`, the same code and message are reported under `error` in
602
- an `ok: false` envelope instead.
603
-
604
- The command still exits with `2` for runtime, export, invalid-input, or
605
- incomplete-scan failures, and human-readable diagnostics remain on stderr.
606
- Use `scan --schema --format json` to discover this failure variant alongside
607
- the successful scan output. Cancellation and termination retain their `130`
608
- and `143` exit codes.
609
-
610
- ### Import findings as a saved scan
611
-
612
- Import an existing findings CSV or JSON file into local scan history and SQLite:
613
-
614
- ```bash
615
- codex-security scan import --csv /path/to/findings.csv
616
- codex-security scan import --json /path/to/findings.json --format json
617
- codex-security scan import --csv /path/to/findings.csv --dry-run
618
- ```
619
-
620
- Supply exactly one of `--csv PATH` or `--json PATH`. CSV uses the existing
621
- [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv),
622
- including the optional `candidate_id` column. JSON accepts a complete
623
- `codex-security.findings` document or `{ "findings": [...] }`, with each finding
624
- matching the existing findings schema. On `scan import`, `--json` selects the
625
- input file; use `--format json` for JSON output. Other commands retain their
626
- existing `--json` output flag. The selected input must be a regular file, and its
627
- path must not traverse symbolic links or directory junctions. Use the direct
628
- filesystem path when the file or a parent directory is linked.
629
-
630
- Each import creates one completed scan using the configured
631
- `CODEX_SECURITY_STATE_DIR`. The target is a retained copy of the input dataset,
632
- independent of the current repository. Every source occurrence remains a separate
633
- finding, including duplicate reports. Original identifiers are preserved in
634
- `extensions.import`; the original file is sealed under `artifacts/import/`.
635
- JSON writeup paths are retained as source metadata without reading external files.
636
-
637
- Completion means the import finished. Coverage is unknown and the report states
638
- that no security analysis was performed. Importing requires no model calls or
639
- authentication. `--dry-run` validates without saving a scan. `--output-dir` and
640
- `--archive-existing` control saved output, and `scans rerun SCAN_ID` reimports the
641
- retained input.
642
-
643
- ### Generate mock scan results
644
-
645
- Use `--mock` to populate a Standard scan with synthetic test data in seconds,
646
- without Codex authentication or any LLM calls:
647
-
648
- ```bash
649
- codex-security scan /path/to/repository --mock
650
- codex-security scan /path/to/repository --mock --output-dir /path/outside/repository/mock-results
651
- ```
652
-
653
- The SDK equivalent is `await security.run(repository, { mock: true })`.
654
- Mock mode is off by default. It uses normal target validation, scan registration,
655
- artifact finalization, reports, and local scan/finding history. Output directories,
656
- archiving, JSON output, exports, and `--fail-on-severity` work as usual.
657
- `--dry-run` only validates inputs; `--mock` saves a completed scan.
658
-
659
- Each run contains 12 findings across all severity levels: eight stable findings
660
- recur on subsequent scans of the same repository, and four have new identities
661
- on every run. Two pairs describe the same root causes with different titles and
662
- identities, providing inputs for deduplication testing. Mock scans skip automatic
663
- LLM matching; existing identity-based history indexing still runs. Separate
664
- comparison or deduplication commands retain their usual model behavior.
665
-
666
- Titles, provenance, artifact metadata, and reports identify the results as
667
- synthetic. Paths and code snippets are fictional and are never written into the
668
- repository. Completion means fixture generation finished, not that the repository
669
- was audited. Results enter the selected local state just like other scans; set
670
- `CODEX_SECURITY_STATE_DIR` to a separate directory when creating disposable data.
671
- Token usage is zero. `scans rerun` preserves mock mode.
672
-
673
- Mock mode supports repository, path, and diff targets in Standard mode. It cannot
674
- be combined with `--dry-run`, `--patch`, Deep mode, custom validation, or post-scan
675
- prompts. Scan prompts and knowledge-base inputs do not change the fixtures, and
676
- mock scans do not offer interactive patching.
677
-
678
- ### Attribute scans to end users
679
-
680
- When scanning on behalf of users, pass each user's stable hashed ID:
202
+ Pass scan settings as the second argument to `run()`. The following SDK snippets
203
+ assume an open `CodexSecurity` client named `security`; close it when finished.
681
204
 
682
205
  ```ts
683
- await security.run("/path/to/repository", {
684
- auth: "api-key",
685
- safetyIdentifier: hashedUserId,
206
+ const result = await security.run("/path/to/repository", {
207
+ target: ["src", "tests"],
208
+ knowledgeBasePaths: ["/path/to/architecture.md"],
209
+ scanPrompt: "Focus on authentication and authorization.",
210
+ outputDir: "/path/outside/repository/results",
211
+ maxCostUsd: 5,
686
212
  });
687
213
  ```
688
214
 
689
- ```bash
690
- codex-security scan /path/to/repository --auth api-key --safety-identifier hashed-user-id
691
- ```
692
-
693
- Use a nonblank ID of 1 to 64 characters without NUL or personal data such as
694
- email addresses. It applies to the scan, workers, retries, and follow-up work
695
- without changing shared configuration. Supply it again for reruns.
696
-
697
- The runtime needs native `--safety-identifier` support, and the plugin must
698
- forward it to workers. The bundled runtime doesn't support it yet; choose a
699
- compatible build with `CODEX_CLI_PATH`. The SDK checks the ID's format, not
700
- runtime or plugin compatibility. Older versions may omit the ID.
701
-
702
- ### Scan project components
215
+ | Option | Use |
216
+ | ------------------------------------------- | ------------------------------------------------------------------------------ |
217
+ | `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |
218
+ | `mode` | `"standard"` (default) or `"deep"`. Deep scans support repositories and paths. |
219
+ | `knowledgeBasePaths` | Supporting text, PDF, DOCX files, or directories. |
220
+ | `scanPrompt` / `scanPromptFile` | Additional scan instructions. Inline text takes precedence. |
221
+ | `validationPrompt` / `validationPromptFile` | Custom validation instructions for standard scans. |
222
+ | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions after the scan. |
223
+ | `outputDir` | Results directory; omit to use the state directory. |
224
+ | `archiveExisting` | Move previous results aside before reusing `outputDir`. |
225
+ | `maxCostUsd` | Stop at an estimated model cost; see [cost limits](#progress-and-cost). |
226
+ | `signal` | An `AbortSignal` to cancel the scan. |
703
227
 
704
- `scan --path` runs one scan across selected paths. To scan each local project
705
- component separately (standard mode by default), use `scan-components`:
228
+ The exported `ScanOptions` type describes all options and callbacks. For full
229
+ CLI behavior, see [scan options and output](docs/cli.md#scan-options-and-output).
706
230
 
707
- ```bash
708
- npx @openai/codex-security scan-components /path/to/project \
709
- --component apps/api --component apps/web --component packages/shared \
710
- --workers 4 --output-dir /path/outside/project/results
711
- ```
712
-
713
- Use `-c FILE` to share settings, including `scan.mode: deep`, context and prompt
714
- files, per-scan deep workers, cost limits, and severity policy. Component plans
715
- override the file's scope. `output.directory` supplies the results directory when
716
- `--output-dir` is omitted. A configured severity threshold returns exit `1` after
717
- completed scans; failures or incomplete results return `2`.
231
+ ### Scan a diff
718
232
 
719
- Use `--auto` instead of `--component` for a proposed split. Save a plan to
720
- review or edit, then run it with a new output directory:
721
-
722
- ```bash
723
- npx @openai/codex-security scan-components /path/to/project \
724
- --auto --plan-only --output-dir /path/outside/project/plan
725
- npx @openai/codex-security scan-components /path/to/project \
726
- --components-file /path/outside/project/plan/components.json \
727
- --output-dir /path/outside/project/results
728
- ```
233
+ ```ts
234
+ import { DiffTarget } from "@openai/codex-security";
729
235
 
730
- For large repositories, automatic planning splits inventories into separate calls
731
- that fit Codex's input character limit. It preserves directory boundaries where
732
- possible and subdivides oversized packages and flat directories as needed. Each
733
- call uses a fresh context and can select only paths within its batch. Omitted
734
- files are retained in `Other files` components within those same boundaries.
735
- Large repositories can therefore require more planning calls and produce more
736
- components. Review or edit the saved plan before scanning with `--components-file`.
737
-
738
- Components use repository-relative paths:
739
-
740
- ```json
741
- {
742
- "components": [
743
- { "name": "API", "paths": ["apps/api", "packages/auth"] },
744
- { "name": "Web", "paths": ["apps/web"] }
745
- ]
746
- }
236
+ const result = await security.run("/path/to/repository", {
237
+ target: DiffTarget.refs({ base: "origin/main" }),
238
+ });
747
239
  ```
748
240
 
749
- Automatic planning respects Git ignore rules and groups omitted files under
750
- `Other files`. Each proposed path must contain an inventoried file. Planning
751
- leaves source files unchanged.
752
-
753
- Each component saves artifacts under `component-N/`. Combined `findings.json`
754
- merges high-confidence root-cause matches, keeping the highest severity and
755
- original IDs. Uncertain matches stay separate. `summary.json` records coverage
756
- and matching status; `report.md` links to component reports. Export and publish
757
- from the individual scan folders, not the combined summary.
758
-
759
- Large comparisons use bounded batches that cover every earlier/later finding
760
- pair. Overlapping confirmed groups are joined in code. Finding text is not
761
- truncated; pairs above Codex's input limit leave matching incomplete.
762
-
763
- Use an empty output directory outside the project. Failed components don't
764
- stop others, but failures, incomplete coverage, or failed matching exit with
765
- `2`. Retry failed or incomplete components with
766
- `--components-file retry-components.json` and a new output directory.
767
- The retry report covers only those components; it does not update the original
768
- combined report.
769
-
770
- `--max-cost` applies per component, excluding planning and matching.
771
- `--model` and `--effort` also apply to matching; `--auth` applies throughout.
772
- Planning and matching reject an ambient command provider that conflicts with
773
- explicit `--auth chatgpt` or `--auth api-key`. A command provider explicitly
774
- selected through SDK `codexOverrides` retains its authentication configuration.
775
- Use `--knowledge-base`, `--scan-prompt-file`, and `--post-scan-prompt-file` as for
776
- bulk scans.
777
-
778
- From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
779
- Use `auto: true` for planning, `planOnly: true` to save the plan without scans,
780
- and `scanOptions.auth` to select credentials.
241
+ `DiffTarget.refs()` compares the base with `HEAD` unless you supply `head`.
242
+ The checkout must be clean, complete, and at that head revision.
243
+ Use `DiffTarget.workingTree()` for staged and unstaged changes relative to `HEAD`.
244
+ Diff targets require standard mode.
781
245
 
782
- ### Configure deep scans
246
+ ### Configure the client
783
247
 
784
- For `scan --mode deep`, `--workers` sets discovery concurrency and `--subagents`
785
- sets subagents per worker. `--stop-after-no-new` stops after that many runs
786
- without new issues. `--max-discovery-runs` and `--max-time-hours` cap discovery
787
- runs and duration. SDK equivalents:
248
+ Set model and native Codex settings on the client:
788
249
 
789
250
  ```ts
790
- await security.run("/path/to/repository", {
791
- mode: "deep",
792
- workers: 2,
793
- subagents: 0,
794
- stopAfterNoNew: 3,
795
- stopAfterConsecutiveErrors: 2,
796
- maxDiscoveryRuns: 10,
797
- maxTimeHours: 1.5,
251
+ const security = new CodexSecurity({
252
+ codexOverrides: {
253
+ model_reasoning_effort: "high",
254
+ analytics: { enabled: false },
255
+ },
798
256
  });
799
257
  ```
800
258
 
801
- Set defaults in `$CODEX_HOME/codex-security/config.toml`:
259
+ Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
260
+ The bundled runtime and plugin are used by default. `pythonPath` overrides the
261
+ `PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
802
262
 
803
- ```toml
804
- [deep_scan]
805
- workers = 4
806
- subagents = 3
807
- stop_after_no_new = 4
808
- stop_after_consecutive_errors = 3
809
- max_discovery_runs = 40
810
- max_time_hours = 96
811
- ```
263
+ New and resumed Deep Scans require a current plugin with
264
+ `directDeepScanEngine: 1`, `workerProviderSnapshot: 4`, and isolated worker
265
+ configuration support. Older custom plugins fail before scan execution; update
266
+ the plugin or omit `pluginPath` to use the bundled version. Discovery, reducer,
267
+ and resumed workers inherit per-scan provider, authentication, environment, and
268
+ executable settings, with their existing read-only permissions. Reading saved
269
+ reports does not require these execution capabilities.
812
270
 
813
- CLI and SDK options override these defaults. Project files can use
814
- `scan.deep.stop_after_consecutive_errors`, and SDK calls can use
815
- `stopAfterConsecutiveErrors`; there is no new CLI flag for it. `--codex` cannot
816
- configure this section. Worker and run counts must
817
- be positive integers; `subagents` can be zero. Legacy `workers = "auto"` means
818
- four workers. Unknown keys are rejected.
819
-
820
- `max_time_hours` accepts positive values up to 96, including fractional hours.
821
- At the deadline, discovery stops; the scan combines and returns completed findings.
822
-
823
- `scan --workers` controls discovery workers within one deep scan;
824
- `bulk-scan --workers` controls how many repositories are scanned concurrently.
825
-
826
- The project-file deep block uses `subagents_per_worker` for the existing SDK/CLI
827
- `subagents` setting. A valid deep block can remain inactive in standard mode;
828
- explicit deep CLI options require deep mode. All six active values are resolved
829
- before runtime preparation and saved in new recipes. Complete saved values are
830
- independent of later changes to the legacy TOML file.
831
-
832
- ### Runtime configuration and worker limits
833
-
834
- Scans use these isolated Codex defaults instead of your user or repository
835
- configuration:
836
-
837
- ```toml
838
- approval_policy = "on-request"
839
- approvals_reviewer = "auto_review"
840
- cli_auth_credentials_store = "auto"
841
- model = "gpt-5.6-sol"
842
- model_reasoning_effort = "xhigh"
843
- model_reasoning_summary = "detailed" # "none" for amazon-bedrock
844
- show_raw_agent_reasoning = true
845
-
846
- [features]
847
- plugins = true
848
- goals = true
849
-
850
- [features.multi_agent_v2]
851
- enabled = true
852
- max_concurrent_threads_per_session = 9
853
-
854
- [windows]
855
- sandbox = "unelevated"
856
- ```
271
+ The SDK no longer adapts the older `node ./mcp/server.mjs` MCP entrypoint; use
272
+ the current shell or Windows launcher for runtime-root routing.
857
273
 
858
- Use `--model` to choose a model and `--effort minimal|low|medium|high|xhigh|max`
859
- for reasoning effort. Repeat `--codex KEY=VALUE` for other TOML settings:
274
+ Custom plugins must support the current workbench protocol for scan comparison
275
+ and archival. Update an older custom plugin or omit `pluginPath` to use the
276
+ bundled version. The SDK no longer adapts payloads or archives scan directories
277
+ on behalf of older workbench implementations.
860
278
 
861
- ```bash
862
- npx @openai/codex-security scan . \
863
- --model gpt-5.6-terra \
864
- --effort high \
865
- --codex features.multi_agent_v2.max_concurrent_threads_per_session=4
866
- ```
867
-
868
- The thread limit of `9` includes the parent and up to eight delegated workers.
869
- It is separate from deep-scan and bulk-scan worker counts.
279
+ Scans use an isolated Codex configuration. See
280
+ [runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)
281
+ for supported overrides and defaults.
870
282
 
871
- Quote string values as TOML, for example
872
- `--codex 'model_reasoning_effort="high"'`. Do not pass both `--model` and
873
- `--codex 'model="..."'`, or both `--effort` and
874
- `--codex 'model_reasoning_effort="..."'`: conflicting or repeated keys are
875
- rejected.
283
+ Windows defaults to `windows.sandbox = "elevated"` to enforce credential read
284
+ denials. Explicit `windows.sandbox` settings remain unchanged; Codex reports
285
+ policies unsupported by the selected backend.
876
286
 
877
- Choose plugins with `--plugin-path`. Overrides of `plugins`, `marketplaces`,
878
- or `features.plugins` are rejected, including in profiles. Multi-agent v2 must
879
- stay enabled: `agents.max_threads` and
880
- `features.multi_agent_v2.enabled=false` are rejected.
287
+ ### Load a project file
881
288
 
882
- `validate`, `patch`, and `verify-fix` accept `--auth`, `--effort`, and the `model`,
883
- `model_reasoning_effort`, and `analytics.enabled` keys in `--codex`, but no
884
- other runtime overrides.
289
+ Load shared CLI and SDK settings explicitly:
885
290
 
886
- Use `--codex 'analytics.enabled=false'` to disable Codex usage analytics and
887
- built-in metrics for a command:
888
-
889
- ```bash
890
- npx @openai/codex-security validate "Candidate finding" --codex 'analytics.enabled=false'
891
- npx @openai/codex-security patch "Security issue" --codex 'analytics.enabled=false'
892
- npx @openai/codex-security verify-fix "Security issue" --codex 'analytics.enabled=false'
893
- ```
894
-
895
- The same setting works for `scan` and `bulk-scan`. An explicit setting is
896
- preserved when `scan --patch` starts remediation and when
897
- `patch --assess-patch-risk` starts its follow-up assessment. Boolean `true`
898
- is also accepted; omitting the setting preserves the command's existing
899
- configuration and Codex defaults. Validation ignores user configuration.
900
- For stored OpenAI credentials, patching and verification read configuration
901
- from the shared credential home. API-key commands and custom providers that use their own credentials retain
902
- their ambient Codex configuration. Patching and verification preserve project trust from the
903
- ambient home; explicit `--codex` settings apply to the command and its
904
- patch-risk assessment.
905
-
906
- This setting does not control explicitly configured OpenTelemetry log or trace
907
- exporters, authentication, integrations, or CLI update checks.
908
-
909
- See [Local security model](#local-security-model) for approval and filesystem
910
- restrictions.
911
-
912
- ### Environment variables
913
-
914
- | Variable | Effect |
915
- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
916
- | `OPENAI_API_KEY`, `CODEX_API_KEY` | Scan credentials; `OPENAI_API_KEY` wins if both are set. |
917
- | `CODEX_SECURITY_EMBEDDINGS_URL` | Findings service endpoint; see [Embeddings and storage](#embeddings-and-storage). |
918
- | `CODEX_SECURITY_LINEAR_TEAM`, `CODEX_SECURITY_LINEAR_PROJECT` | Default team and project for completed-scan publication. |
919
- | `CODEX_SECURITY_LINEAR_API_KEY` | Personal API key for Linear patching and direct publication. |
920
- | `CODEX_SECURITY_LOG_LEVEL` | CLI-only; `debug` enables verbose diagnostics. |
921
- | `LOG_LEVEL` | CLI-only fallback when `CODEX_SECURITY_LOG_LEVEL` is unset. |
922
- | `CODEX_SECURITY_STATE_DIR` | Private scan-history, workbench, and default artifact directory. |
923
- | `CODEX_SECURITY_PROJECT_CONFIG` | Trusted project file for `scan`, `bulk-scan`, `scan-components`, and `info`; `-c` wins. Unset by default. |
924
- | `CODEX_HOME` | Ambient Codex home for file-based sign-in and default state; defaults to `~/.codex`. |
925
- | `CODEX_CLI_PATH` | Codex executable for authentication, plugin setup, scans, and workers. |
926
- | `PYTHON` | Python interpreter when `--python` or SDK `pythonPath` is unset. |
927
- | `GH_HOST` | GitHub Enterprise host for interactive `bulk-scan` discovery. |
928
- | `CODEX_SECURITY_NO_UPDATE_NOTICE`, `NO_UPDATE_NOTIFIER` | Either variable disables interactive update notices. |
929
- | `CODEX_SECURITY_NPM_REGISTRY`, `npm_config_registry`, `NPM_CONFIG_REGISTRY` | Update-check registry, in precedence order. |
930
- | `CI` | Disables interactive update notices. |
931
- | `NO_COLOR`, `TERM` | Disables colored scan history when `NO_COLOR` is defined or `TERM=dumb`. |
932
-
933
- Custom Codex executables need thread source attribution for `exec` and
934
- `app-server` (Codex 0.149.1+). On Windows, use a native `.exe` or `.com`;
935
- command shims such as `codex.cmd` fall back to the bundled executable.
936
-
937
- Python lookup order: `--python` (on `scan`, `bulk-scan`, or `export`) or SDK
938
- `pythonPath`, then `PYTHON`, the managed Codex runtime, and `python3` or `python`
939
- on `PATH` (`py` also works on Windows). `CODEX_SECURITY_STATE_DIR` overrides
940
- `CODEX_HOME` for state storage. Keep state and results outside the repository.
941
-
942
- ### Progress and cost
943
-
944
- Interactive scans show full-screen progress; CI, redirected output, and
945
- `--headless` use plain status lines. Results go to stdout, progress and
946
- diagnostics to stderr. Add `--verbose` for diagnostics. Check logs for
947
- sensitive information before sharing them.
948
-
949
- The token summary shows uncached input, cache reads, cache writes, output,
950
- and total tokens. Total tokens include all input plus output; cache reads and
951
- writes are subsets of input, not extra tokens. When cache-write usage is missing,
952
- the summary shows uncached input and cache writes as unavailable.
953
- The final summary preserves missing-data information from a matching session log.
954
- If the Codex runtime converts an omitted count to zero before recording it, the
955
- CLI cannot distinguish that zero from reported usage.
956
-
957
- Cost displays show a range using
958
- [standard API prices](https://developers.openai.com/api/docs/pricing), because
959
- runtime usage does not identify which requests received long-context pricing.
960
- The minimum assumes short-context pricing; the maximum assumes long-context
961
- pricing. These are token-cost estimates for the observed usage, excluding other
962
- processing tiers, fees, surcharges, and account-specific pricing.
963
-
964
- JSON results, scan history, and bulk-scan receipts preserve
965
- `cost.estimatedUsdRange`: `min`, `max`, and `context: "unknown"`. A `null` maximum
966
- means an upper estimate is unavailable, including models without verified
967
- long-context rates. `cost.pricing` records the price source, verification date,
968
- processing tier, short-context rates, and verified long-context rates when known.
969
- Models without known short-context prices still have no cost estimate.
970
-
971
- For compatibility, `cacheWriteInputTokens` remains the reported token subtotal.
972
- `cacheWriteInputTokensReported: false` means at least one included usage record
973
- did not report cache writes. Raw usage uses `cache_write_input_tokens_reported`.
974
- In that case, the range minimum prices unclassified input as ordinary input,
975
- and the maximum allows it to be cache writes. Token counts remain unchanged.
976
- Older saved records remain readable and display a labeled legacy estimate;
977
- they are not repriced using current rates.
978
-
979
- For compatibility, `cost.estimatedUsd` retains the short-context baseline used
980
- by existing spending limits. `cost.pricing.context: "short"` describes that
981
- baseline, not observed request contexts. Use `estimatedUsdRange` for cost
982
- reporting. This change does not change when spending limits stop scans.
983
-
984
- `--max-cost USD` stops the scan and its workers when estimated cost exceeds
985
- the limit, though in-flight requests can finish above it. If deep-scan
986
- discovery has finished, the scan returns a sealed partial report without more
987
- model calls and lists unvalidated candidates as follow-up work. Bulk scans
988
- apply the limit per repository attempt.
989
-
990
- With `--max-cost`, automatic finding-history matching makes at most one extra
991
- model call. If it needs more context, the completed scan is kept and a warning
992
- directs you to run `scans match --all` explicitly.
993
-
994
- For a single scan in the interactive dashboard, reaching 80% of the limit
995
- offers a higher **total** USD limit. Enter a larger amount to approve it, or
996
- press Enter with an empty input or Escape to keep the current limit. The scan
997
- continues running while you decide, and the existing limit remains enforced
998
- until the increase is saved. Increases keep the same scan and accumulated cost;
999
- they do not restart work or extend time or discovery limits. CI, JSON/JSONL,
1000
- `--headless`, and `--verbose` scans do not offer budget increases. If usage crosses the limit
1001
- before an increase is approved, the scan still stops.
1002
-
1003
- SDK callers can supply `onBudgetApproaching({ maxCostUsd, cost, signal })` and
1004
- return a higher total limit, or `undefined` to keep the current limit. The
1005
- callback runs once per limit at 80% usage without blocking tracking or
1006
- execution. Its signal aborts when the scan stops or finishes model work; late
1007
- answers are ignored. Invalid increases or failures to save them leave the
1008
- existing limit in place and report a warning. `onCost(cost, maxCostUsd)` reports
1009
- the current limit, including after an approved increase.
1010
-
1011
- These amounts estimate API-equivalent model usage, not ChatGPT subscription
1012
- allowance. Post-scan prompts run after scan cost tracking ends and are outside
1013
- this limit.
1014
-
1015
- ### Bulk scans
1016
-
1017
- Run `gh auth login`, then `npx @openai/codex-security bulk-scan` to select
1018
- GitHub repositories pushed in the last 90 days. Forks and archived repositories
1019
- are excluded; private checkouts use your GitHub CLI sign-in. The command asks
1020
- for an output directory and saves your selection there as `repositories.csv`.
1021
- `--output-dir` requires CSV input.
1022
-
1023
- For CI or an existing repository list, pass a CSV with `id`, `repository`, and
1024
- `revision` (full commit hash). Optional `scope`, `mode`, and `prompt` columns
1025
- customize each scan:
1026
-
1027
- ```csv
1028
- id,repository,revision,scope,mode,prompt
1029
- service,https://github.com/acme/service.git,0123456789abcdef0123456789abcdef01234567,src,standard,Focus on authentication and authorization.
1030
- ```
1031
-
1032
- ```bash
1033
- npx @openai/codex-security bulk-scan repositories.csv \
1034
- --output-dir /path/outside/repositories/security-scans --workers 4
1035
- ```
1036
-
1037
- `--scan-prompt-file PATH` adds instructions to a scan or all bulk scans. Each
1038
- repository's CSV `prompt` follows the shared instructions.
1039
- `-c FILE` shares config with single scans: CSV mode/scope override file defaults,
1040
- and deep settings apply only to deep rows. `output.directory` can supply the
1041
- results directory. `fail_on_severity` returns exit `1` without retrying completed
1042
- scans, including when resuming saved results. A changed project configuration
1043
- requires a new campaign output directory.
1044
- `--post-scan-prompt-file PATH` runs a follow-up in the same authenticated session,
1045
- even after a failed or incomplete scan, but not after cancellation or a
1046
- cost-limit stop.
1047
-
1048
- `--workers` defaults to `4`. `--max-attempts` defaults to `1` attempt per pending
1049
- repository per invocation. Rerunning the command continues the campaign, skips
1050
- completed results, and starts new attempts for pending repositories. If an
1051
- attempt directory is occupied, that repository stops before replacing its
1052
- checkout and the command recommends `--recover`.
1053
-
1054
- #### Recovering failed or interrupted bulk scans
291
+ ```ts
292
+ import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
1055
293
 
1056
- Use the original CSV, output directory, and campaign options with `--recover`:
294
+ const { config, options } = await loadProjectConfig("codex-security.yaml");
295
+ const security = new CodexSecurity(config);
1057
296
 
1058
- ```bash
1059
- npx @openai/codex-security bulk-scan repositories.csv \
1060
- --output-dir /path/outside/repositories/security-scans --recover
297
+ try {
298
+ const result = await security.run("/path/to/repository", options);
299
+ if (
300
+ options.failureSeverity !== undefined &&
301
+ result.hasFindingsAtOrAbove(options.failureSeverity)
302
+ ) {
303
+ process.exitCode = 1;
304
+ }
305
+ } finally {
306
+ await security.close();
307
+ }
1061
308
  ```
1062
309
 
1063
- Recovery requires an existing campaign with a matching manifest. It skips
1064
- completed results, including partial coverage, and repositories never started.
1065
- For each failed or interrupted repository, it checks the latest attempt:
1066
-
1067
- - A sealed scan is recorded in `results.jsonl` without scanning again.
1068
- - An eligible running Deep Scan resumes its original session, keeping its scan
1069
- ID, completed workers, artifacts, saved settings, and accumulated cost.
1070
- - A failed, canceled, or otherwise unavailable scan starts a new attempt at the
1071
- CSV's pinned revision. Attempt numbers account for both receipts and existing
1072
- directories. Old artifacts and checkouts are preserved; new attempts use
1073
- `recovery-checkouts/<id>/attempt-<n>`.
1074
-
1075
- `--workers` still defaults to `4`; `--max-attempts` defaults to one recovery or
1076
- new attempt per repository. A resume connection failure stops that repository
1077
- for this invocation instead of starting another scan. Other repositories
1078
- continue. Failed and interrupted recovery checkouts remain available for a later
1079
- `--recover`; fresh completed checkouts are removed after recording the result.
1080
- If a reboot interrupted a receipt write, its unfinished tail is saved beside
1081
- `results.jsonl` as `results.jsonl.interrupted-<id>` before appending valid records.
1082
-
1083
- Same-scan resume requires the original checkout, session logs, and Codex Security
1084
- state directory. Recovery does not reconstruct deleted checkpoints or fix the
1085
- underlying cause of execution failures. New attempts incur new scan costs.
1086
- Any remaining failures or partial coverage keep exit code `2`.
1087
- `bulk-scan --help` lists all options.
1088
-
1089
- ### Custom validation
1090
-
1091
- Replace the final validation step of a standard or diff scan with a prompt
1092
- file. Source review still runs; discovery workers do not receive this prompt.
310
+ `run()` does not discover project files. Paths inside a file resolve from that
311
+ file's directory; scope paths resolve from the repository. For a typed object,
312
+ use `resolveProjectConfig(input, directory?)`. Override loaded options with
313
+ `{ ...options, maxCostUsd: 5 }`.
1093
314
 
1094
- ```bash
1095
- npx @openai/codex-security scan . --validation-prompt-file validation.md
1096
- ```
315
+ Project files are trusted configuration and can select model endpoints or start
316
+ MCP servers. Keep CI scanner configuration outside the checkout being assessed.
317
+ See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
318
+ for the schema and precedence rules.
1097
319
 
1098
- The SDK accepts the same file as `validationPromptFile`, or inline text as
1099
- `validationPrompt`:
320
+ ### Check inputs before scanning
1100
321
 
1101
322
  ```ts
1102
- const result = await security.run(repository, {
1103
- validationPrompt:
1104
- "Run scripts/validate.sh, test each candidate through the local API, and stop the test environment when finished.",
323
+ const plan = await security.preflight("/path/to/repository", {
324
+ target: ["src"],
325
+ maxCostUsd: 5,
1105
326
  });
327
+ console.log(plan);
1106
328
  ```
1107
329
 
1108
- Put setup, allowed targets, required evidence, and cleanup in the prompt.
1109
- There are no separate setup or teardown hooks. Use environment variables for
1110
- credentials; keep secrets out of prompts and validation output. Deep scans
1111
- reject this option; scans without candidates skip it.
1112
-
1113
- The SDK supplies the candidate IDs and requires a `CustomValidationResult`:
1114
-
1115
- ```json
1116
- {
1117
- "status": "complete",
1118
- "reason": null,
1119
- "validations": [
1120
- {
1121
- "candidateId": "candidate-1",
1122
- "validation": {
1123
- "disposition": "reportable",
1124
- "method": "integration test",
1125
- "confidence": "high",
1126
- "confidence_rationale": "The test reproduced the reported behavior.",
1127
- "rubric": "Check the protected operation.",
1128
- "evidence": ["The unauthorized request succeeded."],
1129
- "counterevidence_or_proof_gap": "",
1130
- "remaining_uncertainty": "",
1131
- "artifact_paths": []
1132
- },
1133
- "severity": null,
1134
- "impact": null
1135
- }
1136
- ]
1137
- }
1138
- ```
1139
-
1140
- Return one result per candidate with disposition `reportable`, `suppressed`,
1141
- `not_applicable`, or `deferred`. Set `severity` or `impact` to
1142
- `{ "level": "medium", "rationale": "..." }` to revise an assessment, or `null`
1143
- to retain it. Identity and source locations stay unchanged.
1144
-
1145
- The scan saves candidates and results, including suppressed and deferred
1146
- cases, under `artifacts/custom-validation/`. Coverage is incomplete if setup
1147
- fails, output is incomplete or invalid, or any candidate is deferred. An
1148
- incompatible plugin stops the scan; validation never falls back to the default.
1149
- Repeat `--validation-prompt-file` on reruns.
1150
-
1151
- ### Publish findings to Cloud
1152
-
1153
- Choose completed scans from local history:
1154
-
1155
- ```bash
1156
- npx @openai/codex-security publish scan --to cloud --dry-run --json
1157
- ```
1158
-
1159
- Press Space to select scans, then Enter to submit. Nothing is preselected.
1160
-
1161
- For scripts, repeat `--scan` with saved IDs or unique prefixes of at least
1162
- eight characters:
1163
-
1164
- ```bash
1165
- npx @openai/codex-security publish scan \
1166
- --scan SCAN_ID_A --scan SCAN_ID_B \
1167
- --to cloud --dry-run --json
1168
- ```
1169
-
1170
- Find IDs with `scans list --json`, or use `--scan latest` for the current
1171
- repository's latest completed scan. You still need the local sealed artifacts.
1172
-
1173
- `--dry-run` checks inputs and prints findings without logging in or uploading.
1174
- Uploads need ChatGPT credentials saved to a file. Set this in Codex
1175
- `config.toml`, then sign in with ChatGPT again:
1176
-
1177
- ```toml
1178
- cli_auth_credentials_store = "file"
1179
- ```
1180
-
1181
- Cloud publication rejects automatic and keyring storage, even if an
1182
- `auth.json` file exists: the file may be stale or belong to another account.
1183
-
1184
- For CSV input, use an export from `codex-security export --export-format csv`:
1185
-
1186
- ```bash
1187
- npx @openai/codex-security publish scan --to cloud \
1188
- --csv /path/outside/repository/findings.csv
1189
- ```
1190
-
1191
- The [findings CSV template](https://github.com/openai/codex-security/blob/main/examples/findings.csv)
1192
- has the required columns; deep-scan exports may add `candidate_id`. `--csv`
1193
- only supports Cloud and cannot be combined with scan IDs or directories.
1194
-
1195
- For artifacts outside local history, pass a directory or repeat `--scan-dir PATH`.
1196
- Each directory must contain one completed, sealed scan. Bulk-run directories
1197
- and `results.jsonl` files aren't accepted. Don't mix directories with `--scan`.
1198
-
1199
- Multiple scans return:
1200
-
1201
- - `results`: receipts or dry-run previews, each with its `scanId` and `scanDir`.
1202
- - `failed`: errors with `scanDir` and, for saved selections, `scanId`.
1203
- - `notAttempted`: saved scan IDs, or paths for directory inputs, that the command
1204
- did not reach before cancellation.
1205
-
1206
- One scan returns its result directly. Uploads run sequentially. A failed upload
1207
- doesn't stop the rest, but the command exits with `2` if any failed. Cancellation
1208
- stops new requests and returns results so far with `130` (Ctrl-C) or `143`
1209
- (SIGTERM), unless all publications were already confirmed.
330
+ `preflight()` checks local inputs without starting Codex or using the network.
331
+ It does not verify credentials, model access, Python, or the plugin. The CLI
332
+ equivalent is `scan --dry-run`.
1210
333
 
1211
- Save the output: Cloud receipts aren't stored in scan history. They contain
1212
- Cloud finding IDs in request order, not local IDs. Uploads aren't retried
1213
- automatically. Cloud may have accepted an upload even if its receipt is missing
1214
- or invalid. Check Cloud before retrying; never resend a scan with a confirmed
1215
- receipt.
1216
-
1217
- ### Publish completed scans to Linear
1218
-
1219
- Linear publication accepts one completed scan:
1220
-
1221
- ```bash
1222
- npx @openai/codex-security publish scan --scan SCAN_ID \
1223
- --to linear \
1224
- --linear-team TEAM_ID
1225
- ```
1226
-
1227
- Choose a scan by ID, unique prefix, `latest`, or directory (positional or
1228
- `--scan-dir PATH`). Omit the selector for an interactive picker. Live publication
1229
- and `--skip-existing` require the scan in local history; a directory-based
1230
- `--dry-run` alone does not.
1231
-
1232
- Add `--linear-project PROJECT_ID` (`--project` is an alias) to place issues in
1233
- a project. Destination flags override `CODEX_SECURITY_LINEAR_TEAM` and
1234
- `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run` previews issue titles without
1235
- contacting Linear; `--json` returns structured results.
1236
-
1237
- Sign in to Codex and connect Linear to publish with your existing Codex
1238
- configuration; publication doesn't use the isolated scan home. To use the
1239
- Linear API directly, set a personal API key:
1240
-
1241
- ```bash
1242
- export CODEX_SECURITY_LINEAR_API_KEY=YOUR_LINEAR_PERSONAL_API_KEY
1243
- npx @openai/codex-security publish scan /path/to/completed-scan \
1244
- --to linear \
1245
- --linear-team TEAM_ID
1246
- ```
1247
-
1248
- Direct API publication leaves issues unassigned unless `--linear-assignee`
1249
- specifies a user ID or email. `--linear-api-key KEY` overrides the environment
1250
- variable, but exposes the key in shell history and process listings. Keys are
1251
- omitted from saved results and artifacts; error messages are returned unchanged.
1252
-
1253
- Check scan integrity and recorded publications before publishing:
1254
-
1255
- ```bash
1256
- npx @openai/codex-security publish check /path/to/completed-scan \
1257
- --to linear --linear-team TEAM_ID --json
1258
- ```
1259
-
1260
- `publish check` is read-only. With an API key it also checks authentication,
1261
- team, project, and assignee access; connected-app access is `not-checked`.
1262
- Issue-creation permission is always `not-tested`.
1263
-
1264
- Each finding becomes an issue titled `[Codex Security][HIGH] Finding title`
1265
- with source locations, code, evidence, and remediation. Choose a destination
1266
- authorized to receive these details. Local history stores successful issue IDs
1267
- separately from sealed scan artifacts.
1268
-
1269
- Republishing creates duplicates by default. `--skip-existing` skips recorded
1270
- successes for the same occurrence, team, and project, without checking remote
1271
- issues. Results distinguish `created` and `skipped` issues. Add `--dry-run`
1272
- to preview the remaining findings.
1273
-
1274
- After an interrupted or indeterminate publication, check the retained handoff,
1275
- evidence, and Linear destination before retrying. Issues may exist without a
1276
- local record. The CLI can't recover those issues, and `--skip-existing` can't
1277
- prevent duplicates from them or concurrent publications.
334
+ ### Configure deep scans
1278
335
 
1279
336
  ```ts
1280
- import { publishScan } from "@openai/codex-security";
1281
-
1282
- const publication = await publishScan("/path/to/completed-scan", {
1283
- destination: "linear",
1284
- teamId: "TEAM_ID",
337
+ const result = await security.run("/path/to/repository", {
338
+ mode: "deep",
339
+ workers: 2,
340
+ subagents: 0,
341
+ stopAfterNoNew: 3,
342
+ stopAfterConsecutiveErrors: 3,
343
+ maxDiscoveryRuns: 10,
344
+ maxTimeHours: 1.5,
1285
345
  });
1286
-
1287
- console.log(publication.scanId);
1288
- console.log(publication.created.length);
1289
- ```
1290
-
1291
- Options include `projectId`, `skipExisting`, `linearApiKey` for direct API
1292
- publication, and `assigneeId` (user ID or email). `checkScanPublication` accepts
1293
- the same destination options for a read-only check.
1294
-
1295
- ### Classify finding severity
1296
-
1297
- Classify findings after a scan or dedupe without repeating discovery or changing
1298
- the original severity, evidence, or sealed scan artifacts:
1299
-
1300
- ```bash
1301
- codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md --json
1302
- codex-security classify-severity --scan latest --rubric /path/to/policy.md --json
1303
- codex-security classify-severity --scan-dir /path/to/completed-scan --json
1304
346
  ```
1305
347
 
1306
- `--scan` accepts a saved scan ID, unique prefix, or `latest` for the current
1307
- repository, matching `dedupe` and `publish scan`. `--scan-dir` accepts an external
1308
- completed scan without requiring local history. Supply exactly one selector.
1309
- Omitting `--rubric` inherits each finding's existing severity without a model call.
1310
-
1311
- `--rubric PATH` supplies the classification policy. Repeat `--knowledge-base PATH`
1312
- to provide supporting architecture, deployment, or business context. Both accept
1313
- the same UTF-8 text, PDF, DOCX, and directory inputs as scan knowledge bases.
1314
- Rubric classification uses the full supplied report and context in a separate
1315
- read-only Codex turn per finding, without source inspection, tools, or new
1316
- validation. `--model` and `--effort` select the classification model and reasoning
1317
- effort; otherwise Codex's configured model and the helper's medium effort apply.
1318
-
1319
- The result contains one assessment per selected finding:
1320
-
1321
- - `decision`: `assessed` or `excluded`; policy exclusions do not become Low.
1322
- - `level`: `critical`, `high`, `medium`, `low`, or `informational`; null for exclusions.
1323
- - `rubricLabel`: the policy's original label, such as `URGENT`, normalized to
1324
- `critical`; null for inherited severity or exclusions.
1325
- - `rationale`, separate `confidence`, and `reviewTrigger` describing a missing
1326
- fact that would change the classification. Inherited severity has no new
1327
- classification-confidence judgment.
1328
- - `findingId`, `occurrenceId`, and `inputSha256` binding the assessment to the
1329
- report. Top-level metadata includes `assessedAt`, `rubricSha256`, and
1330
- `knowledgeBaseSha256` for the supplied policy and context snapshots.
1331
-
1332
- Scan classification saves each successful finding immediately in the local
1333
- workbench SQLite database. Rerunning skips assessments with matching finding
1334
- evidence, rubric, and knowledge-base hashes, including exclusions, and returns
1335
- both reused and newly generated assessments. Changed inputs are classified again.
1336
- Use `--reprocess` to rerun every selected finding regardless of its saved
1337
- assessment; each row is replaced only after its new assessment succeeds. A failed
1338
- or canceled run keeps completed checkpoints, so a normal retry resumes missing
1339
- work. Changing only the model or effort requires `--reprocess`.
1340
-
1341
- SQLite is authoritative. A successful run also exports the complete selected
1342
- result to `severity-classification.json` alongside the sealed artifacts. The file
1343
- is replaced atomically and is not read for reuse or publication. The scan's
1344
- original findings and severity are unchanged. The database stores the requested
1345
- selection and policy/context hashes; publication rejects an incomplete selection
1346
- or assessments whose inputs no longer match. Rubric documents are read at
1347
- classification time, not again at publication time.
348
+ `workers` controls concurrent discovery workers; `subagents` controls delegation
349
+ within each worker. Time and run limits apply to discovery. After discovery
350
+ stops, the scan combines and returns completed findings. See
351
+ [deep scan settings](docs/cli.md#configure-deep-scans) for defaults and saved settings.
1348
352
 
1349
- ```bash
1350
- codex-security classify-severity --scan latest --rubric /path/to/policy.md --reprocess
1351
- ```
1352
-
1353
- Use repeatable `--finding-id ID` to classify a selected set, such as the
1354
- `uniqueFindingIds` returned by dedupe. With a saved classification, Linear
1355
- publication defaults to that selection, omits excluded records, and uses assessed
1356
- severity for issue priority and title. The description retains original scan
1357
- severity and adds classification reasoning. Without a saved classification,
1358
- publication retains its existing severity mapping and selection behavior.
1359
- Publication rejects assessments whose IDs or evidence hashes no longer match.
1360
-
1361
- ```bash
1362
- codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
1363
- --finding-id FINDING_ID --json
1364
- codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
1365
- --dry-run --json
1366
- codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID \
1367
- --skip-existing --json
1368
- ```
353
+ ### Progress and cost
1369
354
 
1370
- `publish scan --to linear` also accepts repeatable `--finding-id ID` to select a
1371
- subset directly. If a classification exists, every explicitly selected finding
1372
- must have an assessment. Classification does not change existing Linear tickets;
1373
- `--skip-existing` preserves recorded tickets and any human priority edits. It
1374
- retains the existing limitations around unrecorded or concurrent publications.
355
+ Use `onProgress` for scan progress and `onCost` for cost updates.
1375
356
 
1376
- The SDK exposes the same operations:
357
+ Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
358
+ persisted worker sessions discovered by the SDK's existing session tracker,
359
+ independently of model-emitted status markers:
1377
360
 
1378
361
  ```ts
1379
- import {
1380
- classifySeverity,
1381
- classifyScanSeverity,
1382
- classifyScanDirectorySeverity,
1383
- publishScan,
1384
- } from "@openai/codex-security";
1385
-
1386
- // Supplied reports from any source: returns an assessment without writing files.
1387
- const classification = await classifySeverity(findings, {
1388
- rubricPath: "/path/to/policy.md",
1389
- knowledgeBasePaths: ["/path/to/context.md"],
1390
- });
1391
-
1392
- // Saved IDs (including prefixes/latest), or sealed directories; saves an assessment.
1393
- await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
1394
- await classifyScanDirectorySeverity(scanDirectory, {
1395
- rubricPath: "/path/to/policy.md",
1396
- findingIds: dedupeResult.uniqueFindingIds,
1397
- });
1398
-
1399
- await publishScan(scanDirectory, {
1400
- destination: "linear",
1401
- teamId: "TEAM_ID",
1402
- skipExisting: true,
1403
- });
1404
-
1405
- // Alternatively supply a classification directly, without a saved assessment.
1406
- await publishScan(scanDirectory, {
1407
- destination: "linear",
1408
- teamId: "TEAM_ID",
1409
- classification,
1410
- findingIds: classification.assessments.map(({ findingId }) => findingId),
1411
- dryRun: true,
362
+ await security.run(repository, {
363
+ onWorkerEvent(event) {
364
+ console.log(`Worker ${event.worker} observed`);
365
+ },
1412
366
  });
1413
367
  ```
1414
368
 
1415
- `classifySeverity` accepts reports with `findingId`, `title`, and `summary`, plus
1416
- their available evidence and metadata. Original `severity` and `occurrenceId`
1417
- may be absent for imported reports; reports without severity require a rubric.
1418
- `classifySeverity` remains an in-memory operation without database persistence.
1419
- The scan wrappers use the local state database (also for external scan
1420
- directories), accept `reprocess: true`, and accept `findingIds: []` as an
1421
- intentionally empty selection. Rows outside the selected set are retained.
1422
- Use the same `CODEX_SECURITY_STATE_DIR` for classification and publication.
1423
- JSON exports from versions without database checkpoints must be reclassified
1424
- once before they can be reused.
1425
- Pass `signal` to cancel any classification operation. Keep human overrides in the
1426
- calling workflow or issue tracker; assessments remain separate recommendations.
1427
-
1428
- ### Suggest finding owners
1429
-
1430
- Suggest contributors who can fix findings in a local Git repository:
369
+ The callback contains only `{ kind: "observed", worker: number }`. The scan-local
370
+ worker number matches `onActivity` and `onSessionEvent`; no prompts, raw thread
371
+ IDs, or session contents are exposed. Each session is reported once per run,
372
+ including nested workers and scan-associated validation or Deep Scan sessions.
373
+ On resume, already persisted workers can be reported again. Observation ends
374
+ with scan cost tracking, before `postScanPrompt`.
375
+
376
+ This works with the bundled Codex version. Persistence and polling can delay
377
+ notification, and missing notifications do not prove that delegation was skipped.
378
+ An observed session does not establish that a worker just started or that file
379
+ review has begun. The callback does not report failed spawn attempts, phase names,
380
+ or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
381
+ `signal` for cancellation. Observer failures go to `onObserverError` without
382
+ stopping the scan.
383
+
384
+ `onWorkerStatus` remains available for tool-derived preflight status and
385
+ **best-effort** phase dispatch counts from model-emitted text markers. A missing
386
+ dispatch status does not mean delegation was skipped. `onSessionEvent` receives
387
+ saved events with thread IDs and worker numbers and can contain source code or
388
+ credentials. Deep scans additionally expose durable independent-review counts
389
+ through `onDeepProgress`: `completed`, `active`, and `maximum`. The maximum is a
390
+ configured cap, not a percentage denominator. The optional `consolidating` flag
391
+ reports when results are being combined or the coordinator has finished.
392
+ `ScanOptions` lists all callbacks.
1431
393
 
1432
- ```bash
1433
- npx @openai/codex-security suggest-owners findings.json --source-root /path/to/repo --json > owners.json
1434
- ```
394
+ Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
395
+ allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
396
+ short-context estimate; in-flight requests can exceed it. Post-scan prompts run
397
+ outside that limit. Matching earlier findings can also make model calls.
398
+ See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.
1435
399
 
1436
- The input is a Codex Security findings document or a JSON object containing a
1437
- `findings` array, such as the output of `export --export-format json`. The source
1438
- root defaults to the current directory. The command reads committed `HEAD`,
1439
- source around each finding location, blame for the affected lines, and file
1440
- history reachable from that commit. It does not read uncommitted source or change
1441
- findings, files, or ticket assignments.
1442
-
1443
- The checkout must own its Git references and objects. Linked worktrees and bound
1444
- separate Git directories are supported. Checkouts that borrow external object
1445
- stores, including `git clone --shared`, are rejected; use an independent clone.
1446
-
1447
- Each result preserves the finding and occurrence IDs and has status `identified`,
1448
- `abstained`, or `error`. Identified results include an observed Git author name
1449
- and email, a reason, and checked Git citations. Missing source or unclear
1450
- ownership produces an abstention. Git identities do not establish active
1451
- employment or an issue tracker account. Match accounts before assigning tickets.
1452
- Use a checkout that matches the findings; otherwise their line ranges may be stale.
1453
-
1454
- The command uses existing Codex credentials and the Codex Security default model and effort.
1455
- Use `--model` and `--effort` to override them. Model selection runs with tools and
1456
- network access disabled. Exit code `0` includes successful recommendations and
1457
- abstentions; `2` means invalid input or at least one failed recommendation. A
1458
- per-finding failure retains the other results in the report. Cancellation uses
1459
- exit code `130` for SIGINT or `143` for SIGTERM.
1460
-
1461
- The SDK accepts finding IDs, titles, summaries, and source locations directly:
400
+ ### Validate an existing finding
1462
401
 
1463
402
  ```ts
1464
- import { suggestOwners } from "@openai/codex-security";
1465
-
1466
- const owners = await suggestOwners("/path/to/repo", result.findings, {
1467
- reasoningEffort: "high",
403
+ import { writeFile } from "node:fs/promises";
404
+
405
+ const result = await security.validate({
406
+ repositoryPath: "/path/to/repository",
407
+ finding: {
408
+ title: "Possible SQL injection",
409
+ location: "src/query.ts:42",
410
+ },
1468
411
  });
412
+ console.log(result.disposition, result.report);
413
+ await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
1469
414
  ```
1470
415
 
1471
- SDK inputs may include `sourceRevision`. If it differs from `HEAD`, the collector
1472
- ignores the old line ranges and reports the mismatch. Reports record the analyzed
1473
- revision, model, effort, and limitations; they remain separate from scan artifacts.
416
+ Pass finding text or a JSON-serializable object, not a file path. Standalone
417
+ validation uses source evidence in a read-only, offline session. It does not build
418
+ the target, execute application code, run tests or PoCs, or add a scan to history.
419
+ The validator returns the assessment without writing report files. The example
420
+ saves `result.report` in an existing directory. `outputDir` selects the session
421
+ directory, not a report destination. Callers that previously read reports from it
422
+ must save `result.report` instead.
423
+ Callers needing runtime proof must arrange a separate reproduction step. Standard,
424
+ Deep, and diff scan validation keep their existing workflows.
1474
425
 
1475
- ### Feedback
426
+ The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
427
+ `reportable` can rely on static analysis; `deferred` means there is insufficient
428
+ evidence. Failed or malformed responses reject the promise. `outputDir`, `auth`,
429
+ and `signal` are also supported.
1476
430
 
1477
- Send a problem report to OpenAI and share the returned feedback ID with support:
431
+ To validate GitHub code scanning alerts, first import them with
432
+ `importGitHubCodeScanningAlerts()`. See the
433
+ [import guide](docs/cli.md#import-alerts-from-the-cli) for CLI and SDK examples.
1478
434
 
1479
- ```sh
1480
- codex-security feedback --reason "The scan stopped before it finished"
1481
- codex-security feedback SCAN_ID --reason "The scan stopped before it finished" --include-logs
1482
- ```
435
+ ### Generate and verify a patch
1483
436
 
1484
- Without an ID, `feedback` selects the most recently started scan in the current
1485
- repository, including active or failed scans. If there are no saved scans, it sends
1486
- a general report. The report includes your description, version details, and the selected
1487
- scan and session IDs. Add `--json` for structured output.
1488
-
1489
- Logs are off by default. `--include-logs` uploads Codex diagnostics and saved scan
1490
- and worker activity. These can contain source code, prompts, findings, tool
1491
- output, and other sensitive data. Only include logs you can share with OpenAI.
1492
- The command uses Codex's feedback service and respects `feedback.enabled = false`.
1493
-
1494
- For scans started through the Desktop plugin, run the command on the machine
1495
- where the scan ran, using the same Codex home and Codex Security state directory.
1496
- It searches active and archived sessions in both that Codex home and the CLI's
1497
- managed home, and attaches available worker logs even if the parent log is missing.
1498
- Earlier retries that started separate sessions may be missing when their session
1499
- IDs are no longer recorded.
1500
-
1501
- Standard scans run inside an existing Codex conversation attach only the owner's
1502
- saved session; they do not record which subagents belong to the scan. Deep Scans
1503
- and scans launched by `codex-security` also attach their recorded execution
1504
- threads and descendants, without following unrelated children of the owner.
1505
-
1506
- ### Scan history and reruns
1507
-
1508
- Commands default to the current repository. Select scans by full ID or a
1509
- unique prefix of at least eight characters.
1510
-
1511
- New recipes retain resolved settings and the authentication choice, not
1512
- credentials. Reruns do not reload project files; complete saved deep settings do
1513
- not use current legacy defaults. Older partial recipes retain their previous
1514
- fallback behavior. Context paths and the current checkout are not immutable input
1515
- snapshots.
1516
-
1517
- Reruns require replacement scan instructions when the original scan used them.
1518
- New recipes mark this requirement, and `scans rerun` refuses to omit them silently; use
1519
- `scans rerun [SCAN_ID] --scan-prompt-file FILE` to supply a nonempty replacement.
1520
- Replacement files resolve from the invocation directory. Custom validation keeps its existing
1521
- `scans rerun --validation-prompt-file` requirement.
1522
-
1523
- | Command | Purpose |
1524
- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
1525
- | `scans list [REPOSITORY]` | List scans. Filter by artifact root with `--scan-root DIR`. |
1526
- | `scans show [SCAN_ID]` | Show a scan; defaults to the latest completed one. `--show-linked-findings` includes earlier finding links. |
1527
- | `scans logs [SCAN_ID]` | Show session events; defaults to the latest scan, including active scans. |
1528
- | `scans resume SCAN_ID` | Resume an interrupted Deep Scan in its original session and output directory. |
1529
- | `scans rerun [SCAN_ID]` | Repeat a scan on the current checkout; defaults to the latest completed scan. |
1530
- | `scans match BEFORE AFTER` | Link findings with the same root cause. |
1531
- | `scans match --all` | Match completed scans across the repository's worktrees and clones. |
1532
- | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to the latest two completed scans. |
1533
- | `findings list [REPOSITORY]` | List open findings. `findings` is an alias. |
1534
- | `findings false-positive OCCURRENCE_ID --reason TEXT` | Mark a false positive. Later scans dismiss matches only while the reason applies. |
1535
-
1536
- #### Resuming an interrupted Deep Scan
1537
-
1538
- After the CLI process or host stops unexpectedly, find the scan and rejoin it:
1539
-
1540
- ```bash
1541
- npx @openai/codex-security scans list --scan-root /path/to/security-scans
1542
- npx @openai/codex-security scans resume SCAN_ID
1543
- ```
1544
-
1545
- The scan must still be `running`, with its original checkout, output directory,
1546
- and owning Codex session available in the same Codex Security state directory.
1547
- The checkout's identity, revision, and contents must match the saved target.
1548
- Completed, failed, and canceled scans cannot resume; `scans rerun` starts a new scan.
1549
-
1550
- Resume uses the saved configuration and instructions with the installed plugin.
1551
- New scans save the selected authentication mode, explicit safety identifier, and
1552
- post-scan prompt contents. Resume restores the authentication choice without
1553
- saving credentials. Single-scan resume restores the prompt even if its original
1554
- file changes or disappears.
1555
- Older records that did not save these values cannot reconstruct them. Bulk
1556
- recovery still requires matching campaign inputs and options; it uses the supplied
1557
- post-scan prompt when the scan has no saved prompt.
1558
- It keeps the scan ID, completed workers, artifacts, and accumulated session cost.
1559
- The existing coordinator recovers interrupted workers after its lease expires.
1560
- If discovery finished before the interruption, resume completes and seals the
1561
- same scan. No archiving or new attempt directory is needed. A failed connection
1562
- leaves the existing scan available for another resume attempt.
1563
-
1564
- Compatible saved scans can resume after a plugin update. Already-sealed results
1565
- keep their original producer version and contents when completion is recorded.
1566
- Unsupported or invalid sealed artifacts are rejected before resuming, preserving
1567
- the saved scan state and files.
1568
-
1569
- For bulk campaigns, use [`bulk-scan --recover`](#recovering-failed-or-interrupted-bulk-scans)
1570
- to recover eligible attempts and update `results.jsonl`. Individual `scans resume`
1571
- does not update campaign receipts.
1572
-
1573
- #### Matching saved scans
1574
-
1575
- Matching requires sealed artifacts and reuses saved matches unless you pass
1576
- `--force`. Comparisons classify findings as new, persisting, reopened, resolved,
1577
- or unknown. Missing findings aren't resolved if the later scan is incomplete
1578
- or excludes their original scope. With one ID, `scans compare` compares it
1579
- to the latest completed scan.
1580
-
1581
- Use `scans match --all --force` to rebuild comparisons chronologically while
1582
- retaining stable finding identities. Ctrl-C keeps comparisons already saved.
1583
- Only high-confidence duplicates are grouped; uncertain and independently
1584
- related findings stay separate. Matching preserves triage and sealed artifacts.
1585
-
1586
- Codex is called only when a new decision is needed, using existing authentication.
1587
- Scans without sealed artifacts are skipped, but their confirmed links can still
1588
- be reused. Older custom plugins save confirmed and uncertain matches; use the
1589
- bundled plugin for related links and large comparisons.
1590
-
1591
- SDK callers can compare findings without saving a workbench comparison:
437
+ `patch()` runs the bundled remediation workflow non-interactively against a
438
+ workspace that the caller has intentionally made writable:
1592
439
 
1593
440
  ```ts
1594
- import { readFile } from "node:fs/promises";
1595
- import {
1596
- matchScanFindings,
1597
- type FindingsDocument,
1598
- } from "@openai/codex-security";
1599
-
1600
- const before = JSON.parse(
1601
- await readFile("/path/to/earlier-scan/findings.json", "utf8"),
1602
- ) as FindingsDocument;
1603
- const after = JSON.parse(
1604
- await readFile("/path/to/later-scan/findings.json", "utf8"),
1605
- ) as FindingsDocument;
1606
-
1607
- const comparison = await matchScanFindings(
1608
- { before: before.findings, after: after.findings },
1609
- { workingDirectory: "/path/to/repository" },
1610
- );
1611
- console.log(comparison.matches, comparison.uncertain, comparison.related ?? []);
1612
- ```
1613
-
1614
- Pass `knownFindingGroups` to reuse confirmed groups of stable `findingId` values
1615
- from your store. Results identify the original `occurrenceId` values. Options
1616
- include model, reasoning effort, `AbortSignal`, and an optional `onProgress`
1617
- callback whose errors do not interrupt matching.
1618
-
1619
- History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
1620
- `$CODEX_HOME/state/plugins/codex-security/workbench.sqlite3`. The CLI and
1621
- workbench maintain the database and its journal files as the current user.
1622
- Keep state private, writable, and outside the scanned repository.
1623
-
1624
- On Windows, an older sandboxed run can leave an invalid credential-home ancestor
1625
- ACL. Preserve that state and its reports, and select a **new**, private
1626
- `CODEX_SECURITY_STATE_DIR` outside both the old state and the repository.
1627
- Sign in again if needed and keep using the new setting; it starts separate scan
1628
- history. Existing ancestor ACLs are not rewritten.
1629
-
1630
- Scan configurations don't store credentials; session logs and live details can
1631
- contain them. Press `d` during a scan for details, then `a` for all sources,
1632
- `m` for the main scan, or `1` through `9` for a worker.
1633
-
1634
- ### Exports and CI
1635
-
1636
- `export` writes CSV, JSON, or SARIF from a completed, sealed scan, defaulting to
1637
- the current repository's latest completed scan. It doesn't start Codex or load
1638
- credentials. Use `--output -` for stdout and `--source-root PATH` to add SARIF
1639
- source-line fingerprints. `export --help` lists all options.
1640
-
1641
- JSON preserves the sealed findings document. CSV marks findings as open,
1642
- omits local triage state, and cannot go to stdout when JSON output is requested.
1643
-
1644
- For CI, save output outside the checkout and set a severity threshold:
1645
-
1646
- ```bash
1647
- SCAN_ROOT="$(mktemp -d)"
1648
- npx @openai/codex-security scan . \
1649
- --diff origin/main \
1650
- --output-dir "$SCAN_ROOT/results" \
1651
- --json \
1652
- --fail-on-severity high > "$SCAN_ROOT/findings.json"
1653
- ```
1654
-
1655
- Scan exit codes are `0` for a completed report-only scan or passing policy,
1656
- `1` for a policy violation, `2` for invalid input, incomplete coverage, or a
1657
- runtime/export error, `130` for interruption, and `143` for termination.
1658
- JSON scans do not use interactive controls. `validate`, `login`, and `logout`
1659
- reject `--json`.
1660
-
1661
- `install-hook` adds an optional local Git pre-commit check for staged and
1662
- unstaged changes. It's advisory; use a required CI check to enforce a passing
1663
- scan. When Git runs the hook, it blocks commits if the scan can't finish or
1664
- finds an issue at or above the threshold (`high` by default). Set it when
1665
- installing with `--fail-on-severity`. The installer respects `core.hooksPath`
1666
- and leaves custom hooks alone.
1667
-
1668
- We recommend installing the CLI outside the repository and running that copy
1669
- directly. For a global installation:
1670
-
1671
- ```bash
1672
- npm install --global @openai/codex-security
1673
- ```
1674
-
1675
- If the repository also has a local copy, `npx` may run it instead.
1676
-
1677
- Before installing or replacing a hook, run
1678
- `git -C /path/to/repository rev-parse --git-path hooks/pre-commit`. Git may
1679
- return a path relative to `/path/to/repository`. Check the hook, if it exists,
1680
- and the path to its directory for symlinks or shared locations. Leave custom,
1681
- linked, shared, or unverified hooks alone. If they need to change, contact the
1682
- owner or use a required CI check. Check older generated hooks too; the installer
1683
- can update them automatically.
1684
-
1685
- If the hooks directory belongs only to this repository and there is no hook,
1686
- run the global CLI from outside the repository:
1687
-
1688
- ```bash
1689
- codex-security install-hook /path/to/repository
1690
- ```
1691
-
1692
- To migrate a hook, confirm it's a regular file used only by this repository
1693
- and contains only the generated Codex Security command. Keep its severity.
1694
- The installer can update older hooks that invoke `npx` if you use the same
1695
- severity. Newer hooks store absolute paths to Node and the CLI. If either path
1696
- changes, the installer won't replace the hook: back it up, remove it, and rerun
1697
- `codex-security install-hook /path/to/repository` with the same
1698
- `--fail-on-severity` value (default: `high`). If reinstallation fails, restore
1699
- the backup and verify the hook before relying on it.
1700
-
1701
- ### Import alerts from the CLI
1702
-
1703
- `import github OWNER/REPO` reads open code scanning alerts from the default
1704
- branch. Repeat `--github-alert NUMBER` for exact alerts. Filter with
1705
- `--github-state open|closed|dismissed|fixed|all` or select a reference with
1706
- `--github-ref REF`. Authentication follows the
1707
- [SDK import options](#import-github-code-scanning-alerts).
1708
-
1709
- ```bash
1710
- # Import all open alerts, or a selected subset, as complete JSON.
1711
- npx @openai/codex-security import github example/repository --format json \
1712
- > /path/outside/repository/github-alerts.json
1713
- npx @openai/codex-security import github example/repository \
1714
- --github-alert 12 --github-alert 18 --format json
1715
- # Run from the corresponding local repository; imported contents are data.
1716
- npx @openai/codex-security validate /path/outside/repository/github-alerts.json
1717
- ```
1718
-
1719
- Import is read-only and returns an array (`[]` when empty). `--json` aliases
1720
- `--format json`. Save validation inputs without output filters or token limits.
1721
- Use the SDK loop for a disposition per alert.
1722
-
1723
- ### Validate and patch findings
1724
-
1725
- `validate` assesses candidates; `patch` fixes and verifies them. Both accept
1726
- files or literal text and work in the current directory. Pass a saved finding
1727
- or occurrence ID to `patch` to use its original repository.
1728
-
1729
- Add `--validation-prompt-file PATH` to supply custom dynamic validation
1730
- instructions, using the same UTF-8 prompt file format as `scan`. The patch task
1731
- uses these instructions to set up the environment, build or start the application,
1732
- exercise the fix, check legitimate behavior, and clean up. Include the commands,
1733
- authorized targets, expected results, and cleanup steps for your environment.
1734
- The task must report validation evidence or explain which checks failed or could
1735
- not run before claiming the patch is fixed or verified.
1736
-
1737
- ```bash
1738
- npx @openai/codex-security patch OCCURRENCE_ID --validation-prompt-file validation.md
1739
- npx @openai/codex-security patch issues.md --validation-prompt-file validation.md
1740
- ```
1741
-
1742
- The flag works with saved findings, issue text/files, and Linear inputs. Relative
1743
- prompt paths resolve from the directory where you invoke the CLI, including when
1744
- the saved finding belongs to another repository. The file is read once before
1745
- patching; missing, empty, or non-regular files fail before the patch task starts.
1746
- Without the flag, the usual fix-finding verification applies. The flag does not
1747
- change sandbox permissions and cannot be combined with `--resume-pr`.
1748
-
1749
- Add `--assess-patch-risk` to a `patch` command to run the bundled patch-risk
1750
- assessment skill once on the completed patch. The assessment is advisory and
1751
- does not change the patch or its merge state. Human-readable commands print the
1752
- report after the patch results; saved-finding JSON output returns it as
1753
- `patchRisk.report` in the same result object. When combined with `--create-pr`,
1754
- the draft pull request or merge request body includes only the concise Markdown
1755
- summary from the assessment; the validated JSON remains in the command result.
1756
-
1757
- ```bash
1758
- npx @openai/codex-security validate "Possible SQL injection" --effort high
1759
- npx @openai/codex-security patch OCCURRENCE_ID
1760
- npx @openai/codex-security patch --scan SCAN_ID --severity high --json
1761
- npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
1762
- npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
1763
- npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
1764
- ```
1765
-
1766
- `--scan latest` selects the current repository's latest scan. Patch commands
1767
- support `--json`, including literal-text and file inputs. Change
1768
- the model with `--codex 'model="gpt-5.6-sol"'` or effort with `--effort high`.
1769
- Each finding gets its own saved Codex desktop task.
1770
-
1771
- Before patching, the CLI runs a command with the task's sandbox policy. If the
1772
- sandbox cannot start, the command exits with a nonzero status and reports
1773
- `SANDBOX_UNAVAILABLE`. JSON errors include `ok: false`. A completed model response
1774
- with no repository changes fails with `NO_PATCH_APPLIED`. Results report `applied`,
1775
- `filesChanged`, and `files`; existing local changes do not count as patch changes.
1776
- These fields report file changes, not proof that the security issue is fixed.
1777
- Saved findings still require a verified result from the patch task.
1778
-
1779
- For a controlled container that provides its own isolation, explicitly opt in:
1780
-
1781
- ```bash
1782
- npx @openai/codex-security patch "Security issue" --external-sandbox --json
1783
- ```
1784
-
1785
- `--external-sandbox` defaults to false. It uses Codex's external-sandbox policy
1786
- and prints a warning: Codex does not enforce filesystem or network isolation for
1787
- the patch task. The container must enforce those boundaries. The CLI never
1788
- falls back to this mode automatically. Optional patch-risk assessment still uses
1789
- its read-only Codex sandbox.
1790
-
1791
- `scan --patch` patches after a complete scan. `--patch-severity` defaults to
1792
- `low`; `high` selects high and critical findings. Use the interactive browser
1793
- to select findings and add patch instructions. Results include a `patches`
1794
- entry per finding with status `verified`, `no_change`, `blocked`, or `failed`.
1795
- Verified and already-fixed findings no longer fail `--fail-on-severity`.
1796
- Patching shows each finding's position, elapsed time, and live Codex activity.
1797
- Progress goes to stderr; completed results stay in the terminal history.
1798
-
1799
- `--create-pr` commits generated patch files and opens a draft GitHub pull request
1800
- with `gh` or a draft GitLab merge request with `glab`. Install and authenticate
1801
- the appropriate CLI first (`gh auth login` or `glab auth login`). GitLab.com is
1802
- selected from the `origin` push URL, including SSH URLs and subgroup projects.
1803
- For self-hosted GitLab, set `GITLAB_HOST` to the host in that URL and authenticate
1804
- with `glab auth login --hostname HOST`. The existing `GITLAB_URI` and `GL_HOST`
1805
- aliases are also accepted, in that order after `GITLAB_HOST`. Other hosts retain
1806
- the GitHub workflow.
441
+ const security = new CodexSecurity();
442
+ try {
443
+ const result = await security.patch({
444
+ repositoryPath: "/path/to/disposable/workspace",
445
+ finding: {
446
+ title: "Possible SQL injection",
447
+ summary: "User input reaches a raw SQL query.",
448
+ locations: [{ path: "src/query.ts", startLine: 42 }],
449
+ },
450
+ signal,
451
+ onActivity(activity) {
452
+ console.log(activity.description);
453
+ },
454
+ onCost(cost) {
455
+ console.log(cost.estimatedUsd);
456
+ },
457
+ });
1807
458
 
1808
- ```bash
1809
- GITLAB_HOST=gitlab.example.com npx @openai/codex-security patch --scan SCAN_ID --create-pr
459
+ switch (result.status) {
460
+ case "verified":
461
+ case "no_change":
462
+ console.log(result.verificationReport);
463
+ break;
464
+ case "blocked":
465
+ case "failed":
466
+ console.error(result.reason);
467
+ break;
468
+ }
469
+ } finally {
470
+ await security.close();
471
+ }
1810
472
  ```
1811
473
 
1812
- Both providers use the existing `pullRequest: { branch, url }` JSON result.
1813
- Supplied-issue requests require a clean working tree before patching so
1814
- existing work is never included. If publication fails, run the printed
1815
- `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
1816
- commit without rerunning Codex, but refuses to publish if the branch changed.
1817
- Use the same GitLab host setting when resuming a self-hosted merge request.
1818
-
1819
- To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
1820
- `--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
1821
- Completed and canceled issues are excluded unless the filter sets `state`.
1822
- Use `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for an API key, or
1823
- `LINEAR_ACCESS_TOKEN` for OAuth. `--linear-api-key KEY` overrides these; prefer
1824
- environment variables to keep keys out of shell history. Intake is read-only,
1825
- includes comments, and keeps Linear credentials out of the patch subprocess.
1826
- Issue URLs must match the selected workspace.
1827
-
1828
- ### Verify fixes
1829
-
1830
- `verify-fix` checks fixes in a read-only sandbox. Pass a description, saved
1831
- finding ID, `--scan SCAN_ID`, `--linear-issue ISSUE`, or `--linear-project "PROJECT"`.
1832
- Linear credentials and filters work as for `patch`. To check a finished backlog,
1833
- explicitly filter for completed issues.
474
+ Pass literal finding text or a JSON-serializable object; strings are never read
475
+ as file paths. Sandboxed patch commands may edit only `repositoryPath` and run
476
+ without network access or web search. Patch workspaces are always treated as
477
+ untrusted Codex projects, so repository-local Codex configuration and MCP
478
+ servers are not loaded. Host-configured tools retain their host permissions.
479
+ The method does not create a commit, push, open a pull request, publish findings,
480
+ change remote finding state, or add a scan to history.
481
+ Callers remain responsible for reviewing and deriving the authoritative diff,
482
+ approval, commit creation, and delivery.
483
+
484
+ The discriminated result reports `verified`, `no_change`, `blocked`, or
485
+ `failed`, plus repository-relative `changedFiles`, `threadId`, and estimated
486
+ `cost` when model pricing and usage are available. Verified and no-change
487
+ results include `verificationReport`; blocked and failed results include
488
+ `reason`. Transport, authentication, cancellation, incomplete turns, and
489
+ malformed results reject the promise. Failed, blocked, or interrupted operations
490
+ can leave partial workspace changes for the caller to inspect or discard.
491
+
492
+ `changedFiles` is model-reported metadata, not the authoritative diff.
493
+ Patch-risk assessment is not included in this API.
494
+
495
+ Patch operations reuse constructor configuration and credentials. Pass `auth`,
496
+ `safetyIdentifier`, `model`, or `reasoningEffort` for per-call selection.
497
+ `onActivity`, `onSessionEvent`, `onCost`, `onReconnect`, `onAuthentication`,
498
+ `onWarning`, and `onObserverError` use the same observer contracts as scans.
1834
499
 
1835
- Results include evidence and a status: `fixed`, `still_vulnerable`, or
1836
- `inconclusive`. Use `--json` for structured output. Exit codes are `0` if all
1837
- findings are fixed, `1` if any remain vulnerable, and `2` if verification is
1838
- inconclusive or couldn't finish.
1839
-
1840
- ### Command discovery and integrations
1841
-
1842
- The CLI uses [Incur](https://github.com/wevm/incur). Use `--llms` for the
1843
- command manifest, `scan --schema --format json` for a command schema, and
1844
- `completions bash|zsh|fish` for shell completions. Scan output supports
1845
- `--format toon|json|yaml|jsonl` and `--full-output`.
1846
-
1847
- `skills add` syncs agent skills; `mcp add` registers the CLI as an MCP server.
1848
- MCP exposes only the read-only `info` command because the transport cannot
1849
- cancel active scans.
1850
-
1851
- ## Findings service (preview)
1852
-
1853
- The findings API uses the same `ghcr.io/openai/codex-security` image as the
1854
- scanner, for Linux `amd64` and `arm64`. `compose.findings.yaml` starts the API
1855
- in a separate container with its own state volume and server configuration.
1856
- Once a release is published, it can be pulled without a GitHub login. See
1857
- [container release setup](../../docker/README.md) for the required maintainer
1858
- setup and publication process.
500
+ ## CLI
1859
501
 
1860
- From the repository root, copy the example if you do not already have a `.env`:
502
+ After [installing the CLI](#install-the-cli), sign in if needed:
1861
503
 
1862
504
  ```bash
1863
- cp .env.example .env
505
+ cs login
1864
506
  ```
1865
507
 
1866
- Set `OPENAI_API_KEY` in `.env`, then pull and start the findings API:
508
+ From your repository, optionally [draft a `SECURITY.md`](#generate-a-security-policy)
509
+ that explains what counts as a security issue in your project:
1867
510
 
1868
511
  ```bash
1869
- docker compose -f compose.findings.yaml pull
1870
- docker compose -f compose.findings.yaml up --no-build -d
1871
- curl -i http://127.0.0.1:3000/v1/findings
512
+ cs policy .
1872
513
  ```
1873
514
 
1874
- You can deploy with just `compose.findings.yaml` and a private `.env`; no source
1875
- checkout or Node.js installation is required. `CODEX_SECURITY_FINDINGS_IMAGE`
1876
- defaults to `ghcr.io/openai/codex-security:latest`. Set it to a published
1877
- version, `sha-<commit>` tag, or digest for repeatable deployments.
515
+ The draft is saved outside your repository. Review the diff and notes, edit the
516
+ draft, then copy only `SECURITY.md` to the **Policy target** shown. Skip this step
517
+ to keep your current policy or scan without one.
1878
518
 
1879
- To build from a source checkout, first prepare the
1880
- [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
1881
- for that checkout. Then run from the repository root:
519
+ Then scan the repository:
1882
520
 
1883
521
  ```bash
1884
- docker build --target scanner -t codex-security:local .
1885
- export CODEX_SECURITY_FINDINGS_IMAGE=codex-security:local
1886
- docker compose -f compose.findings.yaml up --no-build -d
522
+ cs scan .
1887
523
  ```
1888
524
 
1889
- For an existing deployment using the separate findings image or
1890
- `--target findings-service`, follow the [single-image migration guide](../../docker/README.md#migrating-the-findings-service).
1891
-
1892
- ### Read-only dashboard
1893
-
1894
- Open `http://localhost:3000/dashboard` on the running findings service. The UI
1895
- uses the public OpenAI Apps SDK UI design system, follows the browser's light
1896
- or dark preference, and polls the service every five seconds. It never starts,
1897
- cancels, resumes, publishes, edits, or deduplicates anything.
1898
-
1899
- The dashboard opens on Findings, followed by Duplicate groups. Both views
1900
- support search, repository filtering, sorting, pagination, and record details.
1901
- Click any column header to sort all matching records; click it again to reverse
1902
- the order. The arrow marks the active column and direction. Changing the sort
1903
- returns to the first page, and automatic refreshes keep the selected order.
1904
- By default, findings sort by last update descending, then severity descending,
1905
- then ID ascending to break ties. Groups sort by last update descending and ID
1906
- ascending.
1907
- Findings show stored content and links to their duplicate groups. Groups link
1908
- back to their member findings, preserving separate overlapping groups and the
1909
- original finding records.
1910
-
1911
- The dashboard reads only findings, repository associations, and duplicate groups
1912
- stored in the service's configured database. It does not display scans or
1913
- workflows: publication sends findings, not remote scan or workflow history. It
1914
- does not read report or source paths from stored records. The UI retains the last
1915
- successful data on a refresh failure and shows a connection warning until polling
1916
- succeeds.
1917
-
1918
- `GET /v1/dashboard` returns a consistent read snapshot with overview counts,
1919
- repository choices, a page of records, and optional selected-record details:
1920
-
1921
- - `view`: `findings` (default) or `groups`.
1922
- - `query`, `repository`: optional search text and exact repository ID.
1923
- - `sort`: `activity` (default; last update), `newest` (created), `title`,
1924
- `repository`, `severity` (findings only), or `members` (groups only).
1925
- - `direction`: `asc` or `desc` (default). Text sorts alphabetically without
1926
- case sensitivity, severity by level, and member counts numerically.
1927
- - `limit`, `offset`: existing pagination conventions, defaulting to 50 and 0.
1928
- - `id`: optional exact record ID to include in `detail`; unknown IDs return
1929
- `detail: null` without hiding the list.
1930
-
1931
- Overview counts are service-wide, not filtered page totals. Responses and UI
1932
- assets are served by the same Node process; no separate frontend server, CDN,
1933
- model credentials, or new CLI flags are needed to view the dashboard. Compiled
1934
- HTML, JavaScript, and CSS are included in the npm package and container. Frontend
1935
- source, build tools, and tests are not shipped as runtime dependencies.
1936
-
1937
- The existing preview access boundary is unchanged. The dashboard contains
1938
- sensitive finding content: keep the service on a trusted local endpoint or behind
1939
- an authenticated proxy. It does not add authentication or broaden the default
1940
- network binding.
1941
-
1942
- ### API
1943
-
1944
- `POST /v1/bulk/findings` accepts `{"findings": [...]}`, using the existing SDK
1945
- `Finding` model, including `findingId`, `occurrenceId`, and `fingerprints`.
1946
- A complete exported `findings.json` document is also accepted; only its
1947
- `findings` array is imported. No files or source paths referenced by the
1948
- findings are opened. Only the supplied JSON is processed.
1949
-
1950
- Include `repositoryId` alongside `findings` to associate every imported finding
1951
- with a repository. For SDK/CLI scans, use `scan.target.targetId` from the sealed
1952
- `scan-manifest.json`. IDs are matched exactly; the service does not infer a
1953
- repository from titles, paths, or URLs. Reimports add associations without
1954
- removing earlier ones, so a finding can belong to more than one repository.
1955
- Imports without this metadata remain accepted, but unassociated findings are
1956
- only available to explicit all-repository retrieval until imported with an ID.
1957
-
1958
- | Method | Path | Response |
1959
- | ------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
1960
- | `POST` | `/v1/bulk/findings` | HTTP 201 with an array of stored finding IDs, in request order |
1961
- | `GET` | `/v1/findings?limit=50&offset=0` | HTTP 200 with a page of complete findings |
1962
- | `GET` | `/v1/finding/{id}/potential-duplicates` | HTTP 200 with the stored finding and up to 50 potential duplicates, without vectors |
1963
- | `POST` | `/v1/dedupe-groups` | HTTP 201 with the persisted duplicate groups |
1964
- | `GET` | `/v1/finding/{id}/dedupe-groups` | HTTP 200 with every stored group containing this finding |
1965
-
1966
- Bulk insertion generates embeddings and then writes the findings and vectors
1967
- in one SQLite transaction. If embedding generation fails or a finding identity
1968
- conflicts with another stored identity, no part of the batch is written.
1969
- Reusing a `findingId` updates that finding and replaces its embedding; retries
1970
- do not create extra rows. An existing ID's fingerprint, rule, and identity
1971
- anchor/instance cannot be replaced. Repeated IDs in one request are applied in order,
1972
- with the last supplied record retained. Stored scan occurrences are unchanged.
1973
-
1974
- For example, add `repositoryId` to a copy of an exported findings document
1975
- saved as `findings-import.json` (leave the sealed scan artifacts unchanged),
1976
- then import it with the API key configured before starting Compose:
525
+ To narrow the scan scope or check the configuration before scanning:
1977
526
 
1978
527
  ```bash
1979
- curl http://127.0.0.1:3000/v1/bulk/findings \
1980
- -H 'Content-Type: application/json' \
1981
- --data-binary @findings-import.json
1982
- ```
1983
-
1984
- ```json
1985
- ["csf_852f90d6e1177502ff113d4a"]
1986
- ```
1987
-
1988
- The potential-duplicates response contains `finding` (the complete stored
1989
- anchor) and `potentialDuplicates` (an array of complete `Finding` records).
1990
- Neither includes embedding vectors. The anchor is not repeated in the array.
1991
- Specify one scope explicitly on the request:
1992
-
1993
- ```text
1994
- GET /v1/finding/{id}/potential-duplicates?repositoryId=target_sha256_example
1995
- GET /v1/finding/{id}/potential-duplicates?allRepositories=true
528
+ cs scan . --path src --path tests
529
+ cs scan . --diff origin/main --json
530
+ cs scan . --dry-run
1996
531
  ```
1997
532
 
1998
- Repository scope requires the anchor and each candidate to be associated with
1999
- that repository. All-repository scope includes tagged and untagged findings.
2000
- Omitting scope or combining a repository with `allRepositories=true` returns
2001
- HTTP 400. Scope selects candidates; it is not an authorization boundary.
533
+ Use `--help` to find commands and `<command> --help` for options. Scans are
534
+ report-only by default. Add `--fail-on-severity high` to return exit code `1`
535
+ for high or critical findings; execution and required-output failures return `2`.
536
+ Scope exclusions and follow-up notes do not change a completed scan's exit code.
2002
537
 
2003
- Candidates have cosine similarity at least 0.55 and the same embedding model
2004
- and dimensions as the anchor. They are ordered by descending similarity, with
2005
- ties resolved by insertion time and finding ID, and limited to 50. Each request
2006
- reads a current snapshot; separate requests do not share a database snapshot.
2007
- SQLite first filters repository associations, reads only IDs and embedding
2008
- vectors (plus the anchor's model), and performs exact cosine ranking. It then
2009
- loads complete documents only for the anchor and the selected top 50 candidates,
2010
- all within the same read transaction.
2011
- The API does not run Codex or decide whether candidates are duplicates.
538
+ The [CLI reference](docs/cli.md) covers scan history, reruns, bulk and component
539
+ scans, custom validation, imports, patching, and integrations.
2012
540
 
2013
- ### Publishing to a custom findings service
541
+ ### Generate a security policy
2014
542
 
2015
- Publish a completed scan directly from the local CLI to the Docker service:
543
+ Use `policy` to draft a new `SECURITY.md` or update an existing one. To select a
544
+ component:
2016
545
 
2017
546
  ```bash
2018
- codex-security publish scan --scan SCAN_ID --to custom \
2019
- --findings-url http://localhost:3000 --json
547
+ cs policy . --path services/api
2020
548
  ```
2021
549
 
2022
- `--findings-url` is required for `--to custom`, with no default. It is the
2023
- service base URL, including `http://` or `https://`; the client appends
2024
- `/v1/bulk/findings`, preserving any base path. A different endpoint must
2025
- implement that API and return the stored finding IDs. The command sends the
2026
- complete sealed findings and their manifest's `scan.target.targetId` as
2027
- `repositoryId`, without changing scan artifacts or forwarding model credentials.
2028
- The service creates embeddings and commits the batch before acknowledging it.
2029
-
2030
- The existing saved-scan selector, external `--scan-dir`, and interactive picker
2031
- work with custom publication. Custom publication accepts one scan, not CSV
2032
- input or Linear options. Add `--dry-run` to validate and preview the payload
2033
- without making an HTTP request. Existing Linear and Cloud destinations are
2034
- unchanged. Upload failures and incomplete receipts fail the command; uploads
2035
- are not automatically retried because a lost response may have been committed.
2036
-
2037
- ```typescript
2038
- import { publishScanToCustom } from "@openai/codex-security";
2039
-
2040
- const receipt = await publishScanToCustom("/path/to/completed-scan", {
2041
- findingsUrl: "http://localhost:3000",
2042
- // dryRun: true,
2043
- // signal: controller.signal,
2044
- });
2045
- console.log(receipt.repositoryId, receipt.findingIds);
2046
- ```
2047
-
2048
- ### Deduplication from the SDK and CLI
2049
-
2050
- Publish the scan with `--to custom` (or import it through the bulk API with its
2051
- `repositoryId`) before deduplicating. The
2052
- workflow reads a completed saved scan, queries candidates by finding ID, and
2053
- runs Luna and Sol in the calling SDK/CLI process. Once all reviews finish,
2054
- it posts accepted groups to the service. It does not re-upload findings or
2055
- change scan artifacts.
2056
-
2057
- ```bash
2058
- codex-security dedupe --scan SCAN_ID --findings-url http://127.0.0.1:3000 --json
2059
- ```
2060
-
2061
- Deduplication runs up to 8 jobs concurrently by default. Set `--concurrency N`
2062
- to choose a positive integer, or `--concurrency 1` for serial execution. The SDK
2063
- equivalent is `concurrency: N`. Candidate neighborhoods are fetched first, with
2064
- the same concurrency limit. Luna screenings and ready Sol pair reviews then use
2065
- two queues sharing one worker pool, with at most 8 jobs running in total by
2066
- default. Each available worker takes a ready job as soon as its current job
2067
- finishes; it does not wait for a batch to finish.
2068
-
2069
- A Sol pair review becomes ready once every Luna screening covering that pair
2070
- has finished and none voted `DISTINCT`. It can run while unrelated Luna
2071
- screenings continue. Results are combined in input order so completion timing
2072
- does not change the groups.
2073
-
2074
- An explicit model refusal keeps the affected pairs separate and allows unrelated
2075
- reviews to continue. It is recorded as `NO_DECISION`, not a reviewed `DISTINCT`
2076
- verdict. A screening refusal applies to every anchor/candidate pair in that
2077
- screening; a pair-review refusal applies only to its assigned pair. Neither pair
2078
- can be merged indirectly through other findings. Recognized policy errors and
2079
- explicit refusal responses are not retried or sent to another model.
2080
-
2081
- If another kind of job fails after its retries, queued jobs stop and already running jobs
2082
- finish before the command reports the failure. No groups are posted from an
2083
- incomplete review. To retain completed reviews across runs, use a
2084
- `--workflow-id` as described below.
2085
-
2086
- The default scope is the saved scan's repository, identified by
2087
- `scan.target.targetId` in its manifest. Add `--all-repositories` to search the
2088
- entire stored corpus explicitly; the flag defaults to false. The SDK has the
2089
- equivalent optional `allRepositories: true` setting. This narrows the previous
2090
- preview's implicit all-repository behavior.
2091
-
2092
- Provide `--findings-url` and either `--scan` or `--workflow-id`, with no implicit
2093
- scan or service URL. As with `publish scan --scan`, the scan selector accepts a full ID, unique
2094
- prefix, or `latest` for the current repository. The saved scan must be complete
2095
- and its sealed artifacts must be available.
2096
-
2097
- ```typescript
2098
- import { deduplicateScan } from "@openai/codex-security";
2099
-
2100
- const result = await deduplicateScan("scan_example_001", {
2101
- findingsUrl: "http://127.0.0.1:3000",
2102
- // concurrency: 8, // Shared worker limit for Luna and Sol; use 1 for serial.
2103
- // allRepositories: true, // Omit to search only this scan's repository.
2104
- // signal: controller.signal,
2105
- });
2106
- console.log(result.duplicateGroups);
2107
- ```
2108
-
2109
- For a complete, sealed scan directory that is not registered in local scan
2110
- history, provide the repository checkout separately:
2111
-
2112
- ```typescript
2113
- import { deduplicateScanDirectory } from "@openai/codex-security";
2114
-
2115
- const result = await deduplicateScanDirectory("/path/to/completed-scan", {
2116
- repository: "/path/to/repository",
2117
- findingsUrl: "http://127.0.0.1:3000",
2118
- // concurrency: 8,
2119
- // expectedScanId: "scan_example_001",
2120
- // allRepositories: true,
2121
- // signal: controller.signal,
2122
- });
2123
- console.log(result.duplicateGroups);
2124
- ```
2125
-
2126
- The CLI and SDK return the same result:
2127
-
2128
- ```json
2129
- {
2130
- "scanId": "scan_example_001",
2131
- "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
2132
- "duplicateGroups": [],
2133
- "deduplicationStatus": "completed"
2134
- }
2135
- ```
2136
-
2137
- `uniqueFindingIds` contains one representative for each selected finding after
2138
- accepted duplicate groups are collapsed. A representative can be an existing
2139
- stored finding outside the scan. Each `duplicateGroups` entry contains all
2140
- members of an accepted group, with its canonical finding first. The canonical
2141
- has the highest reported severity; ties use finding ID. Results do not delete,
2142
- merge, or change stored finding documents. Accepted groups are saved as durable
2143
- associations in the service before `deduplicationStatus` becomes `completed`.
2144
-
2145
- When any review is refused, the result instead has
2146
- `deduplicationStatus: "completed_with_refusals"` and a `refusals` array. Each
2147
- entry contains `decision: "NO_DECISION"`, `stage`, `model`, `findingIds`, and
2148
- `reason`. For screening, the first finding ID is the anchor and the remaining
2149
- IDs are its candidates. The CLI logs each refusal to stderr and exits
2150
- successfully after saving the accepted groups. SDK callers can inspect and log
2151
- the same structured entries. Findings retained because of a refusal are not
2152
- confirmed unique. Successful runs without refusals keep their existing output
2153
- shape. No command, flag, or default changes are required.
2154
-
2155
- This behavior applies to post-scan Luna/Sol deduplication. Deep Scan's internal
2156
- reducer uses a separate workflow.
2157
-
2158
- ### Host-provided records deduplication
2159
-
2160
- `codex-security dedupe --records` accepts a versioned JSON-RPC run over stdin
2161
- and emits serial `review.run` requests on stdout for a host-provided model
2162
- backend. It requires no saved scan or Findings API and performs no local model
2163
- execution or persistence. The SDK exposes `deduplicateRecords(input,
2164
- { reviewRunner, signal })`. The input contains original observations and explicit candidate links. Results
2165
- contain groups of observation IDs and unresolved observations.
2166
-
2167
- See the [records protocol and Python fake-host example](docs/dedupe-records.md)
2168
- for the complete input, review contract, cancellation, and persistence rules.
2169
-
2170
- ### Stored duplicate groups
2171
-
2172
- `POST /v1/dedupe-groups` accepts a batch of explicitly reviewed member sets:
2173
-
2174
- ```json
2175
- {
2176
- "groups": [
2177
- ["csf_000000000000000000000001", "csf_000000000000000000000002"],
2178
- ["csf_000000000000000000000002", "csf_000000000000000000000003"]
2179
- ]
2180
- }
2181
- ```
2182
-
2183
- Each group must contain at least two distinct, existing finding IDs. The entire
2184
- batch is committed in one transaction; a missing finding returns HTTP 409 and
2185
- writes none of the batch. A response contains `groupId`, `findingIds`, and
2186
- `createdAt` for each group. Group identity depends on membership, not member
2187
- order, so submitting the same set again returns its original ID and timestamp.
2188
-
2189
- SQLite stores groups in `finding_dedupe_groups` and memberships in
2190
- `finding_dedupe_group_members`. A finding may belong to multiple groups:
2191
- `[A, B]`, `[B, C]`, and `[C, A]` are three separate reviewed sets. Overlapping
2192
- groups are not automatically united or promoted into an unreviewed larger
2193
- group. Stored members are sorted by ID; their order does not designate a
2194
- canonical. The CLI result retains its existing canonical-first ordering.
2195
-
2196
- `GET /v1/finding/{id}/dedupe-groups` returns every group containing that finding,
2197
- including each group's full membership, or `[]` if it has no groups. These
2198
- associations do not rewrite original findings, fingerprints, scan artifacts,
2199
- embeddings, or external tickets. They do not require an embedding API key or
2200
- trigger model calls. Review-generated merged findings remain review outputs;
2201
- they do not replace stored documents.
2202
-
2203
- ### Resuming a local findings workflow
2204
-
2205
- Add `--workflow-id` to opt into durable state shared by `scan`, `publish scan
2206
- --to custom`, and `dedupe`. The SDK equivalents are the optional `workflowId`
2207
- fields on `ScanOptions`, `PublishScanToCustomOptions`, and `DeduplicateScanOptions`.
2208
- Without a workflow ID, existing command behavior and output shapes are unchanged.
550
+ Existing files stay unchanged until you review and copy the draft to the
551
+ **Policy target** shown. Scans already use root and component policies; you can
552
+ keep them without generating new ones.
2209
553
 
2210
- ```bash
2211
- codex-security scan /path/to/repository --workflow-id run-001
2212
- codex-security publish scan --workflow-id run-001 --to custom --findings-url http://localhost:3000
2213
- codex-security dedupe --workflow-id run-001 --findings-url http://localhost:3000 --json
2214
- ```
554
+ The SDK provides `generatePolicy()`, `preflightPolicy()`, and `previewPolicy()`. See
555
+ [policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,
556
+ policy locations and reporting instructions, headless use, and saved artifacts.
2215
557
 
2216
- Repeat this sequence with the same ID after a process stops. Completed scans and
2217
- acknowledged publications are reused; unfinished stages run again. If the scan
2218
- completed before the workflow recorded its receipt, recovery verifies the saved
2219
- scan and its sealed artifacts instead of scanning again. Scan IDs and artifact
2220
- locations are recorded in the scan-registration transaction. This resumes between
2221
- completed steps; it does not resume individual model turns inside an unfinished
2222
- scan. Existing output-directory and archive safeguards still apply to scan retries.
2223
-
2224
- Publication and dedupe can use the workflow ID in place of `--scan`; an explicit
2225
- scan selector must identify that same scan. A workflow can also begin at custom
2226
- publication of a completed scan. The CLI and `deduplicateScan` require local scan
2227
- history to locate the approved source checkout; `deduplicateScanDirectory` uses
2228
- the supplied repository. For a workflow, dedupe first completes publication
2229
- if its receipt is missing. `--all-repositories` retains its existing default of
2230
- false. Changing a workflow's scan, destination, or bound scope is an error: choose
2231
- a different workflow ID. Use one coordinating process per workflow.
2232
-
2233
- Workflow metadata, stage statuses, errors, publication receipts, and results live
2234
- in the local workbench SQLite database under `CODEX_SECURITY_STATE_DIR`, outside
2235
- the sealed scan artifacts. Identity, scan/artifact references, destination, scope,
2236
- hashes, stage statuses, and errors use explicit columns; only receipts and result
2237
- payloads use JSON. Review source, scope, model settings, and contract/hash bindings
2238
- also use columns; review results remain JSON. Existing workflows and checkpoints
2239
- are migrated atomically in place without changing their review keys.
2240
- Successful empty results are stored as completed
2241
- results, not treated as missing work. An empty scan can complete workflow
2242
- publication with an empty receipt. Dry-run never advances a workflow stage.
2243
-
2244
- A completed `dedupe --workflow-id` returns its saved result without repeating
2245
- reviews or group writes. A publication whose acknowledgement was lost is retried
2246
- using the service's existing idempotent upsert.
2247
-
2248
- Concurrent jobs save their validated reviews independently. Resuming with the
2249
- same workflow ID reuses completed reviews and retries unfinished jobs. The
2250
- concurrency setting is not part of a review's checkpoint identity, so it is safe
2251
- to change `--concurrency` when resuming. Cancellation stops active reviews and
2252
- leaves their completed checkpoints available for the next run.
2253
-
2254
- Each validated screening and pair review is checkpointed locally,
2255
- including DISTINCT decisions. Screening checkpoints retain pair recommendations
2256
- and rationales under host-assigned pair slots bound to the original records.
2257
- Every SAME pair-review checkpoint retains its
2258
- required `canonicalFindingId` and generated `mergedFinding`; the merged record
2259
- must satisfy the Finding schema and preserve the canonical finding ID. Validation
2260
- still happens through `review_validator.submit_decisions`; invalid submissions
2261
- are corrected in the same review conversation. A completed turn without an
2262
- accepted submission receives one corrective turn in that same conversation.
2263
- If formatting remains invalid, the job retries in a fresh review session.
2264
- Explicit transient Codex failures and unexpected process exits also retry, with
2265
- at most three fresh sessions per review. Transient findings-service failures, including
2266
- rate limits and network errors, receive up to three request attempts. Retries use
2267
- exponential backoff with jitter; HTTP retries honor `Retry-After`. Waiting to retry
2268
- occupies the job's concurrency slot.
2269
-
2270
- Cancellation, authentication or configuration errors, permanent HTTP errors, and
2271
- required-source-access blockers are not retried. Model refusals continue with
2272
- `NO_DECISION` as described above. Other exhausted retries fail deduplication;
2273
- invalid or unfinished reviews are not cached. Completed checkpoints remain
2274
- available when the workflow resumes.
2275
-
2276
- Refusals are not saved as validated review checkpoints. A completed workflow
2277
- retains its final `completed_with_refusals` result, including all refusal entries,
2278
- and returns it on subsequent calls. To attempt those reviews again after
2279
- resolving the refusal, run dedupe without that workflow ID or with a new one.
2280
-
2281
- Checkpoints bind to the exact original records and ordering, approved source path,
2282
- Git revision and current file contents (including ignored files), repository scope,
2283
- model and reasoning settings, Codex configuration and version, and prompt/contract version. Changed
2284
- inputs cause a new review rather than reusing a decision. Source changes during
2285
- review stop that attempt before group writes; restart with the same ID to review
2286
- the changed source. Original findings, never prior rationales or merged findings,
2287
- are supplied to later independent reviews. Source snapshots do not follow directory
2288
- links outside the approved checkout.
2289
-
2290
- Before posting groups, the workflow saves the exact final result and write payload.
2291
- If posting fails or its acknowledgement is lost, rerunning dedupe replays that
2292
- payload without looking up candidates or running models. Group persistence reuses
2293
- the existing membership identity, so replay does not create another group. The
2294
- dedupe stage completes only after acknowledgement. Empty results are also retained.
2295
- A completed workflow or pending write represents its already reviewed snapshot;
2296
- use another workflow ID for a fresh review rather than changing that saved result.
2297
-
2298
- ### Deduplication workflow
2299
-
2300
- 1. For each distinct finding ID in the scan, request
2301
- `/v1/finding/{id}/potential-duplicates` with the selected repository or
2302
- explicit all-repository scope. Use the complete stored anchor and
2303
- candidates returned by that request. Fetch all neighborhoods before starting
2304
- reviews so every pair's screening dependencies are known.
2305
- 2. Screen each nonempty neighborhood with `gpt-5.6-luna` at `xhigh` reasoning
2306
- effort. The review covers every anchor-neighbor pair; nominations between
2307
- neighbors are rejected.
2308
- 3. Independently review each nominated pair once with `gpt-5.6-sol` at `high`
2309
- reasoning effort after all Luna screenings covering that pair finish without
2310
- a `DISTINCT` decision. Luna and ready Sol jobs share the configured worker
2311
- pool and can run together. Only accepted pairs contribute to duplicate groups.
2312
- 4. Group accepted duplicate pairs transitively unless a Luna or Sol `DISTINCT`
2313
- decision contradicts the resulting component. Contradicted components are
2314
- split deterministically, preferring legal subgroups that preserve more
2315
- accepted-pair support. There is no additional whole-group review.
2316
- 5. Post all accepted groups to `/v1/dedupe-groups`. Return a completed result
2317
- only after the service accepts the write. An empty result requires no write.
2318
-
2319
- Each review uses a fresh, ephemeral Codex app-server thread with the complete
2320
- original finding records, not earlier model rationales, vector scores, or
2321
- summaries. Reviews can inspect source in the saved scan's local checkout,
2322
- starting with cited paths and revisions. Source inspection establishes duplicate
2323
- identity and shared remediation. Reviews preserve the originals' severity and
2324
- priority metadata without reassessment or normalization. The baseline
2325
- filesystem profile is read-only and excludes credentials
2326
- and Codex state. Screening denies approval requests; final reviews use Codex's
2327
- automatic approval reviewer. Web, plugins, and inherited MCP servers are disabled.
2328
- Finding content never authorizes access to another target.
2329
-
2330
- Pair reviews cover exactly the two supplied findings. Linked parent tickets,
2331
- duplicate targets, and related-ticket records are metadata, not additional
2332
- findings to fetch or prerequisites for a verdict. An unsupplied duplicate target
2333
- is neither automatically canonical nor an error; source-code investigation for
2334
- the supplied pair remains allowed.
2335
-
2336
- Incomplete supplied finding content can produce `DISTINCT` with the limitation
2337
- explained. An execution, tool, or source-access blocker that prevents a required
2338
- check instead uses `review_validator.submit_error` with a nonempty `reason`.
2339
- That submission fails the review without a verdict or review checkpoint, so it
2340
- cannot become a `DISTINCT` veto or a completed duplicate-group result. A failed
2341
- optional lookup does not force failure or `DISTINCT` when other evidence suffices.
2342
-
2343
- Decisions must arrive through the direct `review_validator.submit_decisions`
2344
- tool; invalid submissions can be corrected in the same session. A final text
2345
- answer alone is insufficient. Luna screening returns a `SAME` or `DISTINCT`
2346
- decision and rationale under each required host-assigned slot (`pair-1`,
2347
- `pair-2`, and so on). The host binds each slot to its corresponding
2348
- anchor-neighbor pair, so the model does not submit finding IDs. Luna does not
2349
- select a canonical or generate a merged finding. Every
2350
- Sol `SAME` decision requires an assigned `canonicalFindingId` and
2351
- a generated, inclusive `mergedFinding`; missing or null values are rejected.
2352
- Sol reviews use only the complete originals, never earlier model rationales or
2353
- merged findings. These review fields do not change the command's ID-only result
2354
- or stored findings.
2355
-
2356
- Non-cancellation review failures throw `DeduplicationReviewError`. Its `metadata`
2357
- contains only the review stage, model, failure category, attempt count, and a
2358
- sanitized reason for diagnostics or an external support bundle; it does not
2359
- contain findings, prompts, paths, thread IDs, or credentials.
2360
-
2361
- If a completed turn has no accepted submission, whether it ended with text only
2362
- or after rejected submissions, the runner sends one corrective instruction in
2363
- the same conversation. This preserves the original assignment, source work, and
2364
- tool feedback. Reviews are limited to two turns; `metadata.attempts` counts
2365
- those turns (or the initial attempt if setup fails). Accepted results are not
2366
- replayed. Cancellation, accepted `submit_error` reports, and model or transport
2367
- failures remain terminal.
2368
-
2369
- The SDK does not retain private review transcripts, subprocess stderr, or full
2370
- provider/RPC error payloads, and ephemeral review state is removed after the
2371
- session. The public metadata is a limited diagnostic summary, not a complete
2372
- troubleshooting trace; it intentionally omits the original error cause. Private
2373
- diagnostic retention is not currently implemented.
2374
-
2375
- Model calls run sequentially on the SDK/CLI host using its Codex sign-in or
2376
- `OPENAI_API_KEY`/`CODEX_API_KEY`, with access to the configured models. Model
2377
- credentials are not sent to the findings API. Larger scans can take time and
2378
- incur multiple model calls per finding. Empty scans and findings without
2379
- eligible neighbors do not invoke review models. `completed` means this
2380
- retrieval, review, and group persistence completed, not that every possible pair in the
2381
- database was compared or that model decisions are infallible. An API, review, or write-back
2382
- failure fails the command without claiming a completed result. Retry after
2383
- fixing the failure; stored findings remain unchanged. A lost write-back response
2384
- may have committed groups; retrying the same memberships does not duplicate
2385
- them. Failed or interrupted reviews write no groups. The CLI supports Ctrl-C
2386
- and SIGTERM, and the SDK accepts an `AbortSignal`.
2387
-
2388
- ### Listing and errors
2389
-
2390
- Listing defaults to `limit=50` and `offset=0`; `limit` must be a positive
2391
- integer and `offset` a non-negative integer. Records are ordered by their first
2392
- insertion time, then finding ID. Follow `nextOffset` until it is `null`:
2393
-
2394
- ```json
2395
- {
2396
- "findings": [],
2397
- "limit": 50,
2398
- "offset": 0,
2399
- "total": 0,
2400
- "nextOffset": null
2401
- }
2402
- ```
558
+ ### Exports and CI
2403
559
 
2404
- The list includes API imports and complete finding documents from existing CLI
2405
- scan history. It returns the latest stored document for each finding ID,
2406
- without embedding vectors. Legacy identities without a complete document are
2407
- not included. Pagination reflects current database contents, not a snapshot
2408
- held between HTTP requests.
2409
-
2410
- Malformed JSON, invalid finding objects, repository metadata, groups, scopes, and pagination return HTTP
2411
- 400 (`invalid_request`). Identity conflicts or missing dedupe group members return 409 (`finding_conflict`),
2412
- embedding provider failures or unusable vectors return 502 (`embedding_failed`),
2413
- and missing embedding credentials return 503 (`embedding_unavailable`). A
2414
- potential-duplicates query without a current embedding returns 404
2415
- (`finding_not_indexed`), including findings outside the requested repository or
2416
- whose embedding was invalidated by an update; import the finding with the
2417
- matching `repositoryId` before retrying. This is an error, not an
2418
- empty candidate list. Unknown routes return 404 (`not_found`); unexpected
2419
- server failures return 500 (`internal_error`). Errors have an `error` code and,
2420
- for expected failures, a `message`. Request bodies and provider error bodies
2421
- are not logged.
2422
-
2423
- ### Embeddings and storage
2424
-
2425
- Set `OPENAI_API_KEY` in the repository-root `.env`, using `.env.example` as a
2426
- template, or export `OPENAI_API_KEY` or `CODEX_API_KEY` in the host environment.
2427
- Compose passes the key to the service; exported values override `.env` values.
2428
- The `.env` file is excluded from Git and Docker builds. `OPENAI_API_KEY` takes
2429
- precedence over `CODEX_API_KEY`; remove the `OPENAI_API_KEY` entry if using
2430
- `CODEX_API_KEY` instead. Listing and empty imports do not require a key.
2431
- A Codex ChatGPT login is not an embedding API credential.
2432
-
2433
- Set `CODEX_SECURITY_EMBEDDINGS_URL` to override the full embeddings endpoint URL,
2434
- including its path and any query parameters. Unset or empty values use
2435
- `https://api.openai.com/v1/embeddings`. Export it before `codex-security serve`,
2436
- or set it in `.env` for Docker Compose, which passes it to the service. For example:
560
+ Export saved findings or a threat model without starting another analysis:
2437
561
 
2438
562
  ```bash
2439
- CODEX_SECURITY_EMBEDDINGS_URL=https://embeddings.example.com/v1/embeddings codex-security serve
563
+ cs export --scan SCAN_ID --export-format sarif --output results.sarif
564
+ cs export --scan SCAN_ID --artifact threat-model --output threatmodel.md
2440
565
  ```
2441
566
 
2442
- The configured endpoint receives the finding inputs and the API key as a bearer
2443
- token and must support the same OpenAI embeddings request and response format.
2444
-
2445
- The service calls the OpenAI embeddings API with `text-embedding-3-large` and
2446
- 1,536 dimensions. The complete finding JSON is tokenized using `js-tiktoken`'s
2447
- bundled `cl100k_base` encoding. Long inputs are split without truncation;
2448
- their vectors are combined by token weight and normalized. Requests respect
2449
- the provider's 8,192-token input, 300,000-token request, and 2,048-input limits.
2450
- See the [embedding API contract](https://developers.openai.com/api/reference/resources/embeddings/methods/create).
2451
-
2452
- Storage initializes before the server listens. The SQLite adapter reuses the
2453
- bundled workbench's schema and migrations at
2454
- `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`. An append-only migration adds
2455
- complete finding documents and an embedding table, while retaining the existing
2456
- finding identity table and scan history. Both the API and current CLI indexing
2457
- use the same finding upsert operation. Changing a stored document invalidates
2458
- its old embedding so later matching cannot use a stale vector. Historical
2459
- findings are not automatically embedded; submit them to a bulk endpoint first.
2460
-
2461
- The `findings-state` named volume persists `/state`, including the database,
2462
- across container replacements. Keep the same Compose project name to reuse it.
2463
- The image runs as UID/GID `10001:10001`; a bind mount must be writable by that
2464
- UID/GID if used instead of the named volume.
2465
-
2466
- Stop the service with
2467
- `docker compose -f compose.findings.yaml down`; add `--volumes` only when you
2468
- intend to delete the stored data.
2469
-
2470
- The findings Compose configuration sets `HOST=0.0.0.0`, `PORT=3000`, and
2471
- `CODEX_SECURITY_STATE_DIR=/state`. Keep port and volume mappings aligned if
2472
- changing these settings. Compose binds only to host loopback; the API has no
2473
- authentication. Use an authenticated TLS proxy before sharing access. Finding
2474
- JSON is sent to the configured embeddings endpoint (`api.openai.com` over HTTPS
2475
- by default); the database and generated embeddings stay in the local volume.
2476
-
2477
- ### Upgrades and backups
2478
-
2479
- Read the release notes and stop the service before backing up the entire
2480
- `/state` directory. For the published-image Compose configuration:
567
+ The SDK provides `exportArtifact()` for the same offline operations. See
568
+ [exports and CI](docs/cli.md#exports-and-ci) for details. For repository or pull
569
+ request scans in GitHub Actions, use the
570
+ [GitHub Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md).
571
+ Separate examples cover
572
+ [GitHub Actions with Bedrock](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md)
573
+ and [Azure Pipelines](https://github.com/openai/codex-security/blob/main/examples/azure-pipelines/README.md).
2481
574
 
2482
- ```bash
2483
- docker compose -f compose.findings.yaml stop findings
2484
- mkdir -p backups
2485
- chmod 700 backups
2486
- docker compose -f compose.findings.yaml run --rm --no-deps --user 0:0 \
2487
- --entrypoint tar -T findings -C /state -czf - . > backups/findings-state.tgz
2488
- chmod 600 backups/findings-state.tgz
2489
- ```
575
+ ### Classify finding severity
2490
576
 
2491
- Keep backups separately; this command overwrites an existing backup of the same
2492
- name. Set `CODEX_SECURITY_FINDINGS_IMAGE` to the new version or digest and repeat
2493
- the pull/start commands above, retaining the volume. Startup applies SQLite
2494
- migrations automatically. To roll back, stop the service, restore the pre-upgrade
2495
- backup, and select the previous image digest; an older image may not support the
2496
- migrated database.
577
+ Use `classify-severity` with your own rubric to assess saved findings without
578
+ changing their original severity or evidence. The SDK exposes `classifySeverity()`,
579
+ `classifyScanSeverity()`, and `classifyScanDirectorySeverity()`. See
580
+ [severity classification](docs/cli.md#classify-finding-severity) for selection,
581
+ checkpointing, and publication behavior.
2497
582
 
2498
- ### Running without Docker
583
+ ### Suggest finding owners
2499
584
 
2500
- With Node.js and Python 3 installed:
585
+ Use `suggest-owners` or the SDK's `suggestOwners()` to suggest contributors based
586
+ on CODEOWNERS, source, and Git history. Declared owners take priority over Git
587
+ contributors. Suggestions do not assign tickets. See
588
+ [owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.
2501
589
 
2502
- ```bash
2503
- npm install -g @openai/codex-security
2504
- CODEX_SECURITY_STATE_DIR="$HOME/.codex-security-findings" codex-security serve --port 3000
2505
- ```
590
+ ### Publish findings to Cloud
2506
591
 
2507
- `--port` overrides `PORT` (default: `3000`). Open
2508
- `http://127.0.0.1:3000/dashboard`. Stop with Ctrl+C or SIGTERM.
592
+ `publish scan --to cloud` uploads selected findings to Codex Security Cloud.
593
+ It requires ChatGPT credentials; inference API keys and AWS credentials do not
594
+ grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-cloud)
595
+ for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
596
+ for issue creation.
2509
597
 
2510
- Export `OPENAI_API_KEY` or `CODEX_API_KEY` to import findings with embeddings.
2511
- Startup and listing need no key. The service does not load `.env` or authenticate
2512
- requests; keep it on loopback or behind an authenticated TLS proxy.
598
+ ## Findings storage and deduplication
2513
599
 
2514
- For a source build, first prepare the
2515
- [universal native payload](../../plugins/codex-security/native/README.md#package-inputs)
2516
- for that checkout. Then run from its `sdk/typescript` directory:
600
+ Saved-scan deduplication uses local SQLite directly:
2517
601
 
2518
602
  ```bash
2519
- pnpm install --frozen-lockfile
2520
- pnpm --dir ../../plugins/codex-security/mcp-app install --frozen-lockfile
2521
- pnpm run build:plugin
2522
- pnpm run build
2523
- node bin/codex-security.mjs serve --port 3000
603
+ cs dedupe --scan SCAN_ID --json
2524
604
  ```
2525
605
 
2526
- `pnpm run start:server` and `node dist/server/index.js` still work.
2527
-
2528
- Local defaults are `HOST=127.0.0.1` and `PORT=3000`. The existing
2529
- `CODEX_SECURITY_STATE_DIR` and `PYTHON` settings select storage and Python;
2530
- without a state override, the service uses the same default state directory as
2531
- the CLI. These settings also work on Windows.
2532
-
2533
- HTTP routing, orchestration, embedding generation, and the SQLite adapter live
2534
- separately under `src/server/`. `FindingsService` receives a `FindingEmbedder`
2535
- whose `embed(findings)` method returns one `{ model, vector }` per finding in
2536
- input order. `OpenAiFindingEmbedder` handles tokenization, batching, API calls,
2537
- and vector normalization; it does not access storage. The `FindingsStore`
2538
- interface stores findings and vectors and exposes
2539
- `findPotentialDuplicates(findingId, scope)`. Repository filtering, vector ranking,
2540
- and fetching selected documents stay inside the store implementation; replacing
2541
- SQLite with an indexed store does not change the service or SDK/CLI. Repository
2542
- associations are stored separately from finding documents, with an append-only
2543
- migration that also imports known associations from stored scan occurrences.
2544
- New scan findings retain their target associations when indexed locally.
2545
- The server entrypoint selects the concrete
2546
- embedder and store, so either can be replaced independently.
2547
-
2548
- For renewable embeddings credentials, import `OpenAiFindingEmbedder`,
2549
- `SqliteFindingsStore`, and `startFindingsServer` from
2550
- `@openai/codex-security/server`. The embedder's first argument accepts a static
2551
- key or `() => string | Promise<string>`. It calls the callback before every
2552
- HTTP batch, including subsequent calls to `embed`; callers own token acquisition.
2553
- Pass `fetch` as the second argument and
2554
- `process.env.CODEX_SECURITY_EMBEDDINGS_URL || undefined` as the third to use
2555
- the same full endpoint URL and default as `codex-security serve`. Importing the
2556
- server API does not start a listener.
2557
-
2558
- The local workflow lives under `src/deduplication/`. `FindingDeduplicator`
2559
- receives a candidate API client and a `DeduplicationReviewer`, keeping grouping
2560
- separate from HTTP and model transport. `CodexDeduplicationReviewer` owns prompts
2561
- and result validation; `CodexReviewRunner` owns app-server sessions and cleanup.
2562
- `deduplicateScan` validates saved scan artifacts before running the workflow;
2563
- `deduplicateScanDirectory` performs the same validation for an explicit sealed
2564
- scan directory without consulting local scan history.
2565
- The SDK reuses the existing Codex runtime and credentials without additional
2566
- runtime dependencies.
606
+ The [findings guide](docs/findings-service.md) covers local storage, embedding
607
+ credentials, deduplication, backups, and independently operated HTTP endpoints.
608
+ The local `serve` command and browser dashboard have been removed. Existing
609
+ scans, findings, and duplicate groups remain in the workbench database.
610
+ For records stored in your own system, see
611
+ [SDK records deduplication](docs/dedupe-records.md).
2567
612
 
2568
613
  ## Containerized bulk scans
2569
614
 
2570
- Create `repositories.csv` as described under [Bulk scans](#bulk-scans).
2571
- With a published image, run from the Codex Security repository root:
2572
-
2573
- ```bash
2574
- mkdir -p results state
2575
- chmod 700 results state
2576
- export CODEX_SECURITY_USER="$(id -u):$(id -g)"
2577
- export CODEX_SECURITY_IMAGE=ghcr.io/openai/codex-security:latest
2578
- docker compose pull codex-security
2579
- docker compose run --rm codex-security login --device-auth
2580
- docker compose run --rm codex-security
2581
- ```
2582
-
2583
- Results go to `results/`; device login stays in `state/`. For unattended scans,
2584
- set `OPENAI_API_KEY` or `CODEX_API_KEY`. Private GitHub checkouts use `GH_TOKEN`
2585
- or `GITHUB_TOKEN`; GitHub Enterprise uses `CODEX_SECURITY_GIT_HOST`. The container
2586
- requires CSV input, without interactive discovery.
2587
-
2588
- Compose accepts `CODEX_SECURITY_IMAGE`, `CODEX_SECURITY_USER`,
2589
- `CODEX_SECURITY_SECCOMP`, `CODEX_SECURITY_CSV`, `CODEX_SECURITY_RESULTS`, and
2590
- `CODEX_SECURITY_STATE` for the image, user, seccomp profile, and mounts.
2591
-
2592
- Codex 0.156.1 requires Bubblewrap for filesystem-restricted execution on Linux.
2593
- On Ubuntu hosts that restrict unprivileged user namespaces, an administrator
2594
- must install the AppArmor profile and use the Compose override:
2595
-
2596
- ```bash
2597
- sudo install -m 0644 docker/codex-security.apparmor /etc/apparmor.d/codex-security-container
2598
- sudo apparmor_parser -r -W /etc/apparmor.d/codex-security-container
2599
- docker compose -f compose.yaml -f compose.apparmor.yaml run --rm codex-security
2600
- ```
2601
-
2602
- The override keeps the nonroot user, dropped capabilities, no-new-privileges,
2603
- and seccomp policy. It enables the nested namespaces required by Bubblewrap.
2604
- The legacy Landlock fallback is no longer supported for these scans. Other
2605
- Docker hosts that permit nested user namespaces do not need this override.
615
+ Use the scanner image and Compose files to scan a list of repositories with
616
+ persistent results and authentication. See
617
+ [containerized bulk scans](docs/cli.md#containerized-bulk-scans) for setup, or the
618
+ [workflow runner](https://github.com/openai/codex-security/blob/main/docker/README.md#workflow-runner)
619
+ for individual CLI stages in containers.
2606
620
 
2607
621
  ## Local security model
2608
622
 
2609
- Codex Security runs with your operating-system permissions. Only scan
2610
- repositories you trust and are authorized to assess. Local tools and scans
2611
- under the same account aren't separate security principals.
623
+ Codex Security runs with your operating-system permissions. Scan subprocesses
624
+ can inherit your environment, so start them with only the credentials they need.
625
+ Local tools running under the same account are trusted.
2612
626
 
2613
- The `codex_security_scan` profile allows reads across the local filesystem and
2614
- writes to workspace roots. Execution approvals are reviewed automatically and
2615
- may grant extra permissions for one operation. Set
2616
- `--codex 'approval_policy="never"'`, directly or in a selected profile, to deny
2617
- requests. Other overrides can't replace the reviewer or filesystem profile.
2618
- Saved scans keep their approval policy; older scans stay deny-all on rerun.
627
+ The scan profile allows reads across the local filesystem and writes to workspace
628
+ roots. Execution approvals are reviewed automatically and may grant extra
629
+ permissions for an operation. Set `codexOverrides.approval_policy: "never"`
630
+ (or CLI `--codex 'approval_policy="never"'`) to deny permission requests.
2619
631
  Host and network restrictions still apply.
2620
632
 
2621
- Start scans with only the credentials they need. Scan and workbench subprocesses
2622
- can inherit your environment, including unrelated API tokens and cloud credentials.
2623
-
2624
633
  Repository contents, model output, and imported artifacts do not authorize
2625
634
  access to other targets, disclosure of credentials, or writes outside approved
2626
- paths. See the security policy below for the full threat model.
635
+ paths. Keep state and scan artifacts private and outside the repository.
2627
636
 
2628
637
  ## Documentation and security
2629
638
 
2630
- - [CLI quickstart](https://developers.openai.com/codex/security/cli)
2631
- - [TypeScript SDK guide](https://developers.openai.com/codex/security/sdk)
2632
- - [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and
2633
- feature requests
2634
- - [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md)
2635
- for private vulnerability reporting and safe operation
639
+ - [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)
640
+ - [CLI reference](docs/cli.md)
641
+ - [Findings guide](docs/findings-service.md)
642
+ - [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and feature requests
643
+ - [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for private vulnerability reporting