@openai/codex-security 0.9.1 → 0.10.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 (387) hide show
  1. package/README.md +37 -788
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +2 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  5. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  6. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  7. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  14. package/_bundled_plugin/references/artifact-storage.md +1 -1
  15. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  16. package/_bundled_plugin/references/core-scan.md +5 -42
  17. package/_bundled_plugin/references/final-report.md +1 -1
  18. package/_bundled_plugin/references/focused-investigator.md +13 -0
  19. package/_bundled_plugin/references/scan-prologue.md +2 -2
  20. package/_bundled_plugin/references/scan-runtime.md +4 -2
  21. package/_bundled_plugin/references/security-guidance.md +14 -1
  22. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  23. package/_bundled_plugin/scripts/deep_scan_workbench.py +29 -12
  24. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  25. package/_bundled_plugin/scripts/finalize_scan_contract.py +29 -3
  26. package/_bundled_plugin/scripts/launch_codex_security_mcp +54 -16
  27. package/_bundled_plugin/scripts/posix_scan_local_files.py +26 -1
  28. package/_bundled_plugin/scripts/snapshot_sqlite.py +8 -2
  29. package/_bundled_plugin/scripts/windows_scan_local_files.py +216 -25
  30. package/_bundled_plugin/scripts/workbench/handoff.py +55 -25
  31. package/_bundled_plugin/scripts/workbench/storage.py +25 -5
  32. package/_bundled_plugin/scripts/workbench_cli.py +24 -2
  33. package/_bundled_plugin/scripts/workbench_constants.py +2 -0
  34. package/_bundled_plugin/scripts/workbench_db.py +244 -217
  35. package/_bundled_plugin/scripts/workbench_feedback.py +49 -4
  36. package/_bundled_plugin/scripts/workbench_native_indexes.py +226 -29
  37. package/_bundled_plugin/scripts/workbench_progress.py +159 -3
  38. package/_bundled_plugin/scripts/workbench_publication.py +2 -3
  39. package/_bundled_plugin/scripts/workbench_remediation.py +142 -2
  40. package/_bundled_plugin/scripts/workbench_saved_results.py +48 -8
  41. package/_bundled_plugin/scripts/workbench_scan_history.py +281 -119
  42. package/_bundled_plugin/scripts/workbench_scan_start.py +143 -9
  43. package/_bundled_plugin/scripts/workbench_scan_usage.py +36 -10
  44. package/_bundled_plugin/scripts/workbench_schema.py +220 -14
  45. package/_bundled_plugin/scripts/workbench_setup.py +1 -1
  46. package/_bundled_plugin/scripts/workbench_target.py +471 -84
  47. package/_bundled_plugin/scripts/workbench_target_state.py +1108 -22
  48. package/_bundled_plugin/shared/workbench-history-repairs.json +60 -14
  49. package/_bundled_plugin/shared/workbench-migrations.json +66 -0
  50. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -0
  51. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -160
  52. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  53. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +2 -2
  54. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +3 -58
  55. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  56. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  57. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  58. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  59. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  60. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  61. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  62. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  63. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  64. package/bin/codex-security.mjs +2 -2
  65. package/dist/api.d.ts +6 -1
  66. package/dist/api.d.ts.map +1 -1
  67. package/dist/api.js +437 -154
  68. package/dist/api.js.map +1 -1
  69. package/dist/armorcode-findings.d.ts +9 -0
  70. package/dist/armorcode-findings.d.ts.map +1 -0
  71. package/dist/armorcode-findings.js +145 -0
  72. package/dist/armorcode-findings.js.map +1 -0
  73. package/dist/artifact-export.d.ts +2 -0
  74. package/dist/artifact-export.d.ts.map +1 -1
  75. package/dist/artifact-export.js +29 -13
  76. package/dist/artifact-export.js.map +1 -1
  77. package/dist/auth.d.ts +6 -2
  78. package/dist/auth.d.ts.map +1 -1
  79. package/dist/auth.js +33 -12
  80. package/dist/auth.js.map +1 -1
  81. package/dist/batch-cost.d.ts +18 -0
  82. package/dist/batch-cost.d.ts.map +1 -0
  83. package/dist/batch-cost.js +41 -0
  84. package/dist/batch-cost.js.map +1 -0
  85. package/dist/blackduck-findings.d.ts +1 -1
  86. package/dist/blackduck-findings.d.ts.map +1 -1
  87. package/dist/blackduck-findings.js +5 -18
  88. package/dist/blackduck-findings.js.map +1 -1
  89. package/dist/bundled-plugin.d.ts +4 -0
  90. package/dist/bundled-plugin.d.ts.map +1 -0
  91. package/dist/bundled-plugin.js +23 -0
  92. package/dist/bundled-plugin.js.map +1 -0
  93. package/dist/classify-scan-severity.d.ts +1 -1
  94. package/dist/classify-scan-severity.d.ts.map +1 -1
  95. package/dist/classify-scan-severity.js +11 -3
  96. package/dist/classify-scan-severity.js.map +1 -1
  97. package/dist/classify-severity.d.ts.map +1 -1
  98. package/dist/classify-severity.js +9 -6
  99. package/dist/classify-severity.js.map +1 -1
  100. package/dist/cli-argument.d.ts +4 -0
  101. package/dist/cli-argument.d.ts.map +1 -0
  102. package/dist/cli-argument.js +17 -0
  103. package/dist/cli-argument.js.map +1 -0
  104. package/dist/cli-help.d.ts +1 -1
  105. package/dist/cli-help.d.ts.map +1 -1
  106. package/dist/cli-help.js +71 -29
  107. package/dist/cli-help.js.map +1 -1
  108. package/dist/cli-hook.d.ts +3 -0
  109. package/dist/cli-hook.d.ts.map +1 -0
  110. package/dist/cli-hook.js +87 -0
  111. package/dist/cli-hook.js.map +1 -0
  112. package/dist/cli-integrations.d.ts +13 -0
  113. package/dist/cli-integrations.d.ts.map +1 -0
  114. package/dist/cli-integrations.js +333 -0
  115. package/dist/cli-integrations.js.map +1 -0
  116. package/dist/cli-mcp.d.ts +15 -0
  117. package/dist/cli-mcp.d.ts.map +1 -0
  118. package/dist/cli-mcp.js +178 -0
  119. package/dist/cli-mcp.js.map +1 -0
  120. package/dist/cli-token-view.d.ts +10 -0
  121. package/dist/cli-token-view.d.ts.map +1 -0
  122. package/dist/cli-token-view.js +41 -0
  123. package/dist/cli-token-view.js.map +1 -0
  124. package/dist/cli.d.ts +5 -3
  125. package/dist/cli.d.ts.map +1 -1
  126. package/dist/cli.js +1763 -894
  127. package/dist/cli.js.map +1 -1
  128. package/dist/cloud-publish.d.ts.map +1 -1
  129. package/dist/cloud-publish.js +33 -31
  130. package/dist/cloud-publish.js.map +1 -1
  131. package/dist/codex-sdk-environment.d.ts +6 -0
  132. package/dist/codex-sdk-environment.d.ts.map +1 -1
  133. package/dist/codex-sdk-environment.js +19 -0
  134. package/dist/codex-sdk-environment.js.map +1 -1
  135. package/dist/command-words.d.ts +3 -0
  136. package/dist/command-words.d.ts.map +1 -0
  137. package/dist/command-words.js +46 -0
  138. package/dist/command-words.js.map +1 -0
  139. package/dist/component-scan.d.ts +3 -1
  140. package/dist/component-scan.d.ts.map +1 -1
  141. package/dist/component-scan.js +40 -7
  142. package/dist/component-scan.js.map +1 -1
  143. package/dist/config.d.ts +1 -1
  144. package/dist/config.d.ts.map +1 -1
  145. package/dist/config.js +30 -1
  146. package/dist/config.js.map +1 -1
  147. package/dist/continuum-findings.d.ts +1 -1
  148. package/dist/continuum-findings.d.ts.map +1 -1
  149. package/dist/continuum-findings.js +93 -31
  150. package/dist/continuum-findings.js.map +1 -1
  151. package/dist/cost.d.ts.map +1 -1
  152. package/dist/cost.js +1 -45
  153. package/dist/cost.js.map +1 -1
  154. package/dist/custom-validation-prompt.d.ts +1 -1
  155. package/dist/custom-validation-prompt.d.ts.map +1 -1
  156. package/dist/custom-validation-prompt.js +29 -19
  157. package/dist/custom-validation-prompt.js.map +1 -1
  158. package/dist/deduplication/local.d.ts +3 -1
  159. package/dist/deduplication/local.d.ts.map +1 -1
  160. package/dist/deduplication/local.js +8 -1
  161. package/dist/deduplication/local.js.map +1 -1
  162. package/dist/deduplication/refusal.d.ts.map +1 -1
  163. package/dist/deduplication/refusal.js +2 -1
  164. package/dist/deduplication/refusal.js.map +1 -1
  165. package/dist/deduplication/scan.d.ts +2 -0
  166. package/dist/deduplication/scan.d.ts.map +1 -1
  167. package/dist/deduplication/scan.js +24 -7
  168. package/dist/deduplication/scan.js.map +1 -1
  169. package/dist/deep-scan.d.ts.map +1 -1
  170. package/dist/deep-scan.js +16 -15
  171. package/dist/deep-scan.js.map +1 -1
  172. package/dist/endor-findings.d.ts +2 -2
  173. package/dist/endor-findings.d.ts.map +1 -1
  174. package/dist/endor-findings.js +6 -23
  175. package/dist/endor-findings.js.map +1 -1
  176. package/dist/errors.d.ts +3 -1
  177. package/dist/errors.d.ts.map +1 -1
  178. package/dist/errors.js +7 -3
  179. package/dist/errors.js.map +1 -1
  180. package/dist/executable-path.d.ts +3 -0
  181. package/dist/executable-path.d.ts.map +1 -1
  182. package/dist/executable-path.js +26 -0
  183. package/dist/executable-path.js.map +1 -1
  184. package/dist/external-findings-import.d.ts.map +1 -1
  185. package/dist/external-findings-import.js +12 -1
  186. package/dist/external-findings-import.js.map +1 -1
  187. package/dist/external-findings-local.d.ts +66 -4
  188. package/dist/external-findings-local.d.ts.map +1 -1
  189. package/dist/external-findings-local.js +234 -53
  190. package/dist/external-findings-local.js.map +1 -1
  191. package/dist/external-findings-publish.d.ts +6 -1
  192. package/dist/external-findings-publish.d.ts.map +1 -1
  193. package/dist/external-findings-publish.js +326 -1633
  194. package/dist/external-findings-publish.js.map +1 -1
  195. package/dist/external-findings-read.d.ts +1 -0
  196. package/dist/external-findings-read.d.ts.map +1 -1
  197. package/dist/external-findings-read.js +31 -51
  198. package/dist/external-findings-read.js.map +1 -1
  199. package/dist/external-findings.d.ts +1 -1
  200. package/dist/external-findings.d.ts.map +1 -1
  201. package/dist/external-findings.js +12 -1
  202. package/dist/external-findings.js.map +1 -1
  203. package/dist/external-import-contract.d.ts +3 -11
  204. package/dist/external-import-contract.d.ts.map +1 -1
  205. package/dist/external-import-contract.js +29 -176
  206. package/dist/external-import-contract.js.map +1 -1
  207. package/dist/external-import-models.d.ts +1 -1
  208. package/dist/external-import-models.d.ts.map +1 -1
  209. package/dist/external-import-models.js.map +1 -1
  210. package/dist/finding-prompt.d.ts.map +1 -1
  211. package/dist/finding-prompt.js +2 -2
  212. package/dist/finding-prompt.js.map +1 -1
  213. package/dist/github-dependabot-findings.d.ts.map +1 -1
  214. package/dist/github-dependabot-findings.js +3 -4
  215. package/dist/github-dependabot-findings.js.map +1 -1
  216. package/dist/github-findings.d.ts.map +1 -1
  217. package/dist/github-findings.js +19 -287
  218. package/dist/github-findings.js.map +1 -1
  219. package/dist/hosted-remediation.d.ts +1 -0
  220. package/dist/hosted-remediation.d.ts.map +1 -1
  221. package/dist/hosted-remediation.js +23 -3
  222. package/dist/hosted-remediation.js.map +1 -1
  223. package/dist/index.d.ts +3 -2
  224. package/dist/index.d.ts.map +1 -1
  225. package/dist/index.js +2 -1
  226. package/dist/index.js.map +1 -1
  227. package/dist/inspector-findings.d.ts.map +1 -1
  228. package/dist/inspector-findings.js +19 -35
  229. package/dist/inspector-findings.js.map +1 -1
  230. package/dist/knowledge-base.d.ts +1 -1
  231. package/dist/knowledge-base.d.ts.map +1 -1
  232. package/dist/knowledge-base.js +34 -27
  233. package/dist/knowledge-base.js.map +1 -1
  234. package/dist/linear.d.ts +11 -0
  235. package/dist/linear.d.ts.map +1 -1
  236. package/dist/linear.js.map +1 -1
  237. package/dist/local-git-metadata.d.ts +5 -2
  238. package/dist/local-git-metadata.d.ts.map +1 -1
  239. package/dist/local-git-metadata.js +8 -4
  240. package/dist/local-git-metadata.js.map +1 -1
  241. package/dist/multiscan.d.ts +4 -0
  242. package/dist/multiscan.d.ts.map +1 -1
  243. package/dist/multiscan.js +79 -37
  244. package/dist/multiscan.js.map +1 -1
  245. package/dist/opengrep-findings.d.ts +4 -2
  246. package/dist/opengrep-findings.d.ts.map +1 -1
  247. package/dist/opengrep-findings.js +39 -22
  248. package/dist/opengrep-findings.js.map +1 -1
  249. package/dist/private-finding-import.d.ts +8 -13
  250. package/dist/private-finding-import.d.ts.map +1 -1
  251. package/dist/private-finding-import.js +69 -129
  252. package/dist/private-finding-import.js.map +1 -1
  253. package/dist/project-config.d.ts.map +1 -1
  254. package/dist/project-config.js +53 -13
  255. package/dist/project-config.js.map +1 -1
  256. package/dist/prompt-files.d.ts +7 -2
  257. package/dist/prompt-files.d.ts.map +1 -1
  258. package/dist/prompt-files.js +42 -20
  259. package/dist/prompt-files.js.map +1 -1
  260. package/dist/provider-profile.d.ts.map +1 -1
  261. package/dist/provider-profile.js +4 -9
  262. package/dist/provider-profile.js.map +1 -1
  263. package/dist/publication.d.ts +1 -1
  264. package/dist/publication.d.ts.map +1 -1
  265. package/dist/publication.js.map +1 -1
  266. package/dist/record.d.ts +1 -5
  267. package/dist/record.d.ts.map +1 -1
  268. package/dist/record.js +3 -51
  269. package/dist/record.js.map +1 -1
  270. package/dist/remediation.d.ts.map +1 -1
  271. package/dist/remediation.js +3 -1
  272. package/dist/remediation.js.map +1 -1
  273. package/dist/runtime.d.ts +35 -7
  274. package/dist/runtime.d.ts.map +1 -1
  275. package/dist/runtime.js +778 -153
  276. package/dist/runtime.js.map +1 -1
  277. package/dist/saved-scan-bootstrap.d.ts +6 -1
  278. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  279. package/dist/saved-scan-bootstrap.js +267 -115
  280. package/dist/saved-scan-bootstrap.js.map +1 -1
  281. package/dist/scan-archive-path.d.ts +2 -0
  282. package/dist/scan-archive-path.d.ts.map +1 -0
  283. package/dist/scan-archive-path.js +5 -0
  284. package/dist/scan-archive-path.js.map +1 -0
  285. package/dist/scan-comparison.d.ts.map +1 -1
  286. package/dist/scan-comparison.js +6 -2
  287. package/dist/scan-comparison.js.map +1 -1
  288. package/dist/scan-dashboard.d.ts +1 -0
  289. package/dist/scan-dashboard.d.ts.map +1 -1
  290. package/dist/scan-dashboard.js +18 -2
  291. package/dist/scan-dashboard.js.map +1 -1
  292. package/dist/scan-executor.d.ts.map +1 -1
  293. package/dist/scan-executor.js +4 -2
  294. package/dist/scan-executor.js.map +1 -1
  295. package/dist/scan-history-renderer.d.ts +1 -0
  296. package/dist/scan-history-renderer.d.ts.map +1 -1
  297. package/dist/scan-history-renderer.js +25 -9
  298. package/dist/scan-history-renderer.js.map +1 -1
  299. package/dist/scan-logs.d.ts.map +1 -1
  300. package/dist/scan-logs.js +28 -4
  301. package/dist/scan-logs.js.map +1 -1
  302. package/dist/scanner-import.d.ts +5 -11
  303. package/dist/scanner-import.d.ts.map +1 -1
  304. package/dist/scanner-import.js +16 -89
  305. package/dist/scanner-import.js.map +1 -1
  306. package/dist/security-policy.d.ts.map +1 -1
  307. package/dist/security-policy.js +26 -6
  308. package/dist/security-policy.js.map +1 -1
  309. package/dist/semgrep-findings.d.ts.map +1 -1
  310. package/dist/semgrep-findings.js +14 -48
  311. package/dist/semgrep-findings.js.map +1 -1
  312. package/dist/semgrep-platform-findings.d.ts +20 -70
  313. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  314. package/dist/semgrep-platform-findings.js +116 -333
  315. package/dist/semgrep-platform-findings.js.map +1 -1
  316. package/dist/snyk-findings.d.ts +2 -0
  317. package/dist/snyk-findings.d.ts.map +1 -1
  318. package/dist/snyk-findings.js +5 -8
  319. package/dist/snyk-findings.js.map +1 -1
  320. package/dist/snyk-rest-findings.d.ts +3 -20
  321. package/dist/snyk-rest-findings.d.ts.map +1 -1
  322. package/dist/snyk-rest-findings.js +45 -217
  323. package/dist/snyk-rest-findings.js.map +1 -1
  324. package/dist/sonar-findings.d.ts +1 -1
  325. package/dist/sonar-findings.d.ts.map +1 -1
  326. package/dist/sonar-findings.js +2 -4
  327. package/dist/sonar-findings.js.map +1 -1
  328. package/dist/sonar-import.d.ts +3 -0
  329. package/dist/sonar-import.d.ts.map +1 -1
  330. package/dist/sonar-import.js +28 -30
  331. package/dist/sonar-import.js.map +1 -1
  332. package/dist/stored-finding-projection.d.ts +6 -0
  333. package/dist/stored-finding-projection.d.ts.map +1 -0
  334. package/dist/stored-finding-projection.js +104 -0
  335. package/dist/stored-finding-projection.js.map +1 -0
  336. package/dist/stored-findings-publication.d.ts +23 -0
  337. package/dist/stored-findings-publication.d.ts.map +1 -0
  338. package/dist/stored-findings-publication.js +169 -0
  339. package/dist/stored-findings-publication.js.map +1 -0
  340. package/dist/targets.d.ts +6 -1
  341. package/dist/targets.d.ts.map +1 -1
  342. package/dist/targets.js +76 -23
  343. package/dist/targets.js.map +1 -1
  344. package/dist/tenable-findings.d.ts +1 -4
  345. package/dist/tenable-findings.d.ts.map +1 -1
  346. package/dist/tenable-findings.js.map +1 -1
  347. package/dist/trivy-findings.d.ts.map +1 -1
  348. package/dist/trivy-findings.js +0 -11
  349. package/dist/trivy-findings.js.map +1 -1
  350. package/dist/trusted-executable.d.ts +6 -0
  351. package/dist/trusted-executable.d.ts.map +1 -1
  352. package/dist/trusted-executable.js +140 -37
  353. package/dist/trusted-executable.js.map +1 -1
  354. package/dist/veracode-findings.d.ts +1 -3
  355. package/dist/veracode-findings.d.ts.map +1 -1
  356. package/dist/veracode-findings.js +13 -38
  357. package/dist/veracode-findings.js.map +1 -1
  358. package/dist/version.d.ts +3 -1
  359. package/dist/version.d.ts.map +1 -1
  360. package/dist/version.js +184 -32
  361. package/dist/version.js.map +1 -1
  362. package/dist/wiz-findings.d.ts +2 -2
  363. package/dist/wiz-findings.d.ts.map +1 -1
  364. package/dist/wiz-findings.js +14 -92
  365. package/dist/wiz-findings.js.map +1 -1
  366. package/docs/cli.md +373 -106
  367. package/docs/findings-service.md +22 -9
  368. package/docs/hosted-remediation.md +13 -4
  369. package/docs/sdk.md +903 -0
  370. package/package.json +10 -6
  371. package/schemas/external-findings.schema.json +2 -1
  372. package/dist/hosted-scanner-v1.d.ts +0 -6
  373. package/dist/hosted-scanner-v1.d.ts.map +0 -1
  374. package/dist/hosted-scanner-v1.js +0 -60
  375. package/dist/hosted-scanner-v1.js.map +0 -1
  376. package/dist/reader-selection.d.ts +0 -15
  377. package/dist/reader-selection.d.ts.map +0 -1
  378. package/dist/reader-selection.js +0 -89
  379. package/dist/reader-selection.js.map +0 -1
  380. package/dist/semgrep-platform-v1.d.ts +0 -6
  381. package/dist/semgrep-platform-v1.d.ts.map +0 -1
  382. package/dist/semgrep-platform-v1.js +0 -83
  383. package/dist/semgrep-platform-v1.js.map +0 -1
  384. package/dist/snyk-rest-v1.d.ts +0 -28
  385. package/dist/snyk-rest-v1.d.ts.map +0 -1
  386. package/dist/snyk-rest-v1.js +0 -132
  387. package/dist/snyk-rest-v1.js.map +0 -1
package/docs/cli.md CHANGED
@@ -14,7 +14,10 @@ codex-security info --json
14
14
 
15
15
  `--help` lists commands by task; `<command> --help` lists its options.
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
- `scans` and `findings` default to their `list` subcommands.
17
+ `scans` and `findings` default to their `list` subcommands. Global output options
18
+ can appear around a subcommand, for example `cs scans --json show`. Use `--`
19
+ after the command to pass the remaining words as literal positional arguments,
20
+ including file names that begin with a dash.
18
21
 
19
22
  ## Find a workflow
20
23
 
@@ -37,6 +40,26 @@ codex-security info --json
37
40
  - [Use a hosted executor](#hosted-standard-scan) or
38
41
  [run bulk scans in containers](#containerized-bulk-scans).
39
42
 
43
+ ## Updating the CLI
44
+
45
+ Run `cs update` to update an npm global installation managed by the running
46
+ Node distribution. It uses Node’s bundled npm, the public npm registry, and
47
+ disabled lifecycle scripts. If you use a custom registry or proxy, run your
48
+ package manager’s update command directly.
49
+
50
+ The legacy `cs --update` spelling also works. Invoke the updater or the stdio
51
+ server (`cs --mcp`) on its own.
52
+
53
+ For a project dependency, `cs update` prints the package-manager command for
54
+ you to run in the declaring project. For other global installations it prints
55
+ the corresponding package-manager command and installation location. For npx,
56
+ use `npx @openai/codex-security@latest` on the next run. For a standalone
57
+ release, download and extract the latest release.
58
+
59
+ Interactive update notices use the same installation detection. Set
60
+ `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to disable these notices. Explicit updates
61
+ are available with notifications disabled.
62
+
40
63
  ## Authentication
41
64
 
42
65
  Sign in with ChatGPT, or supply an API key for CI:
@@ -139,6 +162,8 @@ If Codex Security reports that the refresh token was already used, run
139
162
  `codex-security logout`, then `codex-security login`. If your Codex CLI or app
140
163
  reports that error, sign out and sign back in there.
141
164
 
165
+ Use `codex-security login status --json` in automation. Its stdout reports `authenticated`, the effective authentication `method`, and the environment variable name when an API key takes precedence. When an API key takes precedence, stderr names the variable that configures it. This offline status check also labels the separate stored sign-in diagnostic. The command keeps the exit status of the human-readable status check.
166
+
142
167
  For other refresh errors, check `codex-security login status`. Retry if the
143
168
  sign-in recently changed. Otherwise run `codex-security logout`, then
144
169
  `codex-security login`.
@@ -384,11 +409,11 @@ Add context with `--knowledge-base`:
384
409
  codex-security policy . --knowledge-base architecture.md
385
410
  ```
386
411
 
387
- | Invocation | Result |
388
- | ---------------------------- | -------------------------------------------------------- |
389
- | `policy . --headless --json` | Generate without prompts; return paths and review notes. |
390
- | `policy . --format md` | Generate and write the draft to stdout. |
391
- | `policy . --dry-run --json` | Check local inputs without calling Codex. |
412
+ | Invocation | Result |
413
+ | --------------------------- | -------------------------------------------------------- |
414
+ | `policy . --json` | Generate without prompts; return paths and review notes. |
415
+ | `policy . --format md` | Generate and write the draft to stdout. |
416
+ | `policy . --dry-run --json` | Check local inputs without calling Codex. |
392
417
 
393
418
  `--headless` leaves unanswered questions in the review notes. By default, files
394
419
  go in the Codex Security state directory. To choose a location, use an empty
@@ -494,6 +519,10 @@ show requested paths and exclusions. `coverage.deferred` records unfinished
494
519
  requested work separately from optional `coverage.openQuestions` follow-up.
495
520
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
496
521
 
522
+ A dry run reports `stateDirectory`, the root for saved scan state. It checks the
523
+ storage location without creating a scan directory. Pass boolean scan options
524
+ as bare flags or use lowercase `=true` or `=false`.
525
+
497
526
  When a cost limit is configured, `scan --dry-run` shows the resolved
498
527
  `maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
499
528
  against the limit and why in-flight requests can exceed it.
@@ -509,7 +538,8 @@ be clean and at the commit recorded by the parent.
509
538
  Committed-diff scans require a clean, full checkout at the requested head
510
539
  revision, including when using `--validate`. A different checkout revision or
511
540
  local changes are rejected before scanning; check out the requested head and
512
- commit or stash local changes before retrying.
541
+ commit or stash local changes before retrying. The check also verifies tracked
542
+ files marked `assume-unchanged` and preserves their Git index flags.
513
543
 
514
544
  `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
515
545
  committed Git scan, using the same checkout, model, and reasoning effort. Owner
@@ -524,7 +554,9 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
524
554
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
525
555
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
526
556
  explicit unsupported binary files are rejected. Bulk scans share this context
527
- with every repository.
557
+ with every repository. Select external documents directly. Links in a checkout
558
+ must stay inside it. For bulk scans with bare or separate Git storage, use
559
+ canonical paths for shared documents and prompt files.
528
560
 
529
561
  Use `--output-dir DIR` to choose where a scan saves its results. The directory
530
562
  must be empty and outside the scanned directory and enclosing Git worktree.
@@ -538,7 +570,9 @@ through inheritance. Other users must not have permission to set reparse data
538
570
  on the destination directory itself.
539
571
  `--archive-existing` moves earlier output to a sibling directory with a unique
540
572
  suffix, such as `results.previous-ab12cd34` for an output directory named
541
- `results`. Use `--dry-run` to preview the move.
573
+ `results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
574
+ the archive uses a short sibling name starting with `.previous-` and a hash of the
575
+ original filename. Use `--dry-run` to preview the move.
542
576
 
543
577
  Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
544
578
  optional export fails, the scan can still complete. Use the
@@ -595,8 +629,13 @@ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an importe
595
629
  scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
596
630
  on stderr without `--full-output`, or when retained results are unavailable.
597
631
 
598
- Diagnostics stay on stderr. Each command's `--schema --format json` describes
599
- its successful output and failure codes.
632
+ Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
633
+ envelope with `error.code` and `error.message`. Command schema validation errors
634
+ with JSON or JSONL retain their field details and name missing or invalid
635
+ options by their CLI flags. Diagnostics stay on stderr.
636
+ `scan --schema --format json` describes optional caller inputs before defaults
637
+ and the fields returned by preflight, completed scans, and execution failures,
638
+ including sealed results recovered after an interruption.
600
639
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
601
640
 
602
641
  ### Follow-up finding validation
@@ -685,8 +724,8 @@ Choose the next step from the recorded reason:
685
724
  start a new scan with the intended scope, including for plugin scans without
686
725
  a recipe. Retained findings can still be reviewed, but absence of findings
687
726
  from a stopped run is inconclusive.
688
- - **A Deep Scan was interrupted and is still recorded as `running`:** it may
689
- support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
727
+ - **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
728
+ support [resume](#resuming-an-interrupted-scan) with the original checkout,
690
729
  artifacts, and session. Completed, failed, and canceled scans cannot resume.
691
730
 
692
731
  For example, after identifying an omitted API directory:
@@ -731,16 +770,18 @@ from the config directory; scope paths resolve from the repository.
731
770
  ### Import findings as a saved scan
732
771
 
733
772
  ```bash
734
- codex-security scan import --csv /path/to/findings.csv
735
- codex-security scan import --json /path/to/findings.json --format json
736
- codex-security scan import --csv /path/to/findings.csv --dry-run
773
+ codex-security scan import /path/to/findings.csv
774
+ codex-security scan import /path/to/findings.json --json
775
+ codex-security scan import /path/to/report --input-format csv --dry-run
737
776
  ```
738
777
 
739
778
  Supply exactly one input. CSV follows the
740
779
  [findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
741
780
  JSON accepts a complete `codex-security.findings` document or
742
- `{ "findings": [...] }` matching the findings schema. For this command, `--json`
743
- selects the input file; use `--format json` for JSON output. The input must be a
781
+ `{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
782
+ Use `--input-format csv|json` to override it. Put `--json` after the filename
783
+ to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
784
+ can continue to select the input that way. The input must be a
744
785
  regular file with no symlinks or directory junctions in its path.
745
786
 
746
787
  Each import creates a completed scan in local history, retains the input under
@@ -821,6 +862,13 @@ codex-security scan-components . \
821
862
  --output-dir /path/outside/project/results
822
863
  ```
823
864
 
865
+ `--plan-only` with `--component` or `--components-file` validates local paths
866
+ without signing in. The CLI prints a command to scan the saved plan into a fresh
867
+ `results` directory inside the plan directory. Running that command starts scans.
868
+ Run it from the original working directory to reuse relative paths. The command
869
+ includes the selected project configuration and scan flags. Reapply any inline
870
+ `--codex` overrides yourself, since these can contain credentials.
871
+
824
872
  Plans use literal repository-relative paths, so `~/src` selects a directory
825
873
  named `~` inside the repository rather than expanding the home directory.
826
874
  Existing absolute paths inside the repository are also accepted.
@@ -850,9 +898,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry with
850
898
  The retry report covers only those components. Each registered component keeps its
851
899
  scan ID in the summary, including when the scan fails.
852
900
 
853
- `--max-cost` applies per component, excluding planning and matching. `--model`
854
- and `--effort` also apply to matching; `--auth` applies throughout. Planning and
855
- matching reject ambient command providers that conflict with explicit ChatGPT
901
+ `--max-cost` applies per component, excluding planning and matching.
902
+ Use `--max-total-cost USD` with explicit components to split one estimated
903
+ budget among them. The smaller of each component's share and its per-scan
904
+ limit applies. Findings stay separate because model-based matching is skipped.
905
+ The total limit also skips owner suggestions, including when enabled in project configuration.
906
+ Automatic planning and post-scan prompts must run separately.
907
+
908
+ `--model` and `--effort` also apply to matching. `--auth` applies throughout.
909
+ Planning and matching reject ambient command providers that conflict with explicit ChatGPT
856
910
  or API-key auth. SDK-selected command providers retain their authentication.
857
911
 
858
912
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
@@ -877,6 +931,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
877
931
  `markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
878
932
  Markdown. A supplied snapshot takes precedence over a file.
879
933
 
934
+ A dry run reads and validates an explicit rubric before reporting a successful preflight.
880
935
  The scan saves the rubric text in its local launch recipe. Retrying a Standard
881
936
  scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
882
937
  with a saved rubric reuses that copy even if the remote default or file changes.
@@ -901,7 +956,7 @@ behavior are unchanged.
901
956
 
902
957
  The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
903
958
  Each launched scan or rerun gets its own allowance after setup, and reconnects
904
- do not reset it. Standard scans still do not support resume. For batch and
959
+ do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
905
960
  component scans, the project setting applies separately to each scan attempt,
906
961
  not to planning, result matching, or the total campaign.
907
962
 
@@ -925,7 +980,7 @@ completed scans that added no findings. `--max-discovery-runs` caps the total
925
980
  number started, including failures. `--max-time` stops discovery and returns
926
981
  the findings from completed scans.
927
982
 
928
- For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
983
+ For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
929
984
 
930
985
  Use project-file `scan.deep` settings or legacy
931
986
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
@@ -981,7 +1036,9 @@ credentials, and workflow resume behavior.
981
1036
  For `dedupe --scan latest`, matching across worktrees or clones requires a Git
982
1037
  executable outside all saved scan targets. If a historical target includes the
983
1038
  available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
984
- explicit saved scan ID. Exact-path `latest` lookup still works without Git.
1039
+ explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
1040
+ scan targets; recorded Git generations require a trusted Git executable to verify
1041
+ that the checkout still owns its saved history.
985
1042
 
986
1043
  Repeat `--codex KEY=VALUE` for supported native settings. For example,
987
1044
  `--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
@@ -1078,7 +1135,7 @@ client during the scan, or receiving a canceled hosted execution records
1078
1135
  Applications can choose how to collect and export these observations.
1079
1136
 
1080
1137
  For filesystem and approval behavior, see the
1081
- [local security model](../README.md#local-security-model).
1138
+ [local security model](sdk.md#local-security-model).
1082
1139
 
1083
1140
  ### Environment variables
1084
1141
 
@@ -1111,6 +1168,10 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
1111
1168
  `pythonPath`, then
1112
1169
  `PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
1113
1170
  works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
1171
+ On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
1172
+ explicit path that selects an executable. Use an absolute path or a `./`
1173
+ prefix for filenames beginning or ending in whitespace. Bare command names
1174
+ are trimmed before lookup.
1114
1175
 
1115
1176
  ### Troubleshooting
1116
1177
 
@@ -1140,6 +1201,11 @@ and does not migrate existing credentials or reports.
1140
1201
  Sandbox startup errors include the native diagnostic followed by a command to
1141
1202
  reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
1142
1203
 
1204
+ If Windows Application Control blocks `windows.node` while validating a scan
1205
+ output directory, look for the module's block event in Event Viewer under
1206
+ Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
1207
+ [Microsoft's App Control event reference](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/operations/event-id-explanations)
1208
+
1143
1209
  On Windows, credential-home checks require trusted ownership and permissions
1144
1210
  through every ancestor, including the volume root. Codex Security can repair
1145
1211
  the credential home and its descendants; it does not change ancestor ownership
@@ -1219,8 +1285,9 @@ work is needed, the scan is preserved and you can run `scans match --all`.
1219
1285
 
1220
1286
  A scan with a cost limit requires complete token usage for its recorded scan,
1221
1287
  worker, and custom validation sessions before the SDK returns a completed result.
1222
- Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
1223
- `backports.zstd` installed in the selected Python environment.
1288
+ The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
1289
+ (Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
1290
+ Node.js decoder bundled with the plugin.
1224
1291
  Missing or unreadable usage fails budget verification. Without a limit, usage
1225
1292
  reporting remains best effort.
1226
1293
 
@@ -1314,7 +1381,8 @@ the campaign a joint source review across repositories. For that workflow, use
1314
1381
 
1315
1382
  Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
1316
1383
  selection. It lists repositories pushed in the last 90 days, excluding forks
1317
- and archives, asks for output, and saves the selection as `repositories.csv`.
1384
+ and archives, asks where to save results, and saves the selection as `repositories.csv`.
1385
+ Pass `--output-dir DIR` to set the initial answer in the wizard.
1318
1386
  Private checkouts use your GitHub CLI login.
1319
1387
 
1320
1388
  For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
@@ -1330,7 +1398,32 @@ codex-security bulk-scan repositories.csv \
1330
1398
  --output-dir /path/outside/repositories/results --workers 4
1331
1399
  ```
1332
1400
 
1401
+ `--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
1402
+ estimated limit among the pending repositories and their possible attempts for
1403
+ this invocation, including recovery. For example, a $12 limit with three pending
1404
+ repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
1405
+ overrun reduces the remaining budget for queued attempts. In-flight work can
1406
+ exceed a limit. The total limit skips model-based matching and owner suggestions,
1407
+ including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
1408
+ limit and includes prior recorded usage in its cost estimate.
1409
+
1333
1410
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1411
+ Bulk checkout, scan, and recovery processes select host tools outside every local
1412
+ source and campaign checkout. Inventory uses an external ripgrep executable or
1413
+ the copy shipped with the selected Codex installation.
1414
+
1415
+ On POSIX, campaign processes and script-based inventory tools search readable
1416
+ tool directories. Launchers must be readable so their shebang interpreters can
1417
+ be checked. Use an absolute interpreter path for campaign scripts, including
1418
+ `#!/usr/bin/env sh`, because workers run in different directories. If a directory
1419
+ contains an ineligible executable, its other tools remain available through a
1420
+ temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
1421
+ their installed location when the packaged dispatcher can start. Keep other
1422
+ prefix-sensitive tools, including Python virtual environments, in directories
1423
+ where every entry can be used. On Windows, the campaign omits a tool directory
1424
+ from the child PATH if its Git, ripgrep, or Node executable link passes through a
1425
+ selected source.
1426
+
1334
1427
  CSV scopes are literal paths relative to each checkout, including names such
1335
1428
  as `~/src`.
1336
1429
  Configured diff or working-tree scopes are rejected unless every affected row
@@ -1361,6 +1454,12 @@ require a new output directory. Version 1 manifests also require a new directory
1361
1454
  because their original knowledge inputs and direct overrides cannot be verified.
1362
1455
  Worker and retry counts can change when resuming.
1363
1456
 
1457
+ On POSIX, local repository paths retain `..` components in the campaign manifest
1458
+ so distinct symlink traversals remain distinct sources. Older campaigns may have
1459
+ recorded a normalized absolute path instead. Use that recorded path to resume the
1460
+ previously selected source; it can differ from the physical target selected by
1461
+ the original traversal. Use a new output directory to scan the corrected target.
1462
+
1364
1463
  ### Recovering failed or interrupted bulk scans
1365
1464
 
1366
1465
  Use the original CSV, output directory, and options:
@@ -1514,7 +1613,7 @@ SARIF compatibility, and the local preview.
1514
1613
 
1515
1614
  ## Import SonarQube Cloud issues
1516
1615
 
1517
- `import sonar --dry-run` writes a private capture and returns its path. Preview
1616
+ `import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
1518
1617
  that capture for the intended destination before confirming. A Cloud confirmation
1519
1618
  saves the issues locally and publishes them. Use `--full-output` with
1520
1619
  `--format json` or `--format jsonl` for a structured result.
@@ -1564,9 +1663,13 @@ Enterprise repository URL or its Cloud ID. Either works for retries. If
1564
1663
  several connectors share the URL, use the ID. You can import before the
1565
1664
  repository's first native scan.
1566
1665
 
1567
- Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
1568
- set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
1569
- again with the ChatGPT account you want to use.
1666
+ Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
1667
+ `cli_auth_credentials_store` set in your Codex `config.toml`
1668
+ (`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
1669
+ can be saved in the system keyring. To publish, set
1670
+ `cli_auth_credentials_store = "file"` there, then run `codex-security login`
1671
+ with the ChatGPT account you want to use. `codex-security login status`
1672
+ checks the current sign-in without changing credential storage.
1570
1673
 
1571
1674
  ### Review the Cloud destination
1572
1675
 
@@ -1577,11 +1680,10 @@ Run the command with `--dry-run --format json`. Check `accountId`,
1577
1680
  - **Private findings inbox.** If the preview includes `privateImport`, the
1578
1681
  report goes to your inbox. The repository and connector identify the
1579
1682
  suggested assessment target. Check `format`, `bytes` and `sha256` in
1580
- `privateImport` to identify the upload. For an Endor Finding, an Endor
1581
- `list.objects` response or a Wiz vulnerability JSON export, the CLI can
1582
- send the original bytes when Cloud accepts the format and every record
1583
- matches your selection. Other inputs, including arrays of selected Endor
1584
- Findings, use `security.findings.v1`.
1683
+ `privateImport` to identify the upload. The CLI and SDK encode the reviewed
1684
+ occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
1685
+ inbox that requires native records or has a smaller upload limit can receive
1686
+ native records that reproduce the reviewed evidence.
1585
1687
  - **Repository publisher.** Check `repository.environment_id` in each entry
1586
1688
  of `requests`. The publisher checks the current source versions. Existing
1587
1689
  records keep their environment. New records use the repository's authorized
@@ -1610,10 +1712,10 @@ instructions. API requests always use the API root. The older
1610
1712
  ### Resume interrupted imports
1611
1713
 
1612
1714
  If the result includes `savedSubmission`, keep that checkpoint. Rerun the
1613
- original command with `--dry-run --format json` using the same input, account,
1715
+ original command with `--dry-run --format json` using the same build, input, account,
1614
1716
  destination, API endpoint and state directory. Check `cloudApiUrl`. If
1615
1717
  `resumed` is true, confirm to continue the saved submission. If it's false,
1616
- review the new submission before confirming.
1718
+ review the new submission before confirming. Finish older-format pending submissions with the client that created them. If a response was lost, check the inbox job or repository records before starting a fresh upload.
1617
1719
 
1618
1720
  - **Private inbox.** The CLI checks the report digest and reuses its saved
1619
1721
  request IDs. It can read an accepted job even if the deployment has since
@@ -1699,7 +1801,10 @@ The provider guide describes [package JSON and CSV](https://github.com/openai/co
1699
1801
 
1700
1802
  ### Publish completed scans
1701
1803
 
1702
- Preview selected completed scans before uploading:
1804
+ The public `publish scan --help` menu describes Linear and custom publication
1805
+ from saved scans. The CSV input below belongs to Cloud publication.
1806
+ The following workflow is available to installations with Cloud publication access.
1807
+ Preview selected completed scans locally before uploading them.
1703
1808
 
1704
1809
  ```bash
1705
1810
  codex-security publish scan --to cloud --dry-run --json
@@ -1713,12 +1818,15 @@ prefix of at least eight characters, or `latest` for the current repository.
1713
1818
  Local sealed artifacts are required. Dry runs need no login or network access.
1714
1819
 
1715
1820
  Uploads require ChatGPT credentials saved to a file. Set
1716
- `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.
1717
- Cloud publication rejects automatic/keyring storage even when `auth.json` exists,
1718
- because that file may be stale or belong to another account.
1719
-
1720
- Use a positional scan directory or repeated `--scan-dir PATH` for artifacts
1721
- outside history. Each must contain one completed sealed scan, not a bulk-run
1821
+ `cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
1822
+ `codex-security login` again. Login, scans and other commands use that setting
1823
+ for the Codex Security sign-in.
1824
+ A dedicated login using automatic storage can publish if Codex Security
1825
+ recorded the native file fallback. An unverified file can belong to another
1826
+ account, so Cloud publication requires an explicit file store for an ambient login.
1827
+
1828
+ Use `publish scan DIR --to cloud` for one directory outside history. For
1829
+ multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
1722
1830
  directory or `results.jsonl`. Do not mix directories with `--scan`.
1723
1831
  Cloud also accepts exported CSV:
1724
1832
 
@@ -1750,7 +1858,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
1750
1858
  for the picker. Live publication and `--skip-existing` require local history.
1751
1859
  A directory-only dry run does not.
1752
1860
 
1753
- `--linear-project PROJECT_ID` (`--project`) selects a project. Flags override
1861
+ `--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
1862
+ `--project PROJECT_ID` spelling continue to work. Flags override
1754
1863
  `CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
1755
1864
  previews titles offline; `--json` returns structured output.
1756
1865
 
@@ -1762,10 +1871,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
1762
1871
 
1763
1872
  ```bash
1764
1873
  codex-security publish check /path/to/completed-scan \
1765
- --to linear --linear-team TEAM_ID --json
1874
+ --linear-team TEAM_ID --json
1766
1875
  ```
1767
1876
 
1768
- `publish check` verifies artifacts and recorded publications. With an API key,
1877
+ `publish check` verifies scan artifacts and recorded Linear publications. With an API key,
1769
1878
  it also checks authentication and destination access. It does not test issue
1770
1879
  creation; connected-app access is reported as `not-checked`.
1771
1880
 
@@ -1824,7 +1933,9 @@ request. It sends the config name without findings or account identifiers.
1824
1933
  If the request fails, times out, or returns an invalid rubric, the built-in
1825
1934
  rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
1826
1935
  uses your policy for every review. Rubrics and repeatable `--knowledge-base`
1827
- context accept text, PDF, DOCX, and directories.
1936
+ context accept text, PDF, DOCX, and directories. Select external documents directly.
1937
+ Links in the artifact directory or a saved checkout must stay inside their source.
1938
+ When `--scan` cannot verify the saved checkout, use the document's canonical path.
1828
1939
 
1829
1940
  Each finding is classified three times by default. `--runs N` accepts
1830
1941
  an integer from 1 through 10; SDK options use `classificationRuns` with the same
@@ -1866,15 +1977,17 @@ or effort. A successful
1866
1977
  run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
1867
1978
  unchanged.
1868
1979
 
1869
- Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
1870
- `uniqueFindingIds` can represent findings from another scan; replace an outside-scan
1871
- representative with a member of its `duplicateGroups` entry from this scan.
1980
+ Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
1981
+ `scanRepresentativeFindingIds` for this selection, in the same order as its
1982
+ corpus-wide `uniqueFindingIds`.
1872
1983
  Linear publication defaults to saved classification selection, omits exclusions,
1873
1984
  and uses assessed severity for title and priority. Descriptions retain original
1874
1985
  severity and add the classification rationale. Publication rejects incomplete or
1875
1986
  stale assessments. It never reclassifies or rereads the rubric at publication time.
1876
1987
 
1877
1988
  ```bash
1989
+ # List the IDs you can pass to --finding-id.
1990
+ codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
1878
1991
  codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
1879
1992
  --finding-id FINDING_ID
1880
1993
  codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
@@ -1889,46 +2002,32 @@ import {
1889
2002
  classifySeverity,
1890
2003
  classifyScanSeverity,
1891
2004
  classifyScanDirectorySeverity,
2005
+ deduplicateScanDirectory,
1892
2006
  publishScan,
1893
- type FindingsDocument,
1894
2007
  } from "@openai/codex-security";
1895
- import { readFile } from "node:fs/promises";
1896
- import { join } from "node:path";
1897
2008
 
1898
2009
  // Assess supplied reports in memory.
1899
- const classification = await classifySeverity(findings, {
2010
+ await classifySeverity(findings, {
1900
2011
  rubricPath: "/path/to/policy.md",
1901
2012
  knowledgeBasePaths: ["/path/to/context.md"],
1902
2013
  });
1903
2014
 
1904
2015
  // Save assessments for a scan ID or sealed directory.
1905
2016
  await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
1906
- const scanFindings = (
1907
- JSON.parse(
1908
- await readFile(join(scanDirectory, "findings.json"), "utf8"),
1909
- ) as FindingsDocument
1910
- ).findings;
1911
- const scanFindingIds = new Set(
1912
- scanFindings.map((finding) => finding.findingId),
1913
- );
1914
- // dedupeResult was produced by deduplicating this same scan.
1915
- const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
1916
- if (scanFindingIds.has(representative)) return representative;
1917
- return dedupeResult.duplicateGroups
1918
- .find((group) => group.includes(representative))!
1919
- .find((member) => scanFindingIds.has(member))!;
2017
+ const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
2018
+ repository: "/path/to/repository",
1920
2019
  });
1921
- await classifyScanDirectorySeverity(scanDirectory, {
2020
+ const classification = await classifyScanDirectorySeverity(scanDirectory, {
1922
2021
  rubricPath: "/path/to/policy.md",
1923
- findingIds: selectedIds,
2022
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1924
2023
  });
1925
2024
 
1926
- // Or supply an in-memory assessment directly to publication.
2025
+ // Preview Linear publication for those same findings using their assessments.
1927
2026
  await publishScan(scanDirectory, {
1928
2027
  destination: "linear",
1929
2028
  teamId: "TEAM_ID",
1930
2029
  classification,
1931
- findingIds: classification.assessments.map(({ findingId }) => findingId),
2030
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1932
2031
  dryRun: true,
1933
2032
  });
1934
2033
  ```
@@ -2035,24 +2134,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
2035
2134
  ## Scan history and reruns
2036
2135
 
2037
2136
  Commands default to the current repository. IDs accept unique prefixes of at
2038
- least eight characters.
2039
-
2040
- | Command | Purpose |
2041
- | ----------------------------------------------------- | ---------------------------------------------------------- |
2042
- | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
2043
- | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
2044
- | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
2045
- | `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |
2046
- | `scans rerun [SCAN_ID]` | Repeat on the current checkout. |
2047
- | `scans match BEFORE AFTER` | Link findings with the same root cause. |
2048
- | `scans match --all` | Match completed scans across worktrees/clones. |
2049
- | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2050
- | `findings list [REPOSITORY]` | List open findings. |
2051
- | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2052
- | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2053
-
2054
- Without an ID, `scans show` selects the latest completed scan, while `scans logs`
2055
- selects the latest scan of any status. After a successful scan followed by a
2137
+ least eight characters. Reading empty history leaves the workbench database uninitialized.
2138
+
2139
+ Linked Git worktrees share scans, findings, and reviewer decisions when their
2140
+ scans record the same repository generation in the selected state database.
2141
+ Older scans without this evidence remain target-local. Removed worktrees retain
2142
+ their recorded history; a reused checkout path does not inherit its previous
2143
+ owner's history. Separately verified clones can still be compared explicitly,
2144
+ but their finding histories remain separate.
2145
+
2146
+ Finding confirmation and automatic post-scan matching follow completion order
2147
+ in the workbench, without changing sealed report timestamps.
2148
+
2149
+ | Command | Purpose |
2150
+ | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
2151
+ | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
2152
+ | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
2153
+ | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
2154
+ | `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
2155
+ | `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
2156
+ | `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
2157
+ | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2158
+ | `findings list [REPOSITORY]` | List open findings. |
2159
+ | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2160
+ | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2161
+
2162
+ In the terminal, `findings list` shows the occurrence ID for each open finding.
2163
+ Copy that ID into `findings false-positive` with your reason. Subsequent scans can
2164
+ use the explanation while it applies. In `scans show SCAN_ID --json`, each
2165
+ displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
2166
+ a repository with no saved scan history separately from one with zero open findings.
2167
+ From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
2168
+
2169
+ With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
2170
+ selects the latest scan of any status. Both prefer a scan in the current
2171
+ worktree when one qualifies. After a successful scan followed by a
2056
2172
  failed or active scan, these defaults refer to different runs. Human output
2057
2173
  identifies the selected run, labels its saved update time, and gives matching
2058
2174
  commands with its full scan ID:
@@ -2070,7 +2186,10 @@ history. Inspect its saved status before choosing resume or rerun, and supply
2070
2186
  the original custom prompt files for reruns. Structured history and log output
2071
2187
  and command selection defaults are unchanged.
2072
2188
 
2073
- Reruns use the current checkout/context files and do not reload project files.
2189
+ Without an ID, rerun selects the latest completed scan in the current worktree.
2190
+ If only a related checkout has a completed scan, rerun shows its ID, path, and
2191
+ revision. Pass that ID to run the saved recipe using the files currently at its
2192
+ saved checkout and context paths. Reruns do not reload project files.
2074
2193
  The readable scan recipe records your authentication choice. A separate private
2075
2194
  replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
2076
2195
  `model_providers` settings, including any credentials written directly in
@@ -2106,6 +2225,17 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
2106
2225
  writable, and outside the target repository. Session logs may contain sensitive
2107
2226
  data even though scan recipes do not store credentials.
2108
2227
 
2228
+ Keep the same state directory across linked worktrees. Changing it selects
2229
+ separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
2230
+ filters recorded artifact paths; it does not import another directory's scans.
2231
+
2232
+ The workbench records the outer checkout directory when it registers a target.
2233
+ A later nested checkout cannot make tools from that directory eligible for
2234
+ automatic discovery. When an older saved target lacks a recorded checkout
2235
+ directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
2236
+ executable outside the checkouts. If you use a system Python instead of the
2237
+ Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
2238
+
2109
2239
  Saved scan logs retain the finishing turn, including its final response, and
2110
2240
  exclude later turns once the scan records a completion boundary. Older scans
2111
2241
  retain the full history of their attributed sessions and keep their existing
@@ -2117,19 +2247,42 @@ work on all supported Node.js versions, including logs, feedback attachments,
2117
2247
  usage accounting, and saved-session discovery for resume. A bundled decoder
2118
2248
  reads concatenated frames and reports truncated streams as collection errors.
2119
2249
 
2120
- ### Resuming an interrupted Deep Scan
2250
+ ### Resuming an interrupted scan
2121
2251
 
2122
2252
  ```bash
2123
2253
  codex-security scans list --scan-root /path/to/security-scans
2124
2254
  codex-security scans resume SCAN_ID
2125
2255
  ```
2126
2256
 
2257
+ The terminal list shows the full scan ID and labels the last activity of a
2258
+ `running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
2259
+ launch recipe and its original session, it also shows the resume command to use after interruption.
2260
+
2127
2261
  The scan must still be `running`, with its original checkout, output directory,
2128
2262
  and Codex session in the same state directory. Checkout identity, revision, and
2129
2263
  contents must match. Completed, failed, and canceled scans need a rerun instead.
2130
2264
 
2131
- Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
2132
- settings/instructions. Knowledge-bearing scans save their extracted documents in
2265
+ On Windows, keep the protected `.codex-security-resume` directory in the scan
2266
+ output. It lets the workbench verify the original output even before the first
2267
+ checkpoint. If an older scan stopped with an empty output, start a new scan with
2268
+ `codex-security scans rerun SCAN_ID`.
2269
+
2270
+ New Windows Standard and Deep Scans also record the checkout's native volume and file ID
2271
+ when the filesystem supplies them. Validation and remediation verify the same
2272
+ checkout identity. An older scan can resume across Python
2273
+ versions when its saved checkout identity can be verified. If the workbench
2274
+ cannot verify it, resume with the Python runtime that started the scan or use
2275
+ `codex-security scans rerun SCAN_ID` to start a new scan.
2276
+
2277
+ Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
2278
+ and accumulated cost. A Standard scan continues in its original Codex session with
2279
+ the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
2280
+ can run it at a time. If the connection fails after the session is saved, the CLI
2281
+ prints the resume command. Work since the last checkpoint may need to be repeated.
2282
+ Use `scans rerun` for canceled or failed scans, including authentication failures.
2283
+ For custom validation, rerun with the original validation instructions.
2284
+
2285
+ Knowledge-bearing scans save their extracted documents in
2133
2286
  the private `.scan-knowledge.json` continuation file beside the scan artifacts.
2134
2287
  Resume verifies and uses that snapshot even if the original files changed or were
2135
2288
  deleted. Preserve it with the scan directory; canonical reports do not embed its
@@ -2147,7 +2300,10 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
2147
2300
 
2148
2301
  ### Matching saved scans
2149
2302
 
2150
- Matching uses sealed artifacts and cached decisions unless `--force` is supplied.
2303
+ Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
2304
+ and save its matching decisions. Pass `--force` to recompute saved matches.
2305
+ The older `scans match BEFORE AFTER` spelling is also supported.
2306
+ Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
2151
2307
  Comparisons classify findings as new, persisting, reopened, not observed, resolved,
2152
2308
  or unknown. An absent finding in the later scope is not observed; absence alone
2153
2309
  does not verify remediation. A finding is resolved only after it was explicitly
@@ -2214,6 +2370,10 @@ must already exist.
2214
2370
 
2215
2371
  SARIF is the default format, and `./results.sarif` is the default output path.
2216
2372
  Use `--export-format json` or `--export-format csv` to choose another format.
2373
+ An existing default output file is preserved. Pass `--output FILE` to choose
2374
+ a filename or explicitly replace it. Use `--output -` to pipe the complete
2375
+ artifact. Response filters, token controls, and `--full-output` require a
2376
+ command that returns a formatted response.
2217
2377
  To select a saved scan by its ID and export JSON, run:
2218
2378
 
2219
2379
  ```bash
@@ -2385,10 +2545,11 @@ codex-security install-hook /path/to/repository
2385
2545
 
2386
2546
  To migrate an existing generated hook, verify it is a regular file used only by
2387
2547
  this repository and contains only the generated commands. Rerun `install-hook`
2388
- with `--fail-on-severity` set to its original threshold. It recognizes the legacy
2389
- `npx` hook and supported earlier templates with matching absolute Node and CLI
2390
- paths. If it refuses to overwrite the verified hook, back it up, remove it and
2391
- reinstall with the same threshold. Restore the backup if installation fails.
2548
+ with the desired `--fail-on-severity` level to change the threshold. The installer
2549
+ recognizes the legacy `npx` hook and earlier generated templates with matching
2550
+ absolute Node and CLI paths. It refuses to replace a hand-edited hook.
2551
+ On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
2552
+ could not execute it. The installer checks that the resulting hook is executable.
2392
2553
  The installer uses host Git for the selected repository and respects
2393
2554
  `core.hooksPath`.
2394
2555
 
@@ -2417,6 +2578,14 @@ codex-security patch --scan SCAN_ID --severity high --json
2417
2578
  codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
2418
2579
  ```
2419
2580
 
2581
+ For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
2582
+ `file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
2583
+ requires the file to exist. A missing file stops the command before the model
2584
+ runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
2585
+ special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
2586
+ also require an existing file. Use `text:/path is exposed` to pass path-shaped
2587
+ prose verbatim, or `text:text:example` for a finding that starts with `text:`.
2588
+
2420
2589
  Context inputs are optional and can be combined:
2421
2590
 
2422
2591
  - `--context TEXT` adds inline security context or reviewer feedback.
@@ -2424,6 +2593,7 @@ Context inputs are optional and can be combined:
2424
2593
  - Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
2425
2594
  document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
2426
2595
  are searched recursively; binary files, symlinks, and Git metadata are skipped.
2596
+ When validating from a Git checkout, select external documents directly.
2427
2597
 
2428
2598
  Inline and file context are included in the prompt. Knowledge-base documents are
2429
2599
  prepared in a temporary directory for Codex to read during the assessment, then
@@ -2574,7 +2744,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
2574
2744
  task. The container must provide it. There is no automatic fallback; optional
2575
2745
  patch-risk assessment still uses its read-only sandbox.
2576
2746
 
2577
- `scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
2747
+ `scan --patch` runs after a complete scan without a cost limit. A cost-limited
2748
+ scan saves the findings and skips the interactive patch offer. Use
2749
+ `codex-security patch --scan SCAN_ID` to patch separately.
2750
+ `--patch-severity` defaults to `low`;
2578
2751
  `high` selects high and critical findings. Interactive users can select findings
2579
2752
  and add instructions. The interactive finding browser lists critical, high,
2580
2753
  medium, then low findings, preserving scan order within each severity.
@@ -2641,7 +2814,10 @@ SDK's local `validate()` and `patch()` methods use the same fallback.
2641
2814
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2642
2815
 
2643
2816
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2644
- `--json` returns structured output. Exit codes are `0` when all findings are
2817
+ Without output options, each finding prints a verdict and its evidence.
2818
+ Explicit output formats, field selection and token controls operate on the
2819
+ structured result containing `repository`, optional `scanId`, and `results`.
2820
+ Exit codes are `0` when all findings are
2645
2821
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2646
2822
  With `--json` or `--format jsonl`, authentication and execution failures return
2647
2823
  `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
@@ -2654,21 +2830,112 @@ retain exit codes `130` and `143` without a result.
2654
2830
 
2655
2831
  ## Command discovery and integrations
2656
2832
 
2657
- Use `--llms` for the command manifest, `scan --schema --format json` for its
2658
- schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
2833
+ Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
2834
+
2835
+ Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
2659
2836
  `--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
2660
2837
  `--filter-output`, `--token-limit`, and `--token-offset` options accept either
2661
2838
  `--option value` or `--option=value`.
2662
2839
 
2840
+ `--token-limit` and `--token-offset` take nonnegative integers and select a
2841
+ text view of the formatted result. Truncated JSON and JSONL views are returned
2842
+ as a JSON string containing the excerpt and its token range. With
2843
+ `--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
2844
+ the next page when more tokens are available. `--token-count` returns the
2845
+ estimated size instead. A failed full-output JSON or JSONL response always
2846
+ retains its error code and message. If the failure carries result data,
2847
+ `--token-count` reports its size in `meta.tokenCount`.
2848
+
2663
2849
  `skills add` syncs generated CLI command guidance; it does not install the full
2664
2850
  Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
2665
2851
  only read-only `info` because the transport cannot cancel scans. For the plugin's
2666
2852
  scan, triage, patch, and verification workflows, see the
2667
2853
  [agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
2668
2854
 
2855
+ Both installers default to `--scope user`. Use `--scope project` for the current
2856
+ directory. Existing scripts can continue using `--no-global` for project scope.
2857
+ Inspect either command with `--help`, `--schema`, or `--version` before installing.
2858
+
2859
+ `skills add --depth 0` creates a single skill. The default depth of 1 groups
2860
+ guidance by top-level command. To check the installed files, use the same
2861
+ depth with `skills list`, for example `skills list --depth 0 --json`. Each
2862
+ entry includes its canonical `SKILL.md` locations in the current project and
2863
+ user profile.
2864
+
2865
+ `mcp add` registers detected compatible clients. If it finds none in the
2866
+ selected scope, choose a client with `--agent NAME` (repeatable), or register
2867
+ every compatible client with `--all`. For example, `mcp add --scope project
2868
+ --agent cursor` writes Cursor's project configuration. In user scope, Codex
2869
+ detection and registration use `CODEX_HOME` when set. Amp supports user
2870
+ registration only.
2871
+
2872
+ The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
2873
+ an installed executable, use its name or path with `--exec` and repeat
2874
+ `--arg=VALUE` for each argument. Each value is stored literally, including
2875
+ spaces, empty arguments, and leading dashes. To run an npm package, select
2876
+ `--package NAME`. The existing `--command` accepts a command line or HTTP(S)
2877
+ URL. Quotes group command-line words, and backslashes are literal. A bare
2878
+ executable name is stored directly. Use `--exec` for a path with
2879
+ spaces, including when the executable will be installed on another machine.
2880
+
2881
+ ```bash
2882
+ codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
2883
+ codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
2884
+ ```
2885
+
2886
+ `mcp doctor` checks the current CLI's server startup and tool catalog. To
2887
+ verify a registered launcher, connect from the client where it was registered.
2888
+
2669
2889
  For local findings storage, deduplication, and custom endpoints, see the
2670
2890
  [findings guide](findings-service.md).
2671
2891
 
2892
+ ### Shell completions
2893
+
2894
+ The generated scripts register both `codex-security` and `cs`. Choose your shell
2895
+ and open a new session after saving the setup.
2896
+
2897
+ **Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
2898
+
2899
+ ```bash
2900
+ source <(codex-security completions bash)
2901
+ ```
2902
+
2903
+ **Zsh.** In `~/.zshrc`, load the generated script after your completion system
2904
+ calls `compinit`. If you initialize completions yourself, use:
2905
+
2906
+ ```zsh
2907
+ autoload -Uz compinit
2908
+ compinit
2909
+ source <(codex-security completions zsh)
2910
+ ```
2911
+
2912
+ **Fish.** Add this line to `~/.config/fish/config.fish`:
2913
+
2914
+ ```fish
2915
+ codex-security completions fish | source
2916
+ ```
2917
+
2918
+ **Nushell.** Save the generated closures alongside `config.nu`:
2919
+
2920
+ ```nu
2921
+ codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
2922
+ ```
2923
+
2924
+ In `config.nu`, source the file and dispatch the two names to their completers:
2925
+
2926
+ ```nu
2927
+ source codex-security-completions.nu
2928
+ let previous_completer = $env.config.completions.external.completer?
2929
+ $env.config.completions.external.enable = true
2930
+ $env.config.completions.external.completer = {|spans|
2931
+ match $spans.0 {
2932
+ "codex-security" => { do $_incur_complete_codex_security $spans }
2933
+ "cs" => { do $_incur_complete_cs $spans }
2934
+ _ => { if $previous_completer != null { do $previous_completer $spans } }
2935
+ }
2936
+ }
2937
+ ```
2938
+
2672
2939
  ### Hosted Standard scan
2673
2940
 
2674
2941
  `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.