@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
package/README.md CHANGED
@@ -1,795 +1,85 @@
1
1
  # `@openai/codex-security`
2
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 run parallel
8
- discovery workers on repositories and selected paths.
9
- - Validate findings, generate patches, and verify existing fixes.
10
- - Draft security policies and retain threat models.
11
- - Review saved findings, identify duplicates, classify severity, and suggest owners.
12
- - Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
13
- findings to Linear or a findings service.
14
- - 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](docs/cli.md),
19
- [findings guide](docs/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.
3
+ Scan a repository, selected paths, or Git changes for vulnerabilities. The CLI
4
+ and TypeScript SDK can validate findings, generate patches, verify fixes, and
5
+ export results as SARIF, JSON, or CSV. The package includes the Codex runtime
6
+ and security plugin.
23
7
 
24
8
  ## Install
25
9
 
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
- Reading compressed Codex session logs (`.jsonl.zst`) requires Node.js 22.15.0+
33
- within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14, compressed sessions
34
- are unavailable when reading saved activity or attaching scan logs to feedback, and
35
- scans whose original session is compressed cannot resume. Plain `.jsonl` logs
36
- work on all supported runtimes.
10
+ Use Node.js 22.x (22.13.0 or later), 24.x, or 26.x on macOS, Linux, or Windows.
11
+ Scans also require Python 3.10 or later. On Python 3.10, install `tomli`.
37
12
 
38
13
  ### Install the CLI
39
14
 
40
- Install the CLI globally:
41
-
42
- ```bash
15
+ ```sh
43
16
  npm install --global @openai/codex-security
44
- cs --version
45
17
  ```
46
18
 
47
- `cs` is a short alias for `codex-security`; both commands run the same CLI.
48
- The installation creates both commands in npm's global executable directory,
49
- which must be on your `PATH`. If `cs` already resolves to another tool, use
50
- `codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
51
- `npx @openai/codex-security` without a global installation.
52
-
53
- Continue with the [CLI walkthrough](#cli). To run without a global installation,
54
- replace `cs` in the CLI examples with `npx @openai/codex-security`.
19
+ The CLI runs as `cs` or `codex-security`. To skip the global install, use
20
+ `npx @openai/codex-security` in place of `cs` in the examples below.
55
21
 
56
22
  ### Install the TypeScript SDK
57
23
 
58
- Install the package locally in your TypeScript project:
24
+ Install the package in your project directory.
59
25
 
60
- ```bash
26
+ ```sh
61
27
  npm install @openai/codex-security
62
28
  ```
63
29
 
64
- ### Package and plugin versions
65
-
66
- For bug reports, run `npx @openai/codex-security info --json` in the project
67
- where the SDK is installed, or `codex-security info --json` for a global install.
68
- Include the npm version (`cliVersion` and `sdkVersion`), bundled plugin manifest
69
- version (`bundledPluginVersion`), and Codex runtime and SDK pins (`codexVersion`
70
- and `codexSdkVersion`). If you used a marketplace plugin, a plugin supplied by
71
- path, or a custom Codex executable, include its version separately.
72
-
73
- For example, `npm view @openai/codex-security@0.1.5 gitHead dist.integrity`
74
- shows the registry's source commit and tarball digest. Compare `gitHead` with
75
- the commit for tag `npm-v0.1.5`. `npm pack @openai/codex-security@0.1.5` downloads
76
- the archive, including `package/_bundled_plugin/.codex-plugin/plugin.json`.
77
-
78
- The [release workflow](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml)
79
- verifies the signed attestation that binds the tarball to the tagged commit.
80
- For `0.1.0` and `0.1.1`, npm omits `gitHead`. Use the commit from the verified attestation.
30
+ Before 1.0, minor releases may change the public API.
81
31
 
82
32
  ## Authentication
83
33
 
84
- Sign in with ChatGPT:
85
-
86
- ```bash
87
- cs login
88
- ```
89
-
90
- If you installed only the SDK locally, sign in from your project directory:
91
-
92
- ```bash
93
- npx @openai/codex-security login
94
- ```
95
-
96
- In the following CLI examples, replace `cs` with `npx @openai/codex-security`
97
- when using a local SDK installation, including the API-key login example below.
98
-
99
- For CI, set `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan process's environment.
100
- These keys apply to the current command without replacing your saved login.
101
- To save an API key instead, pass it on stdin:
102
-
103
- ```bash
104
- printenv OPENAI_API_KEY | cs login --with-api-key
105
- ```
106
-
107
- SDK calls accept `auth: "auto" | "chatgpt" | "api-key"`. The default, `"auto"`,
108
- prefers `OPENAI_API_KEY`, then `CODEX_API_KEY`, then stored credentials.
109
- Use `"chatgpt"` to ignore environment API keys. The CLI uses the same `--auth`
110
- values and prompts in an interactive terminal when both credential types are available.
111
-
112
- Some cybersecurity requests and protected findings require
113
- [Trusted Access for Cyber](https://chatgpt.com/cyber) approval. See the
114
- [authentication reference](docs/cli.md#authentication) for providers, stored
115
- credentials, and Cyber access program selection.
116
-
117
- ### Remote login with SSH forwarding
118
-
119
- On a remote or headless machine, try `login --device-auth` if your workspace
120
- allows it. Otherwise, open an SSH tunnel from your local machine:
121
-
122
- ```bash
123
- ssh -L 1455:localhost:1455 user@remote-host
124
- ```
125
-
126
- Run `cs login` in that SSH session, then open its sign-in
127
- URL in your local browser. Keep SSH connected until login finishes.
128
-
129
- ### Amazon Bedrock
130
-
131
- Bedrock scans use AWS credentials and model access. They do not require
132
- `codex-security login` or an OpenAI API key. See the
133
- [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
134
- for setup, model selection, and verification.
135
-
136
- ## Read existing Cloud findings
137
-
138
- The Security plugin includes `$cloud-findings` for accounts where Codex Security
139
- Cloud is available. Install the plugin through your configured Codex marketplace,
140
- sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
141
- the intended account and workspace. Installation alone does not authenticate the
142
- connection. Local scans do not require Cloud, and an API key used for scanning
143
- does not replace the Cloud connection.
34
+ Run `cs login` to sign in with ChatGPT. With a local SDK installation, run
35
+ `npx @openai/codex-security login` from your project. In CI, set
36
+ `OPENAI_API_KEY` or `CODEX_API_KEY` in the scan environment.
37
+ Some requests require [Trusted Access for Cyber](https://chatgpt.com/cyber).
144
38
 
145
- In Codex desktop or the interactive Codex CLI, ask:
146
-
147
- > Use $cloud-findings to list findings for example/security-demo in my selected
148
- > workspace. Inspect the highest-severity finding and its report, and show its
149
- > recorded assignee, patch links, verification results, and latest scan status.
150
- > Do not change anything.
39
+ ## CLI
151
40
 
152
- After completing connection setup, the same host connection can be used by
153
- `codex exec`:
41
+ Run a scan from the repository you want to review.
154
42
 
155
- ```bash
156
- 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.'
43
+ ```sh
44
+ cs scan .
157
45
  ```
158
46
 
159
- Noninteractive execution needs an existing authenticated connection; it cannot
160
- complete first-time sign-in. If authentication expires, the app is unavailable,
161
- or workspace policy denies access, complete the reported setup action before
162
- retrying. Those failures do not mean the repository has no findings.
163
-
164
- Assignment, issue validation, patch checks, periodic fix checks, and finding
165
- lifecycle status are separate records. Some finding sources do not provide all
166
- of them. The read workflow reports missing data and incomplete evidence pages,
167
- and does not describe failed or unfinished scans as clean.
47
+ To scan only committed changes from `origin/main` to `HEAD`, run
48
+ `cs scan . --diff origin/main`. A completed scan exits with code `0` by default,
49
+ even when it finds vulnerabilities. Add `--fail-on-severity high` to exit with
50
+ code `1` for high or critical findings.
168
51
 
169
52
  ## Run a scan from TypeScript
170
53
 
171
- Scan a repository you own or have permission to assess:
54
+ Run this ES module from the repository you want to scan.
172
55
 
173
56
  ```ts
174
57
  import { CodexSecurity } from "@openai/codex-security";
175
58
 
176
59
  const security = new CodexSecurity();
177
-
178
60
  try {
179
- const result = await security.run("/path/to/repository");
180
-
61
+ const result = await security.run(".");
181
62
  console.log(result.reportPath);
182
- console.log(result.findings.findings);
183
-
184
- if (result.hasFindingsAtOrAbove("high")) {
185
- process.exitCode = 1;
186
- }
63
+ console.log(`${result.findings.findings.length} findings`);
187
64
  } finally {
188
65
  await security.close();
189
66
  }
190
67
  ```
191
68
 
192
- Omitting `outputDir` saves results in the private Codex Security state directory.
193
- To choose another location, use a new or empty directory outside the scanned
194
- repository and its enclosing Git worktree. Existing output directories keep their
195
- permissions; newly created directories are private to you by default.
196
-
197
69
  ### Read results
198
70
 
199
- | Result | Contents |
200
- | --------------------------------- | ---------------------------------------------------------------- |
201
- | `findings.findings` | Findings from this scan. |
202
- | `reportPath` | Path to the Markdown report. |
203
- | `review` | Additional excluded paths. This is not file coverage. |
204
- | `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
205
- | `sarifPath` | SARIF export path, or `null`. |
206
- | `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
207
- | `cost` | Estimated model usage cost, or `null` when unavailable. |
208
-
209
- Review the requested paths and exclusions alongside the execution outcome.
210
- `reviewState.deferred` records unfinished requested work, while
211
- `reviewState.openQuestions` records optional follow-up separately.
212
-
213
- Review the scan status and scope alongside findings. A report with no findings does not establish
214
- that the repository is secure. Reports and logs can contain source code,
215
- vulnerability details, and credentials; review them before sharing.
216
-
217
- Saved-history excerpts use scanned Git objects without fetching missing data.
218
- Working-tree diff scans omit excerpts, as do historical scans whose source or
219
- scope cannot be established. Unambiguous older scans remain readable. An omitted
220
- excerpt does not remove the finding.
221
-
222
- The SDK does not set your process's exit status. Use `hasFindingsAtOrAbove()`
223
- as in the example to enforce a severity threshold.
224
-
225
- ### Scan options and output
226
-
227
- Pass scan settings as the second argument to `run()`. The following SDK snippets
228
- assume an open `CodexSecurity` client named `security`; close it when finished.
229
-
230
- ```ts
231
- const result = await security.run("/path/to/repository", {
232
- target: ["src", "tests"],
233
- knowledgeBasePaths: ["/path/to/architecture.md"],
234
- scanPrompt: "Focus on authentication and authorization.",
235
- outputDir: "/path/outside/repository/results",
236
- maxCostUsd: 5,
237
- });
238
- ```
239
-
240
- | Option | Use |
241
- | ------------------------------------------- | ------------------------------------------------------------------------------ |
242
- | `target` | Whole repository (default), repository-relative paths, or a `DiffTarget`. |
243
- | `mode` | `"standard"` (default) or `"deep"`. Deep scans support repositories and paths. |
244
- | `knowledgeBasePaths` | Supporting text, PDF, DOCX files, or directories. |
245
- | `scanPrompt` / `scanPromptFile` | Additional scan instructions. Inline text takes precedence. |
246
- | `validationPrompt` / `validationPromptFile` | Custom validation instructions for standard scans. |
247
- | `postScanPrompt` / `postScanPromptFile` | Follow-up instructions after the scan. |
248
- | `ownerSuggestions` | Write optional owner suggestions after a committed scan (default: `false`). |
249
- | `outputDir` | Results directory; omit to use the state directory. |
250
- | `archiveExisting` | Move previous results aside before reusing `outputDir`. |
251
- | `maxCostUsd` | Stop at an estimated model cost; see [cost limits](#progress-and-cost). |
252
- | `signal` | An `AbortSignal` to cancel the scan. |
253
-
254
- The exported `ScanOptions` type describes all options and callbacks. For full
255
- CLI behavior, see [scan options and output](docs/cli.md#scan-options-and-output).
256
-
257
- Set `ownerSuggestions: true` or run `codex-security scan --owner-suggestions`
258
- to write `owner-suggestions.json` beside a completed committed Git scan. Project
259
- files can set `scan.owner_suggestions: true`. The report uses the scan's finding
260
- IDs and frozen revision; it does not change the sealed findings or assign users.
261
- Owner failures leave the base scan completed and appear as
262
- `result.ownerSuggestionsError`; successful reports set `result.ownerSuggestionsPath`.
263
- The scan records optional owner hints within its existing session and budget.
264
- Report finalization applies CODEOWNERS and validates Git evidence without another
265
- model call, including when `maxCostUsd` is set. Missing hints abstain and invalid
266
- hints produce per-finding errors. Working-tree and directory snapshots are
267
- unsupported. Explicit owner-only analysis remains available through `suggestOwners`
268
- and `suggest-owners`, sharing the same evidence validation and report code.
269
-
270
- ### Scan a diff
271
-
272
- ```ts
273
- import { DiffTarget } from "@openai/codex-security";
274
-
275
- const result = await security.run("/path/to/repository", {
276
- target: DiffTarget.refs({ base: "origin/main" }),
277
- });
278
- ```
279
-
280
- `DiffTarget.refs()` compares the base with `HEAD` unless you supply `head`.
281
- The checkout must be clean, complete, and at that head revision.
282
- Use `DiffTarget.workingTree()` for staged and unstaged changes relative to `HEAD`.
283
- Diff targets require standard mode.
284
-
285
- ### Configure the client
286
-
287
- Set model and native Codex settings on the client:
288
-
289
- ```ts
290
- const security = new CodexSecurity({
291
- codexOverrides: {
292
- model_reasoning_effort: "high",
293
- analytics: { enabled: false },
294
- },
295
- });
296
- ```
297
-
298
- Constructor options are `codexOverrides`, `pythonPath`, and `pluginPath`.
299
- The bundled runtime and plugin are used by default. `pythonPath` overrides the
300
- `PYTHON` environment variable. To choose a model, set `codexOverrides.model`.
301
- For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
302
-
303
- To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
304
- The toggle defaults off; an explicit `false` keeps it off. The setting reaches
305
- Deep Scan discovery and reducer workers, including resumed workers. Scans use
306
- isolated configuration, so a desktop toggle or personal Codex configuration does
307
- not configure an SDK scan. See [Daybreak opt-in](docs/cli.md#daybreak-opt-in) for
308
- CLI, project-file, and direct plugin configuration.
309
-
310
- Deep Scan discovery, reducer, and resumed workers inherit per-scan provider,
311
- authentication, environment, and executable settings with read-only permissions.
312
-
313
- Scans use an isolated Codex configuration. See
314
- [runtime configuration](docs/cli.md#runtime-configuration-and-worker-limits)
315
- for supported overrides and defaults.
316
-
317
- Windows defaults to `windows.sandbox = "elevated"` to enforce credential read
318
- denials. Explicit `windows.sandbox` settings remain unchanged; Codex reports
319
- policies unsupported by the selected backend.
320
-
321
- ### Load a project file
322
-
323
- Load shared CLI and SDK settings explicitly:
324
-
325
- ```ts
326
- import { CodexSecurity, loadProjectConfig } from "@openai/codex-security";
327
-
328
- const { config, options } = await loadProjectConfig("codex-security.yaml");
329
- const security = new CodexSecurity(config);
330
-
331
- try {
332
- const result = await security.run("/path/to/repository", options);
333
- if (
334
- options.failureSeverity !== undefined &&
335
- result.hasFindingsAtOrAbove(options.failureSeverity)
336
- ) {
337
- process.exitCode = 1;
338
- }
339
- } finally {
340
- await security.close();
341
- }
342
- ```
343
-
344
- `run()` does not discover project files. Paths inside a file resolve from that
345
- file's directory; scope paths resolve from the repository. For a typed object,
346
- use `resolveProjectConfig(input, directory?)`. Override loaded options with
347
- `{ ...options, maxCostUsd: 5 }`.
348
-
349
- Project files are trusted configuration and can select model endpoints or start
350
- MCP servers. Keep CI scanner configuration outside the checkout being assessed.
351
- See the [project configuration guide](https://github.com/openai/codex-security/blob/main/docs/project-configuration.md)
352
- for the schema and precedence rules.
353
-
354
- ### Check inputs before scanning
355
-
356
- ```ts
357
- const plan = await security.preflight("/path/to/repository", {
358
- target: ["src"],
359
- maxCostUsd: 5,
360
- });
361
- console.log(plan);
362
- ```
363
-
364
- `preflight()` checks local inputs without starting Codex or using the network.
365
- It does not verify credentials, model access, Python, or the plugin. The CLI
366
- equivalent is `scan --dry-run`.
367
-
368
- ### Set investigation time
369
-
370
- ```ts
371
- await security.run("/path/to/repository", { maxTimeMinutes: 15 });
372
- ```
373
-
374
- `maxTimeMinutes` accepts positive fractional minutes. Standard scans use an
375
- advisory allowance, unset by default; Deep scans retain their enforced discovery
376
- limit. Scans may finish early and reporting may run longer. The CLI equivalent is
377
- `scan --max-time 15`; project files use `scan.max_time_minutes`. See
378
- [investigation time](docs/cli.md#set-investigation-time) for lifecycle and limit
379
- semantics. `maxCostUsd` and `signal` keep their existing behavior.
380
-
381
- ### Configure deep scans
382
-
383
- ```ts
384
- const result = await security.run("/path/to/repository", {
385
- mode: "deep",
386
- workers: 2,
387
- subagents: 0,
388
- stopAfterNoNew: 3,
389
- stopAfterConsecutiveErrors: 3,
390
- maxDiscoveryRuns: 10,
391
- maxTimeMinutes: 90,
392
- });
393
- ```
394
-
395
- `workers` controls concurrent discovery workers; `subagents` controls delegation
396
- within each worker. Time and run limits apply to discovery. After discovery
397
- stops, the scan combines and returns completed findings. See
398
- [deep scan settings](docs/cli.md#configure-deep-scans) for defaults and saved settings.
399
- Deep discovery retains its enforced deadline, with a default and maximum of
400
- 5760 minutes. `maxTimeHours` remains a deprecated Deep-only alias in hours.
401
-
402
- ### Progress and cost
403
-
404
- Use `onProgress` for scan progress and `onCost` for cost updates.
405
- Use `onUsageObservation` for the last reported token measurement time
406
- (`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
407
- Each reading includes its own `observedAt` timestamp and the percentage used in
408
- each reported window. A limit-only update can arrive before any token measurement.
409
-
410
- Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
411
- persisted worker sessions discovered by the SDK's existing session tracker,
412
- independently of model-emitted status markers:
413
-
414
- ```ts
415
- await security.run(repository, {
416
- onWorkerEvent(event) {
417
- console.log(`Worker ${event.worker} observed`);
418
- },
419
- });
420
- ```
421
-
422
- The callback contains only `{ kind: "observed", worker: number }`. The scan-local
423
- worker number matches `onActivity` and `onSessionEvent`; no prompts, raw thread
424
- IDs, or session contents are exposed. Each session is reported once per run,
425
- including nested workers and scan-associated validation or Deep Scan sessions.
426
- On resume, already persisted workers can be reported again. Observation ends
427
- with scan cost tracking, before `postScanPrompt`.
428
-
429
- This works with the bundled Codex version. Persistence and polling can delay
430
- notification, and missing notifications do not prove that delegation was skipped.
431
- An observed session does not establish that a worker just started or that file
432
- review has begun. The callback does not report failed spawn attempts, phase names,
433
- or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or
434
- `signal` for cancellation. Observer failures go to `onObserverError` without
435
- stopping the scan.
436
-
437
- `onWorkerStatus` reports **best-effort** phase dispatch counts from model-emitted
438
- text markers. A missing dispatch status does not mean delegation was skipped.
439
- For retired progress hooks, see [older progress integrations](#older-progress-integrations).
440
-
441
- `onSessionEvent` receives saved events with thread IDs and worker numbers and can
442
- contain source code or credentials. Deep scans additionally expose durable
443
- independent-review counts through `onDeepProgress`: `completed`, `active`, and
444
- `maximum`. The maximum is a configured cap, not a percentage denominator. The
445
- optional `consolidating` flag reports when results are being combined or the
446
- coordinator has finished.
447
- `ScanOptions` lists all callbacks.
448
-
449
- Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
450
- allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
451
- short-context estimate; in-flight requests can exceed it. Post-scan prompts run
452
- outside that limit. Matching earlier findings can also make model calls.
453
- See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.
454
-
455
- ### Validate an existing finding
456
-
457
- ```ts
458
- import { writeFile } from "node:fs/promises";
459
-
460
- const result = await security.validate({
461
- repositoryPath: "/path/to/repository",
462
- finding: {
463
- title: "Possible SQL injection",
464
- location: "src/query.ts:42",
465
- },
466
- });
467
- console.log(result.disposition, result.report);
468
- await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
469
- ```
470
-
471
- Pass finding text or a JSON-serializable object, not a file path. Standalone
472
- validation uses source evidence in a read-only, offline session. It does not build
473
- the target, execute application code, run tests or PoCs, or add a scan to history.
474
- The validator returns the assessment without writing report files. The example
475
- saves `result.report` in an existing directory. `outputDir` selects the session
476
- directory, not a report destination. Callers that previously read reports from it
477
- must save `result.report` instead.
478
- Callers needing runtime proof must arrange a separate reproduction step. Standard,
479
- Deep, and diff scan validation keep their existing workflows.
480
-
481
- The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
482
- `reportable` can rely on static analysis; `deferred` means there is insufficient
483
- evidence. Failed or malformed responses reject the promise. `outputDir`, `auth`,
484
- and `signal` are also supported.
485
-
486
- To validate GitHub code scanning alerts, first import them with
487
- `importGitHubCodeScanningAlerts()`. See the
488
- [import guide](docs/cli.md#import-alerts-from-the-cli) for CLI and SDK examples.
489
-
490
- For host-managed model execution, use `validateRecords()` or `validate --records`.
491
- See [host-provided standalone validation](docs/validate-records.md).
492
-
493
- ### Generate and verify a patch
494
-
495
- `patch()` runs the bundled remediation workflow non-interactively against a
496
- workspace that the caller has intentionally made writable:
497
-
498
- ```ts
499
- const security = new CodexSecurity();
500
- try {
501
- const result = await security.patch({
502
- repositoryPath: "/path/to/disposable/workspace",
503
- finding: {
504
- title: "Possible SQL injection",
505
- summary: "User input reaches a raw SQL query.",
506
- locations: [{ path: "src/query.ts", startLine: 42 }],
507
- },
508
- signal,
509
- onActivity(activity) {
510
- console.log(activity.description);
511
- },
512
- onCost(cost) {
513
- console.log(cost.estimatedUsd);
514
- },
515
- });
516
-
517
- switch (result.status) {
518
- case "verified":
519
- case "no_change":
520
- console.log(result.verificationReport);
521
- break;
522
- case "blocked":
523
- case "failed":
524
- console.error(result.reason);
525
- break;
526
- }
527
- } finally {
528
- await security.close();
529
- }
530
- ```
531
-
532
- Pass literal finding text or a JSON-serializable object; strings are never read
533
- as file paths. Sandboxed patch commands may edit only `repositoryPath` and run
534
- without network access or web search. Patch workspaces are always treated as
535
- untrusted Codex projects, so repository-local Codex configuration and MCP
536
- servers are not loaded. Host-configured tools retain their host permissions.
537
- The method does not create a commit, push, open a pull request, publish findings,
538
- change remote finding state, or add a scan to history.
539
- Callers remain responsible for reviewing and deriving the authoritative diff,
540
- approval, commit creation, and delivery.
541
-
542
- The discriminated result reports `verified`, `no_change`, `blocked`, or
543
- `failed`, plus repository-relative `changedFiles`, `threadId`, and estimated
544
- `cost` when model pricing and usage are available. Verified and no-change
545
- results include `verificationReport`; blocked and failed results include
546
- `reason`. Transport, authentication, cancellation, incomplete turns, and
547
- malformed results reject the promise. Failed, blocked, or interrupted operations
548
- can leave partial workspace changes for the caller to inspect or discard.
549
-
550
- `changedFiles` is model-reported metadata, not the authoritative diff.
551
- Patch-risk assessment is not included in this API.
552
-
553
- Patch operations reuse constructor configuration and credentials. Pass `auth`,
554
- `safetyIdentifier`, `model`, or `reasoningEffort` for per-call selection.
555
- `onActivity`, `onSessionEvent`, `onCost`, `onReconnect`, `onAuthentication`,
556
- `onWarning`, and `onObserverError` use the same observer contracts as scans.
557
-
558
- ## CLI
559
-
560
- After [installing the CLI](#install-the-cli), sign in if needed:
561
-
562
- ```bash
563
- cs login
564
- ```
565
-
566
- From your repository, optionally [draft a `SECURITY.md`](#generate-a-security-policy)
567
- that explains what counts as a security issue in your project:
568
-
569
- ```bash
570
- cs policy .
571
- ```
572
-
573
- The draft is saved outside your repository. Review the diff and notes, edit the
574
- draft, then copy only `SECURITY.md` to the **Policy target** shown. Skip this step
575
- to keep your current policy or scan without one.
576
-
577
- Then scan the repository:
578
-
579
- ```bash
580
- cs scan .
581
- ```
582
-
583
- To narrow the scan scope or check the configuration before scanning:
584
-
585
- ```bash
586
- cs scan . --path src --path tests
587
- cs scan . --diff origin/main --json
588
- cs scan . --dry-run
589
- ```
590
-
591
- Use `--help` to find commands and `<command> --help` for options. Scans are
592
- report-only by default. Add `--fail-on-severity high` to return exit code `1`
593
- for high or critical findings; execution and required-output failures return `2`.
594
- Scope exclusions and follow-up notes do not change a completed scan's exit code.
595
-
596
- The [CLI reference](docs/cli.md) covers scan history, reruns, bulk and component
597
- scans, custom validation, imports, patching, and integrations.
598
-
599
- ### Generate a security policy
600
-
601
- Use `policy` to draft a new `SECURITY.md` or update an existing one. To select a
602
- component:
603
-
604
- ```bash
605
- cs policy . --path services/api
606
- ```
607
-
608
- Existing files stay unchanged until you review and copy the draft to the
609
- **Policy target** shown. Scans already use root and component policies; you can
610
- keep them without generating new ones.
611
-
612
- The SDK provides `generatePolicy()`, `preflightPolicy()`, and `previewPolicy()`. See
613
- [policy generation](docs/cli.md#generate-a-security-policy) for SDK examples,
614
- policy locations and reporting instructions, headless use, and saved artifacts.
615
-
616
- ### Exports and CI
617
-
618
- Export a completed scan's findings to a SARIF file:
619
-
620
- ```bash
621
- cs export /path/to/scan-results --output results.sarif
622
- ```
623
-
624
- Replace `/path/to/scan-results` with the results directory printed by `scan`.
625
- Export reads saved results, so you don't need to rerun the scan or sign in.
626
-
627
- See [exports and CI](docs/cli.md#exports-and-ci) for source fingerprints, other
628
- formats, threat models, and the `exportArtifact()` SDK method. For repository or
629
- pull request scans in GitHub Actions, use the
630
- [GitHub Action guide](https://github.com/openai/codex-security/blob/main/github-action/README.md).
631
- Separate examples cover
632
- [GitHub Actions with Bedrock](https://github.com/openai/codex-security/blob/main/examples/github-actions/README.md)
633
- and [Azure Pipelines](https://github.com/openai/codex-security/blob/main/examples/azure-pipelines/README.md).
634
-
635
- ### Classify finding severity
636
-
637
- Use `classify-severity` to assess saved findings with the built-in severity rubric
638
- or an explicit custom rubric, without changing their original severity or evidence.
639
- Each finding receives three independent reviews by default; the most common severity wins,
640
- with the highest severity breaking ties among the top vote counts.
641
- Use `--runs N` to request 1–10 reviews (default: 3). The SDK exposes `classifySeverity()`,
642
- `classifyScanSeverity()`, and `classifyScanDirectorySeverity()`. See
643
- [severity classification](docs/cli.md#classify-finding-severity) for selection,
644
- checkpointing, and publication behavior.
645
-
646
- For canonical records without a saved scan, use `classify-severity --records`
647
- or `classifySeverityRecords()` with [host-provided execution](docs/classify-severity-records.md).
648
-
649
- ### Suggest finding owners
650
-
651
- Use `suggest-owners` or the SDK's `suggestOwners()` to suggest contributors based
652
- on CODEOWNERS, source, and Git history. Declared owners take priority over Git
653
- contributors. Suggestions do not assign tickets. See
654
- [owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.
655
-
656
- ### Publish findings to Cloud
657
-
658
- `publish scan --to cloud` uploads selected findings to Codex Security Cloud.
659
- It requires ChatGPT credentials; inference API keys and AWS credentials do not
660
- grant Cloud access. See [Cloud publication](docs/cli.md#publish-completed-scans)
661
- for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
662
- for issue creation.
663
-
664
- ### Import external findings
665
-
666
- External vendor imports are opt-in. Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`
667
- to enable `publish findings`, `findings imported`, `import sonar`, `import github-advisories`, and
668
- the SDK's external publication, local import/readback, Sonar issue collection, and advisory acquisition
669
- APIs. They are disabled otherwise; CLI commands are hidden from help and schemas.
670
- SDK callers can supply the flag through the existing per-call
671
- `dependencies.environment`, or in `options.environment` for `collectSonarIssues(options)`.
672
- For an SDK import of selected Sonar issues, pass their keys in `options.issueKeys`.
673
- Omit `issueKeys` to collect the project's open security issues. An empty list is rejected.
674
- If you know the source repository, pass its Git URL in `options.sourceRepositoryUrl`
675
- to check the Sonar binding before fetching issues.
676
- Pure normalizers and file readers remain available.
677
- For AWS Continuum code findings, use `readContinuumFindings(path, sourceRepositoryUrl)`
678
- with a saved list or detail response, or `normalizeContinuumFindings(input, sourceRepositoryUrl)`
679
- with parsed JSON. Verify the repository for the selected findings before passing its Git URL.
680
- [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
681
-
682
- Use `normalizeSelectedSemgrepPlatformFindings` for selected SAST findings from saved
683
- 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).
684
- This does not affect scan publishing or the existing GitHub alert collector.
685
-
686
- The SDK also exposes `prepareExternalPublication(file, options)` for supported
687
- vendor exports and `prepareNormalizedExternalPublication(findings, options)` for
688
- normalized external evidence from any provider in the Cloud import contract.
689
- The normalized API accepts `NormalizedExternalPublicationOptions`; file readers
690
- use `ExternalPublicationOptions` for their supported formats. Both resolve the Cloud repository and return a
691
- `preview` plus a separate `publish()` operation. Inspect the preview before
692
- calling `publish()`. Imported evidence remains not assessed by Codex, and saved
693
- requests and receipts support retries after interruption.
694
-
695
- For CLI examples and supported input formats, see the
696
- [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md).
697
-
698
- The SDK's `prepareLocalExternalImport(file, options)` returns a `preview` and a
699
- separate `import()` operation. `prepareNormalizedLocalImport(findings,
700
- options)` accepts already normalized evidence, and
701
- `listLocalExternalFindings({ repository })` reads the stored records. Imports
702
- remain unassessed source evidence, separate from native scan findings. Repeated
703
- imports update the same repository/provider/source-key/source-ID record; omitted
704
- records remain stored, and unknown evidence fields are not inferred.
705
-
706
- File imports forward repository references from the reader automatically. With
707
- `prepareNormalizedLocalImport()`, supply additional known references in the
708
- third argument's `sourceRepositories` when they are absent from
709
- `evidence.details.repository.url`. For a known GitHub custom host, include
710
- `platform: "github"`, for example `{ sourceRepositories: [{ url:
711
- "https://git.example.test/example/project", platform: "github" }] }`. Named Wiz
712
- reports carry this platform in their repository inventory. If you export only the
713
- normalized finding rows to JSONL, supply that metadata separately; the original
714
- finding evidence does not include the surrounding inventory.
715
-
716
- ## Findings storage and deduplication
717
-
718
- Saved-scan deduplication uses local SQLite directly:
719
-
720
- ```bash
721
- cs dedupe --scan SCAN_ID --json
722
- ```
723
-
724
- The [findings guide](docs/findings-service.md) covers local storage, embedding
725
- credentials, deduplication, backups, and independently operated HTTP endpoints.
726
- For an older service deployment, see [migration guidance](docs/findings-service.md#local-service-removal).
727
- For records stored in your own system, see
728
- [SDK records deduplication](docs/dedupe-records.md).
729
-
730
- ## Containerized bulk scans
731
-
732
- Use the scanner image and Compose files to scan a list of repositories with
733
- persistent results and authentication. See
734
- [containerized bulk scans](docs/cli.md#containerized-bulk-scans) for setup, or the
735
- [workflow runner](https://github.com/openai/codex-security/blob/main/docker/README.md#workflow-runner)
736
- for individual CLI stages in containers.
71
+ By default, results are saved in the private Codex Security state directory.
72
+ Open the Markdown report at the CLI’s **REPORT** path or the SDK’s
73
+ `result.reportPath`. Reports and logs can contain source code, credentials, and
74
+ vulnerability details. Review them before sharing.
737
75
 
738
76
  ## Local security model
739
77
 
740
- Codex Security runs with your operating-system permissions. Scan subprocesses
741
- can inherit your environment, so start them with only the credentials they need.
742
- Local tools running under the same account are trusted.
743
-
744
- The scan profile allows reads across the local filesystem and writes to workspace
745
- roots. Execution approvals are reviewed automatically and may grant extra
746
- permissions for an operation. Set `codexOverrides.approval_policy: "never"`
747
- (or CLI `--codex 'approval_policy="never"'`) to deny permission requests.
748
- If you select a Codex profile, its explicit `approval_policy` takes precedence
749
- over the root setting.
750
- Host and network restrictions still apply.
751
-
752
- Repository contents, model output, and imported artifacts do not authorize
753
- access to other targets, disclosure of credentials, or writes outside approved
754
- paths. Keep state and scan artifacts private and outside the repository.
755
-
756
- ## Compatibility
757
-
758
- ### Custom plugins
759
-
760
- New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
761
- `workerProviderSnapshot: 4`, and isolated worker configuration support. Older
762
- custom plugins fail before scan execution; update the plugin or omit `pluginPath`
763
- to use the bundled version. Reading saved reports does not require these
764
- execution capabilities.
765
-
766
- Use the current shell or Windows launcher for runtime-root routing. The SDK does
767
- not adapt the older `node ./mcp/server.mjs` MCP entrypoint.
768
-
769
- Custom plugins must support the current workbench protocol for scan comparison
770
- and archival. The SDK does not adapt older payloads or archive scan directories
771
- on behalf of older workbench implementations.
772
-
773
- ### Older progress integrations
774
-
775
- The helper-derived `kind: "preflight"` event, `config_preflight.py` helper, and
776
- custom capability registries are retired. This includes the `preflightChecks`
777
- progress-tool input and workbench `--preflight-issues-json` /
778
- `--preflight-issues-json-stdin` arguments. Scans use available runtime tools and
779
- parent fallback without a capability registry. Saved preflight history remains
780
- readable. Local `preflight()` input checks, authentication, sandbox enforcement,
781
- and Deep worker configuration still apply.
782
-
783
- ### Error types
784
-
785
- `LocalPluginBootstrapError` identifies local plugin setup failures and extends
786
- `PluginBootstrapError`, so existing catches keep working. Knowledge-base
787
- preparation errors use `ConfigurationError`; wrapped diagnostics remain in `cause`.
78
+ Scans run with your operating-system permissions. Start them with only the
79
+ credentials they need because subprocesses can inherit your environment.
788
80
 
789
81
  ## Documentation and security
790
82
 
791
- - [Online SDK guide](https://learn.chatgpt.com/docs/security/sdk)
792
- - [CLI reference](docs/cli.md)
793
- - [Findings guide](docs/findings-service.md)
794
- - [GitHub issues](https://github.com/openai/codex-security/issues) for bugs and feature requests
795
- - [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for private vulnerability reporting
83
+ - [CLI reference](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md) for scan options, authentication, and exports.
84
+ - [SDK guide](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/sdk.md) for configuration, progress events, and the full set of examples.
85
+ - [Security policy](https://github.com/openai/codex-security/blob/main/SECURITY.md) for reporting vulnerabilities in this package privately.