@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/sdk.md ADDED
@@ -0,0 +1,918 @@
1
+ # Codex Security SDK guide
2
+
3
+ Run Codex Security from TypeScript or the command line to find, validate, and fix
4
+ security vulnerabilities in your code. The package includes the Codex runtime,
5
+ security plugin, and TypeScript declarations. It uses ES modules.
6
+
7
+ - Scan repositories, selected paths, or Git changes. Deep scans repeat Standard
8
+ scans of the selected scope and merge their findings after each batch.
9
+ - Validate findings, generate patches, and verify existing fixes.
10
+ - Draft security policies and retain threat models.
11
+ - Review saved findings, identify duplicates, classify severity, and suggest owners.
12
+ - Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
13
+ findings to Linear or a findings service.
14
+ - Import saved scanner reports locally or publish them to Codex Security Cloud.
15
+ See the [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) for supported vendors and formats.
16
+ - Automate scans across repositories and project components.
17
+
18
+ See the [CLI reference](cli.md),
19
+ [findings guide](findings-service.md), or
20
+ [online documentation](https://learn.chatgpt.com/docs/security) for setup and examples.
21
+
22
+ Before version `1.0.0`, minor releases may change the public API.
23
+
24
+ ## Install
25
+
26
+ Supported runtimes:
27
+
28
+ - Node.js 22.13.0+ within 22.x, or Node.js 24.x or 26.x, on macOS, Linux, or Windows.
29
+ - Python 3.10+ for scans, policy generation, exports, scan history, and saved
30
+ findings. Python 3.10 also needs `tomli`.
31
+
32
+ Compressed Codex session logs (`.jsonl.zst`) are readable on all supported Node.js
33
+ versions. The bundled streaming decoder reads concatenated frames and reports
34
+ truncated streams as collection errors.
35
+
36
+ ### Install the CLI
37
+
38
+ Install the CLI globally:
39
+
40
+ ```bash
41
+ npm install --global @openai/codex-security
42
+ cs --version
43
+ ```
44
+
45
+ Continue with the [CLI walkthrough](#cli). You can use the full command
46
+ `codex-security` if `cs` names another tool on your PATH. If installation
47
+ fails with `EEXIST`, use `npx @openai/codex-security` in place of `cs`.
48
+
49
+ ### Install the TypeScript SDK
50
+
51
+ Install the package locally in your TypeScript project:
52
+
53
+ ```bash
54
+ npm install @openai/codex-security
55
+ ```
56
+
57
+ ## Authentication
58
+
59
+ Sign in with ChatGPT:
60
+
61
+ ```bash
62
+ cs login
63
+ ```
64
+
65
+ If you installed only the SDK locally, sign in from your project directory:
66
+
67
+ ```bash
68
+ npx @openai/codex-security login
69
+ ```
70
+
71
+ In the following CLI examples, replace `cs` with `npx @openai/codex-security`
72
+ when using a local SDK installation, including the API-key login example below.
73
+
74
+ For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.
75
+ These keys apply to the current command without replacing your saved login.
76
+ To save an API key instead, pass it on stdin:
77
+
78
+ ```bash
79
+ printenv OPENAI_API_KEY | cs login --with-api-key
80
+ ```
81
+
82
+ SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,
83
+ prefers `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
84
+ Use `"chatgpt"` to ignore environment API keys. The CLI uses the same `--auth`
85
+ values and prompts in an interactive terminal when both credential types are available.
86
+
87
+ Some cybersecurity requests and protected findings require
88
+ [Trusted Access for Cyber](https://chatgpt.com/cyber) approval. See the
89
+ [authentication reference](cli.md#authentication) for providers, stored
90
+ credentials, and Cyber access program selection.
91
+
92
+ ### Remote login with SSH forwarding
93
+
94
+ On a remote or headless machine, try `login --device-auth` if your workspace
95
+ allows it. Otherwise, open an SSH tunnel from your local machine:
96
+
97
+ ```bash
98
+ ssh -L 1455:localhost:1455 user@remote-host
99
+ ```
100
+
101
+ Run `cs login` in that SSH session, then open its sign-in
102
+ URL in your local browser. Keep SSH connected until login finishes.
103
+
104
+ ### Amazon Bedrock
105
+
106
+ Bedrock scans use AWS credentials and model access. They do not require
107
+ `codex-security login` or an OpenAI API key. See the
108
+ [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
109
+ for setup, model selection, and verification.
110
+
111
+ ## Run a scan from TypeScript
112
+
113
+ Scan a repository you own or have permission to assess:
114
+
115
+ ```ts
116
+ import { CodexSecurity } from "@openai/codex-security";
117
+
118
+ const security = new CodexSecurity();
119
+
120
+ try {
121
+ const result = await security.run("/path/to/repository");
122
+
123
+ console.log(result.reportPath);
124
+ console.log(result.findings.findings);
125
+
126
+ if (result.hasFindingsAtOrAbove("high")) {
127
+ process.exitCode = 1;
128
+ }
129
+ } finally {
130
+ await security.close();
131
+ }
132
+ ```
133
+
134
+ Omitting `outputDir` saves results in the private Codex Security state directory.
135
+ To choose another location, use a new or empty directory outside the scanned
136
+ repository and its enclosing Git worktree. Existing output directories keep their
137
+ permissions; newly created directories are private to you by default.
138
+
139
+ ### Read results
140
+
141
+ | Result | Contents |
142
+ | --------------------------------- | ---------------------------------------------------------------- |
143
+ | `findings.findings` | Findings from this scan. |
144
+ | `reportPath` | Path to the Markdown report. |
145
+ | `review.excludedPaths` | Additional paths the scan excluded. |
146
+ | `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
147
+ | `sarifPath` | SARIF export path, or `null`. |
148
+ | `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
149
+ | `cost` | Estimated model usage cost, or `null` when unavailable. |
150
+
151
+ Read `result.manifest.scan.status` and `result.manifest.scan.scope` alongside
152
+ `result.review.excludedPaths` to see the outcome, the requested scope and any
153
+ additional exclusions. A completed scan can report zero findings within that scope.
154
+
155
+ If the run retained a draft or checkpoint, its `reviewState.deferred` lists
156
+ unfinished work and `reviewState.openQuestions` lists follow-up questions.
157
+ See [saved scan files](cli.md#understand-scan-scope-and-follow-up-work)
158
+ for the current and legacy layouts. Reports and logs can include source code,
159
+ vulnerability details and credentials. Review them before sharing.
160
+
161
+ Saved-history excerpts use scanned Git objects without fetching missing data.
162
+ Working-tree diff scans omit excerpts, as do historical scans whose source or
163
+ scope cannot be established. Unambiguous older scans remain readable. An omitted
164
+ excerpt does not remove the finding.
165
+
166
+ The SDK does not set your process's exit status. Use `hasFindingsAtOrAbove()`
167
+ as in the example to enforce a severity threshold.
168
+
169
+ ### Scan options and output
170
+
171
+ Pass scan settings as the second argument to `run()`. The following SDK snippets
172
+ assume an open `CodexSecurity` client named `security`; close it when finished.
173
+
174
+ ```ts
175
+ const result = await security.run("/path/to/repository", {
176
+ target: ["src", "tests"],
177
+ excludePaths: ["src/examples"],
178
+ knowledgeBasePaths: ["/path/to/architecture.md"],
179
+ scanPrompt: "Focus on authentication and authorization.",
180
+ outputDir: "/path/outside/repository/results",
181
+ maxCostUsd: 5,
182
+ });
183
+ ```
184
+
185
+ `excludePaths` takes literal repository-relative files or directories. A directory
186
+ excludes all descendants, and exclusions take precedence over `target`. The default
187
+ is no exclusions. Requested exclusions are recorded in `result.manifest.scan.scope.excludePaths`.
188
+
189
+ | Option | Use |
190
+ | ------------------------------------------- | ------------------------------------------------------------------------------ |
191
+ | `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |
192
+ | `mode` | `"standard"` (default) or `"deep"`. Deep scans support repositories and paths. |
193
+ | `knowledgeBasePaths` | Supporting text, PDF, DOCX files, or directories. |
194
+ | `scanPrompt` / `scanPromptFile` | Additional scan instructions. Inline text takes precedence. |
195
+ | `validationPrompt` / `validationPromptFile` | Custom validation instructions for standard scans. |
196
+ | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions after the scan. |
197
+ | `ownerSuggestions` | Write optional owner suggestions after a committed scan (default: `false`). |
198
+ | `outputDir` | Results directory; omit to use the state directory. |
199
+ | `archiveExisting` | Move previous results aside before reusing `outputDir`. |
200
+ | `maxCostUsd` | Stop at an estimated model cost; see [cost limits](#progress-and-cost). |
201
+ | `signal` | An `AbortSignal` to cancel the scan. |
202
+
203
+ The exported `ScanOptions` type describes all options and callbacks. For full
204
+ CLI behavior, see [scan options and output](cli.md#scan-options-and-output).
205
+
206
+ Set `ownerSuggestions: true` or run `codex-security scan --owner-suggestions`
207
+ to write `owner-suggestions.json` beside a completed committed Git scan. Project
208
+ files can set `scan.owner_suggestions: true`. The report uses the scan's finding
209
+ IDs and frozen revision; it does not change the sealed findings or assign users.
210
+ Owner failures leave the base scan completed and appear as
211
+ `result.ownerSuggestionsError`; successful reports set `result.ownerSuggestionsPath`.
212
+ The scan records optional owner hints within its existing session and budget.
213
+ Report finalization applies CODEOWNERS and validates Git evidence without another
214
+ model call, including when `maxCostUsd` is set. Missing hints abstain and invalid
215
+ hints produce per-finding errors. Working-tree and directory snapshots are
216
+ unsupported. Explicit owner-only analysis remains available through `suggestOwners`
217
+ and `suggest-owners`, sharing the same evidence validation and report code.
218
+
219
+ ### Scan a diff
220
+
221
+ ```ts
222
+ import { DiffTarget } from "@openai/codex-security";
223
+
224
+ const result = await security.run("/path/to/repository", {
225
+ target: DiffTarget.refs({ base: "origin/main" }),
226
+ });
227
+ ```
228
+
229
+ `DiffTarget.refs()` compares the base with `HEAD` unless you supply `head`.
230
+ The checkout must be clean, complete, and at that head revision.
231
+ Use `DiffTarget.workingTree()` for staged and unstaged changes relative to `HEAD`.
232
+ Diff targets require standard mode.
233
+
234
+ ### Configure the client
235
+
236
+ Set model and native Codex settings on the client:
237
+
238
+ ```ts
239
+ const security = new CodexSecurity({
240
+ codexOverrides: {
241
+ model_reasoning_effort: "high",
242
+ analytics: { enabled: false },
243
+ },
244
+ });
245
+ ```
246
+
247
+ Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
248
+ The bundled runtime and plugin are used by default. `pythonPath` overrides the
249
+ `PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
250
+ For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
251
+
252
+ To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
253
+ The toggle defaults off; an explicit `false` keeps it off. The setting reaches
254
+ Deep Scan discovery workers, including resumed workers. Scans use
255
+ isolated configuration, so a desktop toggle or personal Codex configuration does
256
+ not configure an SDK scan. See [Daybreak opt-in](cli.md#daybreak-opt-in) for
257
+ CLI, project-file, and direct plugin configuration.
258
+
259
+ Deep Scan workers, including resumed workers, inherit per-scan provider,
260
+ authentication, environment, and executable settings with read-only permissions.
261
+
262
+ Scans use an isolated Codex configuration. See
263
+ [runtime configuration](cli.md#runtime-configuration-and-worker-limits)
264
+ for supported overrides and defaults.
265
+
266
+ Windows defaults to `windows.sandbox = "elevated"` to enforce credential read
267
+ denials. Explicit `windows.sandbox` settings remain unchanged; Codex reports
268
+ policies unsupported by the selected backend.
269
+
270
+ ### Load a project file
271
+
272
+ Load shared CLI and SDK settings explicitly:
273
+
274
+ ```ts
275
+ import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
276
+
277
+ const { config, options } = await loadProjectConfig("codex-security.yaml");
278
+ const security = new CodexSecurity(config);
279
+
280
+ try {
281
+ const result = await security.run("/path/to/repository", options);
282
+ if (
283
+ options.failureSeverity !== undefined &&
284
+ result.hasFindingsAtOrAbove(options.failureSeverity)
285
+ ) {
286
+ process.exitCode = 1;
287
+ }
288
+ } finally {
289
+ await security.close();
290
+ }
291
+ ```
292
+
293
+ `run()` does not discover project files. Paths inside a file resolve from that
294
+ file's directory; scope paths resolve from the repository. For a typed object,
295
+ use `resolveProjectConfig(input, directory?)`. Override loaded options with
296
+ `{ ...options, maxCostUsd: 5 }`.
297
+
298
+ Project files are trusted configuration and can select model endpoints or start
299
+ MCP servers. Keep CI scanner configuration outside the checkout being assessed.
300
+ See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
301
+ for the schema and precedence rules.
302
+
303
+ ### Check inputs before scanning
304
+
305
+ ```ts
306
+ const plan = await security.preflight("/path/to/repository", {
307
+ target: ["src"],
308
+ maxCostUsd: 5,
309
+ });
310
+ console.log(plan);
311
+ ```
312
+
313
+ `preflight()` checks local inputs without starting Codex or using the network. The returned `stateDirectory` identifies the checked storage root, including when the final scan directory will be allocated automatically.
314
+ It does not verify credentials, model access, Python, or the plugin. The CLI
315
+ equivalent is `scan --dry-run`.
316
+ Neither preflight starts a Deep Scan worker or executes a command under its
317
+ generated permissions, so neither qualifies the worker sandbox. See [Deep Scan
318
+ sandbox qualification](../../../docs/project-configuration.md#deep-scan-sandbox-qualification)
319
+ for the boundary and the limits of what these checks establish.
320
+
321
+ ### Set investigation time
322
+
323
+ ```ts
324
+ await security.run("/path/to/repository", { maxTimeMinutes: 15 });
325
+ ```
326
+
327
+ `maxTimeMinutes` accepts positive fractional minutes. Standard scans use an
328
+ advisory allowance, unset by default; Deep scans retain their enforced discovery
329
+ limit. Scans may finish early and reporting may run longer. The CLI equivalent is
330
+ `scan --max-time 15`; project files use `scan.max_time_minutes`. See
331
+ [investigation time](cli.md#set-investigation-time) for lifecycle and limit
332
+ semantics. `maxCostUsd` and `signal` keep their existing behavior.
333
+
334
+ ### Configure deep scans
335
+
336
+ ```ts
337
+ const result = await security.run("/path/to/repository", {
338
+ mode: "deep",
339
+ workers: 2,
340
+ subagents: 0,
341
+ stopAfterNoNew: 3,
342
+ stopAfterConsecutiveErrors: 3,
343
+ maxDiscoveryRuns: 10,
344
+ maxTimeMinutes: 90,
345
+ });
346
+ ```
347
+
348
+ `workers` controls concurrent Standard scans and `subagents` controls delegation
349
+ within each scan. Time and run limits apply to discovery. The coordinator merges
350
+ completed findings before the next batch starts. See
351
+ [deep scan settings](cli.md#configure-deep-scans) for defaults and saved settings.
352
+ Deep discovery retains its enforced deadline, with a default and maximum of
353
+ 5760 minutes. `maxTimeHours` remains a deprecated Deep-only alias in hours.
354
+
355
+ ### Progress and cost
356
+
357
+ Use `onLifecycle` to observe the saved state of a top-level scan in your own
358
+ application:
359
+
360
+ ```ts
361
+ await security.run(repository, {
362
+ onLifecycle(scan) {
363
+ console.log(scan.scanId, scan.status, scan.hasReportableFindings);
364
+ },
365
+ });
366
+ ```
367
+
368
+ For `runComponentScans()`, subscribe to `onScanEvent` and select events with
369
+ `type === "lifecycle"` to correlate each snapshot with its `componentId`. Deep
370
+ component scans also emit `deep-progress` events with independent review counts.
371
+
372
+ Group observations by `scanId`. A completed scan with
373
+ `hasReportableFindings: false` finished with zero reportable findings.
374
+ The field is `null` until that outcome is known. Saved scan history retains
375
+ the lifecycle snapshot after the originating process exits. The snapshot
376
+ includes the launch surface, package and plugin versions when available,
377
+ and whether the scan used a mock. Offline imports appear in history with
378
+ lifecycle mode `import`. Exclude imports and mock scans when counting executed
379
+ scans. For older records, saved recipes identify known imports, mock scans,
380
+ and the plugin version used at launch. Missing fields stay unknown.
381
+
382
+ If `run()` rejects before you receive a registration, record the error separately
383
+ from saved scan outcomes. The caller may have missed the registration receipt.
384
+
385
+ Use `onProgress` for scan progress and `onMeasurement` for observed token/cost
386
+ subtotals, coverage, and collection time. `onCost` and `onUsage` report complete
387
+ totals. `onUsageObservation` reports the native token measurement time
388
+ (`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
389
+ Each reading has its own `observedAt` timestamp and percentages used in each
390
+ reported window. An allowance can arrive before any token measurement. See
391
+ [telemetry and measurement](telemetry.md) for operation receipts, collection
392
+ controls, replay, and reporting definitions.
393
+
394
+ Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
395
+ persisted worker sessions discovered by the SDK's existing session tracker,
396
+ independently of model-emitted status markers:
397
+
398
+ ```ts
399
+ await security.run(repository, {
400
+ onWorkerEvent(event) {
401
+ console.log(`Worker ${event.worker} observed`);
402
+ },
403
+ });
404
+ ```
405
+
406
+ The callback contains only `{ kind: "observed", worker: number }`. The scan-local
407
+ worker number matches `onActivity` and `onSessionEvent`; no prompts, raw thread
408
+ IDs, or session contents are exposed. Each session is reported once per run,
409
+ including nested workers and scan-associated validation or Deep Scan sessions.
410
+ On resume, already persisted workers can be reported again. Observation ends
411
+ with scan cost tracking, before `postScanPrompt`.
412
+
413
+ This works with the bundled Codex version. Persistence and polling can delay
414
+ notification, and missing notifications do not prove that delegation was skipped.
415
+ An observed session does not establish that a worker just started or that file
416
+ review has begun. The callback does not report failed spawn attempts, phase names,
417
+ or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
418
+ `signal` for cancellation. Observer failures go to `onObserverError` without
419
+ stopping the scan.
420
+
421
+ `onWorkerStatus` reports **best-effort** phase dispatch counts from model-emitted
422
+ text markers. A missing dispatch status does not mean delegation was skipped.
423
+ For retired progress hooks, see [older progress integrations](#older-progress-integrations).
424
+
425
+ `onSessionEvent` receives saved events with thread IDs and worker numbers and can
426
+ contain source code or credentials. Deep scans additionally expose durable
427
+ independent-review counts through `onDeepProgress`: `completed`, `active`, and
428
+ `maximum`. The maximum is a configured cap, not a percentage denominator. The
429
+ optional `consolidating` flag is true while the running scan combines results or
430
+ waits for finalization after its coordinator finishes. It is false once the scan
431
+ completes, fails, or is canceled.
432
+ `ScanOptions` lists all callbacks.
433
+
434
+ Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
435
+ allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
436
+ short-context estimate; in-flight requests can exceed it. Post-scan prompts run
437
+ outside that limit. With a cost limit, completing the scan requires verifiable
438
+ usage for the scan and its workers. Matching earlier findings can also make model calls.
439
+ See [progress and cost](cli.md#progress-and-cost) for accounting and budget callbacks.
440
+
441
+ ### Validate an existing finding
442
+
443
+ `validate()` sends the finding to your configured model provider. The model's
444
+ review tools can read the checkout, with network access and web search disabled.
445
+ Validation uses source evidence and skips builds, tests and application execution.
446
+
447
+ ```ts
448
+ import { writeFile } from "node:fs/promises";
449
+
450
+ const result = await security.validate({
451
+ repositoryPath: "/path/to/repository",
452
+ finding: {
453
+ title: "Possible SQL injection",
454
+ location: "src/query.ts:42",
455
+ },
456
+ });
457
+ console.log(result.disposition, result.report);
458
+ await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
459
+ ```
460
+
461
+ Pass literal finding text or a JSON-serializable object. The assessment is
462
+ returned to the caller and has no scan history entry. The example saves
463
+ `result.report` in an existing directory. Use `outputDir` to select the
464
+ session directory. If you need runtime evidence, arrange a separate check.
465
+
466
+ The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
467
+ `reportable` can rely on static analysis; `deferred` means there is insufficient
468
+ evidence. Failed or malformed responses reject the promise. `outputDir`, `auth`,
469
+ and `signal` are also supported.
470
+
471
+ To validate GitHub code scanning alerts, first import them with
472
+ `importGitHubCodeScanningAlerts()`. See the
473
+ [import guide](cli.md#import-alerts-from-the-cli) for CLI and SDK examples.
474
+
475
+ For host-managed model execution, use `validateRecords()` or `validate --records`.
476
+ See [host-provided standalone validation](validate-records.md).
477
+
478
+ ### Generate and verify a patch
479
+
480
+ `patch()` runs the bundled remediation workflow non-interactively against a
481
+ workspace that the caller has intentionally made writable:
482
+
483
+ ```ts
484
+ import { CodexSecurity } from "@openai/codex-security";
485
+
486
+ const security = new CodexSecurity();
487
+ try {
488
+ const result = await security.patch({
489
+ repositoryPath: "/path/to/disposable/workspace",
490
+ finding: {
491
+ title: "Possible SQL injection",
492
+ summary: "User input reaches a raw SQL query.",
493
+ locations: [{ path: "src/query.ts", startLine: 42 }],
494
+ },
495
+ onActivity(activity) {
496
+ console.log(activity.description);
497
+ },
498
+ onCost(cost) {
499
+ console.log(cost.estimatedUsd);
500
+ },
501
+ });
502
+
503
+ switch (result.status) {
504
+ case "verified":
505
+ case "no_change":
506
+ console.log(result.verificationReport);
507
+ break;
508
+ case "blocked":
509
+ case "failed":
510
+ console.error(result.reason);
511
+ break;
512
+ }
513
+ } finally {
514
+ await security.close();
515
+ }
516
+ ```
517
+
518
+ Pass literal finding text or a JSON-serializable object; strings are never read
519
+ as file paths. Sandboxed patch commands may edit only `repositoryPath` and run
520
+ without network access or web search. Patch workspaces are always treated as
521
+ untrusted Codex projects, so repository-local Codex configuration and MCP
522
+ servers are not loaded. Host-configured tools retain their host permissions.
523
+ The method does not create a commit, push, open a pull request, publish findings,
524
+ change remote finding state, or add a scan to history.
525
+ Callers remain responsible for reviewing and deriving the authoritative diff,
526
+ approval, commit creation, and delivery.
527
+
528
+ The discriminated result reports `verified`, `no_change`, `blocked`, or
529
+ `failed`, plus repository-relative `changedFiles`, `threadId`, and estimated
530
+ `cost` when model pricing and usage are available. Verified and no-change
531
+ results include `verificationReport`; blocked and failed results include
532
+ `reason`. Transport, authentication, cancellation, incomplete turns, and
533
+ malformed results reject the promise. Failed, blocked, or interrupted operations
534
+ can leave partial workspace changes for the caller to inspect or discard.
535
+
536
+ `changedFiles` is model-reported metadata, not the authoritative diff.
537
+ Patch-risk assessment is not included in this API.
538
+
539
+ Patch operations reuse constructor configuration and credentials. Pass `auth`,
540
+ `safetyIdentifier`, `model`, or `reasoningEffort` for per-call selection.
541
+ `onActivity`, `onSessionEvent`, `onCost`, `onReconnect`, `onAuthentication`,
542
+ `onWarning`, and `onObserverError` use the same observer contracts as scans.
543
+
544
+ ## CLI
545
+
546
+ After [installing the CLI](#install-the-cli), sign in if needed:
547
+
548
+ ```bash
549
+ cs login
550
+ ```
551
+
552
+ From the repository you want to review, run:
553
+
554
+ ```bash
555
+ cs scan .
556
+ ```
557
+
558
+ Open the report at the path printed on completion. To inspect the latest
559
+ completed scan for this checkout, run `cs scans show`. To provide a project
560
+ policy for future scans, [draft and review a `SECURITY.md`](#generate-a-security-policy).
561
+
562
+ To narrow the scan scope or check the configuration before scanning:
563
+
564
+ ```bash
565
+ cs scan . --path src --path tests
566
+ cs scan . --diff origin/main --json
567
+ cs scan . --dry-run
568
+ ```
569
+
570
+ Use `--help` to find commands and `<command> --help` for options. Scans are
571
+ report-only by default. Add `--fail-on-severity high` to return exit code `1`
572
+ for high or critical findings; execution and required-output failures return `2`.
573
+ Scope exclusions and follow-up notes do not change a completed scan's exit code.
574
+
575
+ The [CLI reference](cli.md) covers scan history, reruns, bulk and component
576
+ scans, custom validation, imports, patching, and integrations.
577
+
578
+ ### Generate a security policy
579
+
580
+ Use `policy` to draft a new `SECURITY.md` or update an existing one. To select a
581
+ component:
582
+
583
+ ```bash
584
+ cs policy . --path services/api
585
+ ```
586
+
587
+ Existing files stay unchanged until you review and copy the draft to the
588
+ **Policy target** shown. Scans already use root and component policies; you can
589
+ keep them without generating new ones.
590
+
591
+ The SDK provides `generatePolicy()`, `preflightPolicy()`, and `previewPolicy()`. See
592
+ [policy generation](cli.md#generate-a-security-policy) for SDK examples,
593
+ policy locations and reporting instructions, headless use, and saved artifacts.
594
+
595
+ ### Exports and CI
596
+
597
+ Export a completed scan's findings to a SARIF file:
598
+
599
+ ```bash
600
+ cs export /path/to/scan-results --output results.sarif
601
+ ```
602
+
603
+ Replace `/path/to/scan-results` with the results directory printed by `scan`.
604
+ Export reads saved results, so you don't need to rerun the scan or sign in.
605
+
606
+ See [exports and CI](cli.md#exports-and-ci) for source fingerprints, other
607
+ formats, threat models, and the `exportArtifact()` SDK method. For repository or
608
+ pull request scans in GitHub Actions, use the
609
+ [GitHub Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md).
610
+ Separate examples cover
611
+ [GitHub Actions with Bedrock](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md)
612
+ and [Azure Pipelines](https://github.com/openai/codex-security/blob/main/examples/azure-pipelines/README.md).
613
+
614
+ ### Classify finding severity
615
+
616
+ Use `classify-severity` to assess saved findings with the built-in severity rubric
617
+ or an explicit custom rubric, without changing their original severity or evidence.
618
+ Each finding receives three independent reviews by default; the most common severity wins,
619
+ with the highest severity breaking ties among the top vote counts.
620
+ Use `--runs N` to request 1–10 reviews (default: 3). The SDK exposes `classifySeverity()`,
621
+ `classifyScanSeverity()`, and `classifyScanDirectorySeverity()`. See
622
+ [severity classification](cli.md#classify-finding-severity) for selection,
623
+ checkpointing, and publication behavior.
624
+
625
+ For canonical records without a saved scan, use `classify-severity --records`
626
+ or `classifySeverityRecords()` with [host-provided execution](classify-severity-records.md).
627
+
628
+ ### Suggest finding owners
629
+
630
+ Use `suggest-owners` or the SDK's `suggestOwners()` to suggest contributors based
631
+ on CODEOWNERS, source, and Git history. Declared owners take priority over Git
632
+ contributors. Suggestions do not assign tickets. See
633
+ [owner suggestions](cli.md#suggest-finding-owners) for input and output examples.
634
+
635
+ ### Read existing Cloud findings
636
+
637
+ The Security plugin includes `$cloud-findings` for accounts where Codex Security
638
+ Cloud is available. Install the plugin through your configured Codex marketplace,
639
+ sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
640
+ the intended account and workspace. Installation alone does not authenticate the
641
+ connection. Local scans do not require Cloud, and an API key used for scanning
642
+ does not replace the Cloud connection.
643
+
644
+ In Codex desktop or the interactive Codex CLI, ask:
645
+
646
+ > Use $cloud-findings to list findings for example/security-demo in my selected
647
+ > workspace. Inspect the highest-severity finding and its report, and show its
648
+ > recorded assignee, patch links, verification results, and latest scan status.
649
+ > Do not change anything.
650
+
651
+ After completing connection setup, the same host connection can be used by
652
+ `codex exec`:
653
+
654
+ ```bash
655
+ codex exec --ephemeral --json -s read-only 'Use $codex-security:cloud-findings to read findings and the latest scan status for example/security-demo in my selected workspace. Inspect one finding and its report. If the workspace or repository is ambiguous, explain the required selection and stop. Do not change anything.'
656
+ ```
657
+
658
+ Noninteractive execution needs an existing authenticated connection; it cannot
659
+ complete first-time sign-in. If authentication expires, the app is unavailable,
660
+ or workspace policy denies access, complete the reported setup action before
661
+ retrying. Those failures do not mean the repository has no findings.
662
+
663
+ Assignment, issue validation, patch checks, periodic fix checks, and finding
664
+ lifecycle status are separate records. Some finding sources do not provide all
665
+ of them. The read workflow reports missing data and incomplete evidence pages,
666
+ and does not describe failed or unfinished scans as clean.
667
+
668
+ ### Publish findings to Cloud
669
+
670
+ Use `publish scan --to cloud` for completed Codex Security scans or a Codex
671
+ Security findings CSV. Preview either input offline with `--dry-run`. Uploads
672
+ require a file-backed ChatGPT login. [Cloud publication](cli.md#publish-completed-scans)
673
+
674
+ For a report exported by a scanner, see [Import external findings](#import-external-findings).
675
+ For issue tracking, see [Linear publication](cli.md#publish-completed-scans-to-linear).
676
+
677
+ ### Import external findings
678
+
679
+ For an agent-written parser, use the normalized import API. Pass an absolute
680
+ checkout path, a stable source namespace and the repository URL when known.
681
+ Count each input occurrence in `read` and supply its evidence or a numbered
682
+ exclusion. Keep the upstream occurrence ID as a string.
683
+
684
+ ```ts
685
+ import { prepareNormalizedLocalImport } from "@openai/codex-security";
686
+
687
+ const local = await prepareNormalizedLocalImport(
688
+ {
689
+ read: 1,
690
+ findings: [
691
+ {
692
+ source_finding_id: "17",
693
+ evidence: { title: "Unsafe eval", severity: "high" },
694
+ },
695
+ ],
696
+ excluded: [],
697
+ },
698
+ {
699
+ repository: checkout,
700
+ provider: "example-scanner",
701
+ sourceKey: "payments/main",
702
+ sourceRepositoryUrl: scmUrl,
703
+ },
704
+ );
705
+ console.log(local.preview);
706
+ const { importId } = await local.import(); // After reviewing the preview.
707
+ ```
708
+
709
+ A nonempty import returns an `importId`, including when every finding was
710
+ unchanged. Use `listLocalExternalImports({ repository })` to find an import.
711
+ `selectLocalExternalFindings({ repository, importId })` reads its members and
712
+ fails if a finding has since changed. To select individual findings across
713
+ imports, pass `{ repository, findings: [{ id, version }] }`.
714
+
715
+ ```ts
716
+ import { prepareStoredFindingsPublication } from "@openai/codex-security";
717
+
718
+ const { groups, excluded } = await prepareStoredFindingsPublication(
719
+ { repository: checkout, importId },
720
+ { repository: cloudRepository },
721
+ );
722
+ console.log(
723
+ groups.map(({ preview }) => preview),
724
+ excluded,
725
+ );
726
+ ```
727
+
728
+ Show the user all destinations, findings and exclusions together. For each
729
+ approved group, retain its selection and review ID, then call
730
+ `group.publish(approvedReviewId)`. Check the returned status, receipts and
731
+ per-item errors before proceeding. If a submission is interrupted, reprepare
732
+ that group and subsequent unstarted groups from their saved selections and use
733
+ the original review IDs. Report a terminal partial result with its exclusions
734
+ and errors. If the approved ID was lost or the preview changed, show the new
735
+ preview for review.
736
+ `listLocalFindingPublications({ repository, id })` returns receipts for a
737
+ stored version, including completed private inbox job IDs. Custom provider
738
+ names and Tenable can be used locally. Cloud eligibility follows its provider
739
+ contract and the selected destination.
740
+
741
+ For a saved scanner report, call `prepareLocalExternalImport` for a checkout
742
+ or `prepareExternalPublication` for a connected Cloud repository. Review the
743
+ returned `preview`, then call `import()` to save locally or `publish()` to
744
+ upload. The [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md)
745
+ list the supported report formats and destinations for each provider.
746
+
747
+ For normalized evidence, use `prepareNormalizedLocalImport(findings, options)`
748
+ or `prepareNormalizedExternalPublication(findings, options)` and review the
749
+ preview in the same way. Cloud file imports use `ExternalPublicationOptions`,
750
+ and normalized Cloud imports use `NormalizedExternalPublicationOptions`. Keep
751
+ Cloud receipts and saved requests when retrying an interrupted submission. Use the SDK build that created a pending submission to finish it before upgrading.
752
+
753
+ Use `listLocalExternalFindings({ repository })` to read saved scanner evidence.
754
+ It starts unassessed. Reimporting the same repository, provider, source key
755
+ and finding ID updates that record. Records omitted from the export remain stored.
756
+
757
+ A local SDK import with only excluded records returns the exclusions and zero
758
+ writes. The CLI exits 2 in that case. When Cloud preparation throws
759
+ `NoPublishableFindingsError`, inspect its `selection` for the read count,
760
+ exclusions and scanner diagnostics. A clean empty report needs no upload.
761
+
762
+ File imports forward repository references from the reader automatically. With
763
+ `prepareNormalizedLocalImport()`, supply additional known references in the
764
+ third argument's `sourceRepositories` when they are absent from
765
+ `evidence.details.repository.url`. For a known GitHub custom host, include
766
+ `platform: "github"`, for example `{ sourceRepositories: [{ url:
767
+ "https://git.example.test/example/project", platform: "github" }] }`. Named Wiz
768
+ reports carry this platform in their repository inventory. If you export only the
769
+ normalized finding rows to JSONL, supply that metadata separately; the original
770
+ finding evidence does not include the surrounding inventory.
771
+
772
+ #### Collect and normalize scanner evidence
773
+
774
+ To collect selected Sonar issues, pass their keys to `collectSonarIssues` in `options.issueKeys`.
775
+ Omit `issueKeys` to collect the project's open security issues. An empty list is rejected.
776
+ If you know the source repository, pass its Git URL in `options.sourceRepositoryUrl`
777
+ to check the Sonar binding before fetching issues.
778
+
779
+ For AWS Continuum, use `readContinuumFindings(path, sourceRepositoryUrl)` with a
780
+ saved issue export, single-finding capture, or native finding response. Use
781
+ `normalizeContinuumFindings(input, sourceRepositoryUrl)` with parsed JSON.
782
+ Issue exports with a saved repository URL can omit the second argument.
783
+ For other reports, pass the verified source repository URL.
784
+ [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
785
+
786
+ Pass `"local"` as the third argument to retain full patch contents in collector
787
+ captures. The Cloud projection records `contentOmitted: "cloud_evidence_limit"`
788
+ when the patch contents exceed the evidence budget. Available patches are in
789
+ `evidence.source_data.patches`. Single-finding captures provide their matching
790
+ validation artifacts in `evidence.source_data.evidence_artifacts`. The local
791
+ projection retains each validation body, and Cloud marks omitted bodies with
792
+ the same `contentOmitted` value. When even the validation descriptors exceed
793
+ the budget, Cloud omits them and preserves the finding and its fitting patches.
794
+
795
+ For a saved Checkmarx One CLI JSON or CxSAST XML report, use
796
+ `readCheckmarxFindings(path, sourceRepositoryUrl, "local")` to inspect its evidence.
797
+ To prepare a local import, pass `provider: "checkmarx"` and the verified
798
+ `sourceRepositoryUrl` to `prepareLocalExternalImport`. Keep each batch of normalized
799
+ Checkmarx findings scoped to one scan and its repository.
800
+ [Checkmarx SAST import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/checkmarx.md)
801
+
802
+ Use `collectSelectedSemgrepGuardianFindings` with a connected Guardian MCP client to
803
+ [capture selected Code or Supply Chain findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-guardian-findings) using the user's Guardian sign-in.
804
+ Use `normalizeSelectedSemgrepPlatformFindings` for selected SAST findings from saved
805
+ Semgrep Web API responses. See the [Semgrep SDK example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk).
806
+ Use `selectSemgrepPlatformFindings` to [save a selection for the local CLI](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#existing-platform-findings).
807
+ Use `collectSemgrepPlatformFindings` to [collect one project at an explicit ref](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#collect-a-platform-project-and-branch) for a single product (default `sast`).
808
+
809
+ Use `collectSnykIssues` to [collect existing Open Source or Code issues](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md#existing-issues-from-snyk) for local import or Cloud publication.
810
+ For a private repository with a verified SCM, pass its URL and `platform: "gitlab"` or `"github"` in `sourceRepositories` to match standard SSH clone URLs.
811
+
812
+ To inspect dependency vulnerabilities in a saved Trivy schema-v2 repository or filesystem
813
+ report, call `readTrivyFindings` with the JSON or gzip path. Use `normalizeTrivyFindings`
814
+ for an already parsed report. Supply the scanned directory relative to the checkout
815
+ (`.` for the whole checkout) unless the report's remote target and Git metadata establish it.
816
+
817
+ ```ts
818
+ import { readTrivyFindings } from "@openai/codex-security";
819
+
820
+ const { findings, excluded, report } = await readTrivyFindings(
821
+ "trivy.json.gz",
822
+ "local",
823
+ ".",
824
+ );
825
+ ```
826
+
827
+ ## Findings storage and deduplication
828
+
829
+ Saved-scan deduplication uses local SQLite directly:
830
+
831
+ ```bash
832
+ cs dedupe --scan SCAN_ID --json
833
+ ```
834
+
835
+ The [findings guide](findings-service.md) covers local storage, embedding
836
+ credentials, deduplication, backups, and independently operated HTTP endpoints.
837
+ For an older service deployment, see [migration guidance](findings-service.md#local-service-removal).
838
+ For records stored in your own system, see
839
+ [SDK records deduplication](dedupe-records.md).
840
+
841
+ ## Containerized bulk scans
842
+
843
+ Use the scanner image and Compose files to scan a list of repositories with
844
+ persistent results and authentication. See
845
+ [containerized bulk scans](cli.md#containerized-bulk-scans) for setup, or the
846
+ [workflow runner](https://github.com/openai/codex-security/blob/main/docker/README.md#workflow-runner)
847
+ for individual CLI stages in containers.
848
+
849
+ ## Local security model
850
+
851
+ Codex Security runs with your operating-system permissions. Scan subprocesses
852
+ can inherit your environment, so start them with only the credentials they need.
853
+ Local tools running under the same account are trusted.
854
+
855
+ The scan profile allows reads across the local filesystem and writes to workspace
856
+ roots. Execution approvals are reviewed automatically and may grant extra
857
+ permissions for an operation. Set `codexOverrides.approval_policy: "never"`
858
+ (or CLI `--codex "approval_policy='never'"`) to deny permission requests.
859
+ If you select a Codex profile, its explicit `approval_policy` takes precedence
860
+ over the root setting.
861
+ Host and network restrictions still apply.
862
+
863
+ Repository contents, model output, and imported artifacts do not authorize
864
+ access to other targets, disclosure of credentials, or writes outside approved
865
+ paths. Keep state and scan artifacts private and outside the repository.
866
+
867
+ ## Compatibility
868
+
869
+ ### Package and plugin versions
870
+
871
+ When reporting a problem, run `codex-security info --json` with the installation
872
+ that produced it. For a local SDK installation, run
873
+ `npx @openai/codex-security info --json` in that project. Include `cliVersion`,
874
+ `sdkVersion`, `bundledPluginVersion`, `codexVersion` and `codexSdkVersion`. If
875
+ you supplied a separate plugin or Codex executable, include its version too.
876
+
877
+ For package provenance, compare the registry's `gitHead` and `dist.integrity`
878
+ with the release tag and tarball. If a package omits `gitHead`, use the commit
879
+ in its [verified release attestation](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml).
880
+
881
+ ### Custom plugins
882
+
883
+ New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
884
+ `workerProviderSnapshot: 4`, and isolated worker configuration support. Older
885
+ custom plugins fail before scan execution; update the plugin or omit `pluginPath`
886
+ to use the bundled version. Reading saved reports does not require these
887
+ execution capabilities.
888
+
889
+ Use the current shell or Windows launcher for runtime-root routing. The SDK does
890
+ not adapt the older `node ./mcp/server.mjs` MCP entrypoint.
891
+
892
+ Custom plugins must support the current workbench protocol for scan comparison
893
+ and archival. The SDK does not adapt older payloads or archive scan directories
894
+ on behalf of older workbench implementations.
895
+
896
+ ### Older progress integrations
897
+
898
+ The helper-derived `kind: "preflight"` event, `config_preflight.py` helper, and
899
+ custom capability registries are retired. This includes the `preflightChecks`
900
+ progress-tool input and workbench `--preflight-issues-json` /
901
+ `--preflight-issues-json-stdin` arguments. Scans use available runtime tools and
902
+ parent fallback without a capability registry. Saved preflight history remains
903
+ readable. Local `preflight()` input checks, authentication, sandbox enforcement,
904
+ and Deep worker configuration still apply.
905
+
906
+ ### Error types
907
+
908
+ `LocalPluginBootstrapError` identifies local plugin setup failures and extends
909
+ `PluginBootstrapError`, so existing catches keep working. Knowledge-base
910
+ preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
911
+
912
+ ## Documentation and security
913
+
914
+ - [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)
915
+ - [CLI reference](cli.md)
916
+ - [Findings guide](findings-service.md)
917
+ - [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and feature requests
918
+ - [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for private vulnerability reporting