@openai/codex-security 0.9.1 → 0.10.1

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 (444) hide show
  1. package/README.md +37 -788
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +3 -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/access-advisory.md +1 -1
  15. package/_bundled_plugin/references/artifact-storage.md +1 -1
  16. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  17. package/_bundled_plugin/references/core-scan.md +5 -42
  18. package/_bundled_plugin/references/final-report.md +1 -1
  19. package/_bundled_plugin/references/focused-investigator.md +13 -0
  20. package/_bundled_plugin/references/scan-prologue.md +2 -2
  21. package/_bundled_plugin/references/scan-runtime.md +4 -2
  22. package/_bundled_plugin/references/security-guidance.md +14 -1
  23. package/_bundled_plugin/references/threat-model.md +1 -0
  24. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  25. package/_bundled_plugin/scripts/deep_scan_workbench.py +30 -12
  26. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  27. package/_bundled_plugin/scripts/finalize_scan_contract.py +47 -9
  28. package/_bundled_plugin/scripts/launch_codex_security_mcp +54 -16
  29. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +2 -0
  30. package/_bundled_plugin/scripts/posix_scan_local_files.py +26 -1
  31. package/_bundled_plugin/scripts/snapshot_sqlite.py +8 -2
  32. package/_bundled_plugin/scripts/windows_scan_local_files.py +216 -25
  33. package/_bundled_plugin/scripts/workbench/handoff.py +55 -25
  34. package/_bundled_plugin/scripts/workbench/storage.py +25 -5
  35. package/_bundled_plugin/scripts/workbench_cli.py +24 -2
  36. package/_bundled_plugin/scripts/workbench_constants.py +2 -0
  37. package/_bundled_plugin/scripts/workbench_db.py +257 -268
  38. package/_bundled_plugin/scripts/workbench_feedback.py +49 -4
  39. package/_bundled_plugin/scripts/workbench_native_indexes.py +226 -29
  40. package/_bundled_plugin/scripts/workbench_progress.py +159 -3
  41. package/_bundled_plugin/scripts/workbench_publication.py +2 -3
  42. package/_bundled_plugin/scripts/workbench_remediation.py +142 -2
  43. package/_bundled_plugin/scripts/workbench_saved_results.py +48 -8
  44. package/_bundled_plugin/scripts/workbench_scan_history.py +291 -134
  45. package/_bundled_plugin/scripts/workbench_scan_start.py +208 -11
  46. package/_bundled_plugin/scripts/workbench_scan_usage.py +36 -10
  47. package/_bundled_plugin/scripts/workbench_schema.py +220 -14
  48. package/_bundled_plugin/scripts/workbench_setup.py +1 -1
  49. package/_bundled_plugin/scripts/workbench_source_scopes.py +8 -0
  50. package/_bundled_plugin/scripts/workbench_target.py +486 -85
  51. package/_bundled_plugin/scripts/workbench_target_state.py +1108 -22
  52. package/_bundled_plugin/shared/workbench-history-repairs.json +64 -14
  53. package/_bundled_plugin/shared/workbench-migrations.json +66 -0
  54. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +4 -2
  55. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +2 -2
  56. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -0
  57. package/_bundled_plugin/skills/publish-findings/SKILL.md +26 -160
  58. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  59. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +2 -2
  60. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +3 -58
  61. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  62. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  63. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  64. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  65. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  66. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  67. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  68. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  69. package/bin/codex-security.mjs +2 -2
  70. package/dist/api.d.ts +7 -1
  71. package/dist/api.d.ts.map +1 -1
  72. package/dist/api.js +459 -157
  73. package/dist/api.js.map +1 -1
  74. package/dist/armorcode-findings.d.ts +9 -0
  75. package/dist/armorcode-findings.d.ts.map +1 -0
  76. package/dist/armorcode-findings.js +145 -0
  77. package/dist/armorcode-findings.js.map +1 -0
  78. package/dist/artifact-export.d.ts +2 -0
  79. package/dist/artifact-export.d.ts.map +1 -1
  80. package/dist/artifact-export.js +29 -13
  81. package/dist/artifact-export.js.map +1 -1
  82. package/dist/auth.d.ts +6 -2
  83. package/dist/auth.d.ts.map +1 -1
  84. package/dist/auth.js +33 -12
  85. package/dist/auth.js.map +1 -1
  86. package/dist/batch-cost.d.ts +18 -0
  87. package/dist/batch-cost.d.ts.map +1 -0
  88. package/dist/batch-cost.js +41 -0
  89. package/dist/batch-cost.js.map +1 -0
  90. package/dist/blackduck-findings.d.ts +1 -1
  91. package/dist/blackduck-findings.d.ts.map +1 -1
  92. package/dist/blackduck-findings.js +5 -18
  93. package/dist/blackduck-findings.js.map +1 -1
  94. package/dist/bundled-plugin.d.ts +4 -0
  95. package/dist/bundled-plugin.d.ts.map +1 -0
  96. package/dist/bundled-plugin.js +23 -0
  97. package/dist/bundled-plugin.js.map +1 -0
  98. package/dist/classify-scan-severity.d.ts +1 -1
  99. package/dist/classify-scan-severity.d.ts.map +1 -1
  100. package/dist/classify-scan-severity.js +11 -3
  101. package/dist/classify-scan-severity.js.map +1 -1
  102. package/dist/classify-severity-diagnostics.d.ts +10 -0
  103. package/dist/classify-severity-diagnostics.d.ts.map +1 -0
  104. package/dist/classify-severity-diagnostics.js +57 -0
  105. package/dist/classify-severity-diagnostics.js.map +1 -0
  106. package/dist/classify-severity-records.d.ts +4 -0
  107. package/dist/classify-severity-records.d.ts.map +1 -1
  108. package/dist/classify-severity-records.js +35 -8
  109. package/dist/classify-severity-records.js.map +1 -1
  110. package/dist/classify-severity.d.ts.map +1 -1
  111. package/dist/classify-severity.js +9 -6
  112. package/dist/classify-severity.js.map +1 -1
  113. package/dist/cli-argument.d.ts +4 -0
  114. package/dist/cli-argument.d.ts.map +1 -0
  115. package/dist/cli-argument.js +17 -0
  116. package/dist/cli-argument.js.map +1 -0
  117. package/dist/cli-help.d.ts +1 -1
  118. package/dist/cli-help.d.ts.map +1 -1
  119. package/dist/cli-help.js +71 -29
  120. package/dist/cli-help.js.map +1 -1
  121. package/dist/cli-hook.d.ts +3 -0
  122. package/dist/cli-hook.d.ts.map +1 -0
  123. package/dist/cli-hook.js +87 -0
  124. package/dist/cli-hook.js.map +1 -0
  125. package/dist/cli-integrations.d.ts +13 -0
  126. package/dist/cli-integrations.d.ts.map +1 -0
  127. package/dist/cli-integrations.js +333 -0
  128. package/dist/cli-integrations.js.map +1 -0
  129. package/dist/cli-mcp.d.ts +15 -0
  130. package/dist/cli-mcp.d.ts.map +1 -0
  131. package/dist/cli-mcp.js +178 -0
  132. package/dist/cli-mcp.js.map +1 -0
  133. package/dist/cli-token-view.d.ts +10 -0
  134. package/dist/cli-token-view.d.ts.map +1 -0
  135. package/dist/cli-token-view.js +41 -0
  136. package/dist/cli-token-view.js.map +1 -0
  137. package/dist/cli.d.ts +8 -3
  138. package/dist/cli.d.ts.map +1 -1
  139. package/dist/cli.js +1860 -903
  140. package/dist/cli.js.map +1 -1
  141. package/dist/cloud-publish.d.ts.map +1 -1
  142. package/dist/cloud-publish.js +33 -31
  143. package/dist/cloud-publish.js.map +1 -1
  144. package/dist/codex-sdk-environment.d.ts +6 -0
  145. package/dist/codex-sdk-environment.d.ts.map +1 -1
  146. package/dist/codex-sdk-environment.js +19 -0
  147. package/dist/codex-sdk-environment.js.map +1 -1
  148. package/dist/command-words.d.ts +3 -0
  149. package/dist/command-words.d.ts.map +1 -0
  150. package/dist/command-words.js +46 -0
  151. package/dist/command-words.js.map +1 -0
  152. package/dist/component-plan.d.ts.map +1 -1
  153. package/dist/component-plan.js +3 -3
  154. package/dist/component-plan.js.map +1 -1
  155. package/dist/component-scan.d.ts +3 -1
  156. package/dist/component-scan.d.ts.map +1 -1
  157. package/dist/component-scan.js +40 -7
  158. package/dist/component-scan.js.map +1 -1
  159. package/dist/config.d.ts +1 -1
  160. package/dist/config.d.ts.map +1 -1
  161. package/dist/config.js +30 -1
  162. package/dist/config.js.map +1 -1
  163. package/dist/continuum-aws.d.ts +6 -0
  164. package/dist/continuum-aws.d.ts.map +1 -0
  165. package/dist/continuum-aws.js +202 -0
  166. package/dist/continuum-aws.js.map +1 -0
  167. package/dist/continuum-collector.d.ts +44 -0
  168. package/dist/continuum-collector.d.ts.map +1 -0
  169. package/dist/continuum-collector.js +266 -0
  170. package/dist/continuum-collector.js.map +1 -0
  171. package/dist/continuum-findings.d.ts +31 -2
  172. package/dist/continuum-findings.d.ts.map +1 -1
  173. package/dist/continuum-findings.js +497 -59
  174. package/dist/continuum-findings.js.map +1 -1
  175. package/dist/contract.d.ts +1 -0
  176. package/dist/contract.d.ts.map +1 -1
  177. package/dist/contract.js +3 -0
  178. package/dist/contract.js.map +1 -1
  179. package/dist/cost.d.ts.map +1 -1
  180. package/dist/cost.js +1 -45
  181. package/dist/cost.js.map +1 -1
  182. package/dist/crowdstrike-findings.d.ts +7 -0
  183. package/dist/crowdstrike-findings.d.ts.map +1 -0
  184. package/dist/crowdstrike-findings.js +210 -0
  185. package/dist/crowdstrike-findings.js.map +1 -0
  186. package/dist/custom-validation-prompt.d.ts +1 -1
  187. package/dist/custom-validation-prompt.d.ts.map +1 -1
  188. package/dist/custom-validation-prompt.js +29 -19
  189. package/dist/custom-validation-prompt.js.map +1 -1
  190. package/dist/deduplication/local.d.ts +3 -1
  191. package/dist/deduplication/local.d.ts.map +1 -1
  192. package/dist/deduplication/local.js +8 -1
  193. package/dist/deduplication/local.js.map +1 -1
  194. package/dist/deduplication/refusal.d.ts.map +1 -1
  195. package/dist/deduplication/refusal.js +2 -1
  196. package/dist/deduplication/refusal.js.map +1 -1
  197. package/dist/deduplication/scan.d.ts +2 -0
  198. package/dist/deduplication/scan.d.ts.map +1 -1
  199. package/dist/deduplication/scan.js +24 -7
  200. package/dist/deduplication/scan.js.map +1 -1
  201. package/dist/deep-scan.d.ts.map +1 -1
  202. package/dist/deep-scan.js +16 -15
  203. package/dist/deep-scan.js.map +1 -1
  204. package/dist/endor-findings.d.ts +2 -2
  205. package/dist/endor-findings.d.ts.map +1 -1
  206. package/dist/endor-findings.js +6 -23
  207. package/dist/endor-findings.js.map +1 -1
  208. package/dist/errors.d.ts +3 -1
  209. package/dist/errors.d.ts.map +1 -1
  210. package/dist/errors.js +7 -3
  211. package/dist/errors.js.map +1 -1
  212. package/dist/executable-path.d.ts +3 -0
  213. package/dist/executable-path.d.ts.map +1 -1
  214. package/dist/executable-path.js +26 -0
  215. package/dist/executable-path.js.map +1 -1
  216. package/dist/external-findings-import.d.ts.map +1 -1
  217. package/dist/external-findings-import.js +12 -1
  218. package/dist/external-findings-import.js.map +1 -1
  219. package/dist/external-findings-local.d.ts +66 -4
  220. package/dist/external-findings-local.d.ts.map +1 -1
  221. package/dist/external-findings-local.js +258 -59
  222. package/dist/external-findings-local.js.map +1 -1
  223. package/dist/external-findings-publish.d.ts +6 -1
  224. package/dist/external-findings-publish.d.ts.map +1 -1
  225. package/dist/external-findings-publish.js +330 -1633
  226. package/dist/external-findings-publish.js.map +1 -1
  227. package/dist/external-findings-read.d.ts +11 -2
  228. package/dist/external-findings-read.d.ts.map +1 -1
  229. package/dist/external-findings-read.js +56 -53
  230. package/dist/external-findings-read.js.map +1 -1
  231. package/dist/external-findings.d.ts +1 -1
  232. package/dist/external-findings.d.ts.map +1 -1
  233. package/dist/external-findings.js +12 -1
  234. package/dist/external-findings.js.map +1 -1
  235. package/dist/external-import-contract.d.ts +6 -11
  236. package/dist/external-import-contract.d.ts.map +1 -1
  237. package/dist/external-import-contract.js +35 -177
  238. package/dist/external-import-contract.js.map +1 -1
  239. package/dist/external-import-models.d.ts +1 -1
  240. package/dist/external-import-models.d.ts.map +1 -1
  241. package/dist/external-import-models.js.map +1 -1
  242. package/dist/finding-prompt.d.ts.map +1 -1
  243. package/dist/finding-prompt.js +2 -2
  244. package/dist/finding-prompt.js.map +1 -1
  245. package/dist/github-dependabot-findings.d.ts.map +1 -1
  246. package/dist/github-dependabot-findings.js +3 -4
  247. package/dist/github-dependabot-findings.js.map +1 -1
  248. package/dist/github-findings.d.ts.map +1 -1
  249. package/dist/github-findings.js +19 -287
  250. package/dist/github-findings.js.map +1 -1
  251. package/dist/host-protocol.d.ts +6 -0
  252. package/dist/host-protocol.d.ts.map +1 -1
  253. package/dist/host-protocol.js +11 -1
  254. package/dist/host-protocol.js.map +1 -1
  255. package/dist/host-records-protocol.d.ts +2 -0
  256. package/dist/host-records-protocol.d.ts.map +1 -1
  257. package/dist/host-records-protocol.js +4 -0
  258. package/dist/host-records-protocol.js.map +1 -1
  259. package/dist/hosted-remediation.d.ts +1 -0
  260. package/dist/hosted-remediation.d.ts.map +1 -1
  261. package/dist/hosted-remediation.js +23 -3
  262. package/dist/hosted-remediation.js.map +1 -1
  263. package/dist/index.d.ts +5 -3
  264. package/dist/index.d.ts.map +1 -1
  265. package/dist/index.js +3 -1
  266. package/dist/index.js.map +1 -1
  267. package/dist/inspector-findings.d.ts.map +1 -1
  268. package/dist/inspector-findings.js +19 -35
  269. package/dist/inspector-findings.js.map +1 -1
  270. package/dist/knowledge-base.d.ts +1 -1
  271. package/dist/knowledge-base.d.ts.map +1 -1
  272. package/dist/knowledge-base.js +34 -27
  273. package/dist/knowledge-base.js.map +1 -1
  274. package/dist/linear.d.ts +11 -0
  275. package/dist/linear.d.ts.map +1 -1
  276. package/dist/linear.js.map +1 -1
  277. package/dist/local-git-metadata.d.ts +5 -2
  278. package/dist/local-git-metadata.d.ts.map +1 -1
  279. package/dist/local-git-metadata.js +8 -4
  280. package/dist/local-git-metadata.js.map +1 -1
  281. package/dist/multiscan.d.ts +4 -0
  282. package/dist/multiscan.d.ts.map +1 -1
  283. package/dist/multiscan.js +83 -39
  284. package/dist/multiscan.js.map +1 -1
  285. package/dist/opengrep-findings.d.ts +4 -2
  286. package/dist/opengrep-findings.d.ts.map +1 -1
  287. package/dist/opengrep-findings.js +39 -22
  288. package/dist/opengrep-findings.js.map +1 -1
  289. package/dist/private-finding-import.d.ts +8 -13
  290. package/dist/private-finding-import.d.ts.map +1 -1
  291. package/dist/private-finding-import.js +69 -129
  292. package/dist/private-finding-import.js.map +1 -1
  293. package/dist/project-config-schema.d.ts +2 -0
  294. package/dist/project-config-schema.d.ts.map +1 -1
  295. package/dist/project-config-schema.js +1 -0
  296. package/dist/project-config-schema.js.map +1 -1
  297. package/dist/project-config.d.ts +1 -0
  298. package/dist/project-config.d.ts.map +1 -1
  299. package/dist/project-config.js +56 -13
  300. package/dist/project-config.js.map +1 -1
  301. package/dist/prompt-files.d.ts +7 -2
  302. package/dist/prompt-files.d.ts.map +1 -1
  303. package/dist/prompt-files.js +42 -20
  304. package/dist/prompt-files.js.map +1 -1
  305. package/dist/provider-profile.d.ts.map +1 -1
  306. package/dist/provider-profile.js +4 -9
  307. package/dist/provider-profile.js.map +1 -1
  308. package/dist/publication.d.ts +1 -1
  309. package/dist/publication.d.ts.map +1 -1
  310. package/dist/publication.js.map +1 -1
  311. package/dist/record.d.ts +1 -5
  312. package/dist/record.d.ts.map +1 -1
  313. package/dist/record.js +3 -51
  314. package/dist/record.js.map +1 -1
  315. package/dist/remediation.d.ts.map +1 -1
  316. package/dist/remediation.js +3 -1
  317. package/dist/remediation.js.map +1 -1
  318. package/dist/runtime.d.ts +35 -7
  319. package/dist/runtime.d.ts.map +1 -1
  320. package/dist/runtime.js +782 -153
  321. package/dist/runtime.js.map +1 -1
  322. package/dist/saved-scan-bootstrap.d.ts +6 -1
  323. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  324. package/dist/saved-scan-bootstrap.js +267 -115
  325. package/dist/saved-scan-bootstrap.js.map +1 -1
  326. package/dist/scan-archive-path.d.ts +2 -0
  327. package/dist/scan-archive-path.d.ts.map +1 -0
  328. package/dist/scan-archive-path.js +5 -0
  329. package/dist/scan-archive-path.js.map +1 -0
  330. package/dist/scan-comparison.d.ts +20 -2
  331. package/dist/scan-comparison.d.ts.map +1 -1
  332. package/dist/scan-comparison.js +26 -5
  333. package/dist/scan-comparison.js.map +1 -1
  334. package/dist/scan-dashboard.d.ts +1 -0
  335. package/dist/scan-dashboard.d.ts.map +1 -1
  336. package/dist/scan-dashboard.js +18 -2
  337. package/dist/scan-dashboard.js.map +1 -1
  338. package/dist/scan-executor.d.ts.map +1 -1
  339. package/dist/scan-executor.js +4 -2
  340. package/dist/scan-executor.js.map +1 -1
  341. package/dist/scan-history-renderer.d.ts +1 -0
  342. package/dist/scan-history-renderer.d.ts.map +1 -1
  343. package/dist/scan-history-renderer.js +25 -9
  344. package/dist/scan-history-renderer.js.map +1 -1
  345. package/dist/scan-logs.d.ts.map +1 -1
  346. package/dist/scan-logs.js +28 -4
  347. package/dist/scan-logs.js.map +1 -1
  348. package/dist/scan-settings.d.ts +1 -0
  349. package/dist/scan-settings.d.ts.map +1 -1
  350. package/dist/scan-settings.js +1 -0
  351. package/dist/scan-settings.js.map +1 -1
  352. package/dist/scanner-import.d.ts +5 -11
  353. package/dist/scanner-import.d.ts.map +1 -1
  354. package/dist/scanner-import.js +16 -89
  355. package/dist/scanner-import.js.map +1 -1
  356. package/dist/security-policy.d.ts.map +1 -1
  357. package/dist/security-policy.js +26 -6
  358. package/dist/security-policy.js.map +1 -1
  359. package/dist/semgrep-findings.d.ts.map +1 -1
  360. package/dist/semgrep-findings.js +14 -48
  361. package/dist/semgrep-findings.js.map +1 -1
  362. package/dist/semgrep-platform-findings.d.ts +20 -70
  363. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  364. package/dist/semgrep-platform-findings.js +116 -333
  365. package/dist/semgrep-platform-findings.js.map +1 -1
  366. package/dist/severity-review.d.ts.map +1 -1
  367. package/dist/severity-review.js +1 -0
  368. package/dist/severity-review.js.map +1 -1
  369. package/dist/snyk-findings.d.ts +2 -0
  370. package/dist/snyk-findings.d.ts.map +1 -1
  371. package/dist/snyk-findings.js +5 -8
  372. package/dist/snyk-findings.js.map +1 -1
  373. package/dist/snyk-rest-findings.d.ts +3 -20
  374. package/dist/snyk-rest-findings.d.ts.map +1 -1
  375. package/dist/snyk-rest-findings.js +45 -217
  376. package/dist/snyk-rest-findings.js.map +1 -1
  377. package/dist/sonar-findings.d.ts +1 -1
  378. package/dist/sonar-findings.d.ts.map +1 -1
  379. package/dist/sonar-findings.js +2 -4
  380. package/dist/sonar-findings.js.map +1 -1
  381. package/dist/sonar-import.d.ts +3 -0
  382. package/dist/sonar-import.d.ts.map +1 -1
  383. package/dist/sonar-import.js +28 -30
  384. package/dist/sonar-import.js.map +1 -1
  385. package/dist/stored-finding-projection.d.ts +6 -0
  386. package/dist/stored-finding-projection.d.ts.map +1 -0
  387. package/dist/stored-finding-projection.js +129 -0
  388. package/dist/stored-finding-projection.js.map +1 -0
  389. package/dist/stored-findings-publication.d.ts +23 -0
  390. package/dist/stored-findings-publication.d.ts.map +1 -0
  391. package/dist/stored-findings-publication.js +169 -0
  392. package/dist/stored-findings-publication.js.map +1 -0
  393. package/dist/targets.d.ts +8 -1
  394. package/dist/targets.d.ts.map +1 -1
  395. package/dist/targets.js +103 -23
  396. package/dist/targets.js.map +1 -1
  397. package/dist/tenable-findings.d.ts +1 -4
  398. package/dist/tenable-findings.d.ts.map +1 -1
  399. package/dist/tenable-findings.js.map +1 -1
  400. package/dist/trivy-findings.d.ts.map +1 -1
  401. package/dist/trivy-findings.js +0 -11
  402. package/dist/trivy-findings.js.map +1 -1
  403. package/dist/trusted-executable.d.ts +7 -0
  404. package/dist/trusted-executable.d.ts.map +1 -1
  405. package/dist/trusted-executable.js +148 -37
  406. package/dist/trusted-executable.js.map +1 -1
  407. package/dist/value.js +3 -1
  408. package/dist/value.js.map +1 -1
  409. package/dist/veracode-findings.d.ts +1 -3
  410. package/dist/veracode-findings.d.ts.map +1 -1
  411. package/dist/veracode-findings.js +13 -38
  412. package/dist/veracode-findings.js.map +1 -1
  413. package/dist/version.d.ts +3 -1
  414. package/dist/version.d.ts.map +1 -1
  415. package/dist/version.js +184 -32
  416. package/dist/version.js.map +1 -1
  417. package/dist/wiz-findings.d.ts +2 -2
  418. package/dist/wiz-findings.d.ts.map +1 -1
  419. package/dist/wiz-findings.js +14 -92
  420. package/dist/wiz-findings.js.map +1 -1
  421. package/docs/classify-severity-records.md +30 -0
  422. package/docs/cli.md +537 -124
  423. package/docs/findings-service.md +22 -9
  424. package/docs/hosted-remediation.md +13 -4
  425. package/docs/sdk.md +918 -0
  426. package/package.json +15 -6
  427. package/schemas/external-findings.schema.json +2 -1
  428. package/schemas/project-config.schema.json +5 -0
  429. package/dist/hosted-scanner-v1.d.ts +0 -6
  430. package/dist/hosted-scanner-v1.d.ts.map +0 -1
  431. package/dist/hosted-scanner-v1.js +0 -60
  432. package/dist/hosted-scanner-v1.js.map +0 -1
  433. package/dist/reader-selection.d.ts +0 -15
  434. package/dist/reader-selection.d.ts.map +0 -1
  435. package/dist/reader-selection.js +0 -89
  436. package/dist/reader-selection.js.map +0 -1
  437. package/dist/semgrep-platform-v1.d.ts +0 -6
  438. package/dist/semgrep-platform-v1.d.ts.map +0 -1
  439. package/dist/semgrep-platform-v1.js +0 -83
  440. package/dist/semgrep-platform-v1.js.map +0 -1
  441. package/dist/snyk-rest-v1.d.ts +0 -28
  442. package/dist/snyk-rest-v1.d.ts.map +0 -1
  443. package/dist/snyk-rest-v1.js +0 -132
  444. package/dist/snyk-rest-v1.js.map +0 -1
package/docs/cli.md CHANGED
@@ -14,7 +14,10 @@ codex-security info --json
14
14
 
15
15
  `--help` lists commands by task; `<command> --help` lists its options.
16
16
  `info --json` reports package, plugin, runtime, and model details.
17
- `scans` and `findings` default to their `list` subcommands.
17
+ `scans` and `findings` default to their `list` subcommands. Global output options
18
+ can appear around a subcommand, for example `cs scans --json show`. Use `--`
19
+ after the command to pass the remaining words as literal positional arguments,
20
+ including file names that begin with a dash.
18
21
 
19
22
  ## Find a workflow
20
23
 
@@ -37,6 +40,26 @@ codex-security info --json
37
40
  - [Use a hosted executor](#hosted-standard-scan) or
38
41
  [run bulk scans in containers](#containerized-bulk-scans).
39
42
 
43
+ ## Updating the CLI
44
+
45
+ Run `cs update` to update an npm global installation managed by the running
46
+ Node distribution. It uses Node’s bundled npm, the public npm registry, and
47
+ disabled lifecycle scripts. If you use a custom registry or proxy, run your
48
+ package manager’s update command directly.
49
+
50
+ The legacy `cs --update` spelling also works. Invoke the updater or the stdio
51
+ server (`cs --mcp`) on its own.
52
+
53
+ For a project dependency, `cs update` prints the package-manager command for
54
+ you to run in the declaring project. For other global installations it prints
55
+ the corresponding package-manager command and installation location. For npx,
56
+ use `npx @openai/codex-security@latest` on the next run. For a standalone
57
+ release, download and extract the latest release.
58
+
59
+ Interactive update notices use the same installation detection. Set
60
+ `CODEX_SECURITY_NO_UPDATE_NOTICE=1` to disable these notices. Explicit updates
61
+ are available with notifications disabled.
62
+
40
63
  ## Authentication
41
64
 
42
65
  Sign in with ChatGPT, or supply an API key for CI:
@@ -139,6 +162,8 @@ If Codex Security reports that the refresh token was already used, run
139
162
  `codex-security logout`, then `codex-security login`. If your Codex CLI or app
140
163
  reports that error, sign out and sign back in there.
141
164
 
165
+ Use `codex-security login status --json` in automation. Its stdout reports `authenticated`, the effective authentication `method`, and the environment variable name when an API key takes precedence. When an API key takes precedence, stderr names the variable that configures it. This offline status check also labels the separate stored sign-in diagnostic. The command keeps the exit status of the human-readable status check.
166
+
142
167
  For other refresh errors, check `codex-security login status`. Retry if the
143
168
  sign-in recently changed. Otherwise run `codex-security logout`, then
144
169
  `codex-security login`.
@@ -239,6 +264,27 @@ comparisons, and deduplication preserve that selection. Relative helper paths an
239
264
  `auth.cwd` resolve from `CODEX_HOME` (default `~/.codex`). Comparisons and reviews
240
265
  also honor the selected command provider in that home's `config.toml`.
241
266
 
267
+ For OrcaRouter, save this profile in `$CODEX_HOME/orcarouter.config.toml`
268
+ (default `~/.codex/orcarouter.config.toml`), then run
269
+ `codex-security scan . --codex 'profile="orcarouter"'`. Sign in to the 1Password CLI and
270
+ replace the secret reference below with the one for your router key.
271
+
272
+ ```toml
273
+ model = "orcarouter/fusion"
274
+ model_provider = "orcarouter"
275
+
276
+ [model_providers.orcarouter]
277
+ name = "OrcaRouter"
278
+ base_url = "https://api.orcarouter.ai/v1"
279
+ wire_api = "responses"
280
+
281
+ [model_providers.orcarouter.auth]
282
+ command = "op"
283
+ args = ["read", "op://Private/OrcaRouter/credential"]
284
+ ```
285
+
286
+ This profile was tested up to the outgoing Responses request using a local service.
287
+
242
288
  For other providers, set their key and select a model the provider supports:
243
289
 
244
290
  ```bash
@@ -252,6 +298,88 @@ export CHEAPER_INFERENCE_API_KEY="<your-cheaper-inference-api-key>"
252
298
  codex-security scan . --provider cheaperinference --model gpt-5.4
253
299
  ```
254
300
 
301
+ For Opper, save this profile in `$CODEX_HOME/opper.config.toml`
302
+ (default `~/.codex/opper.config.toml`). Opper requires `web_search = "disabled"`.
303
+
304
+ ```toml
305
+ model_provider = "opper"
306
+ model = "anthropic/claude-sonnet-4-6"
307
+ web_search = "disabled"
308
+
309
+ [model_providers.opper]
310
+ name = "Opper"
311
+ base_url = "https://api.opper.ai/v3/compat"
312
+ wire_api = "responses"
313
+ env_key = "OPPER_API_KEY"
314
+ ```
315
+
316
+ Set `OPPER_API_KEY` in your environment and run
317
+ `codex-security scan . --codex 'profile="opper"'`. Choose a model that supports
318
+ tool calling and streaming. Verification covered profile loading and a request to
319
+ a local Responses endpoint.
320
+ See [Opper's Codex setup guide](https://docs.opper.ai/integrations/coding-agents/codex).
321
+
322
+ ### xAI Responses API through a local gateway
323
+
324
+ Codex 0.167.0 sends collaboration and Codex Security MCP tools as `namespace`
325
+ declarations. A direct scan against xAI can pass `--dry-run` and then fail with
326
+ HTTP 422 on the first model request. CLIProxyAPI's xAI adapter exposes each
327
+ namespace member to xAI as a plain function and restores the namespace when
328
+ Codex receives a tool call. Both connections use the Responses API.
329
+ [Direct xAI provider support](https://github.com/openai/codex-security/issues/2412)
330
+
331
+ Install CLIProxyAPI v8.0.59 and save this gateway config outside the scanned
332
+ repository in a file readable only by the gateway user. Replace the placeholders
333
+ with a private client key of your choice and your xAI API key.
334
+ [CLIProxyAPI release](https://github.com/router-for-me/CLIProxyAPI/releases/tag/v8.0.59)
335
+
336
+ ```yaml
337
+ config-version: 8
338
+ server:
339
+ host: "127.0.0.1"
340
+ port: 8317
341
+ access:
342
+ api-keys: ["<gateway-client-key>"]
343
+ api-keys:
344
+ xai:
345
+ - name: scan
346
+ base-url: "https://api.x.ai/v1"
347
+ models:
348
+ - name: "grok-4.7"
349
+ keys:
350
+ - api-key: "<xai-api-key>"
351
+ oauth:
352
+ auth-dir: "~/.cli-proxy-api-xai"
353
+ ```
354
+
355
+ Start the gateway in one shell.
356
+
357
+ ```bash
358
+ cli-proxy-api -config /path/to/private/config.yaml -local-model
359
+ ```
360
+
361
+ In a second shell on the same machine or in the same container, set
362
+ `CODEX_API_KEY` to the client key from `access.api-keys` and run the scan.
363
+
364
+ ```bash
365
+ codex-security scan . --auth api-key --model grok-4.7 --effort low \
366
+ --codex "model_provider='xai'" \
367
+ --codex "model_providers.xai.name='xAI'" \
368
+ --codex "model_providers.xai.base_url='http://127.0.0.1:8317/v1'" \
369
+ --codex "model_providers.xai.wire_api='responses'" \
370
+ --codex "model_providers.xai.env_key='CODEX_API_KEY'" \
371
+ --codex 'features.multi_agent_v2.max_concurrent_threads_per_session=1'
372
+ ```
373
+
374
+ The one-thread setting keeps Standard scans from spawning subagents. Without it,
375
+ the gateway can forward a subagent's `agent_message` on a later request, which
376
+ xAI rejects with HTTP 422. A contributor completed a live Standard scan with
377
+ this setting. Deep Scan workers have separate concurrency settings and remain
378
+ unverified with this gateway.
379
+
380
+ The SDK has no built-in price for `grok-4.7`, so it rejects `--max-cost` for this
381
+ model before starting a scan.
382
+
255
383
  ### Hugging Face compatibility
256
384
 
257
385
  In compatibility testing, Codex 0.166.0 sent its scan-completion tool inside a
@@ -384,11 +512,11 @@ Add context with `--knowledge-base`:
384
512
  codex-security policy . --knowledge-base architecture.md
385
513
  ```
386
514
 
387
- | Invocation | Result |
388
- | ---------------------------- | -------------------------------------------------------- |
389
- | `policy . --headless --json` | Generate without prompts; return paths and review notes. |
390
- | `policy . --format md` | Generate and write the draft to stdout. |
391
- | `policy . --dry-run --json` | Check local inputs without calling Codex. |
515
+ | Invocation | Result |
516
+ | --------------------------- | -------------------------------------------------------- |
517
+ | `policy . --json` | Generate without prompts; return paths and review notes. |
518
+ | `policy . --format md` | Generate and write the draft to stdout. |
519
+ | `policy . --dry-run --json` | Check local inputs without calling Codex. |
392
520
 
393
521
  `--headless` leaves unanswered questions in the review notes. By default, files
394
522
  go in the Codex Security state directory. To choose a location, use an empty
@@ -483,17 +611,29 @@ callback, questions remain unresolved.
483
611
  ```bash
484
612
  codex-security scan .
485
613
  codex-security scan . --path src --path tests
614
+ codex-security scan . --exclude-path examples/
486
615
  codex-security scan . --diff origin/main --json
487
616
  codex-security scan . --working-tree
488
617
  codex-security scan . --owner-suggestions
489
618
  codex-security scan . --output-dir /path/outside/repository/results --dry-run
490
619
  ```
491
620
 
492
- `--path` selects files or directories. The scan summary and saved scan details
621
+ `--path` selects files or directories. Repeat `--exclude-path` to exclude literal
622
+ repository-relative files or directories, including all descendants of a directory.
623
+ Exclusions take precedence over `--path`, also apply to diff and Deep scans, and
624
+ default to none. For persistent exclusions, set `scan.exclude_paths` in a selected
625
+ project config. CLI exclusions replace that configured list. Excluded files remain
626
+ readable as context, but findings whose locations are all excluded are removed
627
+ from scan results.
628
+ The scan summary and saved scan details
493
629
  show requested paths and exclusions. `coverage.deferred` records unfinished
494
630
  requested work separately from optional `coverage.openQuestions` follow-up.
495
631
  Human-readable output quotes ambiguous paths, while JSON retains their original strings.
496
632
 
633
+ A dry run reports `stateDirectory`, the root for saved scan state. It checks the
634
+ storage location without creating a scan directory. Pass boolean scan options
635
+ as bare flags or use lowercase `=true` or `=false`.
636
+
497
637
  When a cost limit is configured, `scan --dry-run` shows the resolved
498
638
  `maxCostUsd` and a `costLimitNote` explaining how the scan measures usage
499
639
  against the limit and why in-flight requests can exceed it.
@@ -509,7 +649,8 @@ be clean and at the commit recorded by the parent.
509
649
  Committed-diff scans require a clean, full checkout at the requested head
510
650
  revision, including when using `--validate`. A different checkout revision or
511
651
  local changes are rejected before scanning; check out the requested head and
512
- commit or stash local changes before retrying.
652
+ commit or stash local changes before retrying. The check also verifies tracked
653
+ files marked `assume-unchanged` and preserves their Git index flags.
513
654
 
514
655
  `--owner-suggestions` writes optional `owner-suggestions.json` after a completed
515
656
  committed Git scan, using the same checkout, model, and reasoning effort. Owner
@@ -524,7 +665,9 @@ Use the separate `suggest-owners` command for explicit owner-only jobs.
524
665
  Repeat `--knowledge-base PATH` for context: UTF-8 text files (including JSON and
525
666
  SARIF), PDF, DOCX, or directories. Directory traversal skips other binary files;
526
667
  explicit unsupported binary files are rejected. Bulk scans share this context
527
- with every repository.
668
+ with every repository. Select external documents directly. Links in a checkout
669
+ must stay inside it. For bulk scans with bare or separate Git storage, use
670
+ canonical paths for shared documents and prompt files.
528
671
 
529
672
  Use `--output-dir DIR` to choose where a scan saves its results. The directory
530
673
  must be empty and outside the scanned directory and enclosing Git worktree.
@@ -538,7 +681,9 @@ through inheritance. Other users must not have permission to set reparse data
538
681
  on the destination directory itself.
539
682
  `--archive-existing` moves earlier output to a sibling directory with a unique
540
683
  suffix, such as `results.previous-ab12cd34` for an output directory named
541
- `results`. Use `--dry-run` to preview the move.
684
+ `results`. If adding the suffix exceeds the filesystem's filename limit on POSIX,
685
+ the archive uses a short sibling name starting with `.previous-` and a hash of the
686
+ original filename. Use `--dry-run` to preview the move.
542
687
 
543
688
  Scans also attempt to write SARIF to `<scan-dir>/exports/results.sarif`. If that
544
689
  optional export fails, the scan can still complete. Use the
@@ -595,8 +740,13 @@ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an importe
595
740
  scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
596
741
  on stderr without `--full-output`, or when retained results are unavailable.
597
742
 
598
- Diagnostics stay on stderr. Each command's `--schema --format json` describes
599
- its successful output and failure codes.
743
+ Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
744
+ envelope with `error.code` and `error.message`. Command schema validation errors
745
+ with JSON or JSONL retain their field details and name missing or invalid
746
+ options by their CLI flags. Diagnostics stay on stderr.
747
+ `scan --schema --format json` describes optional caller inputs before defaults
748
+ and the fields returned by preflight, completed scans, and execution failures,
749
+ including sealed results recovered after an interruption.
600
750
  See [Exports and CI](#exports-and-ci) for exit codes and CI examples.
601
751
 
602
752
  ### Follow-up finding validation
@@ -685,8 +835,8 @@ Choose the next step from the recorded reason:
685
835
  start a new scan with the intended scope, including for plugin scans without
686
836
  a recipe. Retained findings can still be reviewed, but absence of findings
687
837
  from a stopped run is inconclusive.
688
- - **A Deep Scan was interrupted and is still recorded as `running`:** it may
689
- support [resume](#resuming-an-interrupted-deep-scan) with the original checkout,
838
+ - **A Standard or Deep Scan was interrupted and is still recorded as `running`:** it may
839
+ support [resume](#resuming-an-interrupted-scan) with the original checkout,
690
840
  artifacts, and session. Completed, failed, and canceled scans cannot resume.
691
841
 
692
842
  For example, after identifying an omitted API directory:
@@ -731,16 +881,18 @@ from the config directory; scope paths resolve from the repository.
731
881
  ### Import findings as a saved scan
732
882
 
733
883
  ```bash
734
- codex-security scan import --csv /path/to/findings.csv
735
- codex-security scan import --json /path/to/findings.json --format json
736
- codex-security scan import --csv /path/to/findings.csv --dry-run
884
+ codex-security scan import /path/to/findings.csv
885
+ codex-security scan import /path/to/findings.json --json
886
+ codex-security scan import /path/to/report --input-format csv --dry-run
737
887
  ```
738
888
 
739
889
  Supply exactly one input. CSV follows the
740
890
  [findings template](https://github.com/openai/codex-security/blob/main/examples/findings.csv).
741
891
  JSON accepts a complete `codex-security.findings` document or
742
- `{ "findings": [...] }` matching the findings schema. For this command, `--json`
743
- selects the input file; use `--format json` for JSON output. The input must be a
892
+ `{ "findings": [...] }` matching the findings schema. The CLI infers the format from a `.csv` or `.json` suffix.
893
+ Use `--input-format csv|json` to override it. Put `--json` after the filename
894
+ to request JSON output. Existing scripts using `--csv FILE` or `--json FILE`
895
+ can continue to select the input that way. The input must be a
744
896
  regular file with no symlinks or directory junctions in its path.
745
897
 
746
898
  Each import creates a completed scan in local history, retains the input under
@@ -821,6 +973,13 @@ codex-security scan-components . \
821
973
  --output-dir /path/outside/project/results
822
974
  ```
823
975
 
976
+ `--plan-only` with `--component` or `--components-file` validates local paths
977
+ without signing in. The CLI prints a command to scan the saved plan into a fresh
978
+ `results` directory inside the plan directory. Running that command starts scans.
979
+ Run it from the original working directory to reuse relative paths. The command
980
+ includes the selected project configuration and scan flags. Reapply any inline
981
+ `--codex` overrides yourself, since these can contain credentials.
982
+
824
983
  Plans use literal repository-relative paths, so `~/src` selects a directory
825
984
  named `~` inside the repository rather than expanding the home directory.
826
985
  Existing absolute paths inside the repository are also accepted.
@@ -850,9 +1009,15 @@ failed matching return `2`; severity-policy violations return `1`. Retry with
850
1009
  The retry report covers only those components. Each registered component keeps its
851
1010
  scan ID in the summary, including when the scan fails.
852
1011
 
853
- `--max-cost` applies per component, excluding planning and matching. `--model`
854
- and `--effort` also apply to matching; `--auth` applies throughout. Planning and
855
- matching reject ambient command providers that conflict with explicit ChatGPT
1012
+ `--max-cost` applies per component, excluding planning and matching.
1013
+ Use `--max-total-cost USD` with explicit components to split one estimated
1014
+ budget among them. The smaller of each component's share and its per-scan
1015
+ limit applies. Findings stay separate because model-based matching is skipped.
1016
+ The total limit also skips owner suggestions, including when enabled in project configuration.
1017
+ Automatic planning and post-scan prompts must run separately.
1018
+
1019
+ `--model` and `--effort` also apply to matching. `--auth` applies throughout.
1020
+ Planning and matching reject ambient command providers that conflict with explicit ChatGPT
856
1021
  or API-key auth. SDK-selected command providers retain their authentication.
857
1022
 
858
1023
  From TypeScript, use `runComponentScans({ repository, outputDir, components })`.
@@ -877,6 +1042,7 @@ opted in. The SDK accepts `rubricPath` or a `severityRubric` snapshot with
877
1042
  `markdown`, a positive integer `revision`, and the SHA-256 of the exact UTF-8
878
1043
  Markdown. A supplied snapshot takes precedence over a file.
879
1044
 
1045
+ A dry run reads and validates an explicit rubric before reporting a successful preflight.
880
1046
  The scan saves the rubric text in its local launch recipe. Retrying a Standard
881
1047
  scan with the same `--workflow-id`, resuming a Deep scan, or rerunning a scan
882
1048
  with a saved rubric reuses that copy even if the remote default or file changes.
@@ -901,7 +1067,7 @@ behavior are unchanged.
901
1067
 
902
1068
  The SDK setting is `maxTimeMinutes`; project files use `scan.max_time_minutes`.
903
1069
  Each launched scan or rerun gets its own allowance after setup, and reconnects
904
- do not reset it. Standard scans still do not support resume. For batch and
1070
+ do not reset it. [Resumed Standard scans](#resuming-an-interrupted-scan) keep the original deadline. For batch and
905
1071
  component scans, the project setting applies separately to each scan attempt,
906
1072
  not to planning, result matching, or the total campaign.
907
1073
 
@@ -925,7 +1091,7 @@ completed scans that added no findings. `--max-discovery-runs` caps the total
925
1091
  number started, including failures. `--max-time` stops discovery and returns
926
1092
  the findings from completed scans.
927
1093
 
928
- For TypeScript, see the [SDK Deep Scan example](../README.md#configure-deep-scans).
1094
+ For TypeScript, see the [SDK Deep Scan example](sdk.md#configure-deep-scans).
929
1095
 
930
1096
  Use project-file `scan.deep` settings or legacy
931
1097
  `$CODEX_HOME/codex-security/config.toml` defaults. Counts must be positive except
@@ -981,7 +1147,9 @@ credentials, and workflow resume behavior.
981
1147
  For `dedupe --scan latest`, matching across worktrees or clones requires a Git
982
1148
  executable outside all saved scan targets. If a historical target includes the
983
1149
  available Git installation, use `codex-security dedupe --scan SCAN_ID` with an
984
- explicit saved scan ID. Exact-path `latest` lookup still works without Git.
1150
+ explicit saved scan ID. Exact-path `latest` lookup works without Git for non-Git
1151
+ scan targets; recorded Git generations require a trusted Git executable to verify
1152
+ that the checkout still owns its saved history.
985
1153
 
986
1154
  Repeat `--codex KEY=VALUE` for supported native settings. For example,
987
1155
  `--codex "model_reasoning_effort='high'"` passes the TOML string `high` in Bash,
@@ -1078,7 +1246,7 @@ client during the scan, or receiving a canceled hosted execution records
1078
1246
  Applications can choose how to collect and export these observations.
1079
1247
 
1080
1248
  For filesystem and approval behavior, see the
1081
- [local security model](../README.md#local-security-model).
1249
+ [local security model](sdk.md#local-security-model).
1082
1250
 
1083
1251
  ### Environment variables
1084
1252
 
@@ -1111,6 +1279,10 @@ Python lookup: `--python` on commands that expose interpreter selection or SDK
1111
1279
  `pythonPath`, then
1112
1280
  `PYTHON`, the managed runtime, and `python3` or `python` on `PATH` (`py` also
1113
1281
  works on Windows). `CODEX_SECURITY_STATE_DIR` overrides `CODEX_HOME` for storage.
1282
+ On POSIX, `CODEX_CLI_PATH` and `PYTHON` preserve trailing whitespace in an
1283
+ explicit path that selects an executable. Use an absolute path or a `./`
1284
+ prefix for filenames beginning or ending in whitespace. Bare command names
1285
+ are trimmed before lookup.
1114
1286
 
1115
1287
  ### Troubleshooting
1116
1288
 
@@ -1140,6 +1312,11 @@ and does not migrate existing credentials or reports.
1140
1312
  Sandbox startup errors include the native diagnostic followed by a command to
1141
1313
  reproduce it. Linux namespace and AppArmor guidance appears only on Linux.
1142
1314
 
1315
+ If Windows Application Control blocks `windows.node` while validating a scan
1316
+ output directory, look for the module's block event in Event Viewer under
1317
+ Applications and Services Logs → Microsoft → Windows → CodeIntegrity → Operational.
1318
+ [Microsoft's App Control event reference](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/operations/event-id-explanations)
1319
+
1143
1320
  On Windows, credential-home checks require trusted ownership and permissions
1144
1321
  through every ancestor, including the volume root. Codex Security can repair
1145
1322
  the credential home and its descendants; it does not change ancestor ownership
@@ -1219,8 +1396,9 @@ work is needed, the scan is preserved and you can run `scans match --all`.
1219
1396
 
1220
1397
  A scan with a cost limit requires complete token usage for its recorded scan,
1221
1398
  worker, and custom validation sessions before the SDK returns a completed result.
1222
- Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
1223
- `backports.zstd` installed in the selected Python environment.
1399
+ The workbench reads compressed `.jsonl.zst` sessions with `compression.zstd`
1400
+ (Python 3.14+) or `backports.zstd` when available. Otherwise it uses the
1401
+ Node.js decoder bundled with the plugin.
1224
1402
  Missing or unreadable usage fails budget verification. Without a limit, usage
1225
1403
  reporting remains best effort.
1226
1404
 
@@ -1314,7 +1492,8 @@ the campaign a joint source review across repositories. For that workflow, use
1314
1492
 
1315
1493
  Run `gh auth login`, then `codex-security bulk-scan` for interactive GitHub
1316
1494
  selection. It lists repositories pushed in the last 90 days, excluding forks
1317
- and archives, asks for output, and saves the selection as `repositories.csv`.
1495
+ and archives, asks where to save results, and saves the selection as `repositories.csv`.
1496
+ Pass `--output-dir DIR` to set the initial answer in the wizard.
1318
1497
  Private checkouts use your GitHub CLI login.
1319
1498
 
1320
1499
  For CI, provide CSV with `id`, `repository`, and a full commit `revision`.
@@ -1330,7 +1509,32 @@ codex-security bulk-scan repositories.csv \
1330
1509
  --output-dir /path/outside/repositories/results --workers 4
1331
1510
  ```
1332
1511
 
1512
+ `--max-cost USD` applies per repository attempt. `--max-total-cost USD` divides an
1513
+ estimated limit among the pending repositories and their possible attempts for
1514
+ this invocation, including recovery. For example, a $12 limit with three pending
1515
+ repositories and `--max-attempts 2` reserves up to $2 per attempt. An earlier
1516
+ overrun reduces the remaining budget for queued attempts. In-flight work can
1517
+ exceed a limit. The total limit skips model-based matching and owner suggestions,
1518
+ including during recovery. Run post-scan prompts separately. A resumed scan also respects its saved
1519
+ limit and includes prior recorded usage in its cost estimate.
1520
+
1333
1521
  Bulk scans use clean shallow checkouts and support repository/path scopes.
1522
+ Bulk checkout, scan, and recovery processes select host tools outside every local
1523
+ source and campaign checkout. Inventory uses an external ripgrep executable or
1524
+ the copy shipped with the selected Codex installation.
1525
+
1526
+ On POSIX, campaign processes and script-based inventory tools search readable
1527
+ tool directories. Launchers must be readable so their shebang interpreters can
1528
+ be checked. Use an absolute interpreter path for campaign scripts, including
1529
+ `#!/usr/bin/env sh`, because workers run in different directories. If a directory
1530
+ contains an ineligible executable, its other tools remain available through a
1531
+ temporary PATH. Scripts using the system `/bin/sh` or `/usr/bin/env` run from
1532
+ their installed location when the packaged dispatcher can start. Keep other
1533
+ prefix-sensitive tools, including Python virtual environments, in directories
1534
+ where every entry can be used. On Windows, the campaign omits a tool directory
1535
+ from the child PATH if its Git, ripgrep, or Node executable link passes through a
1536
+ selected source.
1537
+
1334
1538
  CSV scopes are literal paths relative to each checkout, including names such
1335
1539
  as `~/src`.
1336
1540
  Configured diff or working-tree scopes are rejected unless every affected row
@@ -1341,10 +1545,10 @@ Use `-c FILE` for shared settings; CSV mode/scope override file values.
1341
1545
  `--post-scan-prompt-file` runs a follow-up even after failure, but not after
1342
1546
  cancellation or a cost stop.
1343
1547
 
1344
- Concurrency defaults to four repositories. `--max-attempts` defaults to one
1345
- attempt per pending repository per invocation. Repeating the command continues
1346
- the campaign, skips completed results, and starts pending attempts. Occupied
1347
- attempt directories stop that repository and suggest `--recover`.
1548
+ By default, `bulk-scan` runs up to four repositories concurrently and tries each
1549
+ unfinished CSV row once per run. With `--max-attempts 2`, a row that fails
1550
+ attempts 1 and 2 gets up to two more attempts (3 and 4) on the next run.
1551
+ An occupied attempt directory stops that row and prompts for `--recover`.
1348
1552
  If an ordinary attempt finds its checkout path already occupied, it stops before
1349
1553
  fetching. Use `--recover` to scan in a fresh checkout, or inspect and move the
1350
1554
  existing checkout before an ordinary retry.
@@ -1361,6 +1565,12 @@ require a new output directory. Version 1 manifests also require a new directory
1361
1565
  because their original knowledge inputs and direct overrides cannot be verified.
1362
1566
  Worker and retry counts can change when resuming.
1363
1567
 
1568
+ On POSIX, local repository paths retain `..` components in the campaign manifest
1569
+ so distinct symlink traversals remain distinct sources. Older campaigns may have
1570
+ recorded a normalized absolute path instead. Use that recorded path to resume the
1571
+ previously selected source; it can differ from the physical target selected by
1572
+ the original traversal. Use a new output directory to scan the corrected target.
1573
+
1364
1574
  ### Recovering failed or interrupted bulk scans
1365
1575
 
1366
1576
  Use the original CSV, output directory, and options:
@@ -1381,7 +1591,7 @@ failed or interrupted attempt:
1381
1591
  revision, preserving old artifacts and checkouts.
1382
1592
 
1383
1593
  Each nonempty committed line in `results.jsonl` must be valid JSON with a string
1384
- task ID and a positive safe integer attempt number. If a line fails these checks,
1594
+ task ID from the manifest and a positive safe integer attempt number. For an invalid line,
1385
1595
  the command reports its line number and preserves the ledger. Restore a complete
1386
1596
  ledger backup that includes every committed attempt, or start a separate campaign
1387
1597
  in a new `--output-dir`. If a repository exhausts its attempt numbers, starting
@@ -1457,13 +1667,13 @@ Supply the validation prompt again when rerunning.
1457
1667
 
1458
1668
  Choose the command by what you want to keep. [Scanner guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) list the accepted vendor formats.
1459
1669
 
1460
- | Input and goal | Command | Service contacted | Where to find the result |
1461
- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1462
- | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1463
- | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1464
- | Collect upstream records to a file | `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1465
- | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1466
- | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1670
+ | Input and goal | Command | Service contacted | Where to find the result |
1671
+ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
1672
+ | Save vendor evidence for a checkout | `publish findings FILE --to local` | None | `findings imported PATH` lists unassessed local findings. |
1673
+ | Publish a supported vendor report | [`publish findings FILE --to cloud`](#publish-findings-to-cloud) | Codex Security Cloud | The receipt identifies the private inbox job or repository records. |
1674
+ | Collect upstream records to a file | `import continuum`, `import github`, `import github-advisories`, `import semgrep` or `import snyk` | Selected vendor | Redirect the complete `--format json` output to a private file, then preview it with `publish findings`. |
1675
+ | Collect live Sonar issues | [`import sonar --dry-run`](#import-sonarqube-cloud-issues) | SonarQube Cloud during collection | The `capture` field gives a private file path. Replay it to save locally or save locally and publish to Cloud. |
1676
+ | Save Codex Security findings CSV or JSON as a completed scan | [`scan import`](#import-findings-as-a-saved-scan) | None | `scans list --scan-root DIR --json` shows imports under the artifact root. |
1467
1677
 
1468
1678
  For `publish findings`, `--to` is required. With `--to local`, `--repository`
1469
1679
  takes a checkout path. Select the reader with `--provider` and give the source a stable `--source-key`.
@@ -1480,8 +1690,13 @@ codex-security publish findings /private/path/endor-findings.json --provider end
1480
1690
  After reviewing the findings and exclusions, rerun the command without
1481
1691
  `--dry-run` and confirm. [Save or publish and verify](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md#save-or-publish-and-verify).
1482
1692
 
1693
+ When you pass `--source-repository-url` to `publish findings`, the command warns
1694
+ on stderr to verify that every finding belongs to the repository you specify.
1695
+
1483
1696
  For Tenable One Code Repository findings, use `--provider tenable --to local` and set `--source-repository-url` to the checkout’s verified HTTPS remote. [Tenable export and import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/tenable.md)
1484
1697
 
1698
+ For CrowdStrike FCS CLI 4.x IaC reports, use `--provider crowdstrike --to local` and select the directory where FCS ran with `--repository`. It does not need to be a Git checkout, but each scanned file must be unchanged since the scan. Add `--source-repository-url` to record the repository; it must match a fetch remote when the directory is a Git checkout. A `git::https://` report names its repository, and a different `--source-repository-url` stops the import. [CrowdStrike import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/crowdstrike.md)
1699
+
1485
1700
  Local readback uses `findings imported [PATH]`. The path defaults to the current
1486
1701
  directory. Each imported record starts as `not_assessed`. Unknown revisions and
1487
1702
  locations stay unknown. Repository-scoped sources are checked against comparable
@@ -1512,9 +1727,36 @@ Use `--provider endor` for one Endor project and context. The
1512
1727
  [Endor Labs guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/endor.md) covers native Finding JSON,
1513
1728
  SARIF compatibility, and the local preview.
1514
1729
 
1730
+ ## Collect AWS Continuum issues
1731
+
1732
+ `import continuum ENVIRONMENT_ID --format json` writes one report to standard
1733
+ output after collecting every issue page and fetching each issue's linked
1734
+ findings, prevalidation signals (`EVIDENCE`), and validation results
1735
+ (`VALIDATION_EVIDENCE`). Install AWS CLI v2.38.5 or later outside the checkout.
1736
+ The command requires exactly one configured Git repository and records it in the
1737
+ report. It collects patches when Git is the only source.
1738
+ S3 sources are allowed alongside that repository.
1739
+ Collection covers the whole environment. Pass the short
1740
+ Continuum environment ID. Optional
1741
+ `--aws-profile PROFILE` and `--aws-region REGION` override the AWS CLI's
1742
+ credential and Region selection. Preview and import the report separately
1743
+ with `publish findings FILE --provider continuum`. Pass
1744
+ `--source-repository-url URL` when the report has no saved repository URL.
1745
+
1746
+ For one finding, its matching validation evidence, and its generated patches, add `--finding-id FINDING_ID` and
1747
+ `--source-root CHECKOUT` with the absolute checkout path. The CLI uses
1748
+ `GetEnvironment` to verify that the environment has exactly one Git repository
1749
+ and no S3 sources before including unnamed patches. Pass
1750
+ `--repository-name AWS_SOURCE_NAME` for other environments to keep patches
1751
+ with that exact AWS source name. Validation is matched by AWS finding ID. When a
1752
+ validation artifact has no per-finding breakdown, the CLI uses `GetCodeIssue` to
1753
+ check that the issue covers just the selected finding. This mode accepts the same AWS profile and
1754
+ Region overrides and writes the finding-based JSON format for `publish findings`.
1755
+ [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
1756
+
1515
1757
  ## Import SonarQube Cloud issues
1516
1758
 
1517
- `import sonar --dry-run` writes a private capture and returns its path. Preview
1759
+ `import sonar --dry-run` writes a private evidence copy for both live and saved inputs and returns its path. Preview
1518
1760
  that capture for the intended destination before confirming. A Cloud confirmation
1519
1761
  saves the issues locally and publishes them. Use `--full-output` with
1520
1762
  `--format json` or `--format jsonl` for a structured result.
@@ -1564,9 +1806,13 @@ Enterprise repository URL or its Cloud ID. Either works for retries. If
1564
1806
  several connectors share the URL, use the ID. You can import before the
1565
1807
  repository's first native scan.
1566
1808
 
1567
- Cloud requires a file-backed ChatGPT login. To use your regular Codex login,
1568
- set `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in
1569
- again with the ChatGPT account you want to use.
1809
+ Cloud requires a file-backed ChatGPT login. Codex Security signs in with the
1810
+ `cli_auth_credentials_store` set in your Codex `config.toml`
1811
+ (`~/.codex/config.toml`, or `$CODEX_HOME/config.toml`). Without it, the login
1812
+ can be saved in the system keyring. To publish, set
1813
+ `cli_auth_credentials_store = "file"` there, then run `codex-security login`
1814
+ with the ChatGPT account you want to use. `codex-security login status`
1815
+ checks the current sign-in without changing credential storage.
1570
1816
 
1571
1817
  ### Review the Cloud destination
1572
1818
 
@@ -1577,11 +1823,10 @@ Run the command with `--dry-run --format json`. Check `accountId`,
1577
1823
  - **Private findings inbox.** If the preview includes `privateImport`, the
1578
1824
  report goes to your inbox. The repository and connector identify the
1579
1825
  suggested assessment target. Check `format`, `bytes` and `sha256` in
1580
- `privateImport` to identify the upload. For an Endor Finding, an Endor
1581
- `list.objects` response or a Wiz vulnerability JSON export, the CLI can
1582
- send the original bytes when Cloud accepts the format and every record
1583
- matches your selection. Other inputs, including arrays of selected Endor
1584
- Findings, use `security.findings.v1`.
1826
+ `privateImport` to identify the upload. The CLI and SDK encode the reviewed
1827
+ occurrences as `security.findings.v1` when it fits. For Wiz and Endor, an
1828
+ inbox that requires native records or has a smaller upload limit can receive
1829
+ native records that reproduce the reviewed evidence.
1585
1830
  - **Repository publisher.** Check `repository.environment_id` in each entry
1586
1831
  of `requests`. The publisher checks the current source versions. Existing
1587
1832
  records keep their environment. New records use the repository's authorized
@@ -1610,10 +1855,10 @@ instructions. API requests always use the API root. The older
1610
1855
  ### Resume interrupted imports
1611
1856
 
1612
1857
  If the result includes `savedSubmission`, keep that checkpoint. Rerun the
1613
- original command with `--dry-run --format json` using the same input, account,
1858
+ original command with `--dry-run --format json` using the same build, input, account,
1614
1859
  destination, API endpoint and state directory. Check `cloudApiUrl`. If
1615
1860
  `resumed` is true, confirm to continue the saved submission. If it's false,
1616
- review the new submission before confirming.
1861
+ review the new submission before confirming. Finish older-format pending submissions with the client that created them. If a response was lost, check the inbox job or repository records before starting a fresh upload.
1617
1862
 
1618
1863
  - **Private inbox.** The CLI checks the report digest and reuses its saved
1619
1864
  request IDs. It can read an accepted job even if the deployment has since
@@ -1699,7 +1944,10 @@ The provider guide describes [package JSON and CSV](https://github.com/openai/co
1699
1944
 
1700
1945
  ### Publish completed scans
1701
1946
 
1702
- Preview selected completed scans before uploading:
1947
+ The public `publish scan --help` menu describes Linear and custom publication
1948
+ from saved scans. The CSV input below belongs to Cloud publication.
1949
+ The following workflow is available to installations with Cloud publication access.
1950
+ Preview selected completed scans locally before uploading them.
1703
1951
 
1704
1952
  ```bash
1705
1953
  codex-security publish scan --to cloud --dry-run --json
@@ -1713,12 +1961,15 @@ prefix of at least eight characters, or `latest` for the current repository.
1713
1961
  Local sealed artifacts are required. Dry runs need no login or network access.
1714
1962
 
1715
1963
  Uploads require ChatGPT credentials saved to a file. Set
1716
- `cli_auth_credentials_store = "file"` in Codex `config.toml`, then sign in again.
1717
- Cloud publication rejects automatic/keyring storage even when `auth.json` exists,
1718
- because that file may be stale or belong to another account.
1719
-
1720
- Use a positional scan directory or repeated `--scan-dir PATH` for artifacts
1721
- outside history. Each must contain one completed sealed scan, not a bulk-run
1964
+ `cli_auth_credentials_store = "file"` in Codex `config.toml`, then run
1965
+ `codex-security login` again. Login, scans and other commands use that setting
1966
+ for the Codex Security sign-in.
1967
+ A dedicated login using automatic storage can publish if Codex Security
1968
+ recorded the native file fallback. An unverified file can belong to another
1969
+ account, so Cloud publication requires an explicit file store for an ambient login.
1970
+
1971
+ Use `publish scan DIR --to cloud` for one directory outside history. For
1972
+ multiple directories, repeat `--scan-dir PATH`. Each must contain one completed sealed scan, not a bulk-run
1722
1973
  directory or `results.jsonl`. Do not mix directories with `--scan`.
1723
1974
  Cloud also accepts exported CSV:
1724
1975
 
@@ -1750,7 +2001,8 @@ Select one completed scan by ID, prefix, `latest`, or directory; omit the select
1750
2001
  for the picker. Live publication and `--skip-existing` require local history.
1751
2002
  A directory-only dry run does not.
1752
2003
 
1753
- `--linear-project PROJECT_ID` (`--project`) selects a project. Flags override
2004
+ `--linear-project PROJECT_ID` selects a project. Existing scripts using the deprecated
2005
+ `--project PROJECT_ID` spelling continue to work. Flags override
1754
2006
  `CODEX_SECURITY_LINEAR_TEAM` and `CODEX_SECURITY_LINEAR_PROJECT`. `--dry-run`
1755
2007
  previews titles offline; `--json` returns structured output.
1756
2008
 
@@ -1762,10 +2014,10 @@ Keys are omitted from saved results; diagnostic messages remain unchanged.
1762
2014
 
1763
2015
  ```bash
1764
2016
  codex-security publish check /path/to/completed-scan \
1765
- --to linear --linear-team TEAM_ID --json
2017
+ --linear-team TEAM_ID --json
1766
2018
  ```
1767
2019
 
1768
- `publish check` verifies artifacts and recorded publications. With an API key,
2020
+ `publish check` verifies scan artifacts and recorded Linear publications. With an API key,
1769
2021
  it also checks authentication and destination access. It does not test issue
1770
2022
  creation; connected-app access is reported as `not-checked`.
1771
2023
 
@@ -1809,6 +2061,7 @@ codex-security classify-severity --scan-dir /path/to/completed-scan --json
1809
2061
  ```
1810
2062
 
1811
2063
  For repository-free canonical records, use `classify-severity --records` (optionally with `--runs N`).
2064
+ A records host can opt in to the CLI’s structured diagnostic records on its existing JSON-RPC connection. See the [records diagnostic protocol](classify-severity-records.md#cli-diagnostic-records).
1812
2065
  The [records protocol](classify-severity-records.md) accepts immutable Markdown and
1813
2066
  report snapshots and delegates model execution to the host.
1814
2067
 
@@ -1824,7 +2077,9 @@ request. It sends the config name without findings or account identifiers.
1824
2077
  If the request fails, times out, or returns an invalid rubric, the built-in
1825
2078
  rubric is used. An explicit `--rubric` (SDK `rubricPath`) skips the lookup and
1826
2079
  uses your policy for every review. Rubrics and repeatable `--knowledge-base`
1827
- context accept text, PDF, DOCX, and directories.
2080
+ context accept text, PDF, DOCX, and directories. Select external documents directly.
2081
+ Links in the artifact directory or a saved checkout must stay inside their source.
2082
+ When `--scan` cannot verify the saved checkout, use the document's canonical path.
1828
2083
 
1829
2084
  Each finding is classified three times by default. `--runs N` accepts
1830
2085
  an integer from 1 through 10; SDK options use `classificationRuns` with the same
@@ -1866,15 +2121,17 @@ or effort. A successful
1866
2121
  run also writes `severity-classification.json`, but publication reads the database. Original findings and sealed artifacts remain
1867
2122
  unchanged.
1868
2123
 
1869
- Repeat `--finding-id ID` for a subset from the selected scan. Dedupe's
1870
- `uniqueFindingIds` can represent findings from another scan; replace an outside-scan
1871
- representative with a member of its `duplicateGroups` entry from this scan.
2124
+ Repeat `--finding-id ID` for a subset from the selected scan. Dedupe returns
2125
+ `scanRepresentativeFindingIds` for this selection, in the same order as its
2126
+ corpus-wide `uniqueFindingIds`.
1872
2127
  Linear publication defaults to saved classification selection, omits exclusions,
1873
2128
  and uses assessed severity for title and priority. Descriptions retain original
1874
2129
  severity and add the classification rationale. Publication rejects incomplete or
1875
2130
  stale assessments. It never reclassifies or rereads the rubric at publication time.
1876
2131
 
1877
2132
  ```bash
2133
+ # List the IDs you can pass to --finding-id.
2134
+ codex-security dedupe --scan SCAN_ID --json | jq -r '.scanRepresentativeFindingIds[]'
1878
2135
  codex-security classify-severity --scan SCAN_ID --rubric /path/to/policy.md \
1879
2136
  --finding-id FINDING_ID
1880
2137
  codex-security publish scan --scan SCAN_ID --to linear --linear-team TEAM_ID --dry-run
@@ -1889,46 +2146,32 @@ import {
1889
2146
  classifySeverity,
1890
2147
  classifyScanSeverity,
1891
2148
  classifyScanDirectorySeverity,
2149
+ deduplicateScanDirectory,
1892
2150
  publishScan,
1893
- type FindingsDocument,
1894
2151
  } from "@openai/codex-security";
1895
- import { readFile } from "node:fs/promises";
1896
- import { join } from "node:path";
1897
2152
 
1898
2153
  // Assess supplied reports in memory.
1899
- const classification = await classifySeverity(findings, {
2154
+ await classifySeverity(findings, {
1900
2155
  rubricPath: "/path/to/policy.md",
1901
2156
  knowledgeBasePaths: ["/path/to/context.md"],
1902
2157
  });
1903
2158
 
1904
2159
  // Save assessments for a scan ID or sealed directory.
1905
2160
  await classifyScanSeverity("SCAN_ID", { rubricPath: "/path/to/policy.md" });
1906
- const scanFindings = (
1907
- JSON.parse(
1908
- await readFile(join(scanDirectory, "findings.json"), "utf8"),
1909
- ) as FindingsDocument
1910
- ).findings;
1911
- const scanFindingIds = new Set(
1912
- scanFindings.map((finding) => finding.findingId),
1913
- );
1914
- // dedupeResult was produced by deduplicating this same scan.
1915
- const selectedIds = dedupeResult.uniqueFindingIds.map((representative) => {
1916
- if (scanFindingIds.has(representative)) return representative;
1917
- return dedupeResult.duplicateGroups
1918
- .find((group) => group.includes(representative))!
1919
- .find((member) => scanFindingIds.has(member))!;
2161
+ const dedupeResult = await deduplicateScanDirectory(scanDirectory, {
2162
+ repository: "/path/to/repository",
1920
2163
  });
1921
- await classifyScanDirectorySeverity(scanDirectory, {
2164
+ const classification = await classifyScanDirectorySeverity(scanDirectory, {
1922
2165
  rubricPath: "/path/to/policy.md",
1923
- findingIds: selectedIds,
2166
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1924
2167
  });
1925
2168
 
1926
- // Or supply an in-memory assessment directly to publication.
2169
+ // Preview Linear publication for those same findings using their assessments.
1927
2170
  await publishScan(scanDirectory, {
1928
2171
  destination: "linear",
1929
2172
  teamId: "TEAM_ID",
1930
2173
  classification,
1931
- findingIds: classification.assessments.map(({ findingId }) => findingId),
2174
+ findingIds: dedupeResult.scanRepresentativeFindingIds,
1932
2175
  dryRun: true,
1933
2176
  });
1934
2177
  ```
@@ -2035,24 +2278,41 @@ attach only their owner's session. Unrecorded earlier retry sessions may be abse
2035
2278
  ## Scan history and reruns
2036
2279
 
2037
2280
  Commands default to the current repository. IDs accept unique prefixes of at
2038
- least eight characters.
2039
-
2040
- | Command | Purpose |
2041
- | ----------------------------------------------------- | ---------------------------------------------------------- |
2042
- | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
2043
- | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
2044
- | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
2045
- | `scans resume SCAN_ID` | Continue an interrupted Deep Scan. |
2046
- | `scans rerun [SCAN_ID]` | Repeat on the current checkout. |
2047
- | `scans match BEFORE AFTER` | Link findings with the same root cause. |
2048
- | `scans match --all` | Match completed scans across worktrees/clones. |
2049
- | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2050
- | `findings list [REPOSITORY]` | List open findings. |
2051
- | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2052
- | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2053
-
2054
- Without an ID, `scans show` selects the latest completed scan, while `scans logs`
2055
- selects the latest scan of any status. After a successful scan followed by a
2281
+ least eight characters. Reading empty history leaves the workbench database uninitialized.
2282
+
2283
+ Linked Git worktrees share scans, findings, and reviewer decisions when their
2284
+ scans record the same repository generation in the selected state database.
2285
+ Older scans without this evidence remain target-local. Removed worktrees retain
2286
+ their recorded history; a reused checkout path does not inherit its previous
2287
+ owner's history. Separately verified clones can still be compared explicitly,
2288
+ but their finding histories remain separate.
2289
+
2290
+ Finding confirmation and automatic post-scan matching follow completion order
2291
+ in the workbench, without changing sealed report timestamps.
2292
+
2293
+ | Command | Purpose |
2294
+ | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
2295
+ | `scans list [REPOSITORY]` | List scans; `--scan-root DIR` filters artifact roots. |
2296
+ | `scans show [SCAN_ID]` | Show a scan; defaults to latest completed. |
2297
+ | `scans logs [SCAN_ID]` | Show session events; defaults to latest, including active. |
2298
+ | `scans resume SCAN_ID` | Continue an interrupted Standard or Deep Scan. |
2299
+ | `scans rerun [SCAN_ID]` | Rerun a saved recipe in its checkout. |
2300
+ | `scans match --all` | Match completed scans in this repository generation, including linked worktrees. |
2301
+ | `scans compare [BEFORE] [AFTER]` | Compare scans; defaults to latest two completed. |
2302
+ | `findings list [REPOSITORY]` | List open findings. |
2303
+ | `findings imported [REPOSITORY]` | Read locally imported, unassessed vendor evidence. |
2304
+ | `findings false-positive OCCURRENCE_ID --reason TEXT` | Dismiss a finding while the reason applies. |
2305
+
2306
+ In the terminal, `findings list` shows the occurrence ID for each open finding.
2307
+ Copy that ID into `findings false-positive` with your reason. Subsequent scans can
2308
+ use the explanation while it applies. In `scans show SCAN_ID --json`, each
2309
+ displayed occurrence has its saved rationale in `triage.note` after dismissal. The list identifies
2310
+ a repository with no saved scan history separately from one with zero open findings.
2311
+ From an unregistered Git subdirectory with no scan history of its own, it uses the worktree root.
2312
+
2313
+ With an omitted ID or the literal `latest`, `scans show` selects the latest completed scan, while `scans logs`
2314
+ selects the latest scan of any status. Both prefer a scan in the current
2315
+ worktree when one qualifies. After a successful scan followed by a
2056
2316
  failed or active scan, these defaults refer to different runs. Human output
2057
2317
  identifies the selected run, labels its saved update time, and gives matching
2058
2318
  commands with its full scan ID:
@@ -2070,7 +2330,10 @@ history. Inspect its saved status before choosing resume or rerun, and supply
2070
2330
  the original custom prompt files for reruns. Structured history and log output
2071
2331
  and command selection defaults are unchanged.
2072
2332
 
2073
- Reruns use the current checkout/context files and do not reload project files.
2333
+ Without an ID, rerun selects the latest completed scan in the current worktree.
2334
+ If only a related checkout has a completed scan, rerun shows its ID, path, and
2335
+ revision. Pass that ID to run the saved recipe using the files currently at its
2336
+ saved checkout and context paths. Reruns do not reload project files.
2074
2337
  The readable scan recipe records your authentication choice. A separate private
2075
2338
  replay profile stores explicit `openai_base_url`, `chatgpt_base_url`, and custom
2076
2339
  `model_providers` settings, including any credentials written directly in
@@ -2106,6 +2369,17 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
2106
2369
  writable, and outside the target repository. Session logs may contain sensitive
2107
2370
  data even though scan recipes do not store credentials.
2108
2371
 
2372
+ Keep the same state directory across linked worktrees. Changing it selects
2373
+ separate history, artifacts, and a dedicated Codex sign-in. `--scan-root`
2374
+ filters recorded artifact paths; it does not import another directory's scans.
2375
+
2376
+ The workbench records the outer checkout directory when it registers a target.
2377
+ A later nested checkout cannot make tools from that directory eligible for
2378
+ automatic discovery. When an older saved target lacks a recorded checkout
2379
+ directory, set `CODEX_SECURITY_GIT` to the absolute path of a trusted Git
2380
+ executable outside the checkouts. If you use a system Python instead of the
2381
+ Codex managed runtime, set `PYTHON` to the absolute path of your interpreter.
2382
+
2109
2383
  Saved scan logs retain the finishing turn, including its final response, and
2110
2384
  exclude later turns once the scan records a completion boundary. Older scans
2111
2385
  retain the full history of their attributed sessions and keep their existing
@@ -2117,19 +2391,42 @@ work on all supported Node.js versions, including logs, feedback attachments,
2117
2391
  usage accounting, and saved-session discovery for resume. A bundled decoder
2118
2392
  reads concatenated frames and reports truncated streams as collection errors.
2119
2393
 
2120
- ### Resuming an interrupted Deep Scan
2394
+ ### Resuming an interrupted scan
2121
2395
 
2122
2396
  ```bash
2123
2397
  codex-security scans list --scan-root /path/to/security-scans
2124
2398
  codex-security scans resume SCAN_ID
2125
2399
  ```
2126
2400
 
2401
+ The terminal list shows the full scan ID and labels the last activity of a
2402
+ `running` scan after 24 hours without an update. For a Standard or Deep Scan with a saved
2403
+ launch recipe and its original session, it also shows the resume command to use after interruption.
2404
+
2127
2405
  The scan must still be `running`, with its original checkout, output directory,
2128
2406
  and Codex session in the same state directory. Checkout identity, revision, and
2129
2407
  contents must match. Completed, failed, and canceled scans need a rerun instead.
2130
2408
 
2131
- Resume retains scan ID, completed workers, artifacts, accumulated cost, and saved
2132
- settings/instructions. Knowledge-bearing scans save their extracted documents in
2409
+ On Windows, keep the protected `.codex-security-resume` directory in the scan
2410
+ output. It lets the workbench verify the original output even before the first
2411
+ checkpoint. If an older scan stopped with an empty output, start a new scan with
2412
+ `codex-security scans rerun SCAN_ID`.
2413
+
2414
+ New Windows Standard and Deep Scans also record the checkout's native volume and file ID
2415
+ when the filesystem supplies them. Validation and remediation verify the same
2416
+ checkout identity. An older scan can resume across Python
2417
+ versions when its saved checkout identity can be verified. If the workbench
2418
+ cannot verify it, resume with the Python runtime that started the scan or use
2419
+ `codex-security scans rerun SCAN_ID` to start a new scan.
2420
+
2421
+ Resume keeps the scan ID, saved settings and instructions, completed workers, artifacts,
2422
+ and accumulated cost. A Standard scan continues in its original Codex session with
2423
+ the same `--max-cost` limit and `--max-time` deadline. Only one CLI or SDK call
2424
+ can run it at a time. If the connection fails after the session is saved, the CLI
2425
+ prints the resume command. Work since the last checkpoint may need to be repeated.
2426
+ Use `scans rerun` for canceled or failed scans, including authentication failures.
2427
+ For custom validation, rerun with the original validation instructions.
2428
+
2429
+ Knowledge-bearing scans save their extracted documents in
2133
2430
  the private `.scan-knowledge.json` continuation file beside the scan artifacts.
2134
2431
  Resume verifies and uses that snapshot even if the original files changed or were
2135
2432
  deleted. Preserve it with the scan directory; canonical reports do not embed its
@@ -2147,7 +2444,11 @@ to update campaign receipts. Individual resume does not update `results.jsonl`.
2147
2444
 
2148
2445
  ### Matching saved scans
2149
2446
 
2150
- Matching uses sealed artifacts and cached decisions unless `--force` is supplied.
2447
+ Use `scans compare BEFORE AFTER` to compare a pair. A cache miss can use the model
2448
+ and save its matching decisions. Pass `--force` to recompute saved matches.
2449
+ The older `scans match BEFORE AFTER` spelling is also supported.
2450
+ Use `scans match --all` to match completed scans in this repository generation, including linked worktrees.
2451
+ The SDK accepts matching plans with inline findings and asks compatible workbenches to send each scan’s findings once.
2151
2452
  Comparisons classify findings as new, persisting, reopened, not observed, resolved,
2152
2453
  or unknown. An absent finding in the later scope is not observed; absence alone
2153
2454
  does not verify remediation. A finding is resolved only after it was explicitly
@@ -2158,11 +2459,12 @@ One comparison ID is compared with the latest completed scan.
2158
2459
  codex-security scans match --all --force --model gpt-6.1-sol --effort high
2159
2460
  ```
2160
2461
 
2161
- When a saved Standard scan and a Deep scan have the same recorded target,
2162
- revision, and snapshot digest, matching flags findings that have different
2163
- anchors but share a unique rule, first displayed source range, and optional
2164
- instance. Matching preserves the case of saved paths. Codex can request the
2165
- saved evidence to distinguish separate causes at that site. Automatic matching
2462
+ Standard and Deep scans can identify matching candidates in a single target or
2463
+ corresponding paths in linked worktrees with the same saved repository
2464
+ generation. When the revision and snapshot digest agree, matching flags findings
2465
+ with different anchors that share a unique rule, first displayed source range,
2466
+ and optional instance. Matching preserves the case of saved paths. Codex can
2467
+ request the saved evidence to distinguish separate causes at that site. Automatic matching
2166
2468
  under a cost limit keeps its single comparison call.
2167
2469
 
2168
2470
  Only high-confidence root-cause matches are grouped. Uncertain and related
@@ -2214,6 +2516,10 @@ must already exist.
2214
2516
 
2215
2517
  SARIF is the default format, and `./results.sarif` is the default output path.
2216
2518
  Use `--export-format json` or `--export-format csv` to choose another format.
2519
+ An existing default output file is preserved. Pass `--output FILE` to choose
2520
+ a filename or explicitly replace it. Use `--output -` to pipe the complete
2521
+ artifact. Response filters, token controls, and `--full-output` require a
2522
+ command that returns a formatted response.
2217
2523
  To select a saved scan by its ID and export JSON, run:
2218
2524
 
2219
2525
  ```bash
@@ -2385,10 +2691,11 @@ codex-security install-hook /path/to/repository
2385
2691
 
2386
2692
  To migrate an existing generated hook, verify it is a regular file used only by
2387
2693
  this repository and contains only the generated commands. Rerun `install-hook`
2388
- with `--fail-on-severity` set to its original threshold. It recognizes the legacy
2389
- `npx` hook and supported earlier templates with matching absolute Node and CLI
2390
- paths. If it refuses to overwrite the verified hook, back it up, remove it and
2391
- reinstall with the same threshold. Restore the backup if installation fails.
2694
+ with the desired `--fail-on-severity` level to change the threshold. The installer
2695
+ recognizes the legacy `npx` hook and earlier generated templates with matching
2696
+ absolute Node and CLI paths. It refuses to replace a hand-edited hook.
2697
+ On POSIX, reinstalling a recognized hook restores its owner execute bit if Git
2698
+ could not execute it. The installer checks that the resulting hook is executable.
2392
2699
  The installer uses host Git for the selected repository and respects
2393
2700
  `core.hooksPath`.
2394
2701
 
@@ -2417,6 +2724,14 @@ codex-security patch --scan SCAN_ID --severity high --json
2417
2724
  codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
2418
2725
  ```
2419
2726
 
2727
+ For `validate`, `patch`, and `verify-fix`, an explicit local file URL such as
2728
+ `file:///home/reviewer/finding.md` (Windows: `file:///C:/reviews/finding.md`)
2729
+ requires the file to exist. A missing file stops the command before the model
2730
+ runs. Use `pathToFileURL(absolutePath).href` in Node to encode spaces and
2731
+ special characters correctly. Absolute paths and paths starting with `~/`, `./`, or `../`
2732
+ also require an existing file. Use `text:/path is exposed` to pass path-shaped
2733
+ prose verbatim, or `text:text:example` for a finding that starts with `text:`.
2734
+
2420
2735
  Context inputs are optional and can be combined:
2421
2736
 
2422
2737
  - `--context TEXT` adds inline security context or reviewer feedback.
@@ -2424,6 +2739,7 @@ Context inputs are optional and can be combined:
2424
2739
  - Repeat `--knowledge-base PATH` to add files or directories. It uses the scan
2425
2740
  document loader: UTF-8 text (including JSON and YAML), PDF, and DOCX. Directories
2426
2741
  are searched recursively; binary files, symlinks, and Git metadata are skipped.
2742
+ When validating from a Git checkout, select external documents directly.
2427
2743
 
2428
2744
  Inline and file context are included in the prompt. Knowledge-base documents are
2429
2745
  prepared in a temporary directory for Codex to read during the assessment, then
@@ -2574,7 +2890,10 @@ This explicit option disables Codex filesystem/network enforcement for the patch
2574
2890
  task. The container must provide it. There is no automatic fallback; optional
2575
2891
  patch-risk assessment still uses its read-only sandbox.
2576
2892
 
2577
- `scan --patch` runs after a complete scan. `--patch-severity` defaults to `low`;
2893
+ `scan --patch` runs after a complete scan without a cost limit. A cost-limited
2894
+ scan saves the findings and skips the interactive patch offer. Use
2895
+ `codex-security patch --scan SCAN_ID` to patch separately.
2896
+ `--patch-severity` defaults to `low`;
2578
2897
  `high` selects high and critical findings. Interactive users can select findings
2579
2898
  and add instructions. The interactive finding browser lists critical, high,
2580
2899
  medium, then low findings, preserving scan order within each severity.
@@ -2641,7 +2960,10 @@ SDK's local `validate()` and `patch()` methods use the same fallback.
2641
2960
  for `patch`. Omit it or use `--verification-mode standard` for the default checks.
2642
2961
 
2643
2962
  Results include evidence and `fixed`, `still_vulnerable`, or `inconclusive` status.
2644
- `--json` returns structured output. Exit codes are `0` when all findings are
2963
+ Without output options, each finding prints a verdict and its evidence.
2964
+ Explicit output formats, field selection and token controls operate on the
2965
+ structured result containing `repository`, optional `scanId`, and `results`.
2966
+ Exit codes are `0` when all findings are
2645
2967
  fixed, `1` when any remain vulnerable, and `2` for inconclusive/failed checks.
2646
2968
  With `--json` or `--format jsonl`, authentication and execution failures return
2647
2969
  `status: "failed"`, `code: "VERIFICATION_FAILED"`, and `message`. With
@@ -2654,21 +2976,112 @@ retain exit codes `130` and `143` without a result.
2654
2976
 
2655
2977
  ## Command discovery and integrations
2656
2978
 
2657
- Use `--llms` for the command manifest, `scan --schema --format json` for its
2658
- schema, and `completions bash|zsh|fish` for shell completions. Scan output supports
2979
+ Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
2980
+
2981
+ Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
2659
2982
  `--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
2660
2983
  `--filter-output`, `--token-limit`, and `--token-offset` options accept either
2661
2984
  `--option value` or `--option=value`.
2662
2985
 
2986
+ `--token-limit` and `--token-offset` take nonnegative integers and select a
2987
+ text view of the formatted result. Truncated JSON and JSONL views are returned
2988
+ as a JSON string containing the excerpt and its token range. With
2989
+ `--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
2990
+ the next page when more tokens are available. `--token-count` returns the
2991
+ estimated size instead. A failed full-output JSON or JSONL response always
2992
+ retains its error code and message. If the failure carries result data,
2993
+ `--token-count` reports its size in `meta.tokenCount`.
2994
+
2663
2995
  `skills add` syncs generated CLI command guidance; it does not install the full
2664
2996
  Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
2665
2997
  only read-only `info` because the transport cannot cancel scans. For the plugin's
2666
2998
  scan, triage, patch, and verification workflows, see the
2667
2999
  [agent workflow guide](https://github.com/openai/codex-security/blob/main/docs/agent-workflows.md).
2668
3000
 
3001
+ Both installers default to `--scope user`. Use `--scope project` for the current
3002
+ directory. Existing scripts can continue using `--no-global` for project scope.
3003
+ Inspect either command with `--help`, `--schema`, or `--version` before installing.
3004
+
3005
+ `skills add --depth 0` creates a single skill. The default depth of 1 groups
3006
+ guidance by top-level command. To check the installed files, use the same
3007
+ depth with `skills list`, for example `skills list --depth 0 --json`. Each
3008
+ entry includes its canonical `SKILL.md` locations in the current project and
3009
+ user profile.
3010
+
3011
+ `mcp add` registers detected compatible clients. If it finds none in the
3012
+ selected scope, choose a client with `--agent NAME` (repeatable), or register
3013
+ every compatible client with `--all`. For example, `mcp add --scope project
3014
+ --agent cursor` writes Cursor's project configuration. In user scope, Codex
3015
+ detection and registration use `CODEX_HOME` when set. Amp supports user
3016
+ registration only.
3017
+
3018
+ The default launcher runs `npx --yes @openai/codex-security --mcp`. To register
3019
+ an installed executable, use its name or path with `--exec` and repeat
3020
+ `--arg=VALUE` for each argument. Each value is stored literally, including
3021
+ spaces, empty arguments, and leading dashes. To run an npm package, select
3022
+ `--package NAME`. The existing `--command` accepts a command line or HTTP(S)
3023
+ URL. Quotes group command-line words, and backslashes are literal. A bare
3024
+ executable name is stored directly. Use `--exec` for a path with
3025
+ spaces, including when the executable will be installed on another machine.
3026
+
3027
+ ```bash
3028
+ codex-security mcp add --agent cursor --exec "/opt/My Tools/server" --arg=--mcp
3029
+ codex-security mcp add --agent cursor --package @openai/codex-security --arg=--mcp
3030
+ ```
3031
+
3032
+ `mcp doctor` checks the current CLI's server startup and tool catalog. To
3033
+ verify a registered launcher, connect from the client where it was registered.
3034
+
2669
3035
  For local findings storage, deduplication, and custom endpoints, see the
2670
3036
  [findings guide](findings-service.md).
2671
3037
 
3038
+ ### Shell completions
3039
+
3040
+ The generated scripts register both `codex-security` and `cs`. Choose your shell
3041
+ and open a new session after saving the setup.
3042
+
3043
+ **Bash.** Add this to `~/.bashrc` with Bash 4.4 or later:
3044
+
3045
+ ```bash
3046
+ source <(codex-security completions bash)
3047
+ ```
3048
+
3049
+ **Zsh.** In `~/.zshrc`, load the generated script after your completion system
3050
+ calls `compinit`. If you initialize completions yourself, use:
3051
+
3052
+ ```zsh
3053
+ autoload -Uz compinit
3054
+ compinit
3055
+ source <(codex-security completions zsh)
3056
+ ```
3057
+
3058
+ **Fish.** Add this line to `~/.config/fish/config.fish`:
3059
+
3060
+ ```fish
3061
+ codex-security completions fish | source
3062
+ ```
3063
+
3064
+ **Nushell.** Save the generated closures alongside `config.nu`:
3065
+
3066
+ ```nu
3067
+ codex-security completions nushell | save --force ($nu.default-config-dir | path join codex-security-completions.nu)
3068
+ ```
3069
+
3070
+ In `config.nu`, source the file and dispatch the two names to their completers:
3071
+
3072
+ ```nu
3073
+ source codex-security-completions.nu
3074
+ let previous_completer = $env.config.completions.external.completer?
3075
+ $env.config.completions.external.enable = true
3076
+ $env.config.completions.external.completer = {|spans|
3077
+ match $spans.0 {
3078
+ "codex-security" => { do $_incur_complete_codex_security $spans }
3079
+ "cs" => { do $_incur_complete_cs $spans }
3080
+ _ => { if $previous_completer != null { do $previous_completer $spans } }
3081
+ }
3082
+ }
3083
+ ```
3084
+
2672
3085
  ### Hosted Standard scan
2673
3086
 
2674
3087
  `codex-security scan --host` runs one versioned JSON-RPC invocation with an explicit host executor. Use it alone; it never performs local inference. See [the hosted scan protocol](hosted-scans.md) for input, filesystem, artifact, usage, and cancellation requirements.