@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/dist/cli.js CHANGED
@@ -20,53 +20,56 @@ import { execFile as execFileCallback, execFileSync, spawn, } from "node:child_p
20
20
  import { createHash, randomUUID } from "node:crypto";
21
21
  import { errorMonitor } from "node:events";
22
22
  import { accessSync, constants, createReadStream, existsSync, lstatSync, realpathSync, writeSync, } from "node:fs";
23
- import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rm, writeFile, } from "node:fs/promises";
23
+ import { chmod, lstat, mkdtemp, open, readFile, readdir, readlink, realpath, rm, writeFile, } from "node:fs/promises";
24
24
  import { tmpdir } from "node:os";
25
- import { basename, dirname, isAbsolute, join, parse, relative, resolve, win32, } from "node:path";
25
+ import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep, win32, } from "node:path";
26
26
  import { cwd } from "node:process";
27
27
  import { createInterface } from "node:readline";
28
28
  import { Readable, Writable as NodeWritable } from "node:stream";
29
29
  import { fileURLToPath, pathToFileURL } from "node:url";
30
30
  import { isDeepStrictEqual, parseArgs, promisify, stripVTControlCharacters, } from "node:util";
31
31
  import { Cli, Formatter, z } from "incur";
32
+ import { completeCli, completionShell, serveIntegration, } from "./cli-integrations.js";
32
33
  import stringWidth from "string-width";
33
34
  import Ajv2020 from "ajv/dist/2020.js";
34
35
  import { formatCliHelp } from "./cli-help.js";
36
+ import { formatJsonTokenView } from "./cli-token-view.js";
35
37
  import { formatCoverageScope } from "./coverage-presentation.js";
36
38
  import { resolveSkillAuthentication } from "./skill-authentication.js";
37
39
  import { scanLogsJson } from "./cli-scan-logs-json.js";
38
- import { ARTIFACT_EXPORT_FILENAMES, exportEnvironment, resolveArtifactFormat, resolveArtifactExportOutput, resolveSavedArtifactDirectory, runArtifactExport, writeArtifactOutput as writeCliOutput, } from "./artifact-export.js";
40
+ import { ARTIFACT_EXPORT_FILENAMES, exportEnvironment, resolveArtifactFormat, artifactSourceProtectionRoots, resolveArtifactExportOutput, resolveSavedArtifactDirectory, runArtifactExport, writeArtifactOutput as writeCliOutput, } from "./artifact-export.js";
39
41
  export { exportEnvironment } from "./artifact-export.js";
40
42
  import { parse as parseToml } from "smol-toml";
41
- import { classifyConnectionFailure, CodexSecurity, environmentValue, formatEnvironmentVariableRemovalGuidance, initialCredentialsAvailable, scanCodexHome, listRepositoryFindings, SCAN_AUTH_MODES, scanAuthentication, runtimeScanAuthentication, selectedScanEnvironment, } from "./api.js";
42
- import { accountStatus, CODEX_AUTH_CONFIG_KEYS, NO_CREDENTIALS_MESSAGE, configuredCodexHome, environmentEntry, readCodexHomeConfig, withoutOpenAiApiKeys, } from "./auth.js";
43
+ import { classifyConnectionFailure, connectionAdviceDetail, CodexSecurity, environmentValue, formatEnvironmentVariableRemovalGuidance, initialCredentialsAvailable, scanCodexHome, listRepositoryFindings, SCAN_AUTH_MODES, scanAuthentication, runtimeScanAuthentication, selectedScanEnvironment, } from "./api.js";
44
+ import { accountStatus, nativeLogoutArgs, prepareLoginConfig, NO_CREDENTIALS_MESSAGE, configuredCodexHome, environmentEntry, readCodexHomeConfig, withoutOpenAiApiKeys, } from "./auth.js";
43
45
  import { loadContract, sha256Text } from "./contract.js";
44
46
  import { formatDeepScanReviews, } from "./scan-progress.js";
45
- import { isRecord as isJsonObject } from "./record.js";
47
+ import { asRecord, isRecord as isJsonObject } from "./record.js";
46
48
  import { suggestOwnersInternal } from "./suggest-owners.js";
47
49
  import { parseImportedFindings } from "./findings-import.js";
48
50
  import { publishScanToCustom } from "./custom-publish.js";
49
51
  import { ExternalPublicationError, prepareExternalPublication, } from "./external-findings-publish.js";
50
52
  import { prepareLocalExternalImport } from "./external-findings-import.js";
51
53
  import { validateInspectorProjectMapping } from "./inspector-findings.js";
52
- import { listLocalExternalFindings, } from "./external-findings-local.js";
54
+ import { readLocalExternalFindings, } from "./external-findings-local.js";
53
55
  import { prepareSonarImport } from "./sonar-import.js";
54
56
  import { EXTERNAL_FINDINGS_PROVIDERS, EXTERNAL_FINDINGS_READERS, requireCloudReader, } from "./external-findings-read.js";
55
57
  import { externalImportDisposition, NoPublishableFindingsError, } from "./external-findings.js";
56
58
  import { publishPatchReview, resolvePatchReviewPublisher, } from "./patch-publication.js";
57
59
  import { DEFAULT_DEDUPE_CONCURRENCY } from "./deduplication/deduplication.js";
58
- import { savedScanWorkbench } from "./saved-scan-bootstrap.js";
60
+ import { savedCheckoutBoundaries, savedDiscoveryRoots, savedScanWorkbench, } from "./saved-scan-bootstrap.js";
59
61
  import { deduplicateScanInternal } from "./deduplication/scan.js";
60
62
  import { runHostRecordsProtocol } from "./host-records-protocol.js";
61
63
  import { runHostedScanProtocol } from "./hosted-scan-protocol.js";
62
64
  import { runHostedRemediationProtocol } from "./hosted-remediation-protocol.js";
63
- import { FindingPatchSchema as findingPatchSchema, parseFindingVerifications, remediationPrompt, verificationBatches, VerificationModeSchema, } from "./remediation.js";
65
+ import { FindingPatchSchema as findingPatchSchema, parseFindingVerifications, remediationPrompt, verificationBatches, VerificationModeSchema, FindingPatchSchema, FindingVerificationSchema, } from "./remediation.js";
64
66
  import { classifyScanSeverityInternal, classifyScanDirectorySeverityInternal, } from "./classify-scan-severity.js";
65
67
  import { resolveCompletedScan, resolveWorkflowScan, } from "./saved-scan.js";
66
68
  import { publishFindingsCsvToCloud, publishScanToCloud, } from "./cloud-publish.js";
67
69
  import { createBulkScanDiscoveryDependencies, createTerminalPrompt, runBulkScanWizard, } from "./bulk-scan-discovery.js";
68
- import { DEFAULT_CODEX_CONFIG, deepMerge, EXTERNAL_CODEX_PROVIDERS, isExternalModelProvider, mergeCodexOverrides, hasCommandAuth, inlineToml, quoteTomlString, modelProviderConfigOverride, resolveCommandAuthConfig, resolveCodexProfile, mergedCodexConfig, readCodexFileProfile, scanPricingContext, scanModel, scanModelConfiguration, scanModelProvider, scanProviderEnvKey, writeCodexConfig, } from "./config.js";
70
+ import { CODEX_AUTH_CONFIG_KEYS, DEFAULT_CODEX_CONFIG, deepMerge, EXTERNAL_CODEX_PROVIDERS, isExternalModelProvider, mergeCodexOverrides, hasCommandAuth, inlineToml, quoteTomlString, modelProviderConfigOverride, resolveCommandAuthConfig, resolveCodexProfile, mergedCodexConfig, readCodexAuthConfig, readCodexFileProfile, scanPricingContext, scanModel, scanModelConfiguration, scanModelProvider, scanProviderEnvKey, writeCodexConfig, } from "./config.js";
69
71
  import { formatUsd } from "./cost.js";
72
+ import { batchScanBudget } from "./batch-cost.js";
70
73
  import { formatScanCost, formatScanCostTokens, formatTokenUsage, } from "./cost-model.js";
71
74
  import { readRegularInputFile, resolveScanPrompts } from "./prompt-files.js";
72
75
  import { prepareFindingPrompt } from "./finding-prompt.js";
@@ -87,7 +90,7 @@ import { componentPlanSchema } from "./component-plan.js";
87
90
  import { runComponentScans, } from "./component-scan.js";
88
91
  import { checkScanPublication, forceTerminatePublicationProcesses as terminatePublishers, publishScanInternal, } from "./publish.js";
89
92
  import { importScan } from "./import-scan.js";
90
- import { bundledPluginRoot, cleanupSdkDirectory, createIsolatedHome, resolvePluginPath, acquireCodexSecurityCredentialHomeLock, withCredentialHomeLock, requireOutputOutsideRepositories, canonicalizeModelSafePath, codexSecurityCredentialAllowsAmbientImport, codexSecurityCredentialHome, codexSecurityHasStoredFileCredentials, codexSecurityStateDirectory, logoutCredentialHome, executablePathForSpawn, environmentWithGit, expandHome, prepareCodexSecurityCredentialHome, resolveCodexCommand, resolvePluginPython, pluginMetadata, runWorkbench, workbenchEnvironment, sameFile, setCodexSecurityCredentialLogout, } from "./runtime.js";
93
+ import { bundledPluginRoot, runCodexCommand, cleanupSdkDirectory, createIsolatedHome, resolvePluginPath, acquireCodexSecurityCredentialHomeLock, withCredentialHomeLock, writeCredentialHomeConfig, requireOutputOutsideRepositories, canonicalizeModelSafePath, codexSecurityCredentialAllowsAmbientImport, codexSecurityCredentialHome, codexSecurityHasStoredFileCredentials, codexSecurityStateDirectory, logoutCredentialHome, executablePathForSpawn, environmentWithGit, isPythonPathCandidate, expandHome, resolveInputPath, resolveParentTraversal, prepareCodexSecurityCredentialHome, resolveCodexCommand, resolvePluginPython, pluginMetadata, runWorkbench, workbenchEnvironment, setCodexSecurityCredentialLogout, } from "./runtime.js";
91
94
  import { comparisonFindingGroups, selectedComparisonContext, comparisonForScan, matchScanFindingsInternal, unionFindingGroups, } from "./scan-comparison.js";
92
95
  import { scanActivitiesFromEvent } from "./scan-activity.js";
93
96
  import { OperationTelemetry, } from "./operation-telemetry.js";
@@ -101,12 +104,14 @@ import { fitCell, graphemes } from "./terminal-columns.js";
101
104
  import { TerminalErrorListener, } from "./terminal-stream.js";
102
105
  import { ACCOUNT_LIMITS_UNAVAILABLE, formatAccountLimits, formatUsageFreshness, isChatGptAuthentication, USAGE_TIME_UNAVAILABLE, } from "./scan-usage-display.js";
103
106
  import { policyDisplayData, runPolicyCommand, } from "./security-policy-cli.js";
107
+ import { installManagedHook } from "./cli-hook.js";
108
+ import { cliShellLabel, quoteCliPath } from "./cli-argument.js";
104
109
  import { formatSecurityPolicyText as escapeTerminalText } from "./security-policy.js";
105
110
  import { commandGitProtectionRoots } from "./local-git-metadata.js";
106
111
  import { scanPhaseLabel as scanPhase, scanProgressCount, } from "./worker-progress.js";
107
- import { abortable, DiffTarget, enclosingGitWorktreeRoots, gitMarkerRoot, normalizeRepository, trustedGitCommand, UNSUPPORTED_GIT_ENVIRONMENT, relativePathIsOutside as isOutsidePath, } from "./targets.js";
112
+ import { abortable, DiffTarget, resolveRepositoryPath, enclosingGitWorktreeRoots, gitMarkerRoot, normalizeRepository, trustedGitCommand, relativePathIsOutside as isOutsidePath, } from "./targets.js";
108
113
  import { inspectTrustedExecutable, resolveTrustedExecutable, } from "./trusted-executable.js";
109
- import { BUNDLED_PLUGIN_VERSION, checkForUpdate, CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION, formatUpdateNotice, updateNoticeEnabled, VERSION, } from "./version.js";
114
+ import { BUNDLED_PLUGIN_VERSION, checkForUpdate, CODEX_EXECUTABLE_VERSION, CODEX_SDK_VERSION, formatUpdateNotice, installUpdate, invokedWithNpx, updateNoticeEnabled, VERSION, } from "./version.js";
110
115
  import { readProjectConfig, resolveScanSettings, projectScopeTarget, configurationSources, projectConfigStarter, } from "./project-config.js";
111
116
  import { resolveConfigPath } from "./config-path.js";
112
117
  import { deepScanOptions, resolveDeepScanConfig } from "./deep-config.js";
@@ -122,6 +127,14 @@ const FRAMEWORK_VALUE_OPTIONS = new Set([
122
127
  "--token-limit",
123
128
  "--token-offset",
124
129
  ]);
130
+ const INSPECTION_FLAGS = [
131
+ "-h",
132
+ "--help",
133
+ "--schema",
134
+ "--version",
135
+ "--llms",
136
+ "--llms-full",
137
+ ];
125
138
  const OUTPUT_OPTION = /^--(?:format|filter-output|full-output|token-count|token-limit|token-offset)(?:=|$)/u;
126
139
  const HIDE_CURSOR = "\u001B[?25l";
127
140
  const SHOW_CURSOR = "\u001B[?25h";
@@ -129,7 +142,12 @@ const CHILD_TERMINATION_GRACE_MS = 1_000;
129
142
  const DUPLICATE_SIGNAL_WINDOW_MS = 500;
130
143
  const DEFAULT_SCAN_MODEL_CONFIGURATION = scanModelConfiguration(DEFAULT_CODEX_CONFIG);
131
144
  const MODEL_OPTIONS = modelOptions();
132
- const MATCHING_MODEL_OPTIONS = modelOptions("Model for finding matching (default: Codex's configured model).", "Matching reasoning effort (default: medium).");
145
+ const MATCHING_OPTIONS = modelOptions("Model for finding matching (default: Codex's configured model).", "Matching reasoning effort (default: medium).").extend({
146
+ force: z
147
+ .boolean()
148
+ .default(false)
149
+ .describe("Recompute saved finding matches."),
150
+ });
133
151
  const SKILL_CODEX_OVERRIDE_DESCRIPTION = 'Repeat TOML model="gpt-5.6-terra", model_reasoning_effort="high", model_provider="gateway", model_providers.<name>.<key>=VALUE, daybreak=true, or analytics.enabled=false.';
134
152
  const SKILL_CONFIG_OPTIONS = MODEL_OPTIONS.extend({
135
153
  codex: z
@@ -185,7 +203,13 @@ const ASSESS_PATCH_RISK_OPTION = z
185
203
  .default(false)
186
204
  .describe("Assess the completed patch and return the risk report.");
187
205
  function optionValue(flag) {
188
- return z.string().min(1, `${flag} must not be empty.`);
206
+ return z
207
+ .string({
208
+ error: (issue) => issue.input === undefined
209
+ ? `Missing required option ${flag}.`
210
+ : undefined,
211
+ })
212
+ .min(1, `${flag} must not be empty.`);
189
213
  }
190
214
  function remediationInputOptions(verb) {
191
215
  return z.object({
@@ -220,7 +244,10 @@ function linearApiKeyOption() {
220
244
  .describe("Linear personal API key; defaults to CODEX_SECURITY_LINEAR_API_KEY.");
221
245
  }
222
246
  const PUBLICATION_DESTINATION_OPTIONS = z.object({
223
- to: z.literal("linear").describe("Publication destination."),
247
+ to: z
248
+ .literal("linear")
249
+ .default("linear")
250
+ .describe("Publication destination."),
224
251
  linearTeam: optionValue("--linear-team")
225
252
  .optional()
226
253
  .describe("Linear team ID; defaults to CODEX_SECURITY_LINEAR_TEAM."),
@@ -714,15 +741,83 @@ const DEEP_SCAN_OPTION_SCHEMAS = Object.fromEntries(DEEP_SCAN_SETTINGS.flatMap((
714
741
  export function resolveCliPath(directory, value) {
715
742
  return resolveConfigPath(directory, value);
716
743
  }
744
+ const jsonDocument = z.record(z.string(), z.unknown());
745
+ const scanArtifactFields = {
746
+ manifest: jsonDocument,
747
+ findings: jsonDocument,
748
+ review: jsonDocument,
749
+ scanDir: z.string(),
750
+ reportPath: z.string(),
751
+ };
752
+ const retainedScanOutput = z.object({
753
+ ...scanArtifactFields,
754
+ mode: z.string(),
755
+ });
756
+ const completedScanOutput = z.looseObject({
757
+ ...scanArtifactFields,
758
+ artifactsDir: z.string(),
759
+ sarifPath: z.string().nullable(),
760
+ threadId: z.string(),
761
+ turn: jsonDocument,
762
+ cost: jsonDocument.nullable(),
763
+ threatModel: jsonDocument.nullable(),
764
+ threatModelPath: z.string().nullable(),
765
+ repositoryFindings: z.array(jsonDocument).optional(),
766
+ ownerSuggestionsPath: z.string().optional(),
767
+ ownerSuggestionsError: z.string().optional(),
768
+ validation: jsonDocument.optional(),
769
+ warnings: z.array(z.string()).optional(),
770
+ patchSeverity: FailureSeveritySchema.optional(),
771
+ patches: z.array(FindingPatchSchema).optional(),
772
+ pullRequest: jsonDocument.optional(),
773
+ });
774
+ const scanPreflightOutput = z.looseObject({
775
+ ...DeepScanSettingsSchema.shape,
776
+ dryRun: z.literal(true),
777
+ repository: z.string(),
778
+ target: z.object({
779
+ kind: z.enum(["repository", "paths", "refs", "working_tree"]),
780
+ paths: z.array(z.string()),
781
+ base: z.string().optional(),
782
+ head: z.string().optional(),
783
+ baseRef: z.string().optional(),
784
+ headRef: z.string().optional(),
785
+ }),
786
+ mode: ScanSettingsSchema.shape.mode.unwrap(),
787
+ model: z.string(),
788
+ reasoningEffort: z.string(),
789
+ modelProvider: z.string().optional(),
790
+ outputDir: z.string().nullable(),
791
+ stateDirectory: z.string().optional(),
792
+ archiveDir: z.string().optional(),
793
+ authentication: z.looseObject({
794
+ method: z.string(),
795
+ verified: z.literal(false),
796
+ }),
797
+ maxTimeMinutes: ScanSettingsSchema.shape.maxTimeMinutes,
798
+ maxCostUsd: ScanSettingsSchema.shape.maxCostUsd,
799
+ costLimitNote: z.string().optional(),
800
+ knowledgeBasePaths: ScanSettingsSchema.shape.knowledgeBasePaths,
801
+ scanPromptFile: ScanSettingsSchema.shape.scanPromptFile,
802
+ validationPromptFile: ScanSettingsSchema.shape.validationPromptFile,
803
+ failOnSeverity: FailureSeveritySchema.optional(),
804
+ projectConfig: jsonDocument.optional(),
805
+ deepScanSources: jsonDocument.optional(),
806
+ });
807
+ function cliFailureSchema(...codes) {
808
+ return z.object({
809
+ status: z.literal("failed"),
810
+ code: z.literal(codes),
811
+ message: z.string(),
812
+ });
813
+ }
717
814
  function scanOutputSchema(...codes) {
718
815
  return z
719
816
  .union([
720
- z.record(z.string(), z.unknown()),
721
- z.object({
722
- status: z.literal("failed"),
723
- code: z.literal(codes),
724
- message: z.string(),
725
- }),
817
+ completedScanOutput,
818
+ retainedScanOutput,
819
+ scanPreflightOutput,
820
+ cliFailureSchema(...codes),
726
821
  ])
727
822
  .optional();
728
823
  }
@@ -802,9 +897,11 @@ const DEFAULT_DEPENDENCIES = {
802
897
  exportFindings: runArtifactExport,
803
898
  runWorkbench: async (args, input, signal, pythonPath, protectedRoot, gitProtectedRoots = [], pluginPath) => {
804
899
  const checkingTarget = args[0] === "get-scan" && args.includes("--check-target");
900
+ const configuredGit = environmentEntry(process.env, "CODEX_SECURITY_GIT");
805
901
  let environment = !checkingTarget || protectedRoot === undefined
806
902
  ? {
807
903
  ...exportEnvironment(),
904
+ CODEX_SECURITY_GIT: configuredGit,
808
905
  CODEX_SECURITY_STATE_DIR: codexSecurityStateDirectory(),
809
906
  }
810
907
  : workbenchEnvironment(process.env);
@@ -813,18 +910,30 @@ const DEFAULT_DEPENDENCIES = {
813
910
  : typeof protectedRoot === "string"
814
911
  ? [protectedRoot]
815
912
  : protectedRoot).map(async (root) => (await gitMarkerRoot(root, signal, "outermost")) ?? root));
913
+ const configuredPython = pythonPath ?? environmentEntry(environment, "PYTHON");
914
+ const boundaries = configuredPython && isPythonPathCandidate(configuredPython)
915
+ ? undefined
916
+ : await savedCheckoutBoundaries(environment);
816
917
  const python = await resolvePluginPython({
817
918
  configuredPath: pythonPath,
818
919
  environment,
819
920
  signal,
820
921
  protectedRoot: protectedRoot === undefined ? undefined : protectedRoots,
922
+ discoveryProtectedRoots: boundaries
923
+ ? await savedDiscoveryRoots(boundaries, [...boundaries.byTarget.keys()], signal)
924
+ : undefined,
925
+ allowPathLookup: boundaries?.complete,
821
926
  });
822
- if (checkingTarget && protectedRoot !== undefined) {
823
- const git = await inspectTrustedExecutable("git", environment, [
824
- ...protectedRoots,
825
- ...gitProtectedRoots,
826
- ]);
827
- environment = environmentWithGit(git.environment, git);
927
+ if (checkingTarget &&
928
+ gitProtectedRoots.length > 0 &&
929
+ (configuredGit === undefined || isAbsolute(configuredGit))) {
930
+ const git = await inspectTrustedExecutable(configuredGit ?? "git", environment, [...protectedRoots, ...gitProtectedRoots]);
931
+ // Filter knowledge-base tools, then let the workbench choose ambient Git
932
+ // after it also knows the boundaries recorded in the history database.
933
+ environment =
934
+ configuredGit !== undefined || git.executable === null
935
+ ? environmentWithGit(git.environment, git)
936
+ : git.environment;
828
937
  }
829
938
  const workspace = pluginPath === undefined
830
939
  ? undefined
@@ -851,6 +960,8 @@ function signalHandlers(dependencies, operation, interrupt, terminate) {
851
960
  dependencies[`${operation}SignalListener`]("SIGINT", interrupt);
852
961
  dependencies[`${operation}SignalListener`]("SIGTERM", terminate);
853
962
  }
963
+ // Login and status must not load configuration from the caller's checkout.
964
+ const NEUTRAL_CODEX_CWD = parse(process.execPath).root;
854
965
  export async function runCodexSkillCommand(args, output, command = resolveCodexCommand(), processEnvironment = process.env, input) {
855
966
  let journal = null;
856
967
  if (output !== undefined) {
@@ -967,7 +1078,7 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
967
1078
  credentialConfig["model_providers"] = {
968
1079
  [provider]: providerConfiguration,
969
1080
  };
970
- await writeCodexConfig(join(codexHome, "config.toml"), credentialConfig);
1081
+ await writeCredentialHomeConfig(codexHome, credentialConfig);
971
1082
  credentialsAvailable = await initialCredentialsAvailable(selected, configuredCodexHome(selected), codexHome);
972
1083
  selected = {
973
1084
  ...selected,
@@ -1050,11 +1161,9 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
1050
1161
  output?.signal?.throwIfAborted();
1051
1162
  const invocation = spawn(executablePathForSpawn(command.command), [...args], {
1052
1163
  env: environment,
1053
- cwd: output?.appServer?.directory ?? parse(process.execPath).root,
1164
+ cwd: output?.appServer?.directory ?? NEUTRAL_CODEX_CWD,
1054
1165
  stdio: output === undefined
1055
- ? input === undefined
1056
- ? "inherit"
1057
- : ["pipe", "inherit", "inherit"]
1166
+ ? [input === undefined ? "inherit" : "pipe", "inherit", "pipe"]
1058
1167
  : [
1059
1168
  output.appServer !== undefined || input !== undefined
1060
1169
  ? "pipe"
@@ -1111,13 +1220,19 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
1111
1220
  process.on("SIGTERM", onTerminate);
1112
1221
  try {
1113
1222
  let diagnostic = "";
1114
- invocation.stderr?.setEncoding("utf8").on("data", (chunk) => {
1115
- diagnostic += chunk;
1116
- });
1117
- const captured = output === undefined || invocation.stdout === null
1118
- ? Promise.resolve(undefined)
1119
- : Promise.race([
1120
- readSkillCommandOutput(invocation.stdout, output.appServer === undefined
1223
+ let forwarded;
1224
+ if (output === undefined && invocation.stderr) {
1225
+ forwarded = forwardSignInHints(invocation.stderr, processEnvironment);
1226
+ }
1227
+ else {
1228
+ invocation.stderr?.setEncoding("utf8").on("data", (chunk) => {
1229
+ diagnostic += chunk;
1230
+ });
1231
+ }
1232
+ const captured = Promise.race([
1233
+ output === undefined || invocation.stdout === null
1234
+ ? forwarded?.then(() => undefined)
1235
+ : readSkillCommandOutput(invocation.stdout, output.appServer === undefined
1121
1236
  ? undefined
1122
1237
  : {
1123
1238
  ...output.appServer,
@@ -1126,10 +1241,10 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
1126
1241
  onThreadStarted: releaseCredentialHome,
1127
1242
  input: invocation.stdin,
1128
1243
  }),
1129
- new Promise((resolve) => {
1130
- forceCaptureCompletion = () => resolve(undefined);
1131
- }),
1132
- ]);
1244
+ new Promise((resolve) => {
1245
+ forceCaptureCompletion = () => resolve(undefined);
1246
+ }),
1247
+ ]);
1133
1248
  invocationStatus = new Promise((resolve, reject) => {
1134
1249
  const complete = (code, signal) => {
1135
1250
  resolve(requestedSignal === "SIGINT" || signal === "SIGINT"
@@ -1178,6 +1293,10 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
1178
1293
  invocation.stderr?.destroy();
1179
1294
  requestTermination("SIGTERM");
1180
1295
  await invocationStatus?.catch(() => undefined);
1296
+ // The sign-in diagnostic stream is closed; a second diagnostic cannot be delivered.
1297
+ if (output === undefined &&
1298
+ error?.code === "EPIPE")
1299
+ return 1;
1181
1300
  throw error;
1182
1301
  }
1183
1302
  finally {
@@ -1194,6 +1313,32 @@ async function runCodexSkillProcess(args, output, command, processEnvironment, i
1194
1313
  await releaseCredentialHome?.();
1195
1314
  }
1196
1315
  }
1316
+ /** Forward native prompts immediately, including commands split across stderr writes. */
1317
+ async function forwardSignInHints(stderr, environment) {
1318
+ const cli = invokedWithNpx(environment)
1319
+ ? "npx @openai/codex-security"
1320
+ : "codex-security";
1321
+ const hints = ["`codex login", "| codex login"];
1322
+ const rewrite = (text) => text.replace(/(`|\| )codex login(?=[\s`]|$)/gu, `$1${cli} login`);
1323
+ let pending = "";
1324
+ for await (const chunk of stderr.setEncoding("utf8")) {
1325
+ let text = pending + chunk;
1326
+ pending = "";
1327
+ // Hold only a partial command at the end of this chunk.
1328
+ const start = Math.max(text.lastIndexOf("`"), text.lastIndexOf("|"));
1329
+ if (start >= 0) {
1330
+ const tail = text.slice(start);
1331
+ if (hints.some((hint) => hint.startsWith(tail))) {
1332
+ pending = tail;
1333
+ text = text.slice(0, start);
1334
+ }
1335
+ }
1336
+ if (text)
1337
+ await writeCliOutput(process.stderr, rewrite(text));
1338
+ }
1339
+ if (pending)
1340
+ await writeCliOutput(process.stderr, rewrite(pending));
1341
+ }
1197
1342
  /**
1198
1343
  * Stored auth switches homes. Native origins preserve ambient settings at
1199
1344
  * app-server startup, including telemetry controls and model discovery gates.
@@ -1340,76 +1485,41 @@ function handleDisconnectedResize(error) {
1340
1485
  process.stderr.once("error", () => { });
1341
1486
  }
1342
1487
  }
1343
- export async function main(argv = process.argv.slice(2), output = process.stdout, errorOutput = process.stderr, dependencies = DEFAULT_DEPENDENCIES) {
1344
- const remediationOperation = argv[0] === "patch"
1345
- ? "patch"
1346
- : argv[0] === "verify-fix"
1347
- ? "verify"
1348
- : undefined;
1349
- const recordsCommand = argv[0] === "dedupe" ||
1350
- argv[0] === "validate" ||
1351
- argv[0] === "classify-severity"
1352
- ? argv[0]
1353
- : undefined;
1354
- const hostedCommand = argv[0] === "scan" || remediationOperation !== undefined;
1355
- if (((recordsCommand !== undefined && argv.includes("--records")) ||
1356
- (hostedCommand &&
1357
- argv.some((arg) => arg === "--host" || arg.startsWith("--host=")))) &&
1358
- !argv.includes("--help") &&
1359
- !argv.includes("-h") &&
1360
- !argv.includes("--schema")) {
1361
- let classificationRuns;
1362
- if (argv[0] === "classify-severity") {
1363
- try {
1364
- const { values } = parseArgs({
1365
- args: argv.slice(1),
1366
- options: {
1367
- records: { type: "boolean" },
1368
- runs: { type: "string" },
1369
- },
1370
- });
1371
- if (values.runs !== undefined)
1372
- classificationRuns = reviewRunsOption.parse(Number(values.runs));
1373
- }
1374
- catch {
1375
- errorOutput.write(`codex-security: Use --records with only --runs (an integer from 1 to 10; default: ${DEFAULT_REVIEW_RUNS}).\n`);
1376
- return 2;
1377
- }
1378
- }
1379
- else if (argv.length !== 2 || (hostedCommand && argv[1] !== "--host")) {
1380
- errorOutput.write(hostedCommand
1381
- ? `codex-security: --host must be used alone with ${argv[0]}.\n`
1382
- : `codex-security: --records must be used alone with ${argv[0]}.\n`);
1383
- return 2;
1384
- }
1385
- const controller = new AbortController();
1386
- const removeSignals = listenForAbort(dependencies, controller);
1387
- let exitCode;
1388
- try {
1389
- const input = dependencies.recordsInput ?? process.stdin;
1390
- const code = recordsCommand !== undefined
1391
- ? await runHostRecordsProtocol(recordsCommand, input, output, {
1392
- signal: controller.signal,
1393
- classificationRuns,
1394
- })
1395
- : remediationOperation !== undefined
1396
- ? await runHostedRemediationProtocol(input, output, controller.signal, remediationOperation)
1397
- : await runHostedScanProtocol(input, output, controller.signal);
1398
- exitCode =
1399
- controller.signal.reason === "SIGINT"
1400
- ? 130
1401
- : controller.signal.reason === "SIGTERM"
1402
- ? 143
1403
- : code;
1404
- }
1405
- finally {
1406
- removeSignals();
1407
- }
1408
- // Protocol writes have flushed or been canceled. Node's stdout ignores destroy().
1409
- if (output === process.stdout)
1410
- process.exit(exitCode);
1411
- return exitCode;
1412
- }
1488
+ /** Run the standalone CLI, which owns the process and its stdio. */
1489
+ export async function runCli() {
1490
+ let signInInterrupted = false;
1491
+ const exitCode = await main(process.argv.slice(2), process.stdout, process.stderr, DEFAULT_DEPENDENCIES, () => {
1492
+ signInInterrupted = true;
1493
+ });
1494
+ // Managed output and child cleanup are complete. An interrupted prompt may
1495
+ // still have a write pending on stderr if its reader stopped draining.
1496
+ if (signInInterrupted)
1497
+ process.exit(exitCode);
1498
+ return exitCode;
1499
+ }
1500
+ export async function main(argv = process.argv.slice(2), output = process.stdout, errorOutput = process.stderr, dependencies = DEFAULT_DEPENDENCIES, onInterruptedSignIn) {
1501
+ // Build the command tree with no executable arguments for shell callbacks.
1502
+ // Completion words, including literal action flags, belong to the shell.
1503
+ const completion = completionShell.safeParse(process.env["COMPLETE"]);
1504
+ const shellArgv = argv;
1505
+ if (completion.success)
1506
+ argv = [];
1507
+ const separator = argv.indexOf("--");
1508
+ const literalArgs = separator < 0 ? [] : argv.slice(separator + 1);
1509
+ if (separator >= 0)
1510
+ argv = argv.slice(0, separator);
1511
+ const inspection = argv.some((arg) => INSPECTION_FLAGS.includes(arg));
1512
+ const actionFlags = argv.filter((arg) => arg === "--mcp" || arg === "--update");
1513
+ const actionOptions = argv.filter((arg) => arg !== actionFlags[0]);
1514
+ const mixedAction = actionFlags.length > 0 &&
1515
+ (actionFlags.length !== 1 ||
1516
+ literalArgs.length > 0 ||
1517
+ firstNonGlobal(actionOptions, 0) < actionOptions.length ||
1518
+ (actionFlags[0] === "--mcp" && !inspection && actionOptions.length > 0));
1519
+ if (!mixedAction && actionFlags[0] === "--update")
1520
+ argv = ["update", ...actionOptions];
1521
+ if (!mixedAction && actionFlags[0] === "--mcp" && inspection)
1522
+ argv = actionOptions;
1413
1523
  const positionals = [];
1414
1524
  let exitCode = 0;
1415
1525
  let frameworkExit;
@@ -1422,7 +1532,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1422
1532
  let renderedOutput;
1423
1533
  let structuredError = false;
1424
1534
  let failedResultOutput;
1425
- let filteredScanFailure;
1535
+ let unfilteredFailure;
1426
1536
  const includeFailureResults = (format) => argv.includes("--full-output") &&
1427
1537
  (format === "json" ||
1428
1538
  format === "jsonl" ||
@@ -1440,8 +1550,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1440
1550
  const message = errorMessage(outcome.error);
1441
1551
  if (!argv.includes("--full-output")) {
1442
1552
  const data = { status: "failed", code, message };
1443
- if (frameworkFlags.filterOutput)
1444
- filteredScanFailure = { format, data };
1553
+ if (frameworkFlags.filters.length)
1554
+ unfilteredFailure = data;
1445
1555
  return data;
1446
1556
  }
1447
1557
  // Incur would wrap returned data in an ok: true envelope.
@@ -1463,7 +1573,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1463
1573
  const runImport = (options) => withTerminalErrorsHandled(errorOutput, () => runScanImport(options, errorOutput, dependencies));
1464
1574
  const history = async (args, select = (value) => value, pythonPath, protectedRoot) => {
1465
1575
  try {
1466
- return await select(await dependencies.runWorkbench(args, undefined, undefined, pythonPath, protectedRoot));
1576
+ return await select(await (typeof args === "function"
1577
+ ? args()
1578
+ : dependencies.runWorkbench(args, undefined, undefined, pythonPath, protectedRoot)));
1467
1579
  }
1468
1580
  catch (error) {
1469
1581
  errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
@@ -1471,9 +1583,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1471
1583
  throw error;
1472
1584
  }
1473
1585
  };
1474
- const latestScans = async (count = 1, status = "complete", pythonPath, protectedRoot) => {
1586
+ const latestScans = async (count = 1, status = "complete", options = {}) => {
1475
1587
  const result = await history(workbenchArgs("list-scans", {
1476
1588
  repository: dependencies.currentDirectory(),
1589
+ preferWorktree: options.preferWorktree,
1477
1590
  status: status === "complete" ? "complete" : undefined,
1478
1591
  limit: String(count),
1479
1592
  }), (value) => {
@@ -1484,9 +1597,22 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1484
1597
  : `At least ${count} ${kind} scans are required for the current repository.`);
1485
1598
  }
1486
1599
  return value;
1487
- }, pythonPath, protectedRoot);
1600
+ }, options.pythonPath, options.protectedRoot);
1488
1601
  return result?.["scans"];
1489
1602
  };
1603
+ const preferredScan = async (repository, status) => {
1604
+ const result = await dependencies.runWorkbench(workbenchArgs("list-scans", {
1605
+ repository,
1606
+ preferWorktree: true,
1607
+ status,
1608
+ limit: 1,
1609
+ }));
1610
+ return result["scans"][0];
1611
+ };
1612
+ const historyId = z.string().min(1).optional();
1613
+ const resolveHistoryId = async (id, status) => id === "latest"
1614
+ ? (await latestScans(1, status, { preferWorktree: true }))?.[0]?.scanId
1615
+ : id;
1490
1616
  const runMatching = async (operation, selection) => {
1491
1617
  const controller = new AbortController();
1492
1618
  const removeListeners = listenForAbort(dependencies, controller, (signal) => dependencies.forceExit(signal));
@@ -1557,9 +1683,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1557
1683
  color: dependencies.environment["NO_COLOR"] === undefined &&
1558
1684
  dependencies.environment["TERM"] !== "dumb",
1559
1685
  now: dependencies.now(),
1560
- repository: settings.repository,
1561
- scanRoot: settings.scanRoot,
1562
- showLinkedFindings: settings.showLinkedFindings,
1686
+ ...settings,
1563
1687
  });
1564
1688
  return result;
1565
1689
  };
@@ -1580,7 +1704,16 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1580
1704
  const findingFeedback = Cli.create("findings", {
1581
1705
  description: "Review saved findings (default: list).",
1582
1706
  }).command("false-positive", {
1707
+ usage: [{ suffix: "OCCURRENCE_ID --reason TEXT" }],
1583
1708
  description: "Mark a finding as a false positive for future scans.",
1709
+ examples: [
1710
+ {
1711
+ args: { occurrenceId: "occurrence_abc123" },
1712
+ options: { reason: "unreachable" },
1713
+ description: "Use the occurrence ID from findings list and explain why it does not apply.",
1714
+ },
1715
+ ],
1716
+ hint: "Future scans of the repository can reuse the reason while it applies. Read the occurrence’s triage.note in codex-security scans show SCAN_ID --json.",
1584
1717
  destructive: true,
1585
1718
  args: z.object({
1586
1719
  occurrenceId: z
@@ -1614,6 +1747,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1614
1747
  });
1615
1748
  findingFeedback.command("list", {
1616
1749
  description: "List open findings for a repository across its scans.",
1750
+ examples: [{ args: { repository: "." } }],
1751
+ hint: "Use findings false-positive to record a triage decision for an occurrence.",
1617
1752
  args: z.object({
1618
1753
  repository: z
1619
1754
  .string()
@@ -1622,38 +1757,40 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1622
1757
  }),
1623
1758
  output: z.record(z.string(), z.unknown()).optional(),
1624
1759
  async run({ args, format }) {
1625
- const requestedRepository = resolveCliPath(dependencies.currentDirectory(), args.repository ?? ".");
1626
- const repository = await realpath(requestedRepository).catch(() => requestedRepository);
1627
- return presentHistory(await history(["list-repositories", "--status", "scanned"], async (value) => {
1628
- const repositories = value["repositories"];
1629
- let target = repositories.find((entry) => entry["targetPath"] === requestedRepository);
1630
- const canonicalTarget = repositories.find((entry) => entry["targetPath"] === repository);
1631
- if (target === undefined &&
1632
- canonicalTarget !== undefined &&
1633
- (await sameFile(canonicalTarget["targetPath"], requestedRepository))) {
1634
- target = canonicalTarget;
1635
- }
1636
- if (target === undefined) {
1637
- for (const entry of repositories) {
1638
- const storedPath = entry["targetPath"];
1639
- if (await sameFile(storedPath, requestedRepository)) {
1640
- target = entry;
1641
- break;
1642
- }
1643
- }
1644
- }
1645
- const findings = target === undefined
1646
- ? []
1647
- : await listRepositoryFindings(dependencies.runWorkbench, target["targetId"]);
1648
- return {
1760
+ const requestedPath = resolveInputPath(args.repository ?? ".", dependencies.currentDirectory());
1761
+ const storedPath = await resolveParentTraversal(requestedPath).catch(() => undefined);
1762
+ const canonicalPath = storedPath === undefined
1763
+ ? undefined
1764
+ : await realpath(storedPath).catch(() => undefined);
1765
+ const requestedRepository = canonicalPath === undefined
1766
+ ? (storedPath ?? requestedPath)
1767
+ : requestedPath;
1768
+ return await history(async () => {
1769
+ const findings = await listRepositoryFindings(dependencies.runWorkbench, {
1649
1770
  repository: requestedRepository,
1650
- findings: findings ?? [],
1651
- };
1652
- }), "findings", format, { repository: requestedRepository });
1771
+ });
1772
+ if (findings === undefined) {
1773
+ throw new CodexSecurityError("Repository findings are unavailable for the requested checkout.");
1774
+ }
1775
+ let missingRepositoryHistory = false;
1776
+ if (findings.length === 0 && useInteractiveHistory(format)) {
1777
+ const saved = await dependencies.runWorkbench(workbenchArgs("list-scans", {
1778
+ repository: requestedRepository,
1779
+ limit: "1",
1780
+ }));
1781
+ missingRepositoryHistory =
1782
+ saved["scans"].length === 0;
1783
+ }
1784
+ return presentHistory({ repository: requestedRepository, findings }, "findings", format, {
1785
+ missingRepositoryHistory,
1786
+ });
1787
+ });
1653
1788
  },
1654
1789
  });
1655
1790
  findingFeedback.command("imported", {
1656
1791
  description: "List imported vendor evidence for a local repository.",
1792
+ examples: [{ args: { repository: "." } }],
1793
+ hint: "Use publish findings FILE --to local to save a vendor report. See publish findings --help for its required selectors.",
1657
1794
  args: z.object({
1658
1795
  repository: z
1659
1796
  .string()
@@ -1665,14 +1802,15 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1665
1802
  const controller = new AbortController();
1666
1803
  const removeSignals = listenForAbort(dependencies, controller);
1667
1804
  try {
1668
- const repository = resolveCliPath(dependencies.currentDirectory(), args.repository ?? ".");
1669
- const findings = await (dependencies.listLocalExternalFindings ?? listLocalExternalFindings)({ repository }, {
1805
+ const repository = resolveInputPath(args.repository ?? ".", dependencies.currentDirectory());
1806
+ controller.signal.throwIfAborted();
1807
+ const result = await (dependencies.readLocalExternalFindings ?? readLocalExternalFindings)({ repository }, {
1670
1808
  environment: dependencies.environment,
1671
1809
  signal: controller.signal,
1672
1810
  });
1673
1811
  if (useInteractiveHistory(format))
1674
- renderedOutput = renderImportedFindings(repository, findings, output.columns || 96);
1675
- return { repository, findings };
1812
+ renderedOutput = renderImportedFindings(result.repository, result.findings, output.columns || 96);
1813
+ return result;
1676
1814
  }
1677
1815
  catch (error) {
1678
1816
  if (controller.signal.aborted) {
@@ -1700,6 +1838,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1700
1838
  })
1701
1839
  .command("list", {
1702
1840
  description: "List saved scans for a repository or scan root.",
1841
+ examples: [{ args: { repository: "." } }],
1842
+ hint: "Use scans show SCAN_ID for results or scans logs SCAN_ID for activity.",
1703
1843
  args: z.object({
1704
1844
  repository: z
1705
1845
  .string()
@@ -1719,10 +1859,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1719
1859
  ? undefined
1720
1860
  : process.platform === "win32"
1721
1861
  ? await canonicalizeModelSafePath(resolveCliPath(directory, options.scanRoot))
1722
- : resolveCliPath(directory, options.scanRoot);
1862
+ : await resolveParentTraversal(resolveInputPath(options.scanRoot, directory), { allowMissing: true });
1723
1863
  const repository = scanRoot !== undefined && args.repository === undefined
1724
1864
  ? undefined
1725
- : resolveCliPath(directory, args.repository ?? directory);
1865
+ : resolveInputPath(args.repository ?? directory, directory);
1726
1866
  return presentHistory(await history(workbenchArgs("list-scans", {
1727
1867
  repository,
1728
1868
  scanRoot,
@@ -1736,11 +1876,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1736
1876
  description: "Show the results and saved configuration for a scan.",
1737
1877
  hint: "Without an ID, show selects the latest completed scan; logs selects the latest scan of any status. Pass the same ID to inspect one run.",
1738
1878
  args: z.object({
1739
- scanId: z
1740
- .string()
1741
- .min(1)
1742
- .optional()
1743
- .describe("Scan ID or unique prefix (default: latest completed)."),
1879
+ scanId: historyId.describe("Scan ID, unique prefix, or latest (default: latest completed)."),
1744
1880
  }),
1745
1881
  options: z.object({
1746
1882
  showLinkedFindings: z
@@ -1756,24 +1892,22 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1756
1892
  },
1757
1893
  ],
1758
1894
  output: z.record(z.string(), z.unknown()).optional(),
1759
- async run({ args, format, options }) {
1760
- let scanId = args.scanId;
1761
- if (scanId === undefined) {
1762
- try {
1763
- scanId = (await latestScans())?.[0]?.scanId;
1764
- }
1765
- catch (error) {
1766
- if (useDefaultOutput(format)) {
1767
- errorOutput.write("Use codex-security scans list to find failed or active scans, then pass a scan ID to scans show and scans logs.\n");
1768
- }
1769
- throw error;
1895
+ async run({ args: { scanId: requestedId = "latest" }, format, options }) {
1896
+ let scanId;
1897
+ try {
1898
+ scanId = await resolveHistoryId(requestedId, "complete");
1899
+ }
1900
+ catch (error) {
1901
+ if (useDefaultOutput(format)) {
1902
+ errorOutput.write("Use codex-security scans list to find failed or active scans, then pass a scan ID to scans show and scans logs.\n");
1770
1903
  }
1904
+ throw error;
1771
1905
  }
1772
1906
  if (scanId === undefined)
1773
1907
  return;
1774
1908
  return presentHistory(await history(["get-scan", "--scan-id", scanId], async (value) => {
1775
1909
  const { scan, recipe, parentScanId } = value;
1776
- await showHistoryNavigation(scan, format, args.scanId === undefined ? "latest completed scan" : undefined);
1910
+ await showHistoryNavigation(scan, format, requestedId === "latest" ? "latest completed scan" : undefined);
1777
1911
  return {
1778
1912
  ...scan,
1779
1913
  ...(recipe === undefined ? {} : { recipe }),
@@ -1786,11 +1920,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1786
1920
  description: "Show saved activity for a scan and its workers.",
1787
1921
  hint: "Without an ID, logs selects the latest scan, including failed and active runs; show selects the latest completed scan. Pass the same ID to inspect one run.",
1788
1922
  args: z.object({
1789
- scanId: z
1790
- .string()
1791
- .min(1)
1792
- .optional()
1793
- .describe("Scan identifier or unique prefix (default: latest, any status)."),
1923
+ scanId: historyId.describe("Scan ID, unique prefix, or latest (default: latest, any status)."),
1794
1924
  }),
1795
1925
  examples: [
1796
1926
  { args: {}, description: "Show activity from the latest scan." },
@@ -1800,13 +1930,13 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1800
1930
  },
1801
1931
  ],
1802
1932
  output: z.record(z.string(), z.unknown()).optional(),
1803
- async run({ args, format }) {
1804
- const scanId = args.scanId ?? (await latestScans(1, "any"))?.[0]?.scanId;
1933
+ async run({ args: { scanId: requestedId = "latest" }, format }) {
1934
+ const scanId = await resolveHistoryId(requestedId, "any");
1805
1935
  if (scanId === undefined)
1806
1936
  return;
1807
1937
  const result = await history(["get-scan", "--scan-id", scanId], async (value) => {
1808
1938
  const scan = value["scan"];
1809
- await showHistoryNavigation(scan, format, args.scanId === undefined
1939
+ await showHistoryNavigation(scan, format, requestedId === "latest"
1810
1940
  ? "latest scan, including failed and active runs"
1811
1941
  : undefined);
1812
1942
  const logs = await readSavedScanLogs(scan, [
@@ -1829,10 +1959,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1829
1959
  },
1830
1960
  })
1831
1961
  .command("resume", {
1832
- description: "Resume an interrupted Deep Scan in its original session.",
1962
+ description: "Resume an interrupted Standard or Deep Scan in its original session.",
1963
+ examples: [{ args: { scanId: "SCAN_ID" } }],
1833
1964
  hint: "Execution failures keep available scan results under data in failed full-output JSON, JSONL, YAML, or TOON envelopes.",
1834
1965
  args: z.object({
1835
- scanId: z.string().min(1).describe("Interrupted Deep Scan identifier."),
1966
+ scanId: z.string().min(1).describe("Interrupted scan identifier."),
1836
1967
  }),
1837
1968
  options: z.object({
1838
1969
  showCost: SHOW_COST_OPTION,
@@ -1874,7 +2005,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1874
2005
  },
1875
2006
  })
1876
2007
  .command("rerun", {
1877
- description: "Start a new scan using saved settings and current checkout/context files.",
2008
+ description: "Start a new scan using saved settings and the current files at its saved checkout.",
2009
+ examples: [{ args: { scanId: "SCAN_ID" } }],
1878
2010
  hint: "Execution failures keep available scan results under data in failed full-output JSON, JSONL, YAML, or TOON envelopes.",
1879
2011
  destructive: true,
1880
2012
  args: z.object({
@@ -1882,7 +2014,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1882
2014
  .string()
1883
2015
  .min(1)
1884
2016
  .optional()
1885
- .describe("Saved scan identifier (default: latest completed scan)."),
2017
+ .describe("Saved scan identifier (default: latest completed in this worktree)."),
1886
2018
  }),
1887
2019
  options: z.object({
1888
2020
  showCost: SHOW_COST_OPTION,
@@ -1905,20 +2037,18 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1905
2037
  exitCode = 2;
1906
2038
  throw error;
1907
2039
  }
1908
- let scanId;
1909
- try {
1910
- scanId = args.scanId ?? (await latestScans())?.[0]?.scanId;
1911
- }
1912
- catch (error) {
1913
- const message = errorMessage(error);
1914
- if (exitCode === 0)
1915
- errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
1916
- return finishScanCommand({ exitCode: 2, error: message }, format, incurError, "SCAN_REPLAY_UNAVAILABLE");
1917
- }
1918
- if (scanId === undefined)
1919
- return;
1920
2040
  let scanArguments;
1921
2041
  try {
2042
+ let scanId = args.scanId;
2043
+ let localScan;
2044
+ if (scanId === undefined) {
2045
+ localScan = await preferredScan(dependencies.currentDirectory(), "complete");
2046
+ if (!localScan)
2047
+ throw new CodexSecurityError("No completed scans found for the current repository.");
2048
+ scanId = localScan.scanId;
2049
+ if (!localScan.inCurrentWorktree)
2050
+ throw new CodexSecurityError(`No completed scan in this worktree. Scan ${scanId} used ${localScan.targetPath} (revision ${localScan["targetRevision"] ?? "unknown"}). To rerun there, use codex-security scans rerun ${scanId}.`);
2051
+ }
1922
2052
  const saved = await dependencies.runWorkbench(workbenchArgs("get-scan-recipe", { scanId }));
1923
2053
  const recipe = saved["recipe"];
1924
2054
  const parentScanId = saved["scanId"];
@@ -1946,7 +2076,16 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1946
2076
  });
1947
2077
  return finishScanCommand(outcome, format, incurError, "SCAN_IMPORT_FAILED");
1948
2078
  }
1949
- scanArguments = await prepareScanArgumentsFromRecipe(saved, "rerun", dependencies.currentDirectory(), dependencies.environment, options);
2079
+ const replay = localScan && isJsonObject(recipe)
2080
+ ? {
2081
+ ...saved,
2082
+ recipe: {
2083
+ ...recipe,
2084
+ repository: localScan.targetPath,
2085
+ },
2086
+ }
2087
+ : saved;
2088
+ scanArguments = await prepareScanArgumentsFromRecipe(replay, "rerun", dependencies.currentDirectory(), dependencies.environment, options);
1950
2089
  scanArguments.verbose = options.verbose;
1951
2090
  scanArguments.showCost = options.showCost;
1952
2091
  scanArguments.parentScanId = parentScanId;
@@ -1961,7 +2100,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1961
2100
  },
1962
2101
  })
1963
2102
  .command("match", {
1964
- description: "Match findings by root cause across saved scans.",
2103
+ description: "Match findings across completed scans. Uncached matches can use the model and save decisions.",
2104
+ usage: [{ suffix: "--all [options]" }],
2105
+ examples: [{ options: { all: true } }],
2106
+ hint: "For a pair, use scans compare BEFORE AFTER. The older scans match BEFORE AFTER spelling also works.",
1965
2107
  destructive: true,
1966
2108
  args: z.object({
1967
2109
  beforeId: z
@@ -1980,22 +2122,31 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
1980
2122
  .boolean()
1981
2123
  .default(false)
1982
2124
  .describe("Match all completed scans of the current repository."),
1983
- force: z
1984
- .boolean()
1985
- .default(false)
1986
- .describe("Recompute an existing semantic finding comparison."),
1987
- ...MATCHING_MODEL_OPTIONS.shape,
2125
+ ...MATCHING_OPTIONS.shape,
1988
2126
  }),
1989
2127
  output: z.record(z.string(), z.unknown()).optional(),
1990
2128
  async run({ args, format, options }) {
1991
2129
  if (options.all) {
2130
+ if (args.beforeId !== undefined || args.afterId !== undefined) {
2131
+ throw new CodexSecurityError("scans match --all does not accept scan identifiers.");
2132
+ }
1992
2133
  return presentHistory(await runMatching((matchingOptions) => matchAllScans(dependencies, options.force, matchingOptions), options), "match-all", format);
1993
2134
  }
2135
+ if (args.beforeId === undefined || args.afterId === undefined) {
2136
+ throw new CodexSecurityError("scans match requires two scan identifiers or --all.");
2137
+ }
1994
2138
  return presentHistory(await matchScanPair(args.beforeId, args.afterId, options), "compare", format);
1995
2139
  },
1996
2140
  })
1997
2141
  .command("compare", {
1998
- description: "Match and compare findings between scans.",
2142
+ description: "Compare findings from two scans. Uncached matches can use the model and save matching decisions.",
2143
+ examples: [
2144
+ {
2145
+ args: { beforeId: "BEFORE", afterId: "AFTER" },
2146
+ description: "Compare two scans, using the model and saving decisions on a cache miss.",
2147
+ },
2148
+ { args: {}, description: "Compare the latest two completed scans." },
2149
+ ],
1999
2150
  destructive: true,
2000
2151
  args: z.object({
2001
2152
  beforeId: z
@@ -2009,7 +2160,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2009
2160
  .optional()
2010
2161
  .describe("Later saved scan identifier (default: latest completed)."),
2011
2162
  }),
2012
- options: MATCHING_MODEL_OPTIONS,
2163
+ options: MATCHING_OPTIONS,
2013
2164
  output: z.record(z.string(), z.unknown()).optional(),
2014
2165
  async run({ args, format, options }) {
2015
2166
  let { beforeId, afterId } = args;
@@ -2045,10 +2196,25 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2045
2196
  const publication = Cli.create("publish", {
2046
2197
  description: "Publish Codex Security findings.",
2047
2198
  }).command("scan", {
2048
- description: "Publish findings from a completed scan, or a CSV for internal publication.",
2049
- hint: "Examples:\n" +
2050
- " codex-security publish scan --to linear --scan latest --linear-team TEAM_ID --dry-run\n" +
2051
- " codex-security publish scan --to custom --scan latest --findings-url http://localhost:3000",
2199
+ description: "Publish findings from a completed scan.",
2200
+ examples: [
2201
+ {
2202
+ args: { scanDir: "../scan-results" },
2203
+ options: {
2204
+ to: "linear",
2205
+ linearTeam: "TEAM_ID",
2206
+ dryRun: true,
2207
+ },
2208
+ },
2209
+ {
2210
+ options: {
2211
+ to: "custom",
2212
+ scan: ["latest"],
2213
+ findingsUrl: "http://localhost:3000",
2214
+ },
2215
+ },
2216
+ ],
2217
+ hint: "Use --dry-run to preview the selected findings before publishing.",
2052
2218
  destructive: true,
2053
2219
  args: z.object({
2054
2220
  scanDir: z
@@ -2071,7 +2237,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2071
2237
  scanDir: z
2072
2238
  .array(optionValue("--scan-dir"))
2073
2239
  .default([])
2074
- .describe("External completed scan directory; Linear and custom accept one scan."),
2240
+ .describe("Use the positional directory for one scan. Repeat this flag for destinations that accept multiple scans."),
2075
2241
  // Cloud remains an internal destination, omitted from public discovery.
2076
2242
  to: z
2077
2243
  .string()
@@ -2165,22 +2331,24 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2165
2331
  const csvPath = options.csv === undefined
2166
2332
  ? undefined
2167
2333
  : resolveCliPath(currentDirectory, options.csv);
2168
- const directories = [
2169
- ...new Set([
2170
- ...(args.scanDir === undefined ? [] : [args.scanDir]),
2171
- ...options.scanDir,
2172
- ].map((directory) => resolveCliPath(currentDirectory, directory))),
2334
+ const directoryInputs = [
2335
+ ...(args.scanDir === undefined ? [] : [args.scanDir]),
2336
+ ...options.scanDir,
2173
2337
  ];
2174
- if (directories.length > 1 && options.to !== "cloud") {
2175
- throw new CodexSecurityError("Multiple scan directories are only supported with --to cloud.");
2176
- }
2177
- if (options.scan.length > 0 && directories.length > 0) {
2338
+ const uniqueDirectories = (paths) => {
2339
+ const directories = [...new Set(paths)];
2340
+ if (directories.length > 1 && options.to !== "cloud") {
2341
+ throw new CodexSecurityError("Multiple scan directories are only supported with --to cloud.");
2342
+ }
2343
+ return directories;
2344
+ };
2345
+ // Reject conflicting selectors before reading their path components.
2346
+ uniqueDirectories(directoryInputs.map((value) => resolveCliPath(currentDirectory, value)));
2347
+ if (options.scan.length > 0 && directoryInputs.length > 0) {
2178
2348
  throw new CodexSecurityError("Use --scan or scan directory inputs, not both.");
2179
2349
  }
2180
2350
  if (csvPath !== undefined &&
2181
- (args.scanDir !== undefined ||
2182
- options.scan.length > 0 ||
2183
- options.scanDir.length > 0)) {
2351
+ (directoryInputs.length > 0 || options.scan.length > 0)) {
2184
2352
  throw new CodexSecurityError("Use --csv or scan directory and ID inputs, not both.");
2185
2353
  }
2186
2354
  if (csvPath !== undefined && options.to !== "cloud") {
@@ -2228,6 +2396,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2228
2396
  currentDirectory: dependencies.currentDirectory,
2229
2397
  runWorkbench: (args, input) => dependencies.runWorkbench(args, input, controller.signal),
2230
2398
  };
2399
+ const directories = uniqueDirectories(await Promise.all(directoryInputs.map((value) => resolveParentTraversal(resolveInputPath(value, currentDirectory), { allowMissing: true }))));
2231
2400
  const selectedScans = directories.map((scanDir) => ({ scanDir }));
2232
2401
  for (const requestedId of new Set(options.scan)) {
2233
2402
  controller.signal.throwIfAborted();
@@ -2515,7 +2684,31 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2515
2684
  publication
2516
2685
  .command("findings", {
2517
2686
  description: "Preview and import a saved scanner report locally or to Cloud.",
2518
- hint: "Choose your scanner with --provider. Reuse --source-key for later imports from the same source. See the scanner import guide for supported formats, repository setup, and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md. Gzip files are supported. Use --to local to save unassessed findings without a Cloud login. Use --full-output with --format json or --format jsonl.\nExample: codex-security publish findings selected-wiz.json --to local --repository ./project --provider wiz --source-key TENANT_ID/vulnerability-finding --dry-run --format json",
2687
+ usage: [
2688
+ {
2689
+ args: { file: true },
2690
+ options: {
2691
+ to: true,
2692
+ repository: true,
2693
+ provider: true,
2694
+ sourceKey: true,
2695
+ },
2696
+ suffix: "[options]",
2697
+ },
2698
+ ],
2699
+ examples: [
2700
+ {
2701
+ args: { file: "selected-wiz.json" },
2702
+ options: {
2703
+ to: "local",
2704
+ repository: "./project",
2705
+ provider: "wiz",
2706
+ sourceKey: "tenant/vulnerability-finding",
2707
+ dryRun: true,
2708
+ },
2709
+ },
2710
+ ],
2711
+ hint: "Choose your scanner with --provider. Reuse --source-key for later imports from the same source. For findings already in the workbench, use the SDK's prepareStoredFindingsPublication. The installed @openai/codex-security package includes the workflow in docs/sdk.md under Import external findings. See the scanner import guide for supported formats, repository setup, and export examples: https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md. Gzip files are supported. Use --to local to save unassessed findings without a Cloud login. Use --full-output with --format json or --format jsonl.",
2519
2712
  destructive: true,
2520
2713
  args: z.object({
2521
2714
  file: z
@@ -2637,9 +2830,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2637
2830
  inspectorProjectMap = new Map([[inspectorProjectArn, url]]);
2638
2831
  }
2639
2832
  const directory = dependencies.currentDirectory();
2640
- const report = resolveCliPath(directory, args.file);
2833
+ const report = resolveInputPath(args.file, directory);
2641
2834
  const repository = options.to === "local"
2642
- ? resolveCliPath(directory, options.repository)
2835
+ ? resolveInputPath(options.repository, directory)
2643
2836
  : options.repository;
2644
2837
  const publicationOptions = {
2645
2838
  ...readerOptions,
@@ -2659,7 +2852,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2659
2852
  showExclusions(preview.excluded);
2660
2853
  for (const finding of preview.findings.slice(0, 5))
2661
2854
  writeDiagnostic(` ${diagnosticValue(finding.source_finding_id)} [${finding.evidence.severity}] ${diagnosticValue(finding.evidence.title)}\n`);
2662
- writeDiagnostic(`Evidence file: ${diagnosticValue(resolveCliPath(dependencies.currentDirectory(), args.file))}\nImported evidence remains not assessed by Codex.\nUse --dry-run --format json to inspect all normalized findings and complete evidence before storing them.\n`);
2855
+ writeDiagnostic(`Evidence file: ${diagnosticValue(report)}\nImported evidence remains not assessed by Codex.\nUse --dry-run --format json to inspect all normalized findings and complete evidence before storing them.\n`);
2663
2856
  };
2664
2857
  const disposition = externalImportDisposition(preview);
2665
2858
  if (disposition === "excluded" || disposition === "failed")
@@ -2682,7 +2875,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2682
2875
  exitCode = 1;
2683
2876
  const summary = disposition === "empty"
2684
2877
  ? "The report contains no findings. Nothing was stored.\n"
2685
- : `Local import complete.\nCreated: ${result.counts.created} Updated: ${result.counts.updated} Unchanged: ${result.counts.unchanged} Excluded: ${result.excluded.length}\nImported evidence remains not assessed by Codex.\nRead stored evidence with codex-security findings imported REPOSITORY.\n`;
2878
+ : `Local import complete.\nCreated: ${result.counts.created} Updated: ${result.counts.updated} Unchanged: ${result.counts.unchanged} Excluded: ${result.excluded.length}\nImported evidence remains not assessed by Codex.\n${importedFindingsCommand(preview.repository)}\n`;
2686
2879
  if (humanSummary)
2687
2880
  renderedOutput = summary;
2688
2881
  else if (!structured)
@@ -2703,7 +2896,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2703
2896
  if (preview.cloudUrl)
2704
2897
  writeDiagnostic(`Cloud app: ${diagnosticValue(preview.cloudUrl)}\n`);
2705
2898
  showExclusions(preview.excluded);
2706
- writeDiagnostic(`Evidence file: ${diagnosticValue(resolveCliPath(dependencies.currentDirectory(), args.file))}\nImported evidence remains not assessed by Codex.\n`);
2899
+ writeDiagnostic(`Evidence file: ${diagnosticValue(report)}\nImported evidence remains not assessed by Codex.\n`);
2707
2900
  const severities = new Map();
2708
2901
  for (const finding of preview.findings)
2709
2902
  severities.set(finding.evidence.severity, (severities.get(finding.evidence.severity) ?? 0) + 1);
@@ -2787,8 +2980,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2787
2980
  };
2788
2981
  if (machineFormat &&
2789
2982
  (!argv.includes("--full-output") || selection !== undefined) &&
2790
- frameworkFlags.filterOutput)
2791
- filteredScanFailure = { format, data: failure };
2983
+ frameworkFlags.filters.length)
2984
+ unfilteredFailure = failure;
2792
2985
  return structured ? failure : undefined;
2793
2986
  }
2794
2987
  finally {
@@ -2799,6 +2992,13 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2799
2992
  })
2800
2993
  .command("check", {
2801
2994
  description: "Check saved scan history and Linear access without creating issues.",
2995
+ examples: [
2996
+ {
2997
+ args: { scanDir: "../scan-results" },
2998
+ options: { linearTeam: "TEAM_ID" },
2999
+ },
3000
+ ],
3001
+ hint: "Use publish scan --dry-run to preview a publication offline.",
2802
3002
  args: z.object({
2803
3003
  scanDir: z.string().describe("Completed scan directory."),
2804
3004
  }),
@@ -2809,10 +3009,12 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2809
3009
  const controller = new AbortController();
2810
3010
  const removeSignals = listenForAbort(dependencies, controller);
2811
3011
  try {
2812
- const result = await (dependencies.checkScanPublication ?? checkScanPublication)(resolveCliPath(dependencies.currentDirectory(), args.scanDir), {
2813
- ...publicationDestination(options, dependencies.environment),
2814
- signal: controller.signal,
3012
+ const input = resolveInputPath(args.scanDir, dependencies.currentDirectory());
3013
+ const destination = publicationDestination(options, dependencies.environment);
3014
+ const directory = await resolveParentTraversal(input, {
3015
+ allowMissing: true,
2815
3016
  });
3017
+ const result = await (dependencies.checkScanPublication ?? checkScanPublication)(directory, { ...destination, signal: controller.signal });
2816
3018
  controller.signal.throwIfAborted();
2817
3019
  return { ...result };
2818
3020
  }
@@ -2827,8 +3029,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2827
3029
  },
2828
3030
  });
2829
3031
  const imports = Cli.create("import", {
2830
- description: "Import Sonar security issues or read hosted Semgrep, Snyk, and GitHub findings.",
3032
+ description: "Collect findings from GitHub, Semgrep, Snyk or Sonar.",
2831
3033
  }).command("github", {
3034
+ examples: [{ args: { repository: "owner/repo" } }],
2832
3035
  description: "Read GitHub code scanning alerts without changing GitHub.",
2833
3036
  hint: "Save complete --format json output for publish findings --provider github. This command reads code-scanning alerts; Dependabot and secret-scanning alerts are not supported. To save CSV or JSON findings as a local scan, use codex-security scan import --help.",
2834
3037
  destructive: false,
@@ -2860,7 +3063,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2860
3063
  alert: z.record(z.string(), z.unknown()),
2861
3064
  }))
2862
3065
  .optional(),
2863
- async run({ args, options }) {
3066
+ async run({ args, options, error: fail }) {
2864
3067
  const controller = new AbortController();
2865
3068
  const removeSignals = listenForAbort(dependencies, controller);
2866
3069
  try {
@@ -2885,7 +3088,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2885
3088
  exitCode = 2;
2886
3089
  errorOutput.write(`codex-security: ${diagnosticValue(error)}\n`);
2887
3090
  }
2888
- throw error;
3091
+ return fail({
3092
+ code: "GITHUB_IMPORT_FAILED",
3093
+ message: errorMessage(error),
3094
+ exitCode,
3095
+ });
2889
3096
  }
2890
3097
  finally {
2891
3098
  removeSignals();
@@ -2929,12 +3136,13 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2929
3136
  environment: dependencies.environment,
2930
3137
  fetch: dependencies.hostedScannerFetch,
2931
3138
  };
2932
- function setHostedOutputFormat(format) {
3139
+ function setTerminalOutputFormat(format) {
2933
3140
  escapeFrameworkOutput =
2934
3141
  format === "md" || (format === "toon" && output.isTTY === true);
2935
3142
  }
2936
3143
  imports
2937
3144
  .command("github-advisories", {
3145
+ examples: [{ args: { repository: "owner/repo" } }],
2938
3146
  description: "Read GitHub security advisories without changing GitHub.",
2939
3147
  hint: "Defaults to published repository advisories. Use --github-advisory-source global with explicit --github-advisory IDs to select public database entries. Advisories do not establish an installed dependency or applicability to the selected repository.",
2940
3148
  destructive: false,
@@ -2981,14 +3189,30 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
2981
3189
  })),
2982
3190
  })
2983
3191
  .command("snyk", {
3192
+ usage: [
3193
+ {
3194
+ args: { project: true },
3195
+ options: { org: true, sourceRepositoryUrl: true },
3196
+ suffix: "[options]",
3197
+ },
3198
+ ],
2984
3199
  description: "Read Snyk Open Source or Code issues for one monitored project.",
3200
+ examples: [
3201
+ {
3202
+ args: { project: "PROJECT_ID" },
3203
+ options: {
3204
+ org: "ORG_ID",
3205
+ sourceRepositoryUrl: "https://github.com/example/project",
3206
+ },
3207
+ },
3208
+ ],
2985
3209
  hint: "Requires SNYK_TOKEN. Save the complete --format json output. Use publish findings --provider snyk with --to local or --to cloud.",
2986
3210
  destructive: false,
2987
3211
  args: z.object({
2988
3212
  project: z.string().min(1).describe("Snyk project ID."),
2989
3213
  }),
2990
3214
  options: z.object({
2991
- snykOrg: optionValue("--snyk-org").describe("Snyk organization ID."),
3215
+ org: optionValue("--org").describe("Snyk organization ID (alias: --snyk-org)."),
2992
3216
  snykProduct: z
2993
3217
  .enum(["open-source", "code"])
2994
3218
  .default("open-source")
@@ -3017,10 +3241,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3017
3241
  })
3018
3242
  .optional(),
3019
3243
  run: ({ args, options, error, format }) => {
3020
- setHostedOutputFormat(format);
3244
+ setTerminalOutputFormat(format);
3021
3245
  return collectHostedFindings("Snyk", error, (signal) => collectSnykIssues({
3022
3246
  projectId: args.project,
3023
- organizationId: options.snykOrg,
3247
+ organizationId: options.org,
3024
3248
  product: options.snykProduct,
3025
3249
  apiOrigin: options.snykApiOrigin,
3026
3250
  sourceRepositoryUrl: options.sourceRepositoryUrl,
@@ -3029,7 +3253,23 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3029
3253
  },
3030
3254
  })
3031
3255
  .command("semgrep", {
3256
+ usage: [
3257
+ {
3258
+ args: { project: true },
3259
+ options: { deployment: true, ref: true },
3260
+ suffix: "[options]",
3261
+ },
3262
+ ],
3032
3263
  description: "Read a full Semgrep Platform project and ref through the Web API.",
3264
+ examples: [
3265
+ {
3266
+ args: { project: "owner/project" },
3267
+ options: {
3268
+ deployment: "DEPLOYMENT",
3269
+ ref: "refs/heads/main",
3270
+ },
3271
+ },
3272
+ ],
3033
3273
  hint: "Requires SEMGREP_APP_TOKEN with Web API access. Import the saved --format json output with publish findings --provider semgrep and --to local or --to cloud. Selected Guardian MCP captures also support both destinations.",
3034
3274
  destructive: false,
3035
3275
  args: z.object({
@@ -3039,8 +3279,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3039
3279
  .describe("Exact Semgrep project name, typically owner/repository."),
3040
3280
  }),
3041
3281
  options: z.object({
3042
- semgrepDeployment: optionValue("--semgrep-deployment").describe("Semgrep deployment slug."),
3043
- semgrepRef: optionValue("--semgrep-ref").describe("Exact source ref, for example refs/heads/main."),
3282
+ deployment: optionValue("--deployment").describe("Semgrep deployment slug (alias: --semgrep-deployment)."),
3283
+ ref: optionValue("--ref").describe("Exact source ref, for example refs/heads/main (alias: --semgrep-ref)."),
3044
3284
  semgrepProduct: z
3045
3285
  .enum(SEMGREP_PLATFORM_PRODUCTS)
3046
3286
  .default("sast")
@@ -3068,11 +3308,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3068
3308
  })
3069
3309
  .optional(),
3070
3310
  run: ({ args, options, error, format }) => {
3071
- setHostedOutputFormat(format);
3311
+ setTerminalOutputFormat(format);
3072
3312
  return collectHostedFindings("Semgrep", error, (signal) => collectSemgrepPlatformFindings({
3073
3313
  project: args.project,
3074
- deployment: options.semgrepDeployment,
3075
- ref: options.semgrepRef,
3314
+ deployment: options.deployment,
3315
+ ref: options.ref,
3076
3316
  product: options.semgrepProduct,
3077
3317
  sourceRepositoryUrl: options.sourceRepositoryUrl,
3078
3318
  signal,
@@ -3080,8 +3320,16 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3080
3320
  },
3081
3321
  })
3082
3322
  .command("sonar", {
3323
+ usage: [
3324
+ { suffix: "[--sonar-project KEY] [options]" },
3325
+ { suffix: "CAPTURE [options]" },
3326
+ ],
3083
3327
  description: "Collect Sonar security findings or replay a saved capture into the local workbench.",
3084
- hint: "Uses the active sonar CLI login. --to cloud also publishes the locally imported selection to the connected Cloud repository. --dry-run saves a live capture for review without importing findings.",
3328
+ examples: [
3329
+ { options: { sonarProject: "PROJECT_KEY", dryRun: true } },
3330
+ { args: { capture: "../reports/sonar.json" } },
3331
+ ],
3332
+ hint: "Uses the active sonar CLI login. --to cloud also publishes the locally imported selection to the connected Cloud repository. --dry-run saves a private evidence copy for live and saved inputs and prints its path for confirmation.",
3085
3333
  destructive: true,
3086
3334
  args: z.object({
3087
3335
  capture: z
@@ -3114,7 +3362,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3114
3362
  dryRun: z
3115
3363
  .boolean()
3116
3364
  .default(false)
3117
- .describe("Preview destinations and evidence without storing or publishing findings."),
3365
+ .describe("Save a private evidence copy and preview the selected findings and destinations."),
3118
3366
  yes: z
3119
3367
  .boolean()
3120
3368
  .default(false)
@@ -3234,7 +3482,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3234
3482
  note("Cloud repository: " + diagnosticValue(result.cloud.cloudUrl));
3235
3483
  if (humanSummary) {
3236
3484
  const { created, updated, unchanged } = result.local.counts;
3237
- renderedOutput = `Local import: ${created} created, ${updated} updated, ${unchanged} unchanged.\n`;
3485
+ renderedOutput = `Local import: ${created} created, ${updated} updated, ${unchanged} unchanged.\n${importedFindingsCommand(info.repository)}\n`;
3238
3486
  if (result.cloud)
3239
3487
  renderedOutput += renderExternalPublicationSummary(result.cloud);
3240
3488
  }
@@ -3256,9 +3504,14 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3256
3504
  });
3257
3505
  },
3258
3506
  });
3507
+ const withLoginEnvironment = async (run) => {
3508
+ const home = await prepareCodexSecurityCredentialHome(dependencies.environment);
3509
+ return withCredentialHomeLock(home, () => run({ ...dependencies.environment, CODEX_HOME: home }));
3510
+ };
3259
3511
  const infoOutput = z.object({
3260
3512
  sdkVersion: z.string(),
3261
3513
  bundledPluginVersion: z.string(),
3514
+ bundledPluginAvailable: z.boolean(),
3262
3515
  scanMcp: z.literal(false),
3263
3516
  cancellationNote: z.string(),
3264
3517
  cliVersion: z.string(),
@@ -3271,6 +3524,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3271
3524
  });
3272
3525
  const cliOptions = {
3273
3526
  aliases: ["cs"],
3527
+ update: false,
3274
3528
  description: "Find, review, and fix security issues in your code.",
3275
3529
  version: VERSION,
3276
3530
  mcp: {
@@ -3280,6 +3534,27 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3280
3534
  },
3281
3535
  };
3282
3536
  const cli = Cli.create("codex-security", cliOptions)
3537
+ .command("update", {
3538
+ description: "Update the CLI or show the command for this installation.",
3539
+ destructive: true,
3540
+ async run({ format, error }) {
3541
+ try {
3542
+ await installUpdate(dependencies.environment);
3543
+ }
3544
+ catch (cause) {
3545
+ return error({
3546
+ code: "UPDATE_FAILED",
3547
+ message: errorMessage(cause),
3548
+ exitCode: 2,
3549
+ });
3550
+ }
3551
+ const name = "@openai/codex-security";
3552
+ if (output.isTTY && useDefaultOutput(format))
3553
+ renderedOutput = `✓ Updated ${name}\n`;
3554
+ return { name };
3555
+ },
3556
+ })
3557
+ .command(scanHistory)
3283
3558
  .command("policy", {
3284
3559
  description: "Draft SECURITY.md for review.",
3285
3560
  destructive: true,
@@ -3321,7 +3596,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3321
3596
  hint: "Review the diff and notes. Edit the draft, then copy only SECURITY.md to the Policy target shown.\n" +
3322
3597
  "Your existing policy stays unchanged until you replace it.\n\n" +
3323
3598
  "Save a draft without answering questions:\n" +
3324
- " codex-security policy . --headless --output-dir /path/outside/repository/policy --json",
3599
+ " codex-security policy . --output-dir ../policy-draft --json",
3325
3600
  output: z
3326
3601
  .union([z.record(z.string(), z.unknown()), z.string()])
3327
3602
  .optional(),
@@ -3344,7 +3619,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3344
3619
  const directory = dependencies.currentDirectory();
3345
3620
  const codexOverrides = await parseScanCodexOverrides(options, dependencies.environment);
3346
3621
  const outcome = await withTerminalErrorsHandled(errorOutput, () => runPolicyCommand({
3347
- repository: resolveCliPath(directory, args.repository ?? "."),
3622
+ repository: resolveInputPath(args.repository ?? ".", directory),
3348
3623
  config: {
3349
3624
  pluginPath: options.pluginPath,
3350
3625
  pythonPath: options.python,
@@ -3410,214 +3685,296 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3410
3685
  return fail(message, 2);
3411
3686
  }
3412
3687
  },
3413
- })
3414
- .command("scan", {
3415
- description: "Scan a repository, selected paths, or Git changes.",
3416
- hint: "Examples:\n" +
3417
- " codex-security scan .\n" +
3418
- " codex-security scan . --path src --path tests\n" +
3419
- " codex-security scan . --working-tree\n" +
3420
- " codex-security scan . --diff origin/main\n" +
3421
- " codex-security scan . --mode deep\n\n" +
3422
- "Import existing findings without security analysis:\n" +
3423
- " codex-security scan import --csv findings.csv\n" +
3424
- " codex-security scan import --json findings.json\n" +
3425
- "Use ./import to scan a repository named import.\n" +
3426
- "Execution failures in JSON/JSONL --full-output return ok: false and keep scan results under data.",
3427
- destructive: true,
3428
- alias: { config: "c" },
3429
- args: z.object({
3430
- repository: z
3431
- .string()
3432
- .optional()
3433
- .describe("Repository root to scan (default: current directory)."),
3434
- }),
3435
- options: z
3436
- .object({
3437
- config: PROJECT_CONFIG_OPTION,
3438
- host: z
3439
- .boolean()
3440
- .default(false)
3441
- .describe("Run one hosted Standard scan over JSON-RPC stdin/stdout; use alone."),
3442
- workflowId: optionValue("--workflow-id")
3443
- .optional()
3444
- .describe("Reuse completed work in the named local findings workflow."),
3445
- cyberAccessProgram: ScanSettingsSchema.shape.cyberAccessProgram,
3446
- auth: ScanSettingsSchema.shape.auth.describe("Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication (default: auto)."),
3447
- verbose: z
3448
- .boolean()
3449
- .default(false)
3450
- .describe("Print additional scan diagnostics to stderr."),
3451
- safetyIdentifier: optionValue("--safety-identifier")
3452
- .optional()
3453
- .describe("Stable hashed end-user ID for this scan's model requests (1–64 characters)."),
3454
- path: z
3455
- .array(optionValue("--path"))
3456
- .optional()
3457
- .meta({ default: [] })
3458
- .describe("Scan only PATH; repeat for multiple repository-relative paths."),
3459
- knowledgeBase: z
3460
- .array(optionValue("--knowledge-base"))
3461
- .optional()
3462
- .meta({ default: [] })
3463
- .describe("Add security-context files or directories; repeat for multiple paths."),
3464
- rubric: optionValue("--rubric")
3465
- .optional()
3466
- .describe("Use this Markdown file to grade findings. Takes precedence over the default severity rubric."),
3467
- scanPromptFile: optionValue("--scan-prompt-file")
3468
- .optional()
3469
- .describe("Append scan instructions from FILE."),
3470
- validationPromptFile: optionValue("--validation-prompt-file")
3471
- .optional()
3472
- .describe("Replace final validation with the workflow in FILE (not Deep)."),
3473
- postScanPromptFile: optionValue("--post-scan-prompt-file")
3474
- .optional()
3475
- .describe("Run FILE after each scan, including failures."),
3476
- diff: optionValue("--diff")
3477
- .optional()
3478
- .describe("Scan committed Git changes from BASE to --head."),
3479
- workingTree: z
3480
- .boolean()
3481
- .optional()
3482
- .meta({ default: false })
3483
- .describe("Scan staged and unstaged changes against --base."),
3484
- head: optionValue("--head")
3485
- .optional()
3486
- .describe("Git head ref for --diff (default: HEAD)."),
3487
- base: optionValue("--base")
3488
- .optional()
3489
- .describe("Git base ref for --working-tree (default: HEAD)."),
3490
- mode: ScanSettingsSchema.shape.mode.describe("Scan mode (default: standard); deep supports repository and path targets."),
3491
- maxTime: ScanSettingsSchema.shape.maxTimeMinutes,
3492
- ...DEEP_SCAN_OPTION_SCHEMAS,
3493
- ...modelOptions(`OpenAI model to use (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`).shape,
3494
- provider: PROVIDER_OPTION,
3495
- outputDir: optionValue("--output-dir")
3496
- .optional()
3497
- .describe("Artifact directory outside the repository (default: Codex Security state; CODEX_SECURITY_STATE_DIR)."),
3498
- archiveExisting: z
3499
- .boolean()
3500
- .default(false)
3501
- .describe("Archive existing results; requires --output-dir."),
3502
- ...RUNTIME_OPTION_SCHEMAS,
3503
- failOnSeverity: FailureSeveritySchema.optional().describe("Exit 1 for findings at or above LEVEL."),
3504
- patch: z
3505
- .boolean()
3506
- .default(false)
3507
- .describe("Patch and verify confirmed findings after the scan."),
3508
- validate: z
3509
- .boolean()
3510
- .default(false)
3511
- .describe("Run standalone finding validation after the scan."),
3512
- patchSeverity: z
3513
- .enum(REPORTABLE_SEVERITIES)
3514
- .optional()
3515
- .describe("Patch findings at or above LEVEL; requires --patch."),
3516
- createPr: CREATE_PR_OPTION.describe("Create a draft pull request or merge request after verified patches; requires --patch."),
3517
- maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop above AMOUNT in estimated USD; the dashboard offers increases near the limit."),
3518
- ownerSuggestions: ScanSettingsSchema.shape.ownerSuggestions,
3519
- showCost: SHOW_COST_OPTION,
3520
- headless: z
3521
- .boolean()
3522
- .default(false)
3523
- .describe("Use plain text progress instead of the interactive dashboard."),
3524
- dryRun: z
3525
- .boolean()
3526
- .default(false)
3527
- .describe("Validate local scan inputs without starting a scan."),
3528
- mock: z
3529
- .boolean()
3530
- .default(false)
3531
- .describe("Save synthetic Standard scan findings without calling an LLM."),
3532
- })
3533
- .refine((options) => options.patchSeverity === undefined || options.patch, {
3534
- message: "--patch-severity requires --patch.",
3535
- })
3536
- .refine((options) => !options.createPr || options.patch, {
3537
- message: "--create-pr requires --patch.",
3538
- })
3539
- .refine((options) => !options.patch || !options.dryRun, {
3540
- message: "--patch cannot be combined with --dry-run.",
3541
- })
3542
- .refine((options) => !options.validate || !options.dryRun, {
3543
- message: "--validate cannot be combined with --dry-run.",
3544
- })
3545
- .refine((options) => !options.mock ||
3546
- (!options.dryRun && !options.patch && !options.validate), {
3547
- message: "--mock cannot be combined with --dry-run, --patch, or --validate.",
3548
- }),
3549
- output: scanOutputSchema("SCAN_FAILED"),
3550
- async run({ args, error: incurError, format, options }) {
3551
- if (options.host)
3552
- throw new CodexSecurityError("Use scan --host alone.");
3553
- if (format === "md") {
3554
- const error = new CodexSecurityError("Markdown output is not supported for scan results.");
3555
- errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
3556
- exitCode = 2;
3557
- throw error;
3558
- }
3559
- let outcome;
3560
- try {
3561
- const directory = dependencies.currentDirectory();
3562
- const project = await selectedProjectConfig(options.config, dependencies);
3563
- const scope = resolveCliScope(project?.input.scan?.scope, {
3564
- paths: options.path,
3565
- diff: options.diff,
3566
- workingTree: options.workingTree,
3567
- head: options.head,
3568
- base: options.base,
3569
- });
3570
- const { config, options: settings, projectConfig: provenance, } = resolveScanSettings(project, {
3571
- ...pickScanSettings(options),
3572
- target: scope.target,
3573
- knowledgeBasePaths: options.knowledgeBase,
3574
- failureSeverity: options.failOnSeverity,
3575
- maxCostUsd: options.maxCost,
3576
- maxTimeMinutes: options.maxTime,
3577
- codexOverrides: await parseScanCodexOverrides(options, dependencies.environment, project?.input.codex),
3578
- }, directory, scope.sources);
3579
- if (options.archiveExisting && settings.outputDir === undefined) {
3580
- throw new CodexSecurityError("--archive-existing requires --output-dir.");
3688
+ });
3689
+ function createScanCommands() {
3690
+ return Cli.create("scan", {
3691
+ description: "Scan a repository, selected paths, or Git changes.",
3692
+ usage: [
3693
+ {
3694
+ suffix: "[repository] [--path PATH | --diff REF | --working-tree] [options]",
3695
+ },
3696
+ { suffix: "--host" },
3697
+ { suffix: "import (--csv FILE | --json FILE) [options]" },
3698
+ ],
3699
+ examples: [
3700
+ { args: { repository: "." }, options: { dryRun: true } },
3701
+ { args: { repository: "." } },
3702
+ { args: { repository: "." }, options: { path: ["src", "tests"] } },
3703
+ { args: { repository: "." }, options: { workingTree: true } },
3704
+ { args: { repository: "." }, options: { diff: "origin/main" } },
3705
+ { args: { repository: "." }, options: { mode: "deep" } },
3706
+ ],
3707
+ hint: "Import existing findings without security analysis with scan import --help. Use ./import to scan a repository named import. Execution failures in JSON/JSONL --full-output return ok: false and keep scan results under data.",
3708
+ destructive: true,
3709
+ alias: { config: "c" },
3710
+ args: z.object({
3711
+ repository: z
3712
+ .string()
3713
+ .optional()
3714
+ .describe("Repository root to scan (default: current directory)."),
3715
+ }),
3716
+ options: z
3717
+ .object({
3718
+ config: PROJECT_CONFIG_OPTION,
3719
+ host: z
3720
+ .boolean()
3721
+ .default(false)
3722
+ .describe("Run one hosted Standard scan over JSON-RPC stdin/stdout; use alone."),
3723
+ workflowId: optionValue("--workflow-id")
3724
+ .optional()
3725
+ .describe("Reuse completed work in the named local findings workflow."),
3726
+ cyberAccessProgram: ScanSettingsSchema.shape.cyberAccessProgram,
3727
+ auth: ScanSettingsSchema.shape.auth.describe("Select ChatGPT, OPENAI_API_KEY/CODEX_API_KEY, or automatic authentication (default: auto)."),
3728
+ verbose: z
3729
+ .boolean()
3730
+ .default(false)
3731
+ .describe("Print additional scan diagnostics to stderr."),
3732
+ safetyIdentifier: optionValue("--safety-identifier")
3733
+ .optional()
3734
+ .describe("Stable hashed end-user ID for model requests (1–64 characters). Requires a compatible Codex runtime."),
3735
+ path: z
3736
+ .array(optionValue("--path"))
3737
+ .optional()
3738
+ .meta({ default: [] })
3739
+ .describe("Scan only PATH; repeat for multiple repository-relative paths."),
3740
+ knowledgeBase: z
3741
+ .array(optionValue("--knowledge-base"))
3742
+ .optional()
3743
+ .meta({ default: [] })
3744
+ .describe("Add security-context files or directories; repeat for multiple paths."),
3745
+ rubric: optionValue("--rubric")
3746
+ .optional()
3747
+ .describe("Use this Markdown file to grade findings. Takes precedence over the default severity rubric."),
3748
+ scanPromptFile: optionValue("--scan-prompt-file")
3749
+ .optional()
3750
+ .describe("Append scan instructions from FILE."),
3751
+ validationPromptFile: optionValue("--validation-prompt-file")
3752
+ .optional()
3753
+ .describe("Replace final validation with the workflow in FILE (not Deep)."),
3754
+ postScanPromptFile: optionValue("--post-scan-prompt-file")
3755
+ .optional()
3756
+ .describe("Run FILE after each scan, including failures."),
3757
+ diff: optionValue("--diff")
3758
+ .optional()
3759
+ .describe("Scan committed Git changes from BASE to --head."),
3760
+ workingTree: z
3761
+ .boolean()
3762
+ .optional()
3763
+ .meta({ default: false })
3764
+ .describe("Scan staged and unstaged changes against --base."),
3765
+ head: optionValue("--head")
3766
+ .optional()
3767
+ .describe("Git head ref for --diff (default: HEAD)."),
3768
+ base: optionValue("--base")
3769
+ .optional()
3770
+ .describe("Git base ref for --working-tree (default: HEAD)."),
3771
+ mode: ScanSettingsSchema.shape.mode.describe("Scan mode (default: standard); deep supports repository and path targets."),
3772
+ maxTime: ScanSettingsSchema.shape.maxTimeMinutes,
3773
+ ...DEEP_SCAN_OPTION_SCHEMAS,
3774
+ ...modelOptions(`OpenAI model to use (default: ${DEFAULT_SCAN_MODEL_CONFIGURATION.model}).`).shape,
3775
+ provider: PROVIDER_OPTION,
3776
+ outputDir: optionValue("--output-dir")
3777
+ .optional()
3778
+ .describe("Artifact directory outside the repository (default: Codex Security state; CODEX_SECURITY_STATE_DIR)."),
3779
+ archiveExisting: z
3780
+ .boolean()
3781
+ .default(false)
3782
+ .describe("Archive existing results; requires --output-dir."),
3783
+ ...RUNTIME_OPTION_SCHEMAS,
3784
+ failOnSeverity: FailureSeveritySchema.optional().describe("Exit 1 for findings at or above LEVEL."),
3785
+ patch: z
3786
+ .boolean()
3787
+ .default(false)
3788
+ .describe("Patch and verify findings after a scan without a cost limit."),
3789
+ validate: z
3790
+ .boolean()
3791
+ .default(false)
3792
+ .describe("Run standalone finding validation after the scan."),
3793
+ patchSeverity: z
3794
+ .enum(REPORTABLE_SEVERITIES)
3795
+ .optional()
3796
+ .describe("Patch findings at or above LEVEL; requires --patch."),
3797
+ createPr: CREATE_PR_OPTION.describe("Create a draft pull request or merge request after verified patches; requires --patch."),
3798
+ maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop above AMOUNT in estimated USD; the dashboard offers increases near the limit."),
3799
+ ownerSuggestions: ScanSettingsSchema.shape.ownerSuggestions,
3800
+ showCost: SHOW_COST_OPTION,
3801
+ headless: z
3802
+ .boolean()
3803
+ .default(false)
3804
+ .describe("Use plain text progress instead of the interactive dashboard."),
3805
+ dryRun: z
3806
+ .boolean()
3807
+ .default(false)
3808
+ .describe("Validate local scan inputs without starting a scan."),
3809
+ mock: z
3810
+ .boolean()
3811
+ .default(false)
3812
+ .describe("Save synthetic Standard scan findings without calling an LLM."),
3813
+ })
3814
+ .refine((options) => options.patchSeverity === undefined || options.patch, {
3815
+ message: "--patch-severity requires --patch.",
3816
+ })
3817
+ .refine((options) => !options.createPr || options.patch, {
3818
+ message: "--create-pr requires --patch.",
3819
+ })
3820
+ .refine((options) => !options.patch || !options.dryRun, {
3821
+ message: "--patch cannot be combined with --dry-run.",
3822
+ })
3823
+ .refine((options) => !options.validate || !options.dryRun, {
3824
+ message: "--validate cannot be combined with --dry-run.",
3825
+ })
3826
+ .refine((options) => !options.mock ||
3827
+ (!options.dryRun && !options.patch && !options.validate), {
3828
+ message: "--mock cannot be combined with --dry-run, --patch, or --validate.",
3829
+ }),
3830
+ output: scanOutputSchema("SCAN_FAILED"),
3831
+ async run({ args, error: incurError, format, options }) {
3832
+ if (options.host)
3833
+ throw new CodexSecurityError("Use scan --host alone.");
3834
+ if (format === "md") {
3835
+ const error = new CodexSecurityError("Markdown output is not supported for scan results.");
3836
+ errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
3837
+ exitCode = 2;
3838
+ throw error;
3581
3839
  }
3582
- if (options.validate && settings.maxCostUsd !== undefined) {
3583
- throw new CodexSecurityError("--validate cannot be combined with a scan cost limit because standalone validation is not cost-tracked.");
3840
+ let outcome;
3841
+ try {
3842
+ const directory = dependencies.currentDirectory();
3843
+ const project = await selectedProjectConfig(options.config, dependencies);
3844
+ const scope = resolveCliScope(project?.input.scan?.scope, {
3845
+ paths: options.path,
3846
+ diff: options.diff,
3847
+ workingTree: options.workingTree,
3848
+ head: options.head,
3849
+ base: options.base,
3850
+ });
3851
+ const { config, options: settings, projectConfig: provenance, } = resolveScanSettings(project, {
3852
+ ...pickScanSettings(options),
3853
+ target: scope.target,
3854
+ knowledgeBasePaths: options.knowledgeBase,
3855
+ failureSeverity: options.failOnSeverity,
3856
+ maxCostUsd: options.maxCost,
3857
+ maxTimeMinutes: options.maxTime,
3858
+ codexOverrides: await parseScanCodexOverrides(options, dependencies.environment, project?.input.codex),
3859
+ }, directory, scope.sources);
3860
+ if (options.archiveExisting && settings.outputDir === undefined) {
3861
+ throw new CodexSecurityError("--archive-existing requires --output-dir.");
3862
+ }
3863
+ if (options.validate && settings.maxCostUsd !== undefined) {
3864
+ throw new CodexSecurityError("--validate cannot be combined with a scan cost limit because standalone validation is not cost-tracked.");
3865
+ }
3866
+ outcome = await runScan(format, {
3867
+ ...settings,
3868
+ rubricPath: options.rubric === undefined
3869
+ ? undefined
3870
+ : resolveCliPath(directory, options.rubric),
3871
+ codexOverrides: config.codexOverrides,
3872
+ projectConfig: provenance,
3873
+ workflowId: options.workflowId,
3874
+ safetyIdentifier: options.safetyIdentifier,
3875
+ verbose: options.verbose,
3876
+ repository: args.repository,
3877
+ archiveExisting: options.archiveExisting,
3878
+ pluginPath: options.pluginPath,
3879
+ pythonPath: options.python,
3880
+ patch: options.patch,
3881
+ validate: options.validate,
3882
+ patchSeverity: options.patchSeverity,
3883
+ createPr: options.createPr,
3884
+ showCost: options.showCost,
3885
+ headless: options.headless,
3886
+ dryRun: options.dryRun,
3887
+ mock: options.mock,
3888
+ });
3584
3889
  }
3585
- outcome = await runScan(format, {
3586
- ...settings,
3587
- rubricPath: options.rubric === undefined
3890
+ catch (error) {
3891
+ const message = errorMessage(error);
3892
+ errorOutput.write(`${diagnosticLines(message)}\n`);
3893
+ outcome = { exitCode: 2, error: message };
3894
+ }
3895
+ return options.dryRun
3896
+ ? finishScan(outcome, format, incurError)
3897
+ : finishScanCommand(outcome, format, incurError);
3898
+ },
3899
+ }).command("import", {
3900
+ usage: [{ suffix: "FILE [options]" }],
3901
+ description: "Save CSV or JSON findings as a completed scan without security analysis.",
3902
+ destructive: true,
3903
+ args: z.object({
3904
+ file: z
3905
+ .string({ error: "Provide a findings file to import." })
3906
+ .min(1)
3907
+ .describe("Findings file to import."),
3908
+ }),
3909
+ options: z
3910
+ .object({
3911
+ inputFormat: z
3912
+ .enum(["csv", "json"])
3913
+ .optional()
3914
+ .describe("Input format (default: inferred from .csv or .json)."),
3915
+ outputDir: optionValue("--output-dir")
3916
+ .optional()
3917
+ .describe("Artifact directory (default: Codex Security state; CODEX_SECURITY_STATE_DIR)."),
3918
+ archiveExisting: z
3919
+ .boolean()
3920
+ .default(false)
3921
+ .describe("Archive existing results; requires --output-dir."),
3922
+ dryRun: z
3923
+ .boolean()
3924
+ .default(false)
3925
+ .describe("Validate the input without saving a scan."),
3926
+ })
3927
+ .refine((options) => !options.archiveExisting || options.outputDir !== undefined, { message: "--archive-existing requires --output-dir." }),
3928
+ examples: [
3929
+ { args: { file: "findings.csv" } },
3930
+ { args: { file: "report" }, options: { inputFormat: "json" } },
3931
+ ],
3932
+ hint: "Each input row is retained, including duplicates. Use FILE --json for JSON output. Legacy --csv FILE and --json FILE still select the input format.",
3933
+ output: z.record(z.string(), z.unknown()).optional(),
3934
+ async run({ args, options, format, error: incurError }) {
3935
+ const directory = dependencies.currentDirectory();
3936
+ const inputFormat = options.inputFormat ?? extname(args.file).slice(1).toLowerCase();
3937
+ if (inputFormat !== "csv" && inputFormat !== "json") {
3938
+ exitCode = 2;
3939
+ const message = "Cannot infer input format. Use --input-format csv or --input-format json.";
3940
+ errorOutput.write(`codex-security: ${message}\n`);
3941
+ return incurError({
3942
+ code: "INVALID_INPUT_FORMAT",
3943
+ message,
3944
+ exitCode,
3945
+ });
3946
+ }
3947
+ const outcome = await runImport({
3948
+ sourcePath: resolveCliPath(directory, args.file),
3949
+ format: inputFormat,
3950
+ outputDir: options.outputDir === undefined
3588
3951
  ? undefined
3589
- : resolveCliPath(directory, options.rubric),
3590
- codexOverrides: config.codexOverrides,
3591
- projectConfig: provenance,
3592
- workflowId: options.workflowId,
3593
- safetyIdentifier: options.safetyIdentifier,
3594
- verbose: options.verbose,
3595
- repository: args.repository,
3952
+ : resolveCliPath(directory, options.outputDir),
3596
3953
  archiveExisting: options.archiveExisting,
3597
- pluginPath: options.pluginPath,
3598
- pythonPath: options.python,
3599
- patch: options.patch,
3600
- validate: options.validate,
3601
- patchSeverity: options.patchSeverity,
3602
- createPr: options.createPr,
3603
- showCost: options.showCost,
3604
- headless: options.headless,
3605
3954
  dryRun: options.dryRun,
3606
- mock: options.mock,
3607
3955
  });
3608
- }
3609
- catch (error) {
3610
- const message = errorMessage(error);
3611
- errorOutput.write(`${diagnosticLines(message)}\n`);
3612
- outcome = { exitCode: 2, error: message };
3613
- }
3614
- return options.dryRun
3615
- ? finishScan(outcome, format, incurError)
3616
- : finishScanCommand(outcome, format, incurError);
3617
- },
3618
- })
3956
+ exitCode = outcome.exitCode;
3957
+ if (outcome.error !== undefined) {
3958
+ return incurError({
3959
+ code: "SCAN_IMPORT_FAILED",
3960
+ message: outcome.error,
3961
+ exitCode,
3962
+ });
3963
+ }
3964
+ if (!options.dryRun && useDefaultOutput(format)) {
3965
+ return;
3966
+ }
3967
+ return outcome.data;
3968
+ },
3969
+ });
3970
+ }
3971
+ cli
3972
+ .command(createScanCommands())
3619
3973
  .command("install-hook", {
3620
- description: "Install a local pre-commit hook that blocks on scan errors or findings at the selected severity threshold.",
3974
+ description: "Install a pre-commit hook that scans staged and unstaged working-tree changes and blocks on errors or findings at the selected severity.",
3975
+ examples: [
3976
+ { args: { repository: "." }, options: { failOnSeverity: "high" } },
3977
+ ],
3621
3978
  hint: "Require a passing scan in CI to enforce a scan before merging.",
3622
3979
  destructive: true,
3623
3980
  args: z.object({
@@ -3641,43 +3998,26 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3641
3998
  async run({ args, options }) {
3642
3999
  try {
3643
4000
  const cwd = dependencies.currentDirectory();
3644
- const repository = resolveCliPath(cwd, args.repository ?? ".");
3645
4001
  const environment = dependencies.environment;
3646
- const git = await trustedGitCommand(repository, true, environment, await commandGitProtectionRoots(repository, environment, undefined, cwd));
3647
- const hook = execFileSync(git.executable, [
4002
+ const requested = resolveInputPath(args.repository ?? ".", cwd, environment);
4003
+ const repository = await resolveParentTraversal(requested);
4004
+ const git = await trustedGitCommand(repository, true, environment, await commandGitProtectionRoots(repository, environment, undefined, { cwd, requestedPaths: [resolve(requested)] }));
4005
+ const hooksDirectory = execFileSync(git.executable, [
3648
4006
  "-C",
3649
4007
  repository,
3650
4008
  "rev-parse",
3651
4009
  "--path-format=absolute",
3652
4010
  "--git-path",
3653
- "hooks/pre-commit",
3654
- ], { encoding: "utf8", env: git.environment }).trim();
4011
+ "hooks",
4012
+ ], { encoding: "utf8", env: git.environment }).replace(/\r?\n$/u, "");
4013
+ const hook = join(hooksDirectory, "pre-commit");
3655
4014
  const command = [
3656
4015
  realpathSync(process.execPath),
3657
4016
  realpathSync(fileURLToPath(import.meta.url)),
3658
4017
  ]
3659
4018
  .map((path) => `'${path.replaceAll("'", `'"'"'`)}'`)
3660
4019
  .join(" ");
3661
- const invocation = `exec ${command} scan . --working-tree --fail-on-severity ${options.failOnSeverity}\n`;
3662
- const contents = `#!/bin/sh\nset -eu\nunset ${[...UNSUPPORTED_GIT_ENVIRONMENT].join(" ")}\n${invocation}`;
3663
- const previousScopedContents = `#!/bin/sh\nset -eu\nunset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE\n${invocation}`;
3664
- const previousContents = `#!/bin/sh\nset -eu\n${invocation}`;
3665
- const legacyContents = `#!/bin/sh\nset -eu\nexec npx --no-install codex-security scan . --working-tree --fail-on-severity ${options.failOnSeverity}\n`;
3666
- const existing = await readFile(hook, "utf8").catch(() => null);
3667
- if (existing !== null &&
3668
- existing !== contents &&
3669
- existing !== previousScopedContents &&
3670
- existing !== previousContents &&
3671
- existing !== legacyContents) {
3672
- throw new Error(`A pre-commit hook already exists at ${hook}.`);
3673
- }
3674
- if (existing === null) {
3675
- await mkdir(dirname(hook), { recursive: true });
3676
- await writeFile(hook, contents, { flag: "wx", mode: 0o755 });
3677
- }
3678
- else if (existing !== contents) {
3679
- await writeFile(hook, contents, { flag: "w" });
3680
- }
4020
+ await installManagedHook(hook, command, options.failOnSeverity);
3681
4021
  return {
3682
4022
  hook,
3683
4023
  failOnSeverity: options.failOnSeverity,
@@ -3690,10 +4030,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3690
4030
  }
3691
4031
  },
3692
4032
  })
3693
- .command(scanHistory)
3694
4033
  .command(findingFeedback)
3695
4034
  .command(publication)
3696
4035
  .command("suggest-owners", {
4036
+ examples: [{ args: { findings: "findings.json" } }],
3697
4037
  description: "Suggest finding owners from CODEOWNERS and Git history.",
3698
4038
  destructive: false,
3699
4039
  args: z.object({
@@ -3714,7 +4054,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3714
4054
  const removeSignals = listenForAbort(dependencies, controller);
3715
4055
  try {
3716
4056
  const directory = dependencies.currentDirectory();
3717
- const repository = resolveCliPath(directory, options.sourceRoot ?? ".");
4057
+ const repository = resolveInputPath(options.sourceRoot ?? ".", directory);
3718
4058
  const findings = await parseImportedFindings(await readRegularInputFile(resolveCliPath(directory, args.findings), repository), "json", await bundledPluginRoot());
3719
4059
  const result = await (dependencies.suggestOwners ?? suggestOwnersInternal)(repository, findings, {
3720
4060
  environment: dependencies.environment,
@@ -3739,7 +4079,12 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3739
4079
  })
3740
4080
  .command("classify-severity", {
3741
4081
  description: "Assess severity for saved findings or canonical records.",
3742
- hint: "For saved findings, use --rubric for your own policy or set CODEX_SECURITY_ENABLE_REMOTE_SEVERITY_RUBRIC=1 for the Statsig default. For host-provided reviews, use --records.",
4082
+ usage: [
4083
+ { suffix: "(--scan ID | --scan-dir DIR) [options]" },
4084
+ { suffix: "--records [--runs COUNT]" },
4085
+ ],
4086
+ examples: [{ options: { scan: "latest" } }],
4087
+ hint: `Use the built-in severity rubric or select --rubric FILE. Each uncached finding receives ${DEFAULT_REVIEW_RUNS} model reviews by default. Use --reprocess to replace saved assessments. --records accepts host-provided reviews over JSON-RPC.`,
3743
4088
  destructive: true,
3744
4089
  options: z.object({
3745
4090
  runs: reviewRunsOption.describe(`Number of independent classification runs (1–10; default: ${DEFAULT_REVIEW_RUNS}).`),
@@ -3821,8 +4166,14 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3821
4166
  },
3822
4167
  })
3823
4168
  .command("dedupe", {
3824
- description: "Identify duplicate findings in a saved scan.",
3825
- hint: "Use --records alone for host-provided reviews over JSON-RPC.",
4169
+ description: "Find duplicates against the saved findings corpus.",
4170
+ usage: [
4171
+ { suffix: "--scan ID [--workflow-id ID] [options]" },
4172
+ { suffix: "--workflow-id ID [options]" },
4173
+ { suffix: "--records" },
4174
+ ],
4175
+ examples: [{ options: { scan: "latest" } }],
4176
+ hint: "Service-backed deduplication can save duplicate groups to the selected findings service. Use --records alone for host-provided reviews over JSON-RPC.",
3826
4177
  destructive: true,
3827
4178
  options: z.object({
3828
4179
  concurrency: positiveInteger
@@ -3852,6 +4203,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3852
4203
  .object({
3853
4204
  scanId: z.string(),
3854
4205
  uniqueFindingIds: z.array(z.string()),
4206
+ scanRepresentativeFindingIds: z.array(z.string()),
3855
4207
  duplicateGroups: z.array(z.array(z.string())),
3856
4208
  deduplicationStatus: z.enum(["completed", "completed_with_refusals"]),
3857
4209
  refusals: z
@@ -3968,7 +4320,30 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3968
4320
  })
3969
4321
  .command(imports)
3970
4322
  .command("scan-components", {
3971
- description: "Scan project components and combine results.",
4323
+ description: "Scan project components independently and combine their results.",
4324
+ usage: [
4325
+ {
4326
+ suffix: "[repository] (--component PATH | --components-file FILE | --auto) --output-dir DIR [options]",
4327
+ },
4328
+ ],
4329
+ examples: [
4330
+ {
4331
+ args: { repository: "." },
4332
+ options: {
4333
+ component: ["services/api"],
4334
+ outputDir: "../component-results",
4335
+ },
4336
+ },
4337
+ {
4338
+ args: { repository: "." },
4339
+ options: {
4340
+ auto: true,
4341
+ planOnly: true,
4342
+ outputDir: "../component-plan",
4343
+ },
4344
+ },
4345
+ ],
4346
+ hint: "Supply --output-dir or configure output.directory. Automatic planning can call a model even with --plan-only. A per-component --max-cost does not cover planning.",
3972
4347
  destructive: true,
3973
4348
  alias: { config: "c" },
3974
4349
  args: z.object({
@@ -3997,7 +4372,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
3997
4372
  planOnly: z
3998
4373
  .boolean()
3999
4374
  .default(false)
4000
- .describe("Save components.json without starting scans."),
4375
+ .describe("Save components.json and print a command to run it. Explicit plans work offline."),
4001
4376
  headless: z
4002
4377
  .boolean()
4003
4378
  .default(false)
@@ -4022,6 +4397,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4022
4397
  ...modelOptions("Model for planning and component scans.").shape,
4023
4398
  provider: PROVIDER_OPTION,
4024
4399
  maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop each component scan if estimated USD cost exceeds AMOUNT."),
4400
+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe("Divide estimated USD among explicit components for this invocation. Skips model-based finding matching and owner suggestions."),
4025
4401
  showCost: SHOW_COST_OPTION,
4026
4402
  ...RUNTIME_OPTION_SCHEMAS,
4027
4403
  })
@@ -4047,7 +4423,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4047
4423
  signalHandlers(dependencies, "add", onInterrupt, onTerminate);
4048
4424
  try {
4049
4425
  const directory = dependencies.currentDirectory();
4050
- const repository = resolveCliPath(directory, args.repository ?? ".");
4426
+ const repository = resolveInputPath(args.repository ?? ".", directory);
4051
4427
  const project = await selectedProjectConfig(options.config, dependencies);
4052
4428
  const resolved = resolveScanSettings(project, {
4053
4429
  ...pickScanSettings({ ...options, workers: undefined }),
@@ -4080,6 +4456,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4080
4456
  pricingContext: scanPricingContext(dashboardConfig, dependencies.environment),
4081
4457
  mode: settings.mode,
4082
4458
  maxCostUsd: settings.maxCostUsd,
4459
+ maxTotalCostUsd: options.maxTotalCost,
4083
4460
  showCost: options.showCost,
4084
4461
  clock: dependencies,
4085
4462
  color: dependencies.environment["NO_COLOR"] === undefined,
@@ -4099,6 +4476,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4099
4476
  outputDir: settings.outputDir,
4100
4477
  ...(options.auto ? { auto: true } : { components }),
4101
4478
  planOnly: options.planOnly,
4479
+ maxTotalCostUsd: options.maxTotalCost,
4102
4480
  workers: options.workers,
4103
4481
  config,
4104
4482
  scanOptions: {
@@ -4109,6 +4487,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4109
4487
  planComponents: dependencies.planComponents,
4110
4488
  matchFindings: dependencies.matchFindings,
4111
4489
  onPlan: (components) => {
4490
+ if (dashboard === null && options.maxTotalCost !== undefined)
4491
+ errorOutput.write(`codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`);
4112
4492
  for (const component of components)
4113
4493
  componentNames.set(component.id, component.name);
4114
4494
  dashboard?.setComponents(components);
@@ -4117,7 +4497,9 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4117
4497
  ? (event) => {
4118
4498
  const componentName = diagnosticValue(componentNames.get(event.componentId) ??
4119
4499
  event.componentId);
4120
- const line = componentScanEventLine(componentName, event, options.showCost || settings.maxCostUsd !== undefined, settings.auth);
4500
+ const line = componentScanEventLine(componentName, event, options.showCost ||
4501
+ settings.maxCostUsd !== undefined ||
4502
+ options.maxTotalCost !== undefined, settings.auth);
4121
4503
  if (line !== null)
4122
4504
  errorOutput.write(line);
4123
4505
  }
@@ -4133,17 +4515,54 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4133
4515
  onProgress: (component) => {
4134
4516
  if (dashboard !== null)
4135
4517
  dashboard.updateComponent(component);
4136
- else
4137
- errorOutput.write(`codex-security: ${diagnosticValue(component.name)} ${component.status}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`);
4518
+ else {
4519
+ const budget = component.status === "started" &&
4520
+ component.maxCostUsd !== undefined
4521
+ ? ` (${formatUsd(component.maxCostUsd)} per component)`
4522
+ : "";
4523
+ errorOutput.write(`codex-security: ${diagnosticValue(component.name)} ${component.status}${budget}${component.error === undefined ? "" : `: ${diagnosticValue(component.error)}`}\n`);
4524
+ }
4138
4525
  },
4139
4526
  onComplete: (result) => {
4140
4527
  dashboard?.finishComponents(result);
4141
4528
  stopDashboard();
4142
- errorOutput.write(`Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`);
4529
+ errorOutput.write(`Component scans: ${result.completed} complete, ${result.failed} failed.\n${result.sourceFindingCount} findings → ${result.findingCount} groups${result.deduplication?.status === "failed" ? " (matching failed)" : result.deduplication?.status === "skipped" ? " (matching skipped under total cost limit)" : ""}.\nReport: ${errorMessage(result.reportPath)}\n`);
4143
4530
  if (result.retryPlanPath !== undefined)
4144
4531
  errorOutput.write(`Retry with --components-file ${JSON.stringify(errorMessage(result.retryPlanPath))} and a new --output-dir.\n`);
4145
4532
  },
4146
4533
  });
4534
+ if (options.planOnly) {
4535
+ const { auto, component, componentsFile, planOnly, outputDir, config, codex, ...scanOptions } = options;
4536
+ const supplied = new Set(argv.map((arg) => arg.split("=", 1)[0]));
4537
+ const overrides = Object.fromEntries(Object.entries(scanOptions).filter(([key]) => {
4538
+ const flag = cliOptionFlag(key);
4539
+ return (supplied.has(flag) ||
4540
+ supplied.has(`--${key}`) ||
4541
+ supplied.has(`--no-${flag.slice(2)}`));
4542
+ }));
4543
+ const nextCommand = [
4544
+ "codex-security",
4545
+ "scan-components",
4546
+ quoteCliPath(repository),
4547
+ ...cliOptionTokens({
4548
+ componentsFile: result.planPath,
4549
+ outputDir: join(dirname(result.planPath), "results"),
4550
+ config: project?.path,
4551
+ ...overrides,
4552
+ }),
4553
+ ].join(" ");
4554
+ const nextCommandNote = codex.length > 0
4555
+ ? "Reapply your --codex overrides when running this command."
4556
+ : undefined;
4557
+ errorOutput.write(`Run this plan: ${diagnosticValue(nextCommand)}\n`);
4558
+ if (nextCommandNote)
4559
+ errorOutput.write(`${nextCommandNote}\n`);
4560
+ return {
4561
+ ...result,
4562
+ nextCommand,
4563
+ ...(nextCommandNote && { nextCommandNote }),
4564
+ };
4565
+ }
4147
4566
  exitCode =
4148
4567
  interruptedExitCode(controller.signal) ??
4149
4568
  (result.failed || result.deduplication?.status === "failed"
@@ -4186,7 +4605,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4186
4605
  .string()
4187
4606
  .min(1, "--output-dir must not be empty.")
4188
4607
  .optional()
4189
- .describe("Resumable results directory; required with a repository CSV."),
4608
+ .describe("Results directory. Required with a CSV and used as the initial directory in the wizard."),
4190
4609
  knowledgeBase: z
4191
4610
  .array(optionValue("--knowledge-base"))
4192
4611
  .optional()
@@ -4211,18 +4630,25 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4211
4630
  .default(1)
4212
4631
  .describe("Maximum scan attempts per repository."),
4213
4632
  maxCost: ScanSettingsSchema.shape.maxCostUsd.describe("Stop each repository attempt if estimated USD cost exceeds AMOUNT."),
4633
+ maxTotalCost: ScanSettingsSchema.shape.maxCostUsd.describe("Divide estimated USD among pending repository attempts, including retries, for this invocation. Skips model-based finding matching and owner suggestions."),
4214
4634
  ...runtimeOptions(() => z.string().min(1)),
4215
4635
  }),
4636
+ usage: [
4637
+ { suffix: "[options]" },
4638
+ { suffix: "repositories.csv --output-dir DIR [options]" },
4639
+ { suffix: "repositories.csv --recover --output-dir DIR [options]" },
4640
+ ],
4216
4641
  examples: [
4217
4642
  {
4218
- args: {},
4219
- options: { model: "gpt-5.6-terra", effort: "high" },
4643
+ args: { input: "repositories.csv" },
4644
+ options: { outputDir: "../campaign", workers: 4, maxAttempts: 3 },
4645
+ },
4646
+ {
4647
+ args: { input: "repositories.csv" },
4648
+ options: { recover: true, outputDir: "../campaign" },
4220
4649
  },
4221
4650
  ],
4222
- hint: "CSV example:\n" +
4223
- " codex-security bulk-scan repositories.csv " +
4224
- "--output-dir /path/outside/repositories/results " +
4225
- "--workers 4 --max-attempts 3",
4651
+ hint: "Omit the CSV to select repositories interactively. A configured output.directory can supply the results directory; --max-cost applies per repository attempt.",
4226
4652
  output: z.record(z.string(), z.unknown()).optional(),
4227
4653
  async run({ args, options }) {
4228
4654
  const controller = new AbortController();
@@ -4244,9 +4670,6 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4244
4670
  let outputDir;
4245
4671
  let githubHost;
4246
4672
  if (args.input === undefined) {
4247
- if (options.outputDir !== undefined) {
4248
- throw new Error("--output-dir can only be used with a repository CSV; omit it to choose an output directory interactively.");
4249
- }
4250
4673
  const wizard = await runBulkScanWizard(dependencies.bulkScan ??
4251
4674
  createBulkScanDiscoveryDependencies({
4252
4675
  output: errorOutput,
@@ -4263,7 +4686,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4263
4686
  if (settings.outputDir === undefined) {
4264
4687
  throw new Error("--output-dir is required with a repository CSV.");
4265
4688
  }
4266
- inputPath = resolveCliPath(currentDirectory, args.input);
4689
+ inputPath = resolveInputPath(args.input, currentDirectory);
4267
4690
  outputDir = settings.outputDir;
4268
4691
  }
4269
4692
  const scanOptionsByMode = project === undefined
@@ -4272,6 +4695,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4272
4695
  mode,
4273
4696
  resolveScanSettings(project, { ...overrides, mode }, currentDirectory).options,
4274
4697
  ]));
4698
+ if (options.maxTotalCost !== undefined)
4699
+ errorOutput.write(`codex-security: ${formatUsd(options.maxTotalCost)} total limit for this invocation. Model-based finding matching and owner suggestions are skipped.\n`);
4275
4700
  const result = await runMultiscan({
4276
4701
  inputPath,
4277
4702
  outputDir,
@@ -4279,6 +4704,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4279
4704
  workers: options.workers,
4280
4705
  mode: settings.mode,
4281
4706
  maxAttempts: options.maxAttempts,
4707
+ maxTotalCostUsd: options.maxTotalCost,
4282
4708
  ...(settings.maxCostUsd === undefined
4283
4709
  ? {}
4284
4710
  : { maxCostUsd: settings.maxCostUsd }),
@@ -4308,6 +4734,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4308
4734
  signal: controller.signal,
4309
4735
  });
4310
4736
  return {
4737
+ alreadyCompleted: true,
4311
4738
  manifest: contract.manifest,
4312
4739
  findings: contract.findings,
4313
4740
  cost: scan["cost"] ??
@@ -4341,6 +4768,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4341
4768
  try {
4342
4769
  return await security.run(recipe.repository, {
4343
4770
  ...pickScanSettings(recipe),
4771
+ ...batchScanBudget(prompts.maxTotalCostShareUsd, recipe),
4344
4772
  knowledgeBaseSnapshot: prompts.knowledgeBaseSnapshot,
4345
4773
  telemetryContext: prompts.telemetryContext,
4346
4774
  onTelemetry: prompts.onTelemetry,
@@ -4359,9 +4787,12 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4359
4787
  }
4360
4788
  : {}),
4361
4789
  signal: controller.signal,
4362
- onProgress: ({ repository, status, attempt, error, warning }) => {
4790
+ onProgress: ({ repository, status, attempt, maxCostUsd, error, warning, }) => {
4363
4791
  const detail = error ?? warning;
4364
- errorOutput.write(`codex-security: ${repository} ${status} (attempt ${attempt})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`);
4792
+ const budget = maxCostUsd === undefined
4793
+ ? ""
4794
+ : `, ${formatUsd(maxCostUsd)} per repository attempt`;
4795
+ errorOutput.write(`codex-security: ${repository} ${status} (attempt ${attempt}${budget})${detail === undefined ? "" : `: ${diagnosticValue(detail)}`}\n`);
4365
4796
  },
4366
4797
  });
4367
4798
  exitCode =
@@ -4390,6 +4821,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4390
4821
  " codex-security export --export-format json --output -\n" +
4391
4822
  " codex-security export ../scan-results --export-format csv\n" +
4392
4823
  " codex-security export --artifact threat-model --output -\n\n" +
4824
+ "Implicit filenames: results.sarif, findings.json, findings.csv, servicenow-avit.csv, or threatmodel.md.\n" +
4393
4825
  "Use --export-format for artifact format. The global --format option controls\n" +
4394
4826
  "framework output such as --schema; it does not change exported files.",
4395
4827
  destructive: true,
@@ -4417,7 +4849,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4417
4849
  .describe("Per-application CSV template required for servicenow-avit exports."),
4418
4850
  output: optionValue("--output")
4419
4851
  .optional()
4420
- .describe("FILE or '-' for stdout (default: results.sarif, findings.json, findings.csv, servicenow-avit.csv, or threatmodel.md)."),
4852
+ .describe("FILE to replace or '-' for raw stdout. Default filenames are created only if absent."),
4421
4853
  sourceRoot: optionValue("--source-root")
4422
4854
  .optional()
4423
4855
  .describe("Repository checkout used for SARIF source-line fingerprints."),
@@ -4434,6 +4866,26 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4434
4866
  async run({ args, options }) {
4435
4867
  rawExportOutput = options.output === "-";
4436
4868
  try {
4869
+ if (rawExportOutput) {
4870
+ const responseFlag = frameworkFlags.filters.length
4871
+ ? "--filter-output"
4872
+ : frameworkFlags.fullOutput
4873
+ ? "--full-output"
4874
+ : frameworkFlags.tokenArguments[0];
4875
+ if (responseFlag) {
4876
+ throw new CodexSecurityError(`${responseFlag} cannot be used with raw artifact stdout. Omit it to pipe the complete artifact.`);
4877
+ }
4878
+ const markdown = options.artifact === "threat-model" ||
4879
+ options.exportFormat === "md";
4880
+ const csv = options.exportFormat === "csv" ||
4881
+ options.exportFormat === "servicenow-avit";
4882
+ const expectedFormat = markdown ? "md" : csv ? undefined : "json";
4883
+ const incompatible = frameworkFlags.formats.find((value) => value !== expectedFormat);
4884
+ if (incompatible !== undefined) {
4885
+ const label = markdown ? "Markdown" : csv ? "CSV" : "JSON";
4886
+ throw new CodexSecurityError(`${label} stdout cannot be combined with --format ${incompatible}. Omit the response format to pipe the complete artifact.`);
4887
+ }
4888
+ }
4437
4889
  const currentDirectory = dependencies.currentDirectory();
4438
4890
  if (args.scanDir !== undefined && options.scan !== undefined) {
4439
4891
  throw new CodexSecurityError("--scan cannot be combined with a result directory.");
@@ -4441,15 +4893,16 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4441
4893
  const format = resolveArtifactFormat(options.artifact, options.exportFormat, options.avitTemplate);
4442
4894
  const sourceRoot = options.sourceRoot === undefined
4443
4895
  ? undefined
4444
- : resolveCliPath(currentDirectory, options.sourceRoot);
4445
- const protectedRoot = sourceRoot === undefined
4446
- ? undefined
4447
- : [currentDirectory, sourceRoot];
4896
+ : resolveInputPath(options.sourceRoot, currentDirectory);
4897
+ const protectedRoot = await artifactSourceProtectionRoots(sourceRoot, currentDirectory);
4448
4898
  let scanDir = args.scanDir;
4449
4899
  if (scanDir === undefined) {
4450
4900
  let scanId = options.scan;
4451
4901
  if (!scanId || scanId === "latest") {
4452
- const scans = await latestScans(1, "complete", options.python, protectedRoot);
4902
+ const scans = await latestScans(1, "complete", {
4903
+ pythonPath: options.python,
4904
+ protectedRoot,
4905
+ });
4453
4906
  scanId = scans?.[0]?.scanId;
4454
4907
  }
4455
4908
  if (scanId === undefined)
@@ -4461,10 +4914,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4461
4914
  ? "-"
4462
4915
  : resolveCliPath(currentDirectory, destination);
4463
4916
  const prepared = await resolveArtifactExportOutput({
4464
- scanDir: resolveCliPath(currentDirectory, scanDir),
4917
+ scanDir: resolveInputPath(scanDir, currentDirectory),
4465
4918
  artifact: options.artifact,
4466
4919
  format,
4467
4920
  output: outputPath,
4921
+ noClobber: options.output === undefined,
4468
4922
  sourceRoot,
4469
4923
  avitTemplate: options.avitTemplate,
4470
4924
  pythonPath: options.python,
@@ -4490,6 +4944,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4490
4944
  },
4491
4945
  })
4492
4946
  .command("validate", {
4947
+ usage: [{ suffix: "<findings...> [options]" }, { suffix: "--records" }],
4948
+ examples: [{ args: { "findings...": "findings.json" } }],
4493
4949
  hint: "Use --records alone for host-provided reviews over JSON-RPC.",
4494
4950
  description: "Assess candidate security findings using source evidence only.",
4495
4951
  destructive: false,
@@ -4497,7 +4953,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4497
4953
  "findings...": z
4498
4954
  .string()
4499
4955
  .min(1, "A finding must not be empty.")
4500
- .describe("Finding text or a file containing findings."),
4956
+ .describe("Finding text, a local file path or file URL. Use text:VALUE to pass path-shaped prose."),
4501
4957
  }),
4502
4958
  options: z.object({
4503
4959
  records: z
@@ -4526,7 +4982,11 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4526
4982
  if (options.records)
4527
4983
  throw new CodexSecurityError("Use validate --records alone.");
4528
4984
  if (options.knowledgeBase.length > 0) {
4529
- knowledgeBase = await prepareKnowledgeBase(options.knowledgeBase.map((path) => resolveCliPath(dependencies.currentDirectory(), path)));
4985
+ const directory = dependencies.currentDirectory();
4986
+ const checkout = await gitMarkerRoot(directory, undefined, "nearest");
4987
+ const paths = options.knowledgeBase.map((path) => resolveCliPath(directory, path));
4988
+ const snapshot = await readKnowledgeBaseSnapshot(paths, undefined, checkout ? [checkout] : []);
4989
+ knowledgeBase = await prepareKnowledgeBase(snapshot);
4530
4990
  }
4531
4991
  exitCode = await runSkill("validation", positionals, options, output, errorOutput, dependencies, {
4532
4992
  auth: options.auth,
@@ -4549,6 +5009,12 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4549
5009
  },
4550
5010
  })
4551
5011
  .command("verify-fix", {
5012
+ usage: [
5013
+ { suffix: "FINDING... [options]" },
5014
+ { suffix: "--scan ID [--severity LEVEL] [options]" },
5015
+ { suffix: "(--linear-issue ID | --linear-project PROJECT) [options]" },
5016
+ { suffix: "--host" },
5017
+ ],
4552
5018
  description: "Verify existing security fixes without changing the repository.",
4553
5019
  destructive: false,
4554
5020
  args: z.object({
@@ -4556,7 +5022,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4556
5022
  .string()
4557
5023
  .min(1, "A finding must not be empty.")
4558
5024
  .optional()
4559
- .describe("Finding text, a file, or a saved finding identifier."),
5025
+ .describe("Finding text, a local file path or URL, or a saved finding identifier. Use text:VALUE to pass path-shaped prose."),
4560
5026
  }),
4561
5027
  options: z.object({
4562
5028
  host: z
@@ -4579,13 +5045,22 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4579
5045
  description: "Verify a fix described in a file.",
4580
5046
  },
4581
5047
  ],
4582
- output: z.record(z.string(), z.unknown()).optional(),
5048
+ output: z
5049
+ .union([
5050
+ z.object({
5051
+ repository: z.string(),
5052
+ scanId: z.string().optional(),
5053
+ results: z.array(FindingVerificationSchema),
5054
+ }),
5055
+ cliFailureSchema("VERIFICATION_FAILED"),
5056
+ ])
5057
+ .optional(),
4583
5058
  async run({ format, options, error: incurError }) {
4584
5059
  let workerDiagnostic;
4585
5060
  const structured = format === "json" || format === "jsonl";
4586
5061
  const reportDiagnostic = async (chunk) => {
4587
5062
  if (structured) {
4588
- if (!batchedVerification || frameworkFlags.tokenArguments.length)
5063
+ if (!batchedVerification || frameworkFlags.tokenView)
4589
5064
  deferredVerificationDiagnostic = chunk;
4590
5065
  }
4591
5066
  else {
@@ -4705,7 +5180,8 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4705
5180
  return undefined;
4706
5181
  }
4707
5182
  }
4708
- if (structured) {
5183
+ if (!useDefaultOutput(format)) {
5184
+ setTerminalOutputFormat(format);
4709
5185
  return {
4710
5186
  repository,
4711
5187
  ...(selected === undefined ? {} : { scanId: selected.scanId }),
@@ -4728,6 +5204,13 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4728
5204
  },
4729
5205
  })
4730
5206
  .command("patch", {
5207
+ usage: [
5208
+ { suffix: "ISSUE... [options]" },
5209
+ { suffix: "--scan ID [--severity LEVEL] [options]" },
5210
+ { suffix: "(--linear-issue ID | --linear-project PROJECT) [options]" },
5211
+ { suffix: "--resume-pr BRANCH" },
5212
+ { suffix: "--host" },
5213
+ ],
4731
5214
  description: "Patch one or more security issues.",
4732
5215
  destructive: true,
4733
5216
  args: z.object({
@@ -4735,7 +5218,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4735
5218
  .string()
4736
5219
  .min(1, "An issue must not be empty.")
4737
5220
  .optional()
4738
- .describe("Issue text, a file, or a saved finding identifier."),
5221
+ .describe("Issue text, a local file path or URL, or a saved finding identifier. Use text:VALUE to pass path-shaped prose."),
4739
5222
  }),
4740
5223
  options: z.object({
4741
5224
  host: z
@@ -4971,24 +5454,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
4971
5454
  }
4972
5455
  },
4973
5456
  })
4974
- .command("login", {
5457
+ .command(Cli.create("login", {
4975
5458
  description: "Sign in with ChatGPT or store credentials.",
4976
- hint: "For remote login, use --device-auth if your workspace allows it.\n" +
4977
- "If device auth is disabled, sign in over SSH:\n" +
4978
- " On your local machine (replace user@remote):\n" +
4979
- " ssh -L 1455:localhost:1455 user@remote\n" +
4980
- " In that SSH session:\n" +
4981
- " codex-security login\n" +
4982
- " Open the sign-in URL in your local browser.\n" +
4983
- " Keep SSH connected until login finishes.\n" +
4984
- "Docs: https://learn.chatgpt.com/docs/auth?surface=cli#cli-fallback-forward-the-localhost-callback-over-ssh",
5459
+ hint: "Check the effective sign-in with codex-security login status. For a remote machine use --device-auth if your workspace permits it. For SSH, on your local machine run:\n ssh -L 1455:localhost:1455 user@remote\nThen, in that SSH session:\n codex-security login\nOpen the sign-in URL locally and keep SSH connected until login finishes.\nhttps://learn.chatgpt.com/docs/auth?surface=cli#cli-fallback-forward-the-localhost-callback-over-ssh",
4985
5460
  destructive: true,
4986
- args: z.object({
4987
- action: z
4988
- .enum(["status"])
4989
- .optional()
4990
- .describe("Use status to inspect credentials; omit to sign in."),
4991
- }),
4992
5461
  options: z.object({
4993
5462
  deviceAuth: z
4994
5463
  .boolean()
@@ -5004,74 +5473,103 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5004
5473
  .describe("Read an access token from stdin."),
5005
5474
  }),
5006
5475
  examples: [
5007
- { args: {}, description: "Sign in with ChatGPT." },
5008
- { args: { action: "status" }, description: "Check authentication." },
5476
+ { options: {}, description: "Sign in using the browser." },
5477
+ {
5478
+ options: { deviceAuth: true },
5479
+ description: "Sign in from a headless machine with device auth.",
5480
+ },
5481
+ {
5482
+ options: { withApiKey: true },
5483
+ description: "Pipe an API key on stdin from your credential source.",
5484
+ },
5009
5485
  ],
5010
- async run({ args, options }) {
5011
- const credentialHome = await prepareCodexSecurityCredentialHome(dependencies.environment);
5486
+ async run({ options }) {
5012
5487
  const authentication = scanAuthentication(dependencies.environment);
5013
- if (args.action === "status" && authentication.method !== "api_key") {
5014
- const ambientHome = scanCodexHome(dependencies.environment);
5015
- await withCredentialHomeLock(credentialHome, () => initialCredentialsAvailable(dependencies.environment, ambientHome, credentialHome));
5488
+ exitCode = await withLoginEnvironment(async (environment) => {
5489
+ await prepareLoginConfig(environment.CODEX_HOME, await readCodexAuthConfig(scanCodexHome(dependencies.environment), true));
5490
+ const status = await dependencies.runCodex([
5491
+ "login",
5492
+ ...(options.deviceAuth ? ["--device-auth"] : []),
5493
+ ...(options.withApiKey ? ["--with-api-key"] : []),
5494
+ ...(options.withAccessToken ? ["--with-access-token"] : []),
5495
+ ], undefined, environment);
5496
+ if (status === 0)
5497
+ await setCodexSecurityCredentialLogout(environment.CODEX_HOME, false);
5498
+ return status;
5499
+ });
5500
+ if (exitCode === 0 &&
5501
+ !options.withApiKey &&
5502
+ authentication.method === "api_key") {
5503
+ const configuredApiKeyVariables = Object.keys(dependencies.environment).filter((name) => ["OPENAI_API_KEY", "CODEX_API_KEY"].includes(name.toUpperCase()) && dependencies.environment[name]?.trim());
5504
+ const loginWarning = options.withAccessToken
5505
+ ? `Access-token login succeeded, but noninteractive scans will use ${authentication.source}.\n`
5506
+ : "ChatGPT login succeeded. Interactive scans will ask which account to use; " +
5507
+ `noninteractive scans will use ${authentication.source}.\n`;
5508
+ const storedCredentials = options.withAccessToken
5509
+ ? "your stored credentials"
5510
+ : "your ChatGPT sign-in";
5511
+ errorOutput.write(loginWarning +
5512
+ `To use ${storedCredentials}, pass '--auth chatgpt' or ` +
5513
+ `${formatEnvironmentVariableRemovalGuidance(configuredApiKeyVariables)}.\n`);
5016
5514
  }
5017
- const authenticationEnvironment = {
5018
- ...dependencies.environment,
5019
- CODEX_HOME: credentialHome,
5020
- };
5021
- exitCode = await dependencies.runCodex([
5022
- "login",
5023
- ...(args.action === undefined ? [] : [args.action]),
5024
- ...(options.deviceAuth ? ["--device-auth"] : []),
5025
- ...(options.withApiKey ? ["--with-api-key"] : []),
5026
- ...(options.withAccessToken ? ["--with-access-token"] : []),
5027
- ], undefined, authenticationEnvironment);
5028
- if (args.action === undefined && exitCode === 0) {
5029
- await setCodexSecurityCredentialLogout(credentialHome, false);
5030
- }
5031
- if (args.action === "status") {
5032
- if (authentication.method === "api_key" &&
5033
- (exitCode === 0 || exitCode === 1)) {
5034
- exitCode = 0;
5035
- errorOutput.write(`Effective scan authentication: API key from ${authentication.source}.\n`);
5036
- errorOutput.write(`To use a ChatGPT sign-in, ${formatEnvironmentVariableRemovalGuidance(["OPENAI_API_KEY", "CODEX_API_KEY"])}.\n`);
5037
- }
5038
- }
5039
- else if (exitCode === 0 && !options.withApiKey) {
5040
- if (authentication.method === "api_key") {
5041
- const configuredApiKeyVariables = Object.entries(dependencies.environment).flatMap(([name, value]) => value?.trim() &&
5042
- (name.toUpperCase() === "OPENAI_API_KEY" ||
5043
- name.toUpperCase() === "CODEX_API_KEY")
5044
- ? name
5045
- : []);
5046
- const loginWarning = options.withAccessToken
5047
- ? `Access-token login succeeded, but noninteractive scans will use ${authentication.source}.\n`
5048
- : "ChatGPT login succeeded. Interactive scans will ask which account to use; " +
5049
- `noninteractive scans will use ${authentication.source}.\n`;
5050
- const storedCredentials = options.withAccessToken
5051
- ? "your stored credentials"
5052
- : "your ChatGPT sign-in";
5053
- errorOutput.write(loginWarning +
5054
- `To use ${storedCredentials}, pass '--auth chatgpt' or ` +
5055
- `${formatEnvironmentVariableRemovalGuidance(configuredApiKeyVariables)}.\n`);
5056
- }
5515
+ },
5516
+ }).command("status", {
5517
+ description: "Check effective scan authentication.",
5518
+ hint: "Use codex-security login status --json for automation. With stored credentials, the first check can import an existing Codex sign-in.",
5519
+ output: z
5520
+ .object({
5521
+ authenticated: z.boolean(),
5522
+ method: z.enum(["api_key", "stored_credentials"]),
5523
+ source: z.string().optional(),
5524
+ })
5525
+ .optional(),
5526
+ async run({ format }) {
5527
+ const structured = !useDefaultOutput(format);
5528
+ const authentication = scanAuthentication(dependencies.environment);
5529
+ if (authentication.method === "api_key") {
5530
+ errorOutput.write(`API key configured via ${authentication.source} (offline check).\n`);
5531
+ errorOutput.write("Stored sign-in status:\n");
5532
+ }
5533
+ exitCode = await withLoginEnvironment(async (environment) => {
5534
+ if (authentication.method !== "api_key")
5535
+ await initialCredentialsAvailable(dependencies.environment, scanCodexHome(dependencies.environment), environment.CODEX_HOME);
5536
+ if (!structured)
5537
+ return await dependencies.runCodex(["login", "status"], undefined, environment);
5538
+ const native = await runCodexCommand(resolveCodexCommand(environment), ["login", "status"], environment, undefined, undefined, { cwd: NEUTRAL_CODEX_CWD });
5539
+ for (const diagnostic of [native.stdout, native.stderr]) {
5540
+ if (diagnostic.trim())
5541
+ errorOutput.write(`${diagnosticLines(diagnostic.trimEnd())}\n`);
5542
+ }
5543
+ return native.exitCode ?? 2;
5544
+ });
5545
+ if (authentication.method === "api_key" &&
5546
+ (exitCode === 0 || exitCode === 1)) {
5547
+ exitCode = 0;
5548
+ errorOutput.write(`To use a ChatGPT sign-in, ${formatEnvironmentVariableRemovalGuidance(["OPENAI_API_KEY", "CODEX_API_KEY"])}.\n`);
5057
5549
  }
5550
+ if (structured)
5551
+ return {
5552
+ authenticated: exitCode === 0,
5553
+ ...(authentication.method === "api_key"
5554
+ ? {
5555
+ method: authentication.method,
5556
+ source: authentication.source,
5557
+ }
5558
+ : { method: "stored_credentials" }),
5559
+ };
5058
5560
  },
5059
- })
5561
+ }))
5060
5562
  .command("logout", {
5061
- description: "Remove the stored sign-in.",
5563
+ description: "Remove the stored Codex Security sign-in.",
5564
+ hint: "Check the effective account with codex-security login status. Scans can still use an API key configured in your environment.",
5062
5565
  destructive: true,
5063
5566
  async run() {
5064
- const credentialHome = await prepareCodexSecurityCredentialHome(dependencies.environment);
5065
- const runLogout = () => dependencies.runCodex(["logout"], undefined, {
5066
- ...dependencies.environment,
5067
- CODEX_HOME: credentialHome,
5068
- });
5069
- exitCode = await withCredentialHomeLock(credentialHome, () => logoutCredentialHome(credentialHome, scanCodexHome(dependencies.environment), runLogout));
5567
+ exitCode = await withLoginEnvironment((environment) => logoutCredentialHome(environment.CODEX_HOME, scanCodexHome(dependencies.environment), (store) => dependencies.runCodex(nativeLogoutArgs(store), undefined, environment)));
5070
5568
  },
5071
5569
  })
5072
5570
  .command("init", {
5073
5571
  description: "Create a starter project configuration.",
5074
- hint: "Existing files are never overwritten.",
5572
+ hint: "Use the generated file with scan . -c FILE --dry-run. Existing files are never overwritten.",
5075
5573
  destructive: true,
5076
5574
  args: z.object({
5077
5575
  file: z
@@ -5081,24 +5579,36 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5081
5579
  .describe("YAML or JSON destination (default: codex-security.yaml)."),
5082
5580
  }),
5083
5581
  output: z.object({ path: z.string() }).optional(),
5084
- async run({ args }) {
5582
+ async run({ args, format }) {
5583
+ let preview;
5085
5584
  try {
5086
5585
  const directory = dependencies.currentDirectory();
5087
5586
  const path = resolveCliPath(directory, args.file ?? "codex-security.yaml");
5587
+ preview = `${PREVIEW_LABEL}: ${projectPreviewCommand(directory, path)}`;
5088
5588
  await writeFile(path, projectConfigStarter(path, directory), {
5089
5589
  flag: "wx",
5090
5590
  mode: 0o600,
5091
5591
  });
5592
+ if (useDefaultOutput(format)) {
5593
+ if (output.isTTY)
5594
+ renderedOutput = `Created ${escapeTerminalText(path)}\n${preview}\n`;
5595
+ else
5596
+ errorOutput.write(`${preview}\n`);
5597
+ }
5092
5598
  return { path };
5093
5599
  }
5094
5600
  catch (error) {
5095
5601
  exitCode = 2;
5096
5602
  errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
5603
+ if (error.code === "EEXIST" && preview)
5604
+ errorOutput.write(`${preview}\n`);
5097
5605
  throw error;
5098
5606
  }
5099
5607
  },
5100
5608
  })
5101
5609
  .command("feedback", {
5610
+ usage: [{ suffix: "[scan-id] --reason TEXT [--include-logs]" }],
5611
+ examples: [{ options: { reason: "unexpected-result" } }],
5102
5612
  description: "Send feedback to OpenAI and return a feedback ID.",
5103
5613
  destructive: true,
5104
5614
  args: z.object({
@@ -5175,7 +5685,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5175
5685
  },
5176
5686
  },
5177
5687
  output: infoOutput,
5178
- async run({ options }) {
5688
+ async run({ options, format }) {
5179
5689
  const directory = dependencies.currentDirectory();
5180
5690
  const project = await selectedProjectConfig(options.config, dependencies);
5181
5691
  const resolved = resolveScanSettings(project, {}, directory);
@@ -5184,125 +5694,235 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5184
5694
  const deep = resolved.options.mode === "deep"
5185
5695
  ? await resolveDeepScanConfig(resolved.options, join(scanCodexHome(dependencies.environment), "codex-security", "config.toml"))
5186
5696
  : undefined;
5697
+ const model = scanModelConfiguration(codex);
5698
+ const sources = configurationSources(resolved.sources, deep?.sources);
5699
+ const nextStep = projectPreviewCommand(directory, project?.path);
5700
+ const bundledPluginAvailable = Boolean(await bundledPluginRoot().catch(() => undefined));
5701
+ if (output.isTTY && useDefaultOutput(format)) {
5702
+ const overrides = Object.entries(sources)
5703
+ .filter(([, source]) => source !== "default")
5704
+ .map(([key, source]) => `${key} (${source})`);
5705
+ const { mode, auth, target, maxCostUsd } = resolved.options;
5706
+ renderedOutput =
5707
+ [
5708
+ `${PREVIEW_LABEL}: ${nextStep}`,
5709
+ `Configuration: ${project?.path ?? "defaults"}`,
5710
+ `Scope: ${typeof target === "string" ? target : JSON.stringify(target)}`,
5711
+ `Scan: ${mode} · ${model.model} (${model.reasoningEffort}) · auth ${auth}`,
5712
+ ...(maxCostUsd === undefined
5713
+ ? []
5714
+ : [`Cost limit: $${maxCostUsd}`]),
5715
+ `Bundled plugin: ${BUNDLED_PLUGIN_VERSION} (${bundledPluginAvailable ? "available" : "missing"})`,
5716
+ ...(overrides.length
5717
+ ? [`Overrides: ${overrides.join(", ")}`]
5718
+ : []),
5719
+ ]
5720
+ .map((line) => escapeTerminalText(line))
5721
+ .join("\n") + "\n";
5722
+ }
5187
5723
  return {
5188
5724
  sdkVersion: VERSION,
5189
5725
  bundledPluginVersion: BUNDLED_PLUGIN_VERSION,
5726
+ bundledPluginAvailable,
5190
5727
  scanMcp: false,
5191
5728
  cancellationNote: "Scans are CLI-only because the MCP transport cannot cancel active commands.",
5192
5729
  cliVersion: VERSION,
5193
5730
  codexVersion: CODEX_EXECUTABLE_VERSION,
5194
5731
  codexSdkVersion: CODEX_SDK_VERSION,
5195
- ...scanModelConfiguration(codex),
5196
- nextStep: project
5197
- ? "Run codex-security scan . -c FILE --dry-run, replacing FILE with the project configuration you selected."
5198
- : "codex-security scan . --dry-run",
5732
+ ...model,
5733
+ nextStep,
5199
5734
  configuration: {
5200
5735
  ...(project?.path === undefined ? {} : { path: project.path }),
5201
5736
  settings: { ...resolved.options, ...deep?.settings },
5202
- sources: configurationSources(resolved.sources, deep?.sources),
5737
+ sources,
5203
5738
  },
5204
5739
  };
5205
5740
  },
5206
5741
  });
5742
+ if (completion.success) {
5743
+ await writeCliOutput(output, completeCli(cli, cliOptions, completion.data, shellArgv));
5744
+ return 0;
5745
+ }
5207
5746
  const commands = Cli.toCommands.get(cli);
5747
+ prepareCliExamples(commands);
5208
5748
  const valueOptions = cliValueOptions(commands);
5209
- const commandIndex = argv.findIndex((value, index) => {
5210
- if (value.startsWith("-"))
5211
- return false;
5212
- return index === 0 || !valueOptions.has(argv[index - 1]);
5213
- });
5749
+ const isPositional = (value, index) => (value === "-" || !value.startsWith("-")) &&
5750
+ (index === 0 || !valueOptions.has(argv[index - 1]));
5751
+ // A leading terminator still permits a positional command name.
5752
+ let commandIndex = argv.findIndex(isPositional);
5753
+ if (commandIndex < 0 &&
5754
+ !actionFlags.length &&
5755
+ literalArgs[0] &&
5756
+ !literalArgs[0].startsWith("-") &&
5757
+ firstNonGlobal(argv, 0) === argv.length) {
5758
+ commandIndex = argv.length;
5759
+ const name = literalArgs.shift();
5760
+ const group = commands.get(name);
5761
+ const verb = literalArgs[0];
5762
+ argv = [...argv, name];
5763
+ if (group && "_group" in group && verb && group.commands.has(verb))
5764
+ argv = [...argv, literalArgs.shift()];
5765
+ }
5766
+ if (argv[commandIndex] === "codex-security") {
5767
+ argv = argv.toSpliced(commandIndex, 1);
5768
+ commandIndex = argv.findIndex(isPositional);
5769
+ }
5214
5770
  const command = argv[commandIndex];
5215
- const following = argv[commandIndex + 1];
5771
+ const entry = command === undefined ? undefined : commands.get(command);
5772
+ const verbIndex = firstNonGlobal(argv, commandIndex + 1);
5773
+ let following = argv[verbIndex];
5216
5774
  const scanImport = command === "scan" && following === "import";
5775
+ const importArgs = normalizeImportArguments(argv, verbIndex, command, following);
5776
+ argv = importArgs.args;
5777
+ if (command === "scan" &&
5778
+ !scanImport &&
5779
+ (literalArgs.length ||
5780
+ argv.some((value, index) => index > commandIndex && isPositional(value, index)))) {
5781
+ // A repository such as "imports" or "./import" is a positional even when
5782
+ // shared options precede it. Bypass Incur's subcommand typo suggestions.
5783
+ if (entry && "_group" in entry && entry.root)
5784
+ commands.set(command, entry.root);
5785
+ }
5217
5786
  if ((command === "scans" || command === "findings") &&
5218
5787
  !argv.includes("--help") &&
5219
5788
  !argv.includes("-h") &&
5789
+ !argv.some((arg) => arg === "--llms" || arg === "--llms-full") &&
5220
5790
  (following === undefined || following.startsWith("-"))) {
5221
- argv = argv.toSpliced(commandIndex + 1, 0, "list");
5222
- }
5791
+ argv = argv.toSpliced(verbIndex, 0, "list");
5792
+ following = "list";
5793
+ }
5794
+ const nested = entry &&
5795
+ "_group" in entry &&
5796
+ following !== undefined &&
5797
+ entry.commands.has(following);
5798
+ const subcommand = nested ? following : undefined;
5799
+ const selected = entry && "_group" in entry
5800
+ ? subcommand
5801
+ ? entry.commands.get(subcommand)
5802
+ : entry.root
5803
+ : entry;
5804
+ const protocolFlag = ["scan", "patch", "verify-fix"].includes(command ?? "") && !scanImport
5805
+ ? "--host"
5806
+ : ["validate", "classify-severity", "dedupe"].includes(command ?? "")
5807
+ ? "--records"
5808
+ : undefined;
5809
+ let protocol = false;
5810
+ let classificationRuns;
5223
5811
  function validateCliArguments() {
5224
- if (argv.includes("--help") || argv.includes("-h"))
5225
- return undefined;
5226
- if (command === undefined || !commands.has(command))
5227
- return undefined;
5228
- const structuredOutput = argv.some((value, index) => value === "--json" ||
5229
- ((value === "--format" ||
5230
- value === "--format=json" ||
5231
- value === "--format=jsonl") &&
5232
- (value.endsWith("=json") ||
5233
- value.endsWith("=jsonl") ||
5234
- argv[index + 1] === "json" ||
5235
- argv[index + 1] === "jsonl")));
5236
- if (structuredOutput &&
5237
- ["validate", "login", "logout"].includes(command) &&
5238
- !argv.includes("--schema")) {
5239
- return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
5240
- }
5241
- if (command === "export" && structuredOutput) {
5242
- const hasValue = (flag, value) => argv.some((arg, index) => arg === `${flag}=${value}` ||
5243
- (arg === flag && argv[index + 1] === value));
5244
- if (hasValue("--output", "-")) {
5245
- if (["csv", "servicenow-avit"].some((format) => hasValue("--export-format", format) ||
5246
- hasValue("--exportFormat", format))) {
5247
- return "CSV stdout cannot be combined with JSON output; write CSV to a file or omit --json.";
5248
- }
5249
- if (hasValue("--artifact", "threat-model") ||
5250
- hasValue("--export-format", "md")) {
5251
- return "Markdown stdout cannot be combined with JSON output; write Markdown to a file or omit --json.";
5812
+ if (argv.includes("--incur-update-check"))
5813
+ return "Unknown flag: --incur-update-check";
5814
+ if (mixedAction)
5815
+ return `${actionFlags.join(" and ")} must be used alone.`;
5816
+ if (command === undefined && literalArgs.length)
5817
+ return "Select a command before --.";
5818
+ if (importArgs.error)
5819
+ return importArgs.error;
5820
+ if (frameworkFlags.argumentError)
5821
+ return frameworkFlags.argumentError;
5822
+ if (command === undefined)
5823
+ return frameworkFlags.tokenError;
5824
+ if (!entry) {
5825
+ if (["skills", "skill", "mcp", "completions"].includes(command))
5826
+ return frameworkFlags.tokenError;
5827
+ if (inspection)
5828
+ return `Unknown command ${diagnosticValue(command)}. Use codex-security --help.`;
5829
+ return frameworkFlags.tokenError;
5830
+ }
5831
+ if ("_group" in entry &&
5832
+ !entry.root &&
5833
+ following &&
5834
+ !following.startsWith("-") &&
5835
+ !subcommand)
5836
+ // Discovery otherwise widens an unknown path to its parent. Execution
5837
+ // already reports unknown verbs with Incur's spelling suggestions.
5838
+ return inspection
5839
+ ? `Unknown command ${diagnosticValue(command + " " + following)}. Use codex-security ${command} --help.`
5840
+ : undefined;
5841
+ if (protocolFlag && !inspection) {
5842
+ const negative = "--no-" + protocolFlag.slice(2);
5843
+ const flags = argv.filter((arg) => arg === protocolFlag ||
5844
+ arg.startsWith(protocolFlag + "=") ||
5845
+ arg === negative);
5846
+ const last = flags.at(-1);
5847
+ protocol = last === protocolFlag || last === protocolFlag + "=true";
5848
+ if (protocol) {
5849
+ const rest = argv.filter((arg, index) => index !== commandIndex && !flags.includes(arg));
5850
+ if (command === "classify-severity" &&
5851
+ commandIndex === 0 &&
5852
+ !literalArgs.length) {
5853
+ try {
5854
+ const { values } = parseArgs({
5855
+ args: rest,
5856
+ options: { runs: { type: "string" } },
5857
+ });
5858
+ if (values.runs !== undefined)
5859
+ classificationRuns = reviewRunsOption.parse(Number(values.runs));
5860
+ }
5861
+ catch {
5862
+ return `Use --records with only --runs (an integer from 1 to 10; default: ${DEFAULT_REVIEW_RUNS}).`;
5863
+ }
5252
5864
  }
5865
+ else if (rest.length || literalArgs.length || commandIndex !== 0)
5866
+ return `${protocolFlag} must be used alone with ${command}.`;
5253
5867
  }
5254
5868
  }
5255
- if (command === "scan" && !argv.includes("--schema")) {
5256
- if (argv.some((value) => value === "--filter-output" || value.startsWith("--filter-output="))) {
5869
+ const structuredOutput = frameworkFlags.formats.some(isJsonFormat);
5870
+ if (structuredOutput &&
5871
+ (["validate", "logout"].includes(command) ||
5872
+ (command === "login" && following !== "status")) &&
5873
+ !inspection) {
5874
+ return `${command} does not support noninteractive JSON output; run it without --json, --format json, or --format jsonl.`;
5875
+ }
5876
+ if (command === "scan" && !inspection) {
5877
+ if (frameworkFlags.filters.length) {
5257
5878
  return "--filter-output is not supported for scan results.";
5258
5879
  }
5259
- if (argv.some((value, index) => value === "--format=md" ||
5260
- (value === "--format" && argv[index + 1] === "md"))) {
5880
+ if (frameworkFlags.formats.includes("md")) {
5261
5881
  return "Markdown output is not supported for scan results.";
5262
5882
  }
5263
5883
  }
5264
- const nestedCommand = scanImport ||
5265
- command === "scans" ||
5266
- command === "findings" ||
5267
- command === "publish" ||
5268
- command === "import";
5269
- const subcommand = nestedCommand ? argv[commandIndex + 1] : undefined;
5270
- if (command === "import" &&
5271
- subcommand !== "sonar" &&
5272
- frameworkFlags.rawCollector) {
5273
- // Incur's skill-sync notice turns a saved collector array into an object.
5884
+ if (frameworkFlags.rawStructuredOutput &&
5885
+ !(command === "scans" && subcommand === "logs")) {
5886
+ // Saved logs include the framework's CTA after streamed events. Other
5887
+ // raw result objects and arrays keep notices in full-output metadata.
5274
5888
  cliOptions.sync = false;
5275
5889
  }
5276
5890
  if (command === "info") {
5277
- for (let index = 0; index < argv.length; index += 1) {
5278
- const argument = argv[index];
5279
- if (argument !== "--filter-output" &&
5280
- !argument.startsWith("--filter-output=")) {
5891
+ for (const selector of frameworkFlags.filters) {
5892
+ if (selector === undefined)
5281
5893
  continue;
5282
- }
5283
- const selector = argument.includes("=")
5284
- ? argument.slice(argument.indexOf("=") + 1)
5285
- : argv[index + 1];
5286
- if (selector !== undefined &&
5287
- !selector
5288
- .split(",")
5289
- .every((field) => Object.hasOwn(infoOutput.shape, field))) {
5894
+ const valid = selector.split(/,(?!\d+\])/u).every((field) => {
5895
+ const match = /^([\w-]+)(?:\.[\w-]+|\[\d+,\d+\])*$/u.exec(field);
5896
+ return match !== null && Object.hasOwn(infoOutput.shape, match[1]);
5897
+ });
5898
+ if (!valid)
5290
5899
  return "--filter-output must select an info metadata field.";
5291
- }
5292
5900
  }
5293
5901
  }
5294
- for (let index = commandIndex + (nestedCommand ? 2 : 1); index < argv.length; index += 1) {
5902
+ let lastPositionalIndex = -1;
5903
+ for (let index = nested ? verbIndex + 1 : commandIndex + 1; index < argv.length; index += 1) {
5295
5904
  const value = argv[index];
5296
- if (!value.startsWith("-")) {
5905
+ if (value === "-" || !value.startsWith("-")) {
5297
5906
  positionals.push(value);
5907
+ lastPositionalIndex = index;
5298
5908
  continue;
5299
5909
  }
5300
5910
  const equals = value.indexOf("=");
5301
5911
  const option = equals < 0 ? value : value.slice(0, equals);
5302
5912
  const canonicalOption = option.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
5303
- if (equals >= 0 ||
5304
- (!valueOptions.has(canonicalOption) &&
5305
- !(scanImport && option === "--json")))
5913
+ if (equals >= 0 && selected && "options" in selected) {
5914
+ const name = option
5915
+ .slice(2)
5916
+ .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
5917
+ const shape = selected.options?.shape;
5918
+ const field = shape && Object.hasOwn(shape, name) ? shape[name] : undefined;
5919
+ if (field &&
5920
+ z.toJSONSchema(field, { io: "input" }).type === "boolean" &&
5921
+ !["true", "false"].includes(value.slice(equals + 1))) {
5922
+ return `Invalid boolean value for ${option}: ${diagnosticValue(value.slice(equals + 1))}. Use ${option}, ${option}=true, or ${option}=false.`;
5923
+ }
5924
+ }
5925
+ if (equals >= 0 || !valueOptions.has(canonicalOption))
5306
5926
  continue;
5307
5927
  const next = argv[index + 1];
5308
5928
  if (next === undefined || next.startsWith("--") || next === "-h") {
@@ -5310,178 +5930,149 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5310
5930
  }
5311
5931
  index += 1;
5312
5932
  }
5313
- if (subcommand === "match" &&
5314
- !argv.some((value) => ["--schema", "--llms", "--llms-full"].includes(value))) {
5315
- if (argv.includes("--all") && positionals.length > 0) {
5316
- return "scans match --all does not accept scan identifiers.";
5317
- }
5318
- if (!argv.includes("--all") && positionals.length !== 2) {
5319
- return "scans match requires two scan identifiers or --all.";
5320
- }
5933
+ const beforeDelimiter = positionals.length;
5934
+ positionals.push(...literalArgs);
5935
+ if (command === "login" && !subcommand && positionals.length)
5936
+ return "Use login to sign in or login status to inspect authentication.";
5937
+ // Incur's global flag extractor doesn't recognize --. Supply literal
5938
+ // arguments to the positional schema as inputs so its normal validation
5939
+ // still applies and no layer can reinterpret a value as a framework flag.
5940
+ if (literalArgs.length && selected && "args" in selected && selected.args) {
5941
+ const shape = {};
5942
+ for (const [index, key] of Object.keys(selected.args.shape).entries()) {
5943
+ const literal = literalArgs[index - beforeDelimiter];
5944
+ if (literal !== undefined)
5945
+ shape[key] = selected.args.shape[key].prefault(literal);
5946
+ }
5947
+ selected.args = selected.args.extend(shape);
5321
5948
  }
5322
5949
  if (command !== "validate" &&
5323
5950
  command !== "verify-fix" &&
5324
5951
  command !== "patch" &&
5325
5952
  positionals.length >
5326
- (scanImport || command === "logout" || command === "info"
5327
- ? 0
5328
- : subcommand === "compare" || subcommand === "match"
5329
- ? 2
5330
- : 1)) {
5331
- return `Unexpected positional argument for ${command}${subcommand === undefined ? "" : ` ${subcommand}`}.`;
5332
- }
5333
- }
5334
- const firstImportOption = scanImport ? commandIndex + 2 : argv.length;
5335
- const frameworkArgv = [];
5336
- for (let index = 0; index < argv.length; index++) {
5337
- const argument = argv[index];
5338
- const next = argv[index + 1];
5339
- const separator = argument.indexOf("=");
5340
- if (index >= firstImportOption &&
5341
- argument === "--json" &&
5342
- next !== undefined &&
5343
- !next.startsWith("--") &&
5344
- next !== "-h") {
5345
- // Incur reserves bare --json for output, but parses --json=FILE normally.
5346
- frameworkArgv.push(`--json=${next}`);
5347
- index++;
5348
- }
5349
- else if (separator >= 0 &&
5350
- FRAMEWORK_VALUE_OPTIONS.has(argument.slice(0, separator))) {
5351
- frameworkArgv.push(argument.slice(0, separator), argument.slice(separator + 1));
5953
+ (selected && "args" in selected && selected.args
5954
+ ? Object.keys(selected.args.shape).length
5955
+ : 0)) {
5956
+ const previous = argv[lastPositionalIndex - 1]?.split("=", 1)[0];
5957
+ const hint = previous?.startsWith("-")
5958
+ ? ` Check the flag ${diagnosticValue(previous)} and whether it takes a value.`
5959
+ : "";
5960
+ return `Unexpected positional argument for ${command}${subcommand === undefined ? "" : ` ${subcommand}`}.${hint}`;
5961
+ }
5962
+ return frameworkFlags.tokenError;
5963
+ }
5964
+ const frameworkFlags = parseFrameworkArguments(argv);
5965
+ const frameworkArgv = frameworkFlags.args;
5966
+ const { jsonFormat } = frameworkFlags;
5967
+ const policyFullOutput = command === "policy" &&
5968
+ frameworkFlags.fullOutput &&
5969
+ !mixedAction &&
5970
+ !argv.includes("--incur-update-check");
5971
+ const envelopeFormat = frameworkFlags.fullOutput ? jsonFormat : undefined;
5972
+ const commandPath = subcommand
5973
+ ? `${command} ${subcommand}`
5974
+ : (command ?? "codex-security");
5975
+ const argumentFailure = (message, code = commandPath === "scan"
5976
+ ? "SCAN_FAILED"
5977
+ : command === "policy"
5978
+ ? "POLICY_FAILED"
5979
+ : "INVALID_ARGUMENTS") => Formatter.format({ ok: false, error: { code, message }, meta: { command: commandPath } }, envelopeFormat) + "\n";
5980
+ const reportError = async (message, code) => {
5981
+ errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
5982
+ if (envelopeFormat)
5983
+ await writeCliOutput(output, argumentFailure(message, code));
5984
+ return 2;
5985
+ };
5986
+ const argumentError = validateCliArguments();
5987
+ if (argumentError !== undefined && (!policyFullOutput || envelopeFormat))
5988
+ return reportError(argumentError);
5989
+ if (protocol) {
5990
+ const recordsCommand = command === "dedupe" ||
5991
+ command === "validate" ||
5992
+ command === "classify-severity"
5993
+ ? command
5994
+ : undefined;
5995
+ const remediationOperation = command === "patch"
5996
+ ? "patch"
5997
+ : command === "verify-fix"
5998
+ ? "verify"
5999
+ : undefined;
6000
+ const controller = new AbortController();
6001
+ const removeSignals = listenForAbort(dependencies, controller);
6002
+ let exitCode;
6003
+ try {
6004
+ const input = dependencies.recordsInput ?? process.stdin;
6005
+ const code = recordsCommand !== undefined
6006
+ ? await runHostRecordsProtocol(recordsCommand, input, output, {
6007
+ signal: controller.signal,
6008
+ classificationRuns,
6009
+ })
6010
+ : remediationOperation !== undefined
6011
+ ? await runHostedRemediationProtocol(input, output, controller.signal, remediationOperation)
6012
+ : await runHostedScanProtocol(input, output, controller.signal);
6013
+ exitCode =
6014
+ controller.signal.reason === "SIGINT"
6015
+ ? 130
6016
+ : controller.signal.reason === "SIGTERM"
6017
+ ? 143
6018
+ : code;
5352
6019
  }
5353
- else {
5354
- frameworkArgv.push(argument);
6020
+ finally {
6021
+ removeSignals();
5355
6022
  }
5356
- }
5357
- const frameworkFlags = frameworkOutputFlags(frameworkArgv);
5358
- const policyFullOutput = command === "policy" && argv.includes("--full-output");
5359
- const argumentError = validateCliArguments();
5360
- if (argumentError !== undefined && !policyFullOutput) {
5361
- errorOutput.write(`codex-security: ${argumentError}\n`);
5362
- return 2;
6023
+ // Protocol writes have flushed or been canceled. Node's stdout ignores destroy().
6024
+ if (output === process.stdout)
6025
+ process.exit(exitCode);
6026
+ return exitCode;
5363
6027
  }
5364
6028
  const updateController = new AbortController();
5365
6029
  const pendingUpdate = errorOutput.isTTY === true &&
5366
6030
  argv.length > 0 &&
5367
- argv[0] !== "completions" &&
5368
- !argv.some((argument) => [
5369
- "--help",
5370
- "-h",
5371
- "--version",
5372
- "--llms",
5373
- "--llms-full",
5374
- "--schema",
5375
- "--dry-run",
5376
- ].includes(argument)) &&
6031
+ command !== "completions" &&
6032
+ command !== "update" &&
6033
+ !process.env["COMPLETE"] &&
6034
+ !argv.some((argument) => [...INSPECTION_FLAGS, "--dry-run", "--mcp"].includes(argument)) &&
5377
6035
  updateNoticeEnabled(dependencies.environment)
5378
6036
  ? dependencies
5379
6037
  .checkForUpdate(updateController.signal)
5380
6038
  .catch(() => undefined)
5381
6039
  : undefined;
5382
- // Incur cannot mount a command with both a handler and subcommands.
5383
- // Select the nested import route while preserving scan [repository].
5384
- if (scanImport) {
5385
- cli.command(Cli.create("scan", {
5386
- description: "Run or import a saved scan.",
5387
- }).command("import", {
5388
- description: "Save CSV or JSON findings as a completed scan without security analysis.",
5389
- destructive: true,
5390
- options: z
5391
- .object({
5392
- csv: optionValue("--csv")
5393
- .optional()
5394
- .describe("Findings CSV in the codex-security export format."),
5395
- json: optionValue("--json")
5396
- .optional()
5397
- .describe("Findings JSON document or object with a findings array."),
5398
- outputDir: optionValue("--output-dir")
5399
- .optional()
5400
- .describe("Artifact directory (default: Codex Security state; CODEX_SECURITY_STATE_DIR)."),
5401
- archiveExisting: z
5402
- .boolean()
5403
- .default(false)
5404
- .describe("Archive existing results; requires --output-dir."),
5405
- dryRun: z
5406
- .boolean()
5407
- .default(false)
5408
- .describe("Validate the input without saving a scan."),
5409
- })
5410
- .refine((options) => Number(options.csv !== undefined) +
5411
- Number(options.json !== undefined) ===
5412
- 1, { message: "Provide exactly one of --csv FILE or --json FILE." })
5413
- .refine((options) => !options.archiveExisting || options.outputDir !== undefined, { message: "--archive-existing requires --output-dir." }),
5414
- examples: [
5415
- { options: { csv: "findings.csv" } },
5416
- { options: { json: "findings.json" } },
5417
- ],
5418
- hint: "Each input row is retained, including duplicates. --json selects the input file; use --format json for JSON output.",
5419
- output: z.record(z.string(), z.unknown()).optional(),
5420
- async run({ options, format, error: incurError }) {
5421
- const directory = dependencies.currentDirectory();
5422
- const outcome = await runImport({
5423
- sourcePath: resolveCliPath(directory, options.csv ?? options.json),
5424
- format: options.csv === undefined ? "json" : "csv",
5425
- outputDir: options.outputDir === undefined
5426
- ? undefined
5427
- : resolveCliPath(directory, options.outputDir),
5428
- archiveExisting: options.archiveExisting,
5429
- dryRun: options.dryRun,
5430
- });
5431
- exitCode = outcome.exitCode;
5432
- if (outcome.error !== undefined) {
5433
- return incurError({
5434
- code: "SCAN_IMPORT_FAILED",
5435
- message: outcome.error,
5436
- exitCode,
5437
- });
5438
- }
5439
- if (!options.dryRun && useDefaultOutput(format)) {
5440
- return;
5441
- }
5442
- return outcome.data;
5443
- },
5444
- }));
5445
- }
5446
6040
  let notice;
6041
+ if (argv.includes("--schema") || argv.includes("--llms-full")) {
6042
+ describeCommandInputs(commands);
6043
+ }
5447
6044
  try {
5448
- await cli.serve(frameworkArgv, {
6045
+ const serveOptions = {
5449
6046
  stdout: frameworkCapture.stream.write,
5450
6047
  exit: (code) => {
5451
6048
  frameworkExit = code;
5452
6049
  },
5453
- });
6050
+ };
6051
+ if (!(await serveIntegration(frameworkArgv, cli, cliOptions, serveOptions, command, literalArgs))) {
6052
+ await cli.serve(frameworkArgv, serveOptions);
6053
+ }
5454
6054
  if (pendingUpdate !== undefined) {
5455
6055
  notice = await Promise.race([pendingUpdate, undefined]);
5456
6056
  }
5457
6057
  }
6058
+ catch (error) {
6059
+ return reportError(errorMessage(error), "COMMAND_FAILED");
6060
+ }
5458
6061
  finally {
5459
6062
  updateController.abort();
5460
6063
  }
6064
+ if ((command === "login" || command === "logout") &&
6065
+ (exitCode === 130 || exitCode === 143))
6066
+ onInterruptedSignIn?.();
5461
6067
  let frameworkOutput = frameworkCapture.text();
5462
- if (filteredScanFailure !== undefined) {
5463
- // Success-field filters do not apply to diagnostics. Reuse Incur's format
5464
- // and token controls without running the saved scan a second time.
5465
- const failureOutput = captureOutput();
5466
- const failureArguments = [
5467
- "render",
5468
- "--format",
5469
- filteredScanFailure.format,
5470
- ...frameworkFlags.tokenArguments,
5471
- ];
5472
- if (failedResultOutput)
5473
- failureArguments.push("--full-output");
5474
- const failure = filteredScanFailure.data;
5475
- await Cli.create("codex-security-scan-error")
5476
- .command("render", { run: () => failure })
5477
- .serve(failureArguments, {
5478
- stdout: failureOutput.stream.write,
5479
- exit: () => undefined,
5480
- });
5481
- if (failedResultOutput)
5482
- frameworkOutput = failureOutput.text();
5483
- else
5484
- renderedOutput = failureOutput.text();
6068
+ if (command !== undefined &&
6069
+ (argv.includes("--help") || argv.includes("-h")) &&
6070
+ frameworkOutput.includes("\nUsage: codex-security <command>\n")) {
6071
+ // Incur returns the root menu for unresolved application help paths.
6072
+ const parent = commands.get(command);
6073
+ const group = parent && "_group" in parent ? command : undefined;
6074
+ const path = group && following ? `${group} ${following}` : command;
6075
+ return reportError(`Unknown command ${diagnosticValue(path)}. Use codex-security${group ? ` ${group}` : ""} --help.`, "COMMAND_NOT_FOUND");
5485
6076
  }
5486
6077
  if (escapeFrameworkOutput)
5487
6078
  frameworkOutput = escapeTerminalText(frameworkOutput, true);
@@ -5496,22 +6087,68 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5496
6087
  if (deferredVerificationDiagnostic === undefined)
5497
6088
  writeUpdateNotice();
5498
6089
  if (frameworkExit !== undefined) {
5499
- if (policyFullOutput || structuredError) {
6090
+ // A canceled command can deliberately finish without a result.
6091
+ if (!structuredError &&
6092
+ !policyFullOutput &&
6093
+ (exitCode === 130 || exitCode === 143))
6094
+ return exitCode;
6095
+ if (!envelopeFormat && (policyFullOutput || structuredError)) {
5500
6096
  if (exitCode === 0)
5501
6097
  exitCode = 2;
5502
6098
  }
5503
6099
  else {
5504
- if (exitCode !== 0)
6100
+ if (exitCode !== 0 && !envelopeFormat)
5505
6101
  return exitCode;
5506
- errorOutput.write(`codex-security: ${diagnosticLines(await incurErrorMessage(frameworkOutput))}\n`);
5507
- return 2;
6102
+ const envelope = jsonFormat
6103
+ ? parseJson(() => frameworkOutput)
6104
+ : undefined;
6105
+ const record = asRecord(envelope);
6106
+ const error = record?.["ok"] === false ? asRecord(record["error"]) : record;
6107
+ const validationError = error?.["code"] === "VALIDATION_ERROR";
6108
+ const structuredFailure = Boolean(envelopeFormat || validationError);
6109
+ let message = structuredFailure && typeof error?.["message"] === "string"
6110
+ ? error["message"]
6111
+ : await incurErrorMessage(frameworkOutput);
6112
+ if (validationError && Array.isArray(error["fieldErrors"])) {
6113
+ const entry = command ? commands.get(command) : undefined;
6114
+ const leaf = entry && "_group" in entry
6115
+ ? (entry.commands.get(following ?? "") ?? entry.root)
6116
+ : entry;
6117
+ const options = leaf && "options" in leaf ? leaf.options?.shape : undefined;
6118
+ const messages = error["fieldErrors"].map((field) => {
6119
+ if (!isJsonObject(field) || typeof field["path"] !== "string")
6120
+ return message;
6121
+ const detail = typeof field["message"] === "string" ? field["message"] : message;
6122
+ if (options && Object.hasOwn(options, field["path"])) {
6123
+ const flag = field["path"].replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
6124
+ return field["missing"]
6125
+ ? `Missing required option --${flag}.`
6126
+ : `Invalid value for --${flag}: ${detail}`;
6127
+ }
6128
+ return detail;
6129
+ });
6130
+ message = messages.join("\n");
6131
+ error["message"] = message;
6132
+ frameworkOutput = Formatter.format(envelope, jsonFormat) + "\n";
6133
+ }
6134
+ // Handlers that set an exit code have already reported the execution error.
6135
+ if (exitCode === 0)
6136
+ errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
6137
+ if (!structuredFailure)
6138
+ return 2;
6139
+ if (exitCode === 0)
6140
+ exitCode = 2;
6141
+ // Incur parses its built-in flags before selecting a format.
6142
+ if (envelopeFormat && record?.["ok"] !== false)
6143
+ frameworkOutput = argumentFailure(message);
5508
6144
  }
5509
6145
  }
5510
6146
  if (rawExportOutput)
5511
6147
  return exitCode;
5512
6148
  if (frameworkOutput.length === 0 &&
6149
+ !(jsonFormat && frameworkFlags.tokenView?.count && exitCode === 0) &&
5513
6150
  streamedLogs === undefined &&
5514
- filteredScanFailure === undefined &&
6151
+ unfilteredFailure === undefined &&
5515
6152
  deferredVerificationDiagnostic === undefined)
5516
6153
  return exitCode;
5517
6154
  try {
@@ -5537,19 +6174,10 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5537
6174
  }
5538
6175
  else if (failedResultOutput !== undefined) {
5539
6176
  const envelope = JSON.parse(frameworkOutput);
5540
- // Token-count output is a number, not a full-output envelope.
5541
6177
  if (isJsonObject(envelope) && envelope["ok"] === true) {
5542
- // Re-rendered failures carry the unfiltered page, but the command's
5543
- // original metadata describes the actual invocation.
5544
- const meta = filteredScanFailure && isJsonObject(envelope["meta"])
5545
- ? {
5546
- ...JSON.parse(frameworkCapture.text()).meta,
5547
- nextOffset: envelope["meta"]["nextOffset"],
5548
- }
5549
- : envelope["meta"];
5550
6178
  frameworkOutput = `${JSON.stringify({
5551
6179
  ...envelope,
5552
- meta,
6180
+ ...(unfilteredFailure && { data: unfilteredFailure }),
5553
6181
  ok: false,
5554
6182
  error: {
5555
6183
  code: failedResultOutput.code ?? "SCAN_FAILED",
@@ -5558,9 +6186,23 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5558
6186
  }, null, failedResultOutput.format === "json" ? 2 : undefined)}\n`;
5559
6187
  }
5560
6188
  }
5561
- await writeCliOutput(output, logOutput ??
5562
- renderedOutput ??
5563
- formatCliHelp(frameworkOutput, output.columns));
6189
+ const help = formatCliHelp(frameworkOutput, output.columns);
6190
+ let response = renderedOutput ?? help ?? frameworkOutput;
6191
+ // Incur writes menus and completion scripts directly as plain text.
6192
+ if (jsonFormat &&
6193
+ !inspection &&
6194
+ exitCode === 0 &&
6195
+ (help !== undefined || command === "completions")) {
6196
+ response =
6197
+ Formatter.format(frameworkFlags.fullOutput
6198
+ ? { ok: true, data: response, meta: { command: commandPath } }
6199
+ : response, jsonFormat) + "\n";
6200
+ }
6201
+ if (jsonFormat && unfilteredFailure && !failedResultOutput)
6202
+ response = Formatter.format(unfilteredFailure, jsonFormat) + "\n";
6203
+ if (jsonFormat && frameworkFlags.tokenView && !inspection)
6204
+ response = formatJsonTokenView(response, jsonFormat, frameworkFlags.fullOutput, frameworkFlags.tokenView);
6205
+ await writeCliOutput(output, logOutput ?? response);
5564
6206
  return exitCode;
5565
6207
  }
5566
6208
  catch (error) {
@@ -5571,7 +6213,7 @@ export async function main(argv = process.argv.slice(2), output = process.stdout
5571
6213
  if (deferredVerificationDiagnostic !== undefined) {
5572
6214
  // Token output can omit the diagnostic. Otherwise a buffered stderr
5573
6215
  // write is optional once the complete structured failure is on stdout.
5574
- if (frameworkFlags.tokenArguments.length) {
6216
+ if (frameworkFlags.tokenView) {
5575
6217
  await writeCliOutput(errorOutput, deferredVerificationDiagnostic).catch(() => { });
5576
6218
  }
5577
6219
  else {
@@ -5727,7 +6369,7 @@ async function prepareScanArgumentsFromRecipe({ recipe, userContext }, operation
5727
6369
  : kind === "working_tree"
5728
6370
  ? DiffTarget.workingTree({ base: reference ?? "HEAD" })
5729
6371
  : "repository",
5730
- knowledgeBasePaths: knowledgeBasePaths.map((path) => resolveCliPath(directory, path)),
6372
+ knowledgeBasePaths: knowledgeBasePaths.map((path) => resolveInputPath(path, directory)),
5731
6373
  ...prompts,
5732
6374
  safetyIdentifier,
5733
6375
  postScanPrompt,
@@ -5751,45 +6393,230 @@ async function prepareScanArgumentsFromRecipe({ recipe, userContext }, operation
5751
6393
  : undefined,
5752
6394
  };
5753
6395
  }
5754
- function frameworkOutputFlags(argv) {
5755
- let fullOutput = false;
5756
- let rawCollector = false;
5757
- const tokenArguments = [];
5758
- let filterOutput = false;
5759
- for (let index = 0; index < argv.length; index++) {
6396
+ /** Incur describes parsed Zod outputs by default. Callers supply the inputs,
6397
+ * which may omit fields populated by CLI defaults. Keep the runtime defaults. */
6398
+ function describeCommandInputs(commands) {
6399
+ for (const entry of commands.values()) {
6400
+ if ("_group" in entry)
6401
+ describeCommandInputs(entry.commands);
6402
+ const command = "_group" in entry ? entry.root : entry;
6403
+ if (command && "options" in command && command.options) {
6404
+ const input = z.toJSONSchema(command.options, { io: "input" });
6405
+ command.options = command.options.meta({
6406
+ required: input.required ?? [],
6407
+ });
6408
+ }
6409
+ }
6410
+ }
6411
+ function isJsonFormat(format) {
6412
+ return format === "json" || format === "jsonl";
6413
+ }
6414
+ /** Skip recognized global options and their operands while locating a command. */
6415
+ function firstNonGlobal(argv, start) {
6416
+ let index = start;
6417
+ while (index < argv.length) {
5760
6418
  const value = argv[index];
5761
- if (value === "--full-output")
5762
- fullOutput = true;
5763
- if (value === "--json")
5764
- rawCollector = true;
5765
- if (value === "--token-count")
5766
- tokenArguments.push(value);
5767
- if (FRAMEWORK_VALUE_OPTIONS.has(value)) {
5768
- const operand = argv[++index];
5769
- if (value === "--filter-output")
5770
- filterOutput = true;
5771
- if ((value === "--token-limit" || value === "--token-offset") &&
5772
- operand !== undefined)
5773
- tokenArguments.push(value, operand);
5774
- if (value === "--format")
5775
- rawCollector =
5776
- operand === "json" || operand === "jsonl" || operand === "yaml";
6419
+ const [flag] = value.split("=", 1);
6420
+ if (FRAMEWORK_VALUE_OPTIONS.has(flag)) {
6421
+ if (!value.includes("=") &&
6422
+ (argv[index + 1] === undefined || argv[index + 1].startsWith("-")))
6423
+ break;
6424
+ index += value.includes("=") ? 1 : 2;
6425
+ }
6426
+ else if (INSPECTION_FLAGS.includes(value) ||
6427
+ ["--json", "--full-output", "--token-count"].includes(value)) {
6428
+ index++;
6429
+ }
6430
+ else
6431
+ break;
6432
+ }
6433
+ return index;
6434
+ }
6435
+ /** Translate historical input flags only within their original command. */
6436
+ function normalizeImportArguments(argv, verbIndex, command, subcommand) {
6437
+ const scanImport = command === "scan" && subcommand === "import";
6438
+ const providerAliases = command === "import" && subcommand === "semgrep"
6439
+ ? { "--semgrep-deployment": "--deployment", "--semgrep-ref": "--ref" }
6440
+ : command === "import" && subcommand === "snyk"
6441
+ ? { "--snyk-org": "--org" }
6442
+ : {};
6443
+ if (!scanImport && Object.keys(providerAliases).length === 0)
6444
+ return { args: argv };
6445
+ const args = argv.slice(0, verbIndex + 1);
6446
+ const seen = new Map();
6447
+ for (let index = args.length; index < argv.length; index++) {
6448
+ const token = argv[index];
6449
+ const equals = token.indexOf("=");
6450
+ const name = equals < 0 ? token : token.slice(0, equals);
6451
+ const flag = name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
6452
+ let value = equals < 0 ? argv[index + 1] : token.slice(equals + 1);
6453
+ let canonical = providerAliases[flag] ?? flag;
6454
+ if (scanImport && (flag === "--csv" || flag === "--json")) {
6455
+ if (equals < 0 &&
6456
+ (value === undefined || value.startsWith("--") || value === "-h")) {
6457
+ if (flag === "--csv")
6458
+ return { args: argv, error: "Missing value for flag: --csv" };
6459
+ args.push(token);
6460
+ continue;
6461
+ }
6462
+ if (!value)
6463
+ return { args: argv, error: `${flag} must not be empty.` };
6464
+ args.push(value.startsWith("-") ? "./" + value : value);
6465
+ if (equals < 0)
6466
+ index++;
6467
+ canonical = "--input-format";
6468
+ value = flag.slice(2);
6469
+ args.push(canonical + "=" + value);
6470
+ }
6471
+ else if (Object.hasOwn(providerAliases, flag)) {
6472
+ args.push(canonical + (equals < 0 ? "" : token.slice(equals)));
6473
+ }
6474
+ else {
6475
+ args.push(token);
6476
+ }
6477
+ if (value !== undefined &&
6478
+ (canonical === "--input-format" ||
6479
+ Object.values(providerAliases).includes(canonical))) {
6480
+ if (seen.has(canonical) && seen.get(canonical) !== value)
6481
+ return { args: argv, error: `Conflicting values for ${canonical}.` };
6482
+ seen.set(canonical, value);
5777
6483
  }
5778
6484
  }
6485
+ return { args };
6486
+ }
6487
+ function parseFrameworkArguments(argv) {
6488
+ const args = [];
6489
+ const formats = [];
6490
+ const filters = [];
6491
+ const tokenArguments = [];
6492
+ let tokenView;
6493
+ let tokenError;
6494
+ let fullOutput = false;
6495
+ let argumentError;
6496
+ for (let index = 0; index < argv.length; index++) {
6497
+ const argument = argv[index];
6498
+ const next = argv[index + 1];
6499
+ const equals = argument.indexOf("=");
6500
+ const flag = equals < 0 ? argument : argument.slice(0, equals);
6501
+ if (!FRAMEWORK_VALUE_OPTIONS.has(flag)) {
6502
+ if (argument === "--token-count") {
6503
+ (tokenView ??= {}).count = true;
6504
+ tokenArguments.push(argument);
6505
+ continue;
6506
+ }
6507
+ args.push(argument);
6508
+ if (argument === "--json")
6509
+ formats.push("json");
6510
+ if (argument === "--full-output")
6511
+ fullOutput = true;
6512
+ continue;
6513
+ }
6514
+ // Leave a following flag available when the option is missing its operand.
6515
+ const operand = equals >= 0
6516
+ ? argument.slice(equals + 1)
6517
+ : /^-(?:-|[a-z])/iu.test(next ?? "")
6518
+ ? undefined
6519
+ : next;
6520
+ if (equals < 0 && operand !== undefined)
6521
+ index++;
6522
+ if (operand === undefined ||
6523
+ (!operand && (flag === "--filter-output" || flag === "--format"))) {
6524
+ argumentError ??= `Missing value for flag: ${flag}`;
6525
+ }
6526
+ if (flag === "--filter-output") {
6527
+ filters.push(operand);
6528
+ // Incur cannot advance past an unterminated array slice.
6529
+ if (operand !== undefined &&
6530
+ !/^(?:[^\[\]]|\[[^\[\]]*\])*$/u.test(operand)) {
6531
+ argumentError ??=
6532
+ "--filter-output requires matching brackets for array slices.";
6533
+ continue;
6534
+ }
6535
+ }
6536
+ if (flag === "--token-limit" || flag === "--token-offset") {
6537
+ if (operand === undefined ||
6538
+ !/^\d+$/u.test(operand) ||
6539
+ !Number.isSafeInteger(Number(operand))) {
6540
+ tokenError ??= `${flag} requires a nonnegative integer.`;
6541
+ }
6542
+ else {
6543
+ (tokenView ??= {})[flag === "--token-limit" ? "limit" : "offset"] =
6544
+ Number(operand);
6545
+ tokenArguments.push(flag, operand);
6546
+ }
6547
+ continue;
6548
+ }
6549
+ args.push(flag);
6550
+ if (operand !== undefined)
6551
+ args.push(operand);
6552
+ if (flag === "--format" && operand)
6553
+ formats.push(operand);
6554
+ }
6555
+ // Invalid format operands still go to Incur. Preserve a valid request for
6556
+ // JSON diagnostics if parsing a later operand fails.
6557
+ const format = formats.findLast((value) => ["json", "jsonl", "toon", "yaml", "md"].includes(value));
6558
+ const jsonFormat = isJsonFormat(format) ? format : undefined;
6559
+ if (!jsonFormat)
6560
+ args.push(...tokenArguments);
5779
6561
  return {
5780
- rawCollector: rawCollector && !fullOutput,
5781
- filterOutput,
6562
+ args,
6563
+ formats,
6564
+ jsonFormat,
6565
+ fullOutput,
6566
+ argumentError,
6567
+ filters,
5782
6568
  tokenArguments,
6569
+ tokenView,
6570
+ tokenError,
6571
+ rawStructuredOutput: !fullOutput && (jsonFormat !== undefined || format === "yaml"),
5783
6572
  };
5784
6573
  }
5785
- function cliValueOptions(commands) {
5786
- const options = new Set(FRAMEWORK_VALUE_OPTIONS);
5787
- for (const command of commands.values()) {
5788
- if ("_group" in command) {
5789
- for (const option of cliValueOptions(command.commands))
5790
- options.add(option);
5791
- }
5792
- else if ("options" in command && command.options) {
6574
+ function cliOptionFlag(key) {
6575
+ return `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
6576
+ }
6577
+ function cliOptionTokens(options) {
6578
+ const tokens = [];
6579
+ for (const [key, value] of Object.entries(options)) {
6580
+ if (value === undefined)
6581
+ continue;
6582
+ const flag = cliOptionFlag(key);
6583
+ for (const item of Array.isArray(value) ? value : [value]) {
6584
+ if (typeof item === "boolean") {
6585
+ tokens.push(item ? flag : `${flag}=false`);
6586
+ }
6587
+ else if (String(item).startsWith("-")) {
6588
+ tokens.push(quoteCliPath(`${flag}=${item}`));
6589
+ }
6590
+ else {
6591
+ tokens.push(flag, quoteCliPath(String(item)));
6592
+ }
6593
+ }
6594
+ }
6595
+ return tokens;
6596
+ }
6597
+ /** Incur prints example keys verbatim and treats every option as a single value.
6598
+ * Give its shared help, manifest and skill renderers the actual shell tokens.
6599
+ */
6600
+ function prepareCliExamples(commands) {
6601
+ for (const entry of commands.values()) {
6602
+ if ("_group" in entry)
6603
+ prepareCliExamples(entry.commands);
6604
+ const command = "_group" in entry ? entry.root : entry;
6605
+ if (!command || !("examples" in command))
6606
+ continue;
6607
+ for (const example of command.examples ?? []) {
6608
+ const tokens = Object.values(example.args ?? {}).map((value) => quoteCliPath(String(value)));
6609
+ example.args = [...tokens, ...cliOptionTokens(example.options ?? {})];
6610
+ delete example.options;
6611
+ }
6612
+ }
6613
+ }
6614
+ function cliValueOptions(commands, options = new Set(FRAMEWORK_VALUE_OPTIONS)) {
6615
+ for (const entry of commands.values()) {
6616
+ if ("_group" in entry)
6617
+ cliValueOptions(entry.commands, options);
6618
+ const command = "_group" in entry ? entry.root : entry;
6619
+ if (command && "options" in command && command.options) {
5793
6620
  for (const [name, schema] of Object.entries(z.toJSONSchema(command.options, { io: "input" }).properties ?? {})) {
5794
6621
  if (typeof schema === "object" && schema.type === "boolean")
5795
6622
  continue;
@@ -6377,7 +7204,7 @@ async function assessPatchRisk(request, stderr, dependencies) {
6377
7204
  const pathspec = request.files === undefined
6378
7205
  ? []
6379
7206
  : ["--", ...request.files.map((file) => file)];
6380
- const root = await mkdtemp(join(tmpdir(), "codex-security-patch-risk-"));
7207
+ const root = await mkdtemp(join(await realpath(tmpdir()), "codex-security-patch-risk-"));
6381
7208
  const patchPath = join(root, "patch.diff");
6382
7209
  try {
6383
7210
  const head = request.head ??
@@ -6434,7 +7261,7 @@ async function assessPatchRisk(request, stderr, dependencies) {
6434
7261
  }
6435
7262
  }
6436
7263
  async function withPatchIndex(repository, dependencies, operation) {
6437
- const root = await mkdtemp(join(tmpdir(), "codex-security-patch-tree-"));
7264
+ const root = await mkdtemp(join(await realpath(tmpdir()), "codex-security-patch-tree-"));
6438
7265
  try {
6439
7266
  return await operation((args, input) => dependencies.runRepositoryCommand("git", args, repository, {
6440
7267
  environment: {
@@ -6671,7 +7498,20 @@ async function runSkill(skill, inputs, configuration, stdout, stderr, dependenci
6671
7498
  if (input.trim().length === 0) {
6672
7499
  throw new CodexSecurityError("Finding or issue inputs must not be empty.");
6673
7500
  }
7501
+ if (input.startsWith("text:")) {
7502
+ const literal = input.slice("text:".length);
7503
+ if (!literal.trim())
7504
+ throw new CodexSecurityError("Finding or issue inputs must not be empty.");
7505
+ contents.push(literal);
7506
+ continue;
7507
+ }
6674
7508
  let contentsOrLiteral = input;
7509
+ const explicitFile = /^file:\/\//iu.test(input)
7510
+ ? new URL(input)
7511
+ : undefined;
7512
+ if (explicitFile?.hostname) {
7513
+ throw new CodexSecurityError("Finding file URLs must refer to local files.");
7514
+ }
6675
7515
  const windowsNamespace = process.platform === "win32" || input.startsWith("\\");
6676
7516
  const rawDeviceRoot = WINDOWS_LOCAL_DEVICE_ROOT.exec(input)?.[0];
6677
7517
  const localDeviceRoot = rawDeviceRoot?.replaceAll("/", "\\").toLowerCase();
@@ -6686,8 +7526,14 @@ async function runSkill(skill, inputs, configuration, stdout, stderr, dependenci
6686
7526
  !staysWithinWindowsDeviceRoot(input, rawDeviceRoot) ||
6687
7527
  localDeviceRoot !== normalizedDeviceRoot);
6688
7528
  if (!windowsNetworkPath) {
6689
- const path = resolveCliPath(directory, input);
7529
+ const path = resolveCliPath(directory, explicitFile ? fileURLToPath(explicitFile) : input);
6690
7530
  const metadata = await lstat(path, { bigint: true }).catch((error) => {
7531
+ if (explicitFile ||
7532
+ isAbsolute(expandHome(input)) ||
7533
+ input.startsWith("./") ||
7534
+ input.startsWith("../") ||
7535
+ (process.platform === "win32" && /^\.{1,2}\\/u.test(input)))
7536
+ throw error;
6691
7537
  if (typeof error === "object" &&
6692
7538
  error !== null &&
6693
7539
  "code" in error &&
@@ -7209,12 +8055,10 @@ export async function readSkillCommandOutput(stream, appServer) {
7209
8055
  };
7210
8056
  }
7211
8057
  export function skillCommandFailure(command, status, detail, authentication = null) {
7212
- // Paths may contain provider error codes as filenames. Keep the original for display.
8058
+ // Exclude paths and parser locations from advice, but keep the original diagnostic for display.
7213
8059
  const containsParserError = /\b(?:syntax\s*error|pars(?:e|er|ing)|unexpected token|at (?:line|column) \d+)\b/iu.test(detail);
7214
8060
  // Keep a neutral token so a quoted provider/model remains a named model in the message.
7215
- const withoutPaths = detail
7216
- .replace(/\bhttps?:\/\/[^\s"'`<>]+/giu, "")
7217
- .replace(/[^\s"'`()<>,]+/gu, (token) => /[/\\]/u.test(token) && !/^HTTP\/\d+(?:\.\d+)?$/iu.test(token)
8061
+ const withoutPaths = connectionAdviceDetail(detail).replace(/[^\s"'`()<>,]+/gu, (token) => /[/\\]/u.test(token) && !/^HTTP\/\d+(?:\.\d+)?$/iu.test(token)
7218
8062
  ? "[path]"
7219
8063
  : token);
7220
8064
  const diagnosticDetail = containsParserError
@@ -7224,15 +8068,15 @@ export function skillCommandFailure(command, status, detail, authentication = nu
7224
8068
  const classification = classifyConnectionFailure(classificationDetail);
7225
8069
  let advice;
7226
8070
  if (classification === "unauthorized" ||
7227
- /\b(?:authorizationrequired|invalid[._ -]api[._ -]key|token[._ -]expired)\b/iu.test(classificationDetail)) {
8071
+ /\bauthorizationrequired\b/iu.test(classificationDetail)) {
7228
8072
  advice = authenticationFailureMessage(authentication);
7229
8073
  }
7230
8074
  else if (/\bpermissions? to use (?:this |the )?model\b/iu.test(classificationDetail) ||
7231
8075
  (!/\b(?:sqlite3?|database|workbench)\b/iu.test(classificationDetail) &&
7232
- /\bmodel[ \t]+(?:'[^'\r\n]+'|"[^"\r\n]+"|`[^`\r\n]+`)[ \t]+not[ \t]+found\b/iu.test(classificationDetail)) ||
7233
- /\b(?:model[._ -]not[._ -]found|model[._ -]?access[._ -]?denied|access[._ -]?(?:denied[._ -]?to[._ -]?model|to[._ -]?model[._ -]?denied))\b/iu.test(classificationDetail) ||
8076
+ /(?<![\w./\\-])model[ \t]+(?:'[^'\r\n]+'|"[^"\r\n]+"|`[^`\r\n]+`)[ \t]+not[ \t]+found(?!\.?[\w/\\-])/iu.test(classificationDetail)) ||
8077
+ /(?<![\w./\\-])(?:model[._ -]not[._ -]found|model[._ -]?access[._ -]?denied|access[._ -]?(?:denied[._ -]?to[._ -]?model|to[._ -]?model[._ -]?denied))(?!\.?[\w/\\-])/iu.test(classificationDetail) ||
7234
8078
  (classification === "forbidden" &&
7235
- /\b403\b|\bforbidden\b|\bmodel[ _-]?(?:not[ _-]?found|access)\b|\baccess.*model\b/iu.test(classificationDetail))) {
8079
+ /\b403\b|\bforbidden\b|\bmodel[ ._-]?(?:not[ ._-]?found|access)\b|\baccess.*model\b/iu.test(classificationDetail))) {
7236
8080
  advice = "The selected model is unavailable for the current credentials.";
7237
8081
  }
7238
8082
  else if (classification === "rate_limited" ||
@@ -7246,7 +8090,7 @@ export function skillCommandFailure(command, status, detail, authentication = nu
7246
8090
  else if (classification === "network_error" ||
7247
8091
  classification === "timeout" ||
7248
8092
  (!/\b(?:sqlite3?|database|workbench)\b/iu.test(classificationDetail) &&
7249
- /\b(?:ECONNABORTED|timed[._ -]out|network[._ -]?error|(?:(?:network|request)[._ -]?)?timeout(?:[._ -]?error)?)\b/iu.test(classificationDetail))) {
8093
+ /\b(?:ECONNABORTED|network[._ -]?error|(?:(?:network|request)[._ -]?)?timeout(?:[._ -]?error)?)\b/iu.test(classificationDetail))) {
7250
8094
  advice =
7251
8095
  "Codex could not connect to the model service. Check the network and retry.";
7252
8096
  }
@@ -7277,6 +8121,19 @@ async function incurErrorMessage(output) {
7277
8121
  function diagnosticLines(value) {
7278
8122
  return errorMessage(value).split("\n").map(diagnosticValue).join("\n");
7279
8123
  }
8124
+ const PREVIEW_LABEL = process.platform === "win32" ? "Next (PowerShell)" : "Next";
8125
+ function projectPreviewCommand(directory, path) {
8126
+ if (path === undefined)
8127
+ return "codex-security scan . --dry-run";
8128
+ const local = relative(directory, path);
8129
+ let file = local.split(/[\\/]/u)[0] === ".." ? path : local;
8130
+ if (file.startsWith("-") || file.startsWith("~"))
8131
+ file = `./${file}`;
8132
+ // Keep terminal controls out of suggested commands and quote shell syntax.
8133
+ if (escapeTerminalText(file) !== file)
8134
+ return "codex-security scan . -c FILE --dry-run (replace FILE with the selected path)";
8135
+ return `codex-security scan . -c ${quoteCliPath(file)} --dry-run`;
8136
+ }
7280
8137
  function diagnosticValue(value) {
7281
8138
  return errorMessage(value).replaceAll(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/gu, " ");
7282
8139
  }
@@ -7343,6 +8200,8 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
7343
8200
  let usageFreshness = null;
7344
8201
  let accountLimits = null;
7345
8202
  let maxCostUsd = arguments_.maxCostUsd;
8203
+ if (maxCostUsd !== undefined && arguments_.patch)
8204
+ throw new CodexSecurityError("--patch cannot be combined with a scan cost limit. Run the bounded scan first, then use `codex-security patch --scan SCAN_ID` separately.");
7346
8205
  const showCost = arguments_.showCost === true || maxCostUsd !== undefined;
7347
8206
  let phase = null;
7348
8207
  const targetWarnings = [];
@@ -7430,17 +8289,21 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
7430
8289
  let patchDaybreakFeatures = {};
7431
8290
  let selectedAuthentication = null;
7432
8291
  let repository = "";
8292
+ let runningMockScan = false;
7433
8293
  let failed = false;
7434
8294
  let failure;
7435
8295
  try {
7436
8296
  deepScanOptions(arguments_);
7437
8297
  const directory = dependencies.currentDirectory();
7438
8298
  repository = arguments_.repository ?? directory;
7439
- if (arguments_.validate) {
7440
- repository = await normalizeRepository(resolve(directory, expandHome(repository)), preparationAbortController.signal);
8299
+ const repositoryPath = arguments_.validate
8300
+ ? resolveInputPath(repository, directory)
8301
+ : resolveRepositoryPath(repository, directory);
8302
+ if (arguments_.validate || repositoryPath.split(sep).includes("..")) {
8303
+ repository = await normalizeRepository(repositoryPath, preparationAbortController.signal);
7441
8304
  }
7442
8305
  const target = arguments_.target;
7443
- const prompts = await resolveScanPrompts(arguments_, resolve(directory, repository), directory);
8306
+ const prompts = await resolveScanPrompts(arguments_, resolveRepositoryPath(repository, directory), directory);
7444
8307
  const config = {
7445
8308
  pluginPath: arguments_.pluginPath,
7446
8309
  pythonPath: arguments_.pythonPath,
@@ -7965,7 +8828,7 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
7965
8828
  if (((arguments_.validate && !arguments_.dryRun) ||
7966
8829
  arguments_.rerunInputIdentity !== undefined) &&
7967
8830
  options.knowledgeBasePaths?.length) {
7968
- options.knowledgeBaseSnapshot = await readKnowledgeBaseSnapshot(options.knowledgeBasePaths, preparationAbortController.signal);
8831
+ options.knowledgeBaseSnapshot = await readKnowledgeBaseSnapshot(options.knowledgeBasePaths, preparationAbortController.signal, resolve(directory, expandHome(repository)));
7969
8832
  }
7970
8833
  if (arguments_.rerunInputIdentity !== undefined) {
7971
8834
  const previousInputs = arguments_.rerunInputIdentity;
@@ -7989,9 +8852,11 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
7989
8852
  preflight = await security.preflight(repository, options);
7990
8853
  }
7991
8854
  else {
8855
+ runningMockScan = arguments_.mock === true;
7992
8856
  result = await security.run(repository, options);
8857
+ runningMockScan = false;
7993
8858
  scanDir = result.scanDir;
7994
- repository = resolve(dependencies.currentDirectory(), repository);
8859
+ repository = resolveRepositoryPath(repository, dependencies.currentDirectory());
7995
8860
  if (arguments_.validate) {
7996
8861
  const scanId = result.manifest.scan.id;
7997
8862
  const checkTarget = async () => {
@@ -8142,7 +9007,7 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
8142
9007
  if (result !== null && arguments_.validate) {
8143
9008
  const exitCode = requestedSignal === "SIGINT" ? 130 : 143;
8144
9009
  const scanId = quoteCliPath(diagnosticValue(result.manifest.scan.id));
8145
- const message = `Validation interrupted. Original output directory: ${errorMessage(result.scanDir)}. Run codex-security scans show ${scanId} to inspect the completed scan.`;
9010
+ const message = `Validation interrupted. Original output directory: ${errorMessage(result.scanDir)}. Run${cliShellLabel(scanId)} codex-security scans show ${scanId} to inspect the completed scan.`;
8146
9011
  errorOutput.write(`codex-security: ${message}\n`);
8147
9012
  return {
8148
9013
  exitCode,
@@ -8167,7 +9032,9 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
8167
9032
  }
8168
9033
  if (failed) {
8169
9034
  const costLimitFailure = failure instanceof ScanCostLimitExceededError ? failure : undefined;
8170
- const classification = classifyScanFailure(failure);
9035
+ const classification = runningMockScan
9036
+ ? "local"
9037
+ : classifyScanFailure(failure);
8171
9038
  const message = failure instanceof OutputInsideProtectedRootError
8172
9039
  ? errorMessage(protectedRootErrorMessage(failure))
8173
9040
  : scanFailureMessage(failure, classification, selectedAuthentication, providerOptions.provider);
@@ -8294,6 +9161,7 @@ async function executeScan(arguments_, errorOutput, dependencies, interactive, r
8294
9161
  let patchSelection = null;
8295
9162
  try {
8296
9163
  if (!arguments_.mock &&
9164
+ maxCostUsd === undefined &&
8297
9165
  actionableFindings.length > 0 &&
8298
9166
  arguments_.patchSeverity === undefined &&
8299
9167
  progress?.interactive === true &&
@@ -8502,7 +9370,7 @@ function scanFailureMessage(error, classification, authentication, provider) {
8502
9370
  return error instanceof IncompleteScanError
8503
9371
  ? diagnosticValue(error)
8504
9372
  : nativeRefreshRecovery;
8505
- const detail = error instanceof IncompleteScanError ? `${diagnosticValue(error)}\n` : "";
9373
+ const detail = `${diagnosticValue(error)}\n`;
8506
9374
  const refreshFailure = message.match(/\byour access token could not be refreshed(?: because your refresh token (has expired|was already used|was revoked))?\. Please log out and sign in again\./iu);
8507
9375
  if (refreshFailure) {
8508
9376
  const recovery = refreshFailure[1]?.toLowerCase() === "was already used"
@@ -8575,7 +9443,7 @@ async function readDeepScanStop(result, maxCostUsd, runWorkbench) {
8575
9443
  const state = response["deepScan"];
8576
9444
  if (state?.terminalReason === "saturated") {
8577
9445
  return {
8578
- reason: `The last ${state.noNewStreak} review rounds found no new issues. More issues may remain.`,
9446
+ reason: `The last ${state.noNewStreak} review round${state.noNewStreak === 1 ? "" : "s"} found no new issues. More issues may remain.`,
8579
9447
  };
8580
9448
  }
8581
9449
  if (state?.terminalReason !== "capped")
@@ -8585,7 +9453,7 @@ async function readDeepScanStop(result, maxCostUsd, runWorkbench) {
8585
9453
  if (state.completionSequence > 0 &&
8586
9454
  state.dispatchedCount >= maxDiscoveryRuns) {
8587
9455
  return {
8588
- reason: `Reached the limit of ${maxDiscoveryRuns} review rounds. ${state.noNewStreak === 0 ? "The latest review still found new issues." : "More issues may remain."}`,
9456
+ reason: `Reached the limit of ${maxDiscoveryRuns} review round${maxDiscoveryRuns === 1 ? "" : "s"}. ${state.noNewStreak === 0 ? "The latest review still found new issues." : "More issues may remain."}`,
8589
9457
  nextStep: `To scan further, rerun with --max-discovery-runs greater than ${maxDiscoveryRuns}.`,
8590
9458
  };
8591
9459
  }
@@ -8628,8 +9496,10 @@ function printScanReference(scan, output, showLogs, selection) {
8628
9496
  const argument = quoteCliPath(diagnosticValue(scanId));
8629
9497
  output.write(`\n${detail.join(" · ")}\n` +
8630
9498
  (selection === undefined ? "" : `Selected ${selection}.\n`) +
8631
- `Inspect: codex-security scans show ${argument}\n` +
8632
- (showLogs ? `Logs: codex-security scans logs ${argument}\n` : ""));
9499
+ `Inspect${cliShellLabel(argument)}: codex-security scans show ${argument}\n` +
9500
+ (showLogs
9501
+ ? `Logs${cliShellLabel(argument)}: codex-security scans logs ${argument}\n`
9502
+ : ""));
8633
9503
  }
8634
9504
  function printFailedScanReference(scan, phase, arguments_, output) {
8635
9505
  if (scan === undefined)
@@ -8681,7 +9551,7 @@ function printScanSummary(result, progress, errorOutput, color, showCost, deepSc
8681
9551
  const confirmedCount = repositoryFindings?.filter((finding) => finding.confirmedInLatestScan)
8682
9552
  .length ?? 0;
8683
9553
  const findingSummary = repositoryFindings?.length
8684
- ? `${confirmedCount} confirmed this scan; ${findingCount - confirmedCount} previously found; ${severitySummary}`
9554
+ ? `${confirmedCount} confirmed in latest repository scan; ${findingCount - confirmedCount} previously found; ${severitySummary}`
8685
9555
  : severitySummary;
8686
9556
  const findingColor = findingCount === 0
8687
9557
  ? 32
@@ -8779,7 +9649,7 @@ function protectedRootErrorMessage(error) {
8779
9649
  const reason = error.pathKind === "output"
8780
9650
  ? "Scan artifacts cannot be written inside the protected scan root."
8781
9651
  : "Temporary and runtime files cannot be created inside the protected scan root.";
8782
- const suggestion = suggestedOutputDirectory(error.protectedRoot);
9652
+ const suggestion = suggestedOutputArgument(error.protectedRoot);
8783
9653
  return [
8784
9654
  `${description} must be outside the scanned directory and any enclosing Git worktree.`,
8785
9655
  ` Resolved path: ${error.outputDirectory}`,
@@ -8788,13 +9658,13 @@ function protectedRootErrorMessage(error) {
8788
9658
  error.pathKind === "output"
8789
9659
  ? suggestion === undefined
8790
9660
  ? "Choose an output directory outside the protected root."
8791
- : `Re-run with --output-dir ${quoteCliPath(suggestion)}.`
9661
+ : `Re-run${cliShellLabel(suggestion)} with --output-dir ${suggestion}.`
8792
9662
  : suggestion === undefined
8793
9663
  ? "Set TMPDIR (or TEMP on Windows) to a writable directory outside the protected root."
8794
- : `Set TMPDIR (or TEMP on Windows) to ${quoteCliPath(suggestion)} after creating that directory.`,
9664
+ : `Set TMPDIR (or TEMP on Windows) to ${suggestion} after creating that directory.`,
8795
9665
  ].join("\n");
8796
9666
  }
8797
- function suggestedOutputDirectory(protectedRoot) {
9667
+ function suggestedOutputArgument(protectedRoot) {
8798
9668
  const parent = dirname(protectedRoot);
8799
9669
  if (parent === protectedRoot)
8800
9670
  return undefined;
@@ -8815,19 +9685,18 @@ function suggestedOutputDirectory(protectedRoot) {
8815
9685
  error !== null &&
8816
9686
  "code" in error &&
8817
9687
  error.code === "ENOENT") {
8818
- return candidate;
9688
+ return quoteCliPath(candidate);
8819
9689
  }
8820
9690
  return undefined;
8821
9691
  }
8822
9692
  }
8823
9693
  return undefined;
8824
9694
  }
8825
- function quoteCliPath(path) {
8826
- if (/^[A-Za-z0-9_./:\\-]+$/u.test(path))
8827
- return path;
8828
- return process.platform === "win32"
8829
- ? `"${path}"`
8830
- : `'${path.replaceAll("'", `'"'"'`)}'`;
9695
+ function importedFindingsCommand(repository) {
9696
+ if (diagnosticValue(repository) !== repository)
9697
+ return "From the repository directory, run codex-security findings imported.";
9698
+ const path = quoteCliPath(repository);
9699
+ return `Stored evidence${cliShellLabel(path)}: codex-security findings imported ${path}`;
8831
9700
  }
8832
9701
  async function selectedProjectConfig(file, dependencies) {
8833
9702
  const selected = file ??
@@ -9123,7 +9992,7 @@ const interruptedExitCode = (signal) => signal.reason === "SIGINT"
9123
9992
  ? 143
9124
9993
  : undefined;
9125
9994
  if (invokedAsMain()) {
9126
- void main().then((exitCode) => {
9995
+ void runCli().then((exitCode) => {
9127
9996
  process.exitCode = exitCode;
9128
9997
  }, (error) => {
9129
9998
  process.stderr.write(`codex-security: ${diagnosticLines(error)}\n`);