@openai/codex-security 0.8.2 → 0.9.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 (649) hide show
  1. package/README.md +201 -178
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +6 -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 +51 -14
  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/core-scan.md +14 -5
  26. package/_bundled_plugin/references/default-severity-rubric.md +33 -0
  27. package/_bundled_plugin/references/final-report.md +5 -3
  28. package/_bundled_plugin/references/finding-detail-fields.md +19 -18
  29. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  30. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  31. package/_bundled_plugin/references/scan-contract.md +27 -33
  32. package/_bundled_plugin/references/threat-model.md +1 -0
  33. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  34. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  35. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  36. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  37. package/_bundled_plugin/scripts/deep_scan_workbench.py +188 -454
  38. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  39. package/_bundled_plugin/scripts/finalize_scan_contract.py +317 -377
  40. package/_bundled_plugin/scripts/finding_preview.py +25 -29
  41. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  42. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  43. package/_bundled_plugin/scripts/posix_scan_local_files.py +198 -0
  44. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  45. package/_bundled_plugin/scripts/report_projection.py +167 -178
  46. package/_bundled_plugin/scripts/review_state.py +8 -2
  47. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  48. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  49. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  50. package/_bundled_plugin/scripts/validate_scan_contract.py +9 -7
  51. package/_bundled_plugin/scripts/windows_scan_local_files.py +600 -72
  52. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  53. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  54. package/_bundled_plugin/scripts/workbench/retained_coverage.py +38 -75
  55. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  56. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  57. package/_bundled_plugin/scripts/workbench/saved_coverage.py +152 -248
  58. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  59. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  60. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  61. package/_bundled_plugin/scripts/workbench_cli.py +121 -14
  62. package/_bundled_plugin/scripts/workbench_constants.py +19 -0
  63. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  64. package/_bundled_plugin/scripts/workbench_db.py +550 -492
  65. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  66. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  67. package/_bundled_plugin/scripts/workbench_finding_workflows.py +90 -4
  68. package/_bundled_plugin/scripts/workbench_native_indexes.py +29 -33
  69. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  70. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  71. package/_bundled_plugin/scripts/workbench_remediation.py +508 -11
  72. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  73. package/_bundled_plugin/scripts/workbench_scan_history.py +139 -80
  74. package/_bundled_plugin/scripts/workbench_scan_start.py +84 -25
  75. package/_bundled_plugin/scripts/workbench_scan_usage.py +666 -117
  76. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  77. package/_bundled_plugin/scripts/workbench_setup.py +251 -0
  78. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  79. package/_bundled_plugin/scripts/workbench_source_scopes.py +33 -23
  80. package/_bundled_plugin/scripts/workbench_target.py +330 -66
  81. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  82. package/_bundled_plugin/scripts/workbench_validation.py +44 -12
  83. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -16
  84. package/_bundled_plugin/shared/workbench-migrations.json +53 -0
  85. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  86. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  87. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  88. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  89. package/_bundled_plugin/skills/cloud-findings/SKILL.md +6 -4
  90. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  91. package/_bundled_plugin/skills/fix-finding/SKILL.md +19 -2
  92. package/_bundled_plugin/skills/publish-findings/SKILL.md +81 -45
  93. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  94. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +5 -24
  95. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  96. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +36 -9
  97. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  98. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  99. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +12 -6
  100. package/dist/api.d.ts +45 -5
  101. package/dist/api.d.ts.map +1 -1
  102. package/dist/api.js +1144 -411
  103. package/dist/api.js.map +1 -1
  104. package/dist/auth.d.ts.map +1 -1
  105. package/dist/auth.js +10 -7
  106. package/dist/auth.js.map +1 -1
  107. package/dist/bedrock-oss-pricing.d.ts +6 -0
  108. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  109. package/dist/bedrock-oss-pricing.js +58 -0
  110. package/dist/bedrock-oss-pricing.js.map +1 -0
  111. package/dist/bedrock-pricing.d.ts +15 -0
  112. package/dist/bedrock-pricing.d.ts.map +1 -0
  113. package/dist/bedrock-pricing.js +117 -0
  114. package/dist/bedrock-pricing.js.map +1 -0
  115. package/dist/blackduck-findings.d.ts +8 -0
  116. package/dist/blackduck-findings.d.ts.map +1 -0
  117. package/dist/blackduck-findings.js +320 -0
  118. package/dist/blackduck-findings.js.map +1 -0
  119. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  120. package/dist/bulk-scan-discovery.js +51 -36
  121. package/dist/bulk-scan-discovery.js.map +1 -1
  122. package/dist/checkmarx-evidence.d.ts +19 -0
  123. package/dist/checkmarx-evidence.d.ts.map +1 -0
  124. package/dist/checkmarx-evidence.js +36 -0
  125. package/dist/checkmarx-evidence.js.map +1 -0
  126. package/dist/checkmarx-findings.d.ts +4 -0
  127. package/dist/checkmarx-findings.d.ts.map +1 -0
  128. package/dist/checkmarx-findings.js +27 -0
  129. package/dist/checkmarx-findings.js.map +1 -0
  130. package/dist/checkmarx-one.d.ts +4 -0
  131. package/dist/checkmarx-one.d.ts.map +1 -0
  132. package/dist/checkmarx-one.js +53 -0
  133. package/dist/checkmarx-one.js.map +1 -0
  134. package/dist/checkmarx-repository.d.ts +12 -0
  135. package/dist/checkmarx-repository.d.ts.map +1 -0
  136. package/dist/checkmarx-repository.js +181 -0
  137. package/dist/checkmarx-repository.js.map +1 -0
  138. package/dist/checkmarx-xml.d.ts +12 -0
  139. package/dist/checkmarx-xml.d.ts.map +1 -0
  140. package/dist/checkmarx-xml.js +196 -0
  141. package/dist/checkmarx-xml.js.map +1 -0
  142. package/dist/classify-severity-records.d.ts +6 -9
  143. package/dist/classify-severity-records.d.ts.map +1 -1
  144. package/dist/classify-severity-records.js +9 -21
  145. package/dist/classify-severity-records.js.map +1 -1
  146. package/dist/classify-severity.d.ts +4 -1
  147. package/dist/classify-severity.d.ts.map +1 -1
  148. package/dist/classify-severity.js +30 -13
  149. package/dist/classify-severity.js.map +1 -1
  150. package/dist/cli.d.ts +14 -5
  151. package/dist/cli.d.ts.map +1 -1
  152. package/dist/cli.js +2112 -1266
  153. package/dist/cli.js.map +1 -1
  154. package/dist/cloud-publish.js +2 -2
  155. package/dist/cloud-publish.js.map +1 -1
  156. package/dist/codex-prompt.d.ts +2 -0
  157. package/dist/codex-prompt.d.ts.map +1 -1
  158. package/dist/codex-prompt.js +6 -0
  159. package/dist/codex-prompt.js.map +1 -1
  160. package/dist/component-scan.d.ts +16 -3
  161. package/dist/component-scan.d.ts.map +1 -1
  162. package/dist/component-scan.js +32 -6
  163. package/dist/component-scan.js.map +1 -1
  164. package/dist/config.d.ts +2 -1
  165. package/dist/config.d.ts.map +1 -1
  166. package/dist/config.js +221 -65
  167. package/dist/config.js.map +1 -1
  168. package/dist/continuum-findings.d.ts +7 -0
  169. package/dist/continuum-findings.d.ts.map +1 -0
  170. package/dist/continuum-findings.js +225 -0
  171. package/dist/continuum-findings.js.map +1 -0
  172. package/dist/contract-values.d.ts +30 -0
  173. package/dist/contract-values.d.ts.map +1 -0
  174. package/dist/contract-values.js +78 -0
  175. package/dist/contract-values.js.map +1 -0
  176. package/dist/contract.d.ts +2 -20
  177. package/dist/contract.d.ts.map +1 -1
  178. package/dist/contract.js +58 -669
  179. package/dist/contract.js.map +1 -1
  180. package/dist/cost-model.d.ts +13 -1
  181. package/dist/cost-model.d.ts.map +1 -1
  182. package/dist/cost-model.js +66 -115
  183. package/dist/cost-model.js.map +1 -1
  184. package/dist/cost.d.ts +61 -4
  185. package/dist/cost.d.ts.map +1 -1
  186. package/dist/cost.js +2560 -100
  187. package/dist/cost.js.map +1 -1
  188. package/dist/custom-publish.d.ts +4 -0
  189. package/dist/custom-publish.d.ts.map +1 -1
  190. package/dist/custom-publish.js +40 -3
  191. package/dist/custom-publish.js.map +1 -1
  192. package/dist/custom-validation-prompt.d.ts +1 -1
  193. package/dist/custom-validation-prompt.d.ts.map +1 -1
  194. package/dist/custom-validation-prompt.js +5 -0
  195. package/dist/custom-validation-prompt.js.map +1 -1
  196. package/dist/custom-validation.d.ts +2 -0
  197. package/dist/custom-validation.d.ts.map +1 -1
  198. package/dist/custom-validation.js +4 -0
  199. package/dist/custom-validation.js.map +1 -1
  200. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  201. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  202. package/dist/deduplication/deduplication-prompts.js +2 -2
  203. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  204. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  205. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  206. package/dist/deduplication/deduplication-reviewer.js +11 -4
  207. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  208. package/dist/deduplication/deduplication.js.map +1 -1
  209. package/dist/deduplication/finding-schema.d.ts +19 -1
  210. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  211. package/dist/deduplication/finding-schema.js +25 -0
  212. package/dist/deduplication/finding-schema.js.map +1 -1
  213. package/dist/deduplication/local.d.ts +2 -2
  214. package/dist/deduplication/local.d.ts.map +1 -1
  215. package/dist/deduplication/local.js +5 -10
  216. package/dist/deduplication/local.js.map +1 -1
  217. package/dist/deduplication/records.d.ts +8 -2
  218. package/dist/deduplication/records.d.ts.map +1 -1
  219. package/dist/deduplication/records.js +36 -8
  220. package/dist/deduplication/records.js.map +1 -1
  221. package/dist/deduplication/refusal.d.ts.map +1 -1
  222. package/dist/deduplication/refusal.js +25 -5
  223. package/dist/deduplication/refusal.js.map +1 -1
  224. package/dist/deduplication/scan.d.ts +3 -0
  225. package/dist/deduplication/scan.d.ts.map +1 -1
  226. package/dist/deduplication/scan.js +1 -1
  227. package/dist/deduplication/scan.js.map +1 -1
  228. package/dist/deep-config.d.ts +0 -1
  229. package/dist/deep-config.d.ts.map +1 -1
  230. package/dist/deep-config.js +22 -33
  231. package/dist/deep-config.js.map +1 -1
  232. package/dist/deep-scan-defaults.d.ts +2 -0
  233. package/dist/deep-scan-defaults.d.ts.map +1 -1
  234. package/dist/deep-scan-defaults.js +28 -1
  235. package/dist/deep-scan-defaults.js.map +1 -1
  236. package/dist/deep-scan.d.ts +13 -0
  237. package/dist/deep-scan.d.ts.map +1 -1
  238. package/dist/deep-scan.js +262 -7
  239. package/dist/deep-scan.js.map +1 -1
  240. package/dist/default-severity-rubric.d.ts +1 -2
  241. package/dist/default-severity-rubric.d.ts.map +1 -1
  242. package/dist/default-severity-rubric.js +2 -66
  243. package/dist/default-severity-rubric.js.map +1 -1
  244. package/dist/endor-findings.d.ts +3 -1
  245. package/dist/endor-findings.d.ts.map +1 -1
  246. package/dist/endor-findings.js +108 -80
  247. package/dist/endor-findings.js.map +1 -1
  248. package/dist/errors.d.ts +1 -1
  249. package/dist/errors.d.ts.map +1 -1
  250. package/dist/errors.js +9 -2
  251. package/dist/errors.js.map +1 -1
  252. package/dist/external-findings-import.d.ts +5 -3
  253. package/dist/external-findings-import.d.ts.map +1 -1
  254. package/dist/external-findings-import.js +11 -16
  255. package/dist/external-findings-import.js.map +1 -1
  256. package/dist/external-findings-local.d.ts +15 -4
  257. package/dist/external-findings-local.d.ts.map +1 -1
  258. package/dist/external-findings-local.js +619 -225
  259. package/dist/external-findings-local.js.map +1 -1
  260. package/dist/external-findings-publish.d.ts +20 -6
  261. package/dist/external-findings-publish.d.ts.map +1 -1
  262. package/dist/external-findings-publish.js +2356 -308
  263. package/dist/external-findings-publish.js.map +1 -1
  264. package/dist/external-findings-read.d.ts +28 -2
  265. package/dist/external-findings-read.d.ts.map +1 -1
  266. package/dist/external-findings-read.js +174 -81
  267. package/dist/external-findings-read.js.map +1 -1
  268. package/dist/external-findings.d.ts +17 -3
  269. package/dist/external-findings.d.ts.map +1 -1
  270. package/dist/external-findings.js +153 -1
  271. package/dist/external-findings.js.map +1 -1
  272. package/dist/external-import-contract.d.ts +33 -1
  273. package/dist/external-import-contract.d.ts.map +1 -1
  274. package/dist/external-import-contract.js +335 -51
  275. package/dist/external-import-contract.js.map +1 -1
  276. package/dist/external-import-models.d.ts +1 -1
  277. package/dist/external-import-models.d.ts.map +1 -1
  278. package/dist/external-import-models.js.map +1 -1
  279. package/dist/feedback.d.ts.map +1 -1
  280. package/dist/feedback.js +5 -4
  281. package/dist/feedback.js.map +1 -1
  282. package/dist/finding-prompt.d.ts +5 -0
  283. package/dist/finding-prompt.d.ts.map +1 -0
  284. package/dist/finding-prompt.js +32 -0
  285. package/dist/finding-prompt.js.map +1 -0
  286. package/dist/finding-retrieval.d.ts +3 -3
  287. package/dist/finding-retrieval.d.ts.map +1 -1
  288. package/dist/finding-retrieval.js.map +1 -1
  289. package/dist/finding-workflow.d.ts +6 -1
  290. package/dist/finding-workflow.d.ts.map +1 -1
  291. package/dist/finding-workflow.js +2 -2
  292. package/dist/finding-workflow.js.map +1 -1
  293. package/dist/findings-client.d.ts +1 -0
  294. package/dist/findings-client.d.ts.map +1 -1
  295. package/dist/findings-client.js +27 -3
  296. package/dist/findings-client.js.map +1 -1
  297. package/dist/git-remote.d.ts +4 -0
  298. package/dist/git-remote.d.ts.map +1 -1
  299. package/dist/git-remote.js +20 -0
  300. package/dist/git-remote.js.map +1 -1
  301. package/dist/github-advisories.d.ts +3 -12
  302. package/dist/github-advisories.d.ts.map +1 -1
  303. package/dist/github-advisories.js +9 -31
  304. package/dist/github-advisories.js.map +1 -1
  305. package/dist/github-dependabot-findings.d.ts.map +1 -1
  306. package/dist/github-dependabot-findings.js +22 -20
  307. package/dist/github-dependabot-findings.js.map +1 -1
  308. package/dist/github-findings.d.ts +4 -1
  309. package/dist/github-findings.d.ts.map +1 -1
  310. package/dist/github-findings.js +392 -79
  311. package/dist/github-findings.js.map +1 -1
  312. package/dist/github.d.ts +17 -7
  313. package/dist/github.d.ts.map +1 -1
  314. package/dist/github.js +43 -30
  315. package/dist/github.js.map +1 -1
  316. package/dist/host-protocol.d.ts +2 -2
  317. package/dist/host-protocol.d.ts.map +1 -1
  318. package/dist/host-protocol.js.map +1 -1
  319. package/dist/host-records-protocol.d.ts +10 -11
  320. package/dist/host-records-protocol.d.ts.map +1 -1
  321. package/dist/host-records-protocol.js +69 -9
  322. package/dist/host-records-protocol.js.map +1 -1
  323. package/dist/hosted-git-remotes.d.ts +5 -0
  324. package/dist/hosted-git-remotes.d.ts.map +1 -0
  325. package/dist/hosted-git-remotes.js +285 -0
  326. package/dist/hosted-git-remotes.js.map +1 -0
  327. package/dist/hosted-git-repository.d.ts +28 -0
  328. package/dist/hosted-git-repository.d.ts.map +1 -0
  329. package/dist/hosted-git-repository.js +222 -0
  330. package/dist/hosted-git-repository.js.map +1 -0
  331. package/dist/hosted-scan-protocol.js +2 -2
  332. package/dist/hosted-scan-protocol.js.map +1 -1
  333. package/dist/hosted-scan.d.ts +15 -0
  334. package/dist/hosted-scan.d.ts.map +1 -1
  335. package/dist/hosted-scan.js +71 -44
  336. package/dist/hosted-scan.js.map +1 -1
  337. package/dist/hosted-scanner-http.d.ts +21 -0
  338. package/dist/hosted-scanner-http.d.ts.map +1 -0
  339. package/dist/hosted-scanner-http.js +204 -0
  340. package/dist/hosted-scanner-http.js.map +1 -0
  341. package/dist/hosted-scanner-v1.d.ts +6 -0
  342. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  343. package/dist/hosted-scanner-v1.js +60 -0
  344. package/dist/hosted-scanner-v1.js.map +1 -0
  345. package/dist/import-scan.d.ts.map +1 -1
  346. package/dist/import-scan.js +3 -0
  347. package/dist/import-scan.js.map +1 -1
  348. package/dist/index.d.ts +24 -6
  349. package/dist/index.d.ts.map +1 -1
  350. package/dist/index.js +15 -1
  351. package/dist/index.js.map +1 -1
  352. package/dist/inspector-findings.d.ts.map +1 -1
  353. package/dist/inspector-findings.js +58 -81
  354. package/dist/inspector-findings.js.map +1 -1
  355. package/dist/knowledge-base.d.ts.map +1 -1
  356. package/dist/knowledge-base.js +86 -10
  357. package/dist/knowledge-base.js.map +1 -1
  358. package/dist/local-git-metadata.d.ts +5 -0
  359. package/dist/local-git-metadata.d.ts.map +1 -0
  360. package/dist/local-git-metadata.js +130 -0
  361. package/dist/local-git-metadata.js.map +1 -0
  362. package/dist/multiscan.d.ts +6 -4
  363. package/dist/multiscan.d.ts.map +1 -1
  364. package/dist/multiscan.js +160 -77
  365. package/dist/multiscan.js.map +1 -1
  366. package/dist/native-json-findings.d.ts +2 -1
  367. package/dist/native-json-findings.d.ts.map +1 -1
  368. package/dist/native-json-findings.js +12 -2
  369. package/dist/native-json-findings.js.map +1 -1
  370. package/dist/opengrep-findings.d.ts +1 -0
  371. package/dist/opengrep-findings.d.ts.map +1 -1
  372. package/dist/opengrep-findings.js +49 -31
  373. package/dist/opengrep-findings.js.map +1 -1
  374. package/dist/operation-telemetry.d.ts +104 -0
  375. package/dist/operation-telemetry.d.ts.map +1 -0
  376. package/dist/operation-telemetry.js +293 -0
  377. package/dist/operation-telemetry.js.map +1 -0
  378. package/dist/patch-tui.d.ts.map +1 -1
  379. package/dist/patch-tui.js +90 -35
  380. package/dist/patch-tui.js.map +1 -1
  381. package/dist/plugin-python-probe.d.ts +4 -0
  382. package/dist/plugin-python-probe.d.ts.map +1 -0
  383. package/dist/plugin-python-probe.js +10 -0
  384. package/dist/plugin-python-probe.js.map +1 -0
  385. package/dist/private-finding-import.d.ts +341 -0
  386. package/dist/private-finding-import.d.ts.map +1 -0
  387. package/dist/private-finding-import.js +411 -0
  388. package/dist/private-finding-import.js.map +1 -0
  389. package/dist/project-config.d.ts.map +1 -1
  390. package/dist/project-config.js +2 -2
  391. package/dist/project-config.js.map +1 -1
  392. package/dist/provider-profile.d.ts +11 -3
  393. package/dist/provider-profile.d.ts.map +1 -1
  394. package/dist/provider-profile.js +80 -11
  395. package/dist/provider-profile.js.map +1 -1
  396. package/dist/publication-telemetry.d.ts +45 -0
  397. package/dist/publication-telemetry.d.ts.map +1 -0
  398. package/dist/publication-telemetry.js +50 -0
  399. package/dist/publication-telemetry.js.map +1 -0
  400. package/dist/publication.js +7 -1
  401. package/dist/publication.js.map +1 -1
  402. package/dist/publish.d.ts +4 -0
  403. package/dist/publish.d.ts.map +1 -1
  404. package/dist/publish.js +42 -2
  405. package/dist/publish.js.map +1 -1
  406. package/dist/reader-selection.d.ts +15 -0
  407. package/dist/reader-selection.d.ts.map +1 -0
  408. package/dist/reader-selection.js +89 -0
  409. package/dist/reader-selection.js.map +1 -0
  410. package/dist/record.d.ts +6 -1
  411. package/dist/record.d.ts.map +1 -1
  412. package/dist/record.js +53 -2
  413. package/dist/record.js.map +1 -1
  414. package/dist/remediation.d.ts +3 -1
  415. package/dist/remediation.d.ts.map +1 -1
  416. package/dist/remediation.js +28 -2
  417. package/dist/remediation.js.map +1 -1
  418. package/dist/request-metadata.d.ts +3 -0
  419. package/dist/request-metadata.d.ts.map +1 -1
  420. package/dist/request-metadata.js +9 -0
  421. package/dist/request-metadata.js.map +1 -1
  422. package/dist/result.d.ts +6 -0
  423. package/dist/result.d.ts.map +1 -1
  424. package/dist/result.js +3 -1
  425. package/dist/result.js.map +1 -1
  426. package/dist/retry-windows-rename.d.ts +8 -0
  427. package/dist/retry-windows-rename.d.ts.map +1 -0
  428. package/dist/retry-windows-rename.js +24 -0
  429. package/dist/retry-windows-rename.js.map +1 -0
  430. package/dist/runtime.d.ts +22 -1
  431. package/dist/runtime.d.ts.map +1 -1
  432. package/dist/runtime.js +408 -162
  433. package/dist/runtime.js.map +1 -1
  434. package/dist/saved-scan-bootstrap.d.ts +1 -0
  435. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  436. package/dist/saved-scan-bootstrap.js +18 -15
  437. package/dist/saved-scan-bootstrap.js.map +1 -1
  438. package/dist/scan-activity.d.ts.map +1 -1
  439. package/dist/scan-activity.js +172 -64
  440. package/dist/scan-activity.js.map +1 -1
  441. package/dist/scan-comparison.d.ts +10 -5
  442. package/dist/scan-comparison.d.ts.map +1 -1
  443. package/dist/scan-comparison.js +68 -25
  444. package/dist/scan-comparison.js.map +1 -1
  445. package/dist/scan-dashboard.d.ts +7 -6
  446. package/dist/scan-dashboard.d.ts.map +1 -1
  447. package/dist/scan-dashboard.js +91 -79
  448. package/dist/scan-dashboard.js.map +1 -1
  449. package/dist/scan-executor.d.ts +12 -1
  450. package/dist/scan-executor.d.ts.map +1 -1
  451. package/dist/scan-executor.js +22 -2
  452. package/dist/scan-executor.js.map +1 -1
  453. package/dist/scan-history-renderer.d.ts.map +1 -1
  454. package/dist/scan-history-renderer.js +31 -28
  455. package/dist/scan-history-renderer.js.map +1 -1
  456. package/dist/scan-logs.d.ts +12 -0
  457. package/dist/scan-logs.d.ts.map +1 -1
  458. package/dist/scan-logs.js +106 -77
  459. package/dist/scan-logs.js.map +1 -1
  460. package/dist/scan-measurement.d.ts +26 -0
  461. package/dist/scan-measurement.d.ts.map +1 -0
  462. package/dist/scan-measurement.js +77 -0
  463. package/dist/scan-measurement.js.map +1 -0
  464. package/dist/scan-progress.d.ts +1 -0
  465. package/dist/scan-progress.d.ts.map +1 -1
  466. package/dist/scan-progress.js +3 -0
  467. package/dist/scan-progress.js.map +1 -1
  468. package/dist/scan-sessions.d.ts.map +1 -1
  469. package/dist/scan-sessions.js +4 -1
  470. package/dist/scan-sessions.js.map +1 -1
  471. package/dist/scan-settings.d.ts +1 -1
  472. package/dist/scan-settings.d.ts.map +1 -1
  473. package/dist/scan-settings.js +1 -24
  474. package/dist/scan-settings.js.map +1 -1
  475. package/dist/scanner-import.d.ts +64 -6
  476. package/dist/scanner-import.d.ts.map +1 -1
  477. package/dist/scanner-import.js +406 -48
  478. package/dist/scanner-import.js.map +1 -1
  479. package/dist/scanner-repository-url.d.ts +17 -0
  480. package/dist/scanner-repository-url.d.ts.map +1 -0
  481. package/dist/scanner-repository-url.js +71 -0
  482. package/dist/scanner-repository-url.js.map +1 -0
  483. package/dist/security-policy.d.ts +1 -1
  484. package/dist/security-policy.d.ts.map +1 -1
  485. package/dist/security-policy.js.map +1 -1
  486. package/dist/semgrep-findings.d.ts +6 -3
  487. package/dist/semgrep-findings.d.ts.map +1 -1
  488. package/dist/semgrep-findings.js +124 -88
  489. package/dist/semgrep-findings.js.map +1 -1
  490. package/dist/semgrep-guardian-findings.d.ts +38 -0
  491. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  492. package/dist/semgrep-guardian-findings.js +165 -0
  493. package/dist/semgrep-guardian-findings.js.map +1 -0
  494. package/dist/semgrep-platform-collector.d.ts +26 -0
  495. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  496. package/dist/semgrep-platform-collector.js +108 -0
  497. package/dist/semgrep-platform-collector.js.map +1 -0
  498. package/dist/semgrep-platform-findings.d.ts +213 -0
  499. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  500. package/dist/semgrep-platform-findings.js +1078 -0
  501. package/dist/semgrep-platform-findings.js.map +1 -0
  502. package/dist/semgrep-platform-v1.d.ts +6 -0
  503. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  504. package/dist/semgrep-platform-v1.js +83 -0
  505. package/dist/semgrep-platform-v1.js.map +1 -0
  506. package/dist/server/api.d.ts +1 -1
  507. package/dist/server/api.d.ts.map +1 -1
  508. package/dist/server/api.js.map +1 -1
  509. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  510. package/dist/server/embedding-tokenizer.d.ts +2 -0
  511. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  512. package/dist/server/embedding-tokenizer.js +322 -0
  513. package/dist/server/embedding-tokenizer.js.map +6 -0
  514. package/dist/server/embeddings.d.ts +16 -2
  515. package/dist/server/embeddings.d.ts.map +1 -1
  516. package/dist/server/embeddings.js +35 -5
  517. package/dist/server/embeddings.js.map +1 -1
  518. package/dist/session-lines.d.ts +5 -0
  519. package/dist/session-lines.d.ts.map +1 -0
  520. package/dist/session-lines.js +60 -0
  521. package/dist/session-lines.js.map +1 -0
  522. package/dist/severity-review.d.ts +3 -1
  523. package/dist/severity-review.d.ts.map +1 -1
  524. package/dist/severity-review.js +3 -2
  525. package/dist/severity-review.js.map +1 -1
  526. package/dist/severity-rubric.d.ts +20 -0
  527. package/dist/severity-rubric.d.ts.map +1 -0
  528. package/dist/severity-rubric.js +73 -0
  529. package/dist/severity-rubric.js.map +1 -0
  530. package/dist/severity-store.js +15 -5
  531. package/dist/severity-store.js.map +1 -1
  532. package/dist/skill-authentication.d.ts +1 -0
  533. package/dist/skill-authentication.d.ts.map +1 -1
  534. package/dist/skill-authentication.js +1 -0
  535. package/dist/skill-authentication.js.map +1 -1
  536. package/dist/snyk-findings.d.ts +7 -2
  537. package/dist/snyk-findings.d.ts.map +1 -1
  538. package/dist/snyk-findings.js +108 -84
  539. package/dist/snyk-findings.js.map +1 -1
  540. package/dist/snyk-rest-findings.d.ts +76 -0
  541. package/dist/snyk-rest-findings.d.ts.map +1 -0
  542. package/dist/snyk-rest-findings.js +1051 -0
  543. package/dist/snyk-rest-findings.js.map +1 -0
  544. package/dist/snyk-rest-v1.d.ts +28 -0
  545. package/dist/snyk-rest-v1.d.ts.map +1 -0
  546. package/dist/snyk-rest-v1.js +132 -0
  547. package/dist/snyk-rest-v1.js.map +1 -0
  548. package/dist/snyk-token-origin.d.ts +4 -0
  549. package/dist/snyk-token-origin.d.ts.map +1 -0
  550. package/dist/snyk-token-origin.js +82 -0
  551. package/dist/snyk-token-origin.js.map +1 -0
  552. package/dist/sonar-collector.d.ts +16 -0
  553. package/dist/sonar-collector.d.ts.map +1 -0
  554. package/dist/sonar-collector.js +380 -0
  555. package/dist/sonar-collector.js.map +1 -0
  556. package/dist/sonar-findings.d.ts +49 -0
  557. package/dist/sonar-findings.d.ts.map +1 -0
  558. package/dist/sonar-findings.js +288 -0
  559. package/dist/sonar-findings.js.map +1 -0
  560. package/dist/sonar-import.d.ts +111 -0
  561. package/dist/sonar-import.d.ts.map +1 -0
  562. package/dist/sonar-import.js +277 -0
  563. package/dist/sonar-import.js.map +1 -0
  564. package/dist/suggest-owners.d.ts.map +1 -1
  565. package/dist/suggest-owners.js +2 -1
  566. package/dist/suggest-owners.js.map +1 -1
  567. package/dist/target-drift.d.ts +9 -0
  568. package/dist/target-drift.d.ts.map +1 -0
  569. package/dist/target-drift.js +27 -0
  570. package/dist/target-drift.js.map +1 -0
  571. package/dist/targets.d.ts +5 -0
  572. package/dist/targets.d.ts.map +1 -1
  573. package/dist/targets.js +73 -31
  574. package/dist/targets.js.map +1 -1
  575. package/dist/tenable-findings.d.ts +9 -0
  576. package/dist/tenable-findings.d.ts.map +1 -0
  577. package/dist/tenable-findings.js +122 -0
  578. package/dist/tenable-findings.js.map +1 -0
  579. package/dist/terminal-columns.d.ts +4 -0
  580. package/dist/terminal-columns.d.ts.map +1 -0
  581. package/dist/terminal-columns.js +19 -0
  582. package/dist/terminal-columns.js.map +1 -0
  583. package/dist/terminal-stream.d.ts +13 -0
  584. package/dist/terminal-stream.d.ts.map +1 -0
  585. package/dist/terminal-stream.js +35 -0
  586. package/dist/terminal-stream.js.map +1 -0
  587. package/dist/trivy-findings.d.ts +19 -0
  588. package/dist/trivy-findings.d.ts.map +1 -0
  589. package/dist/trivy-findings.js +435 -0
  590. package/dist/trivy-findings.js.map +1 -0
  591. package/dist/trivy-import.d.ts +19 -0
  592. package/dist/trivy-import.d.ts.map +1 -0
  593. package/dist/trivy-import.js +151 -0
  594. package/dist/trivy-import.js.map +1 -0
  595. package/dist/validation-records.d.ts +0 -3
  596. package/dist/validation-records.d.ts.map +1 -1
  597. package/dist/validation-records.js +1 -17
  598. package/dist/validation-records.js.map +1 -1
  599. package/dist/veracode-findings.d.ts +9 -0
  600. package/dist/veracode-findings.d.ts.map +1 -0
  601. package/dist/veracode-findings.js +409 -0
  602. package/dist/veracode-findings.js.map +1 -0
  603. package/dist/vertex-pricing.d.ts +8 -0
  604. package/dist/vertex-pricing.d.ts.map +1 -0
  605. package/dist/vertex-pricing.js +20 -0
  606. package/dist/vertex-pricing.js.map +1 -0
  607. package/dist/windows-path.d.ts +1 -0
  608. package/dist/windows-path.d.ts.map +1 -1
  609. package/dist/windows-path.js +27 -1
  610. package/dist/windows-path.js.map +1 -1
  611. package/dist/wiz-csv.d.ts +2 -2
  612. package/dist/wiz-csv.d.ts.map +1 -1
  613. package/dist/wiz-csv.js +1 -3
  614. package/dist/wiz-csv.js.map +1 -1
  615. package/dist/wiz-findings.d.ts +14 -2
  616. package/dist/wiz-findings.d.ts.map +1 -1
  617. package/dist/wiz-findings.js +143 -50
  618. package/dist/wiz-findings.js.map +1 -1
  619. package/docs/classify-severity-records.md +28 -13
  620. package/docs/cli.md +623 -843
  621. package/docs/dedupe-records.md +54 -24
  622. package/docs/findings-service.md +87 -47
  623. package/docs/hosted-remediation.md +14 -7
  624. package/docs/hosted-scans.md +64 -41
  625. package/docs/telemetry.md +236 -0
  626. package/docs/validate-records.md +78 -44
  627. package/package.json +19 -17
  628. package/schemas/external-findings.schema.json +14 -1
  629. package/schemas/hosted-scan-v2.fixture.json +16 -1
  630. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  631. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  632. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  633. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  634. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  635. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  636. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  637. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  638. package/dist/deduplication/records-protocol.d.ts +0 -4
  639. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  640. package/dist/deduplication/records-protocol.js +0 -49
  641. package/dist/deduplication/records-protocol.js.map +0 -1
  642. package/dist/external-imports-feature.d.ts +0 -6
  643. package/dist/external-imports-feature.d.ts.map +0 -1
  644. package/dist/external-imports-feature.js +0 -51
  645. package/dist/external-imports-feature.js.map +0 -1
  646. package/dist/finding-normalization.d.ts +0 -5
  647. package/dist/finding-normalization.d.ts.map +0 -1
  648. package/dist/finding-normalization.js +0 -120
  649. package/dist/finding-normalization.js.map +0 -1
package/README.md CHANGED
@@ -4,16 +4,15 @@ Run Codex Security from TypeScript or the command line to find, validate, and fi
4
4
  security vulnerabilities in your code. The package includes the Codex runtime,
5
5
  security plugin, and TypeScript declarations. It uses ES modules.
6
6
 
7
- - Scan repositories, selected paths, or Git changes. Deep scans run parallel
8
- discovery workers on repositories and selected paths.
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
9
  - Validate findings, generate patches, and verify existing fixes.
10
10
  - Draft security policies and retain threat models.
11
11
  - Review saved findings, identify duplicates, classify severity, and suggest owners.
12
12
  - Import GitHub code scanning alerts, export SARIF, JSON, or CSV, and publish
13
13
  findings to Linear or a findings service.
14
- - Import [Snyk Open Source findings](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/snyk.md) from
15
- official plugin JSON or native CLI JSON locally or into Cloud; Open Source
16
- SARIF is also supported. License findings and other Snyk products are excluded.
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.
17
16
  - Automate scans across repositories and project components.
18
17
 
19
18
  See the [CLI reference](docs/cli.md),
@@ -30,11 +29,9 @@ Supported runtimes:
30
29
  - Python 3.10+ for scans, policy generation, exports, scan history, and saved
31
30
  findings. Python 3.10 also needs `tomli`.
32
31
 
33
- Reading compressed Codex session logs (`.jsonl.zst`) requires Node.js 22.15.0+
34
- within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14, compressed sessions
35
- are unavailable when reading saved activity or attaching scan logs to feedback, and
36
- scans whose original session is compressed cannot resume. Plain `.jsonl` logs
37
- work on all supported runtimes.
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.
38
35
 
39
36
  ### Install the CLI
40
37
 
@@ -45,14 +42,9 @@ npm install --global @openai/codex-security
45
42
  cs --version
46
43
  ```
47
44
 
48
- `cs` is a short alias for `codex-security`; both commands run the same CLI.
49
- The installation creates both commands in npm's global executable directory,
50
- which must be on your `PATH`. If `cs` already resolves to another tool, use
51
- `codex-security` instead. If npm stops with an `EEXIST` error for `cs`, use
52
- `npx @openai/codex-security` without a global installation.
53
-
54
- Continue with the [CLI walkthrough](#cli). To run without a global installation,
55
- replace `cs` in the CLI examples with `npx @openai/codex-security`.
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`.
56
48
 
57
49
  ### Install the TypeScript SDK
58
50
 
@@ -116,39 +108,6 @@ Bedrock scans use AWS credentials and model access. They do not require
116
108
  [Bedrock guide](https://github.com/openai/codex-security/blob/main/docs/bedrock.md)
117
109
  for setup, model selection, and verification.
118
110
 
119
- ## Read existing Cloud findings
120
-
121
- The Security plugin includes `$cloud-findings` for accounts where Codex Security
122
- Cloud is available. Install the plugin through your configured Codex marketplace,
123
- sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
124
- the intended account and workspace. Installation alone does not authenticate the
125
- connection. Local scans do not require Cloud, and an API key used for scanning
126
- does not replace the Cloud connection.
127
-
128
- In Codex desktop or the interactive Codex CLI, ask:
129
-
130
- > Use $cloud-findings to list findings for example/security-demo in my selected
131
- > workspace. Inspect the highest-severity finding and its report, and show its
132
- > recorded assignee, patch links, verification results, and latest scan status.
133
- > Do not change anything.
134
-
135
- After completing connection setup, the same host connection can be used by
136
- `codex exec`:
137
-
138
- ```bash
139
- 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.'
140
- ```
141
-
142
- Noninteractive execution needs an existing authenticated connection; it cannot
143
- complete first-time sign-in. If authentication expires, the app is unavailable,
144
- or workspace policy denies access, complete the reported setup action before
145
- retrying. Those failures do not mean the repository has no findings.
146
-
147
- Assignment, issue validation, patch checks, periodic fix checks, and finding
148
- lifecycle status are separate records. Some finding sources do not provide all
149
- of them. The read workflow reports missing data and incomplete evidence pages,
150
- and does not describe failed or unfinished scans as clean.
151
-
152
111
  ## Run a scan from TypeScript
153
112
 
154
113
  Scan a repository you own or have permission to assess:
@@ -183,19 +142,21 @@ permissions; newly created directories are private to you by default.
183
142
  | --------------------------------- | ---------------------------------------------------------------- |
184
143
  | `findings.findings` | Findings from this scan. |
185
144
  | `reportPath` | Path to the Markdown report. |
186
- | `review` | Additional excluded paths. This is not file coverage. |
145
+ | `review.excludedPaths` | Additional paths the scan excluded. |
187
146
  | `repositoryFindings` | This scan's findings plus earlier open findings, when available. |
188
147
  | `sarifPath` | SARIF export path, or `null`. |
189
148
  | `threatModel` / `threatModelPath` | Saved threat model and document path; either can be `null`. |
190
149
  | `cost` | Estimated model usage cost, or `null` when unavailable. |
191
150
 
192
- Review the requested paths and exclusions alongside the execution outcome.
193
- `reviewState.deferred` records unfinished requested work, while
194
- `reviewState.openQuestions` records optional follow-up separately.
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.
195
154
 
196
- Review the scan status and scope alongside findings. A report with no findings does not establish
197
- that the repository is secure. Reports and logs can contain source code,
198
- vulnerability details, and credentials; review them before sharing.
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](docs/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.
199
160
 
200
161
  Saved-history excerpts use scanned Git objects without fetching missing data.
201
162
  Working-tree diff scans omit excerpts, as do historical scans whose source or
@@ -285,12 +246,12 @@ For a custom `pluginPath`, check [custom plugin compatibility](#custom-plugins).
285
246
 
286
247
  To enable Daybreak on Codex 0.163.0 or later, set `codexOverrides.daybreak: true`.
287
248
  The toggle defaults off; an explicit `false` keeps it off. The setting reaches
288
- Deep Scan discovery and reducer workers, including resumed workers. Scans use
249
+ Deep Scan discovery workers, including resumed workers. Scans use
289
250
  isolated configuration, so a desktop toggle or personal Codex configuration does
290
251
  not configure an SDK scan. See [Daybreak opt-in](docs/cli.md#daybreak-opt-in) for
291
252
  CLI, project-file, and direct plugin configuration.
292
253
 
293
- Deep Scan discovery, reducer, and resumed workers inherit per-scan provider,
254
+ Deep Scan workers, including resumed workers, inherit per-scan provider,
294
255
  authentication, environment, and executable settings with read-only permissions.
295
256
 
296
257
  Scans use an isolated Codex configuration. See
@@ -375,20 +336,51 @@ const result = await security.run("/path/to/repository", {
375
336
  });
376
337
  ```
377
338
 
378
- `workers` controls concurrent discovery workers; `subagents` controls delegation
379
- within each worker. Time and run limits apply to discovery. After discovery
380
- stops, the scan combines and returns completed findings. See
339
+ `workers` controls concurrent Standard scans and `subagents` controls delegation
340
+ within each scan. Time and run limits apply to discovery. The coordinator merges
341
+ completed findings before the next batch starts. See
381
342
  [deep scan settings](docs/cli.md#configure-deep-scans) for defaults and saved settings.
382
343
  Deep discovery retains its enforced deadline, with a default and maximum of
383
344
  5760 minutes. `maxTimeHours` remains a deprecated Deep-only alias in hours.
384
345
 
385
346
  ### Progress and cost
386
347
 
387
- Use `onProgress` for scan progress and `onCost` for cost updates.
388
- Use `onUsageObservation` for the last reported token measurement time
348
+ Use `onLifecycle` to observe the saved state of a top-level scan in your own
349
+ application:
350
+
351
+ ```ts
352
+ await security.run(repository, {
353
+ onLifecycle(scan) {
354
+ console.log(scan.scanId, scan.status, scan.hasReportableFindings);
355
+ },
356
+ });
357
+ ```
358
+
359
+ For `runComponentScans()`, subscribe to `onScanEvent` and select events with
360
+ `type === "lifecycle"` to correlate each snapshot with its `componentId`. Deep
361
+ component scans also emit `deep-progress` events with independent review counts.
362
+
363
+ Group observations by `scanId`. A completed scan with
364
+ `hasReportableFindings: false` finished with zero reportable findings.
365
+ The field is `null` until that outcome is known. Saved scan history retains
366
+ the lifecycle snapshot after the originating process exits. The snapshot
367
+ includes the launch surface, package and plugin versions when available,
368
+ and whether the scan used a mock. Offline imports appear in history with
369
+ lifecycle mode `import`. Exclude imports and mock scans when counting executed
370
+ scans. For older records, saved recipes identify known imports, mock scans,
371
+ and the plugin version used at launch. Missing fields stay unknown.
372
+
373
+ If `run()` rejects before you receive a registration, record the error separately
374
+ from saved scan outcomes. The caller may have missed the registration receipt.
375
+
376
+ Use `onProgress` for scan progress and `onMeasurement` for observed token/cost
377
+ subtotals, coverage, and collection time. `onCost` and `onUsage` report complete
378
+ totals. `onUsageObservation` reports the native token measurement time
389
379
  (`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
390
- Each reading includes its own `observedAt` timestamp and the percentage used in
391
- each reported window. A limit-only update can arrive before any token measurement.
380
+ Each reading has its own `observedAt` timestamp and percentages used in each
381
+ reported window. An allowance can arrive before any token measurement. See
382
+ [telemetry and measurement](docs/telemetry.md) for operation receipts, collection
383
+ controls, replay, and reporting definitions.
392
384
 
393
385
  Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
394
386
  persisted worker sessions discovered by the SDK's existing session tracker,
@@ -425,18 +417,24 @@ For retired progress hooks, see [older progress integrations](#older-progress-in
425
417
  contain source code or credentials. Deep scans additionally expose durable
426
418
  independent-review counts through `onDeepProgress`: `completed`, `active`, and
427
419
  `maximum`. The maximum is a configured cap, not a percentage denominator. The
428
- optional `consolidating` flag reports when results are being combined or the
429
- coordinator has finished.
420
+ optional `consolidating` flag is true while the running scan combines results or
421
+ waits for finalization after its coordinator finishes. It is false once the scan
422
+ completes, fails, or is canceled.
430
423
  `ScanOptions` lists all callbacks.
431
424
 
432
425
  Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
433
426
  allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
434
427
  short-context estimate; in-flight requests can exceed it. Post-scan prompts run
435
- outside that limit. Matching earlier findings can also make model calls.
428
+ outside that limit. With a cost limit, completing the scan requires verifiable
429
+ usage for the scan and its workers. Matching earlier findings can also make model calls.
436
430
  See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.
437
431
 
438
432
  ### Validate an existing finding
439
433
 
434
+ `validate()` sends the finding to your configured model provider. The model's
435
+ review tools can read the checkout, with network access and web search disabled.
436
+ Validation uses source evidence and skips builds, tests and application execution.
437
+
440
438
  ```ts
441
439
  import { writeFile } from "node:fs/promises";
442
440
 
@@ -451,15 +449,10 @@ console.log(result.disposition, result.report);
451
449
  await writeFile("/path/to/reports/assessment.md", result.report, "utf8");
452
450
  ```
453
451
 
454
- Pass finding text or a JSON-serializable object, not a file path. Standalone
455
- validation uses source evidence in a read-only, offline session. It does not build
456
- the target, execute application code, run tests or PoCs, or add a scan to history.
457
- The validator returns the assessment without writing report files. The example
458
- saves `result.report` in an existing directory. `outputDir` selects the session
459
- directory, not a report destination. Callers that previously read reports from it
460
- must save `result.report` instead.
461
- Callers needing runtime proof must arrange a separate reproduction step. Standard,
462
- Deep, and diff scan validation keep their existing workflows.
452
+ Pass literal finding text or a JSON-serializable object. The assessment is
453
+ returned to the caller and has no scan history entry. The example saves
454
+ `result.report` in an existing directory. Use `outputDir` to select the
455
+ session directory. If you need runtime evidence, arrange a separate check.
463
456
 
464
457
  The disposition is `reportable`, `suppressed`, `not_applicable`, or `deferred`.
465
458
  `reportable` can rely on static analysis; `deferred` means there is insufficient
@@ -479,6 +472,8 @@ See [host-provided standalone validation](docs/validate-records.md).
479
472
  workspace that the caller has intentionally made writable:
480
473
 
481
474
  ```ts
475
+ import { CodexSecurity } from "@openai/codex-security";
476
+
482
477
  const security = new CodexSecurity();
483
478
  try {
484
479
  const result = await security.patch({
@@ -488,7 +483,6 @@ try {
488
483
  summary: "User input reaches a raw SQL query.",
489
484
  locations: [{ path: "src/query.ts", startLine: 42 }],
490
485
  },
491
- signal,
492
486
  onActivity(activity) {
493
487
  console.log(activity.description);
494
488
  },
@@ -546,23 +540,16 @@ After [installing the CLI](#install-the-cli), sign in if needed:
546
540
  cs login
547
541
  ```
548
542
 
549
- From your repository, optionally [draft a `SECURITY.md`](#generate-a-security-policy)
550
- that explains what counts as a security issue in your project:
551
-
552
- ```bash
553
- cs policy .
554
- ```
555
-
556
- The draft is saved outside your repository. Review the diff and notes, edit the
557
- draft, then copy only `SECURITY.md` to the **Policy target** shown. Skip this step
558
- to keep your current policy or scan without one.
559
-
560
- Then scan the repository:
543
+ From the repository you want to review, run:
561
544
 
562
545
  ```bash
563
546
  cs scan .
564
547
  ```
565
548
 
549
+ Open the report at the path printed on completion. To inspect the latest
550
+ completed scan for this checkout, run `cs scans show`. To provide a project
551
+ policy for future scans, [draft and review a `SECURITY.md`](#generate-a-security-policy).
552
+
566
553
  To narrow the scan scope or check the configuration before scanning:
567
554
 
568
555
  ```bash
@@ -636,92 +623,74 @@ on CODEOWNERS, source, and Git history. Declared owners take priority over Git
636
623
  contributors. Suggestions do not assign tickets. See
637
624
  [owner suggestions](docs/cli.md#suggest-finding-owners) for input and output examples.
638
625
 
626
+ ### Read existing Cloud findings
627
+
628
+ The Security plugin includes `$cloud-findings` for accounts where Codex Security
629
+ Cloud is available. Install the plugin through your configured Codex marketplace,
630
+ sign in to Codex with ChatGPT, and complete the Cloud connection interactively in
631
+ the intended account and workspace. Installation alone does not authenticate the
632
+ connection. Local scans do not require Cloud, and an API key used for scanning
633
+ does not replace the Cloud connection.
634
+
635
+ In Codex desktop or the interactive Codex CLI, ask:
636
+
637
+ > Use $cloud-findings to list findings for example/security-demo in my selected
638
+ > workspace. Inspect the highest-severity finding and its report, and show its
639
+ > recorded assignee, patch links, verification results, and latest scan status.
640
+ > Do not change anything.
641
+
642
+ After completing connection setup, the same host connection can be used by
643
+ `codex exec`:
644
+
645
+ ```bash
646
+ 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.'
647
+ ```
648
+
649
+ Noninteractive execution needs an existing authenticated connection; it cannot
650
+ complete first-time sign-in. If authentication expires, the app is unavailable,
651
+ or workspace policy denies access, complete the reported setup action before
652
+ retrying. Those failures do not mean the repository has no findings.
653
+
654
+ Assignment, issue validation, patch checks, periodic fix checks, and finding
655
+ lifecycle status are separate records. Some finding sources do not provide all
656
+ of them. The read workflow reports missing data and incomplete evidence pages,
657
+ and does not describe failed or unfinished scans as clean.
658
+
639
659
  ### Publish findings to Cloud
640
660
 
641
- `publish scan --to cloud` uploads selected findings to Codex Security Cloud.
642
- It requires ChatGPT credentials; inference API keys and AWS credentials do not
643
- grant Cloud access. See [Cloud publication](docs/cli.md#publish-findings-to-cloud)
644
- for setup and review steps, or [Linear publication](docs/cli.md#publish-completed-scans-to-linear)
645
- for issue creation.
646
-
647
- External vendor imports are opt-in. Set `CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS=1`
648
- to enable `publish findings`, `findings imported`, `import github-advisories`, and
649
- the SDK's external publication, local import/readback, and advisory acquisition
650
- APIs. They are disabled otherwise; CLI commands are hidden from help and schemas.
651
- SDK callers can supply the flag through the existing per-call
652
- `dependencies.environment`. Pure normalizers and file readers remain available.
653
- This does not affect scan publishing or the existing GitHub alert collector.
654
-
655
- The SDK also exposes `prepareExternalPublication(file, options)` for supported
656
- vendor exports and `prepareNormalizedExternalPublication(findings, options)` for
657
- normalized external evidence from any provider in the Cloud import contract.
658
- The normalized API accepts `NormalizedExternalPublicationOptions`; file readers
659
- use `ExternalPublicationOptions` for their supported formats. Both resolve the Cloud repository and return a
660
- `preview` plus a separate `publish()` operation. Inspect the preview before
661
- calling `publish()`. Imported evidence remains not assessed by Codex, and saved
662
- requests and receipts support retries after interruption.
663
-
664
- Prefer each provider's supported native JSON for local and Cloud imports. Keep
665
- the same acquisition format for repeat imports: SARIF and CSV are compatibility
666
- options where supported, and changing formats can change record identities or
667
- replace richer evidence with less detail. See the
668
- [import guide](docs/cli.md#import-vendor-findings-locally) for format selection.
669
-
670
- For Amazon Inspector Code Security, use `--provider inspector` with a complete
671
- ListFindings JSON export and `--source-repository-url`. When the export identifies
672
- the repository by an ARN and name, pass `--inspector-project-arn ARN` with the ARN
673
- you verified for that Git URL in the SCM integration. See the
674
- [Inspector guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/inspector.md).
675
-
676
- For OpenGrep, use `--provider opengrep` with native JSON or gzip and an explicit
677
- `--source-repository-url`. Local and Cloud imports retain unassessed OpenGrep
678
- evidence through the existing Semgrep source-provider contract. See the
679
- [OpenGrep guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/opengrep.md) for preview commands,
680
- coverage diagnostics, stable source identities, and local SDK assessment.
681
-
682
- For Wiz, prefer supported native JSON acquired through an authorized MCP or API
683
- connection. The [CSV compatibility reader](docs/cli.md#import-wiz-findings) covers
684
- repository package vulnerabilities (SCA) only; it does not add SAST, CSPM or
685
- complete code-to-cloud coverage. Both formats support gzip. The acquisition path
686
- still needs validation with an authorized Wiz tenant.
687
-
688
- For GitHub code scanning and GHSA advisories, save complete JSON from
689
- `import github` or `import github-advisories`, respectively. **GHSA import
690
- does not establish an installed dependency or applicability to the repository.**
691
- For Dependabot, save the native REST alert records from one repository using the
692
- [Dependabot export guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/github-dependabot.md).
693
- The GitHub file reader accepts all three families. Secret-scanning alerts and
694
- writeback to GitHub are outside its scope.
695
-
696
- Use `publish findings FILE --to local --repository PATH --provider wiz
697
- --source-key KEY` to store the same vendor evidence in the local workbench SQLite
698
- database. Preview with `--dry-run --format json`, then confirm interactively or
699
- use `--yes`. Read it with `findings imported [REPOSITORY] --format json`; the
700
- repository defaults to the current directory. No Cloud login or model call is
701
- needed. Use `--provider snyk` for native CLI JSON, a Snyk plugin SCA bundle or
702
- Open Source SARIF. Prefer JSON, and keep one format and stable source key per scan
703
- target; switching formats creates separate source identities. See
704
- [local imports](docs/cli.md#import-vendor-findings-locally).
705
-
706
- Use `--provider endor` with native Endor Finding JSON; existing endorctl SARIF is
707
- accepted as a lossy compatibility format. See
708
- [Endor imports](docs/cli.md#import-endor-labs-findings).
709
-
710
- For saved GitHub code-scanning alerts, GHSA advisories, or Dependabot alerts, use
711
- `--provider github` with a separate stable source key for each finding family.
712
- See [local imports](docs/cli.md#import-vendor-findings-locally).
713
-
714
- The SDK's `prepareLocalExternalImport(file, options)` returns a `preview` and a
715
- separate `import()` operation. `prepareNormalizedLocalImport(findings,
716
- options)` accepts already normalized evidence, and
717
- `listLocalExternalFindings({ repository })` reads the stored records. Imports
718
- remain unassessed source evidence, separate from native scan findings. Repeated
719
- imports update the same repository/provider/source-key/source-ID record; omitted
720
- records remain stored, and unknown evidence fields are not inferred.
721
-
722
- File imports forward repository references from the reader automatically. Direct
723
- normalized callers should provide additional known references in the third
724
- argument's `sourceRepositories` when they are absent from
661
+ Use `publish scan --to cloud` for completed Codex Security scans or a Codex
662
+ Security findings CSV. Preview either input offline with `--dry-run`. Uploads
663
+ require a file-backed ChatGPT login. [Cloud publication](docs/cli.md#publish-completed-scans)
664
+
665
+ For a report exported by a scanner, see [Import external findings](#import-external-findings).
666
+ For issue tracking, see [Linear publication](docs/cli.md#publish-completed-scans-to-linear).
667
+
668
+ ### Import external findings
669
+
670
+ For a saved scanner report, call `prepareLocalExternalImport` for a checkout
671
+ or `prepareExternalPublication` for a connected Cloud repository. Review the
672
+ returned `preview`, then call `import()` to save locally or `publish()` to
673
+ upload. The [scanner import guides](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md)
674
+ list the supported report formats and destinations for each provider.
675
+
676
+ For normalized evidence, use `prepareNormalizedLocalImport(findings, options)`
677
+ or `prepareNormalizedExternalPublication(findings, options)` and review the
678
+ preview in the same way. Cloud file imports use `ExternalPublicationOptions`,
679
+ and normalized Cloud imports use `NormalizedExternalPublicationOptions`. Keep
680
+ Cloud receipts and saved requests when retrying an interrupted submission.
681
+
682
+ Use `listLocalExternalFindings({ repository })` to read saved scanner evidence.
683
+ It starts unassessed. Reimporting the same repository, provider, source key
684
+ and finding ID updates that record. Records omitted from the export remain stored.
685
+
686
+ A local SDK import with only excluded records returns the exclusions and zero
687
+ writes. The CLI exits 2 in that case. When Cloud preparation throws
688
+ `NoPublishableFindingsError`, inspect its `selection` for the read count,
689
+ exclusions and scanner diagnostics. A clean empty report needs no upload.
690
+
691
+ File imports forward repository references from the reader automatically. With
692
+ `prepareNormalizedLocalImport()`, supply additional known references in the
693
+ third argument's `sourceRepositories` when they are absent from
725
694
  `evidence.details.repository.url`. For a known GitHub custom host, include
726
695
  `platform: "github"`, for example `{ sourceRepositories: [{ url:
727
696
  "https://git.example.test/example/project", platform: "github" }] }`. Named Wiz
@@ -729,7 +698,49 @@ reports carry this platform in their repository inventory. If you export only th
729
698
  normalized finding rows to JSONL, supply that metadata separately; the original
730
699
  finding evidence does not include the surrounding inventory.
731
700
 
732
- See [Semgrep Code imports](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md) for native CLI/CI JSON, SARIF compatibility, and local or Cloud imports. Platform API and Guardian/MCP responses need a separate mapping.
701
+ #### Collect and normalize scanner evidence
702
+
703
+ To collect selected Sonar issues, pass their keys to `collectSonarIssues` in `options.issueKeys`.
704
+ Omit `issueKeys` to collect the project's open security issues. An empty list is rejected.
705
+ If you know the source repository, pass its Git URL in `options.sourceRepositoryUrl`
706
+ to check the Sonar binding before fetching issues.
707
+
708
+ For AWS Continuum code findings, use `readContinuumFindings(path, sourceRepositoryUrl)`
709
+ with a saved list or detail response, or `normalizeContinuumFindings(input, sourceRepositoryUrl)`
710
+ with parsed JSON. Verify the repository for the selected findings before passing its Git URL.
711
+ [Continuum import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/continuum.md)
712
+
713
+ For a saved Checkmarx One CLI JSON or CxSAST XML report, use
714
+ `readCheckmarxFindings(path, sourceRepositoryUrl, "local")` to inspect its evidence.
715
+ To prepare a local import, pass `provider: "checkmarx"` and the verified
716
+ `sourceRepositoryUrl` to `prepareLocalExternalImport`. Keep each batch of normalized
717
+ Checkmarx findings scoped to one scan and its repository.
718
+ [Checkmarx SAST import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/checkmarx.md)
719
+
720
+ Use `collectSelectedSemgrepGuardianFindings` with a connected Guardian MCP client to
721
+ [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.
722
+ Use `normalizeSelectedSemgrepPlatformFindings` for selected SAST findings from saved
723
+ 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).
724
+ 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).
725
+ 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`).
726
+
727
+ 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.
728
+ For a private repository with a verified SCM, pass its URL and `platform: "gitlab"` or `"github"` in `sourceRepositories` to match standard SSH clone URLs.
729
+
730
+ To inspect dependency vulnerabilities in a saved Trivy schema-v2 repository or filesystem
731
+ report, call `readTrivyFindings` with the JSON or gzip path. Use `normalizeTrivyFindings`
732
+ for an already parsed report. Supply the scanned directory relative to the checkout
733
+ (`.` for the whole checkout) unless the report's remote target and Git metadata establish it.
734
+
735
+ ```ts
736
+ import { readTrivyFindings } from "@openai/codex-security";
737
+
738
+ const { findings, excluded, report } = await readTrivyFindings(
739
+ "trivy.json.gz",
740
+ "local",
741
+ ".",
742
+ );
743
+ ```
733
744
 
734
745
  ## Findings storage and deduplication
735
746
 
@@ -762,7 +773,7 @@ Local tools running under the same account are trusted.
762
773
  The scan profile allows reads across the local filesystem and writes to workspace
763
774
  roots. Execution approvals are reviewed automatically and may grant extra
764
775
  permissions for an operation. Set `codexOverrides.approval_policy: "never"`
765
- (or CLI `--codex 'approval_policy="never"'`) to deny permission requests.
776
+ (or CLI `--codex "approval_policy='never'"`) to deny permission requests.
766
777
  If you select a Codex profile, its explicit `approval_policy` takes precedence
767
778
  over the root setting.
768
779
  Host and network restrictions still apply.
@@ -773,6 +784,18 @@ paths. Keep state and scan artifacts private and outside the repository.
773
784
 
774
785
  ## Compatibility
775
786
 
787
+ ### Package and plugin versions
788
+
789
+ When reporting a problem, run `codex-security info --json` with the installation
790
+ that produced it. For a local SDK installation, run
791
+ `npx @openai/codex-security info --json` in that project. Include `cliVersion`,
792
+ `sdkVersion`, `bundledPluginVersion`, `codexVersion` and `codexSdkVersion`. If
793
+ you supplied a separate plugin or Codex executable, include its version too.
794
+
795
+ For package provenance, compare the registry's `gitHead` and `dist.integrity`
796
+ with the release tag and tarball. If a package omits `gitHead`, use the commit
797
+ in its [verified release attestation](https://github.com/openai/codex-security/blob/main/.github/workflows/node-github-release.yml).
798
+
776
799
  ### Custom plugins
777
800
 
778
801
  New and resumed Deep Scans require a plugin with `directDeepScanEngine: 1`,
@@ -2,18 +2,22 @@
2
2
  "apps": {
3
3
  "codex-security-cloud": {
4
4
  "id": "connector_openai_defense_factory",
5
+ "required": false,
5
6
  "category": "Code Hosting & Security Findings"
6
7
  },
7
8
  "linear": {
8
9
  "id": "asdk_app_69a089a326dc8191b32a3f2553f5be2c",
10
+ "required": false,
9
11
  "category": "Work Tracking & Coordination"
10
12
  },
11
13
  "github": {
12
14
  "id": "connector_76869538009648d5b282a4bb21c3d157",
15
+ "required": false,
13
16
  "category": "Code Hosting & Security Findings"
14
17
  },
15
18
  "atlassian": {
16
19
  "id": "asdk_app_6a83901dde988191b3f3cefdcc19acfa",
20
+ "required": false,
17
21
  "category": "Work Tracking & Coordination",
18
22
  "capabilities": [
19
23
  "read",
@@ -8,6 +8,8 @@
8
8
  "CODEX_HOME",
9
9
  "CODEX_SQLITE_HOME",
10
10
  "CODEX_API_KEY",
11
+ "CODEX_OSS_BASE_URL",
12
+ "CODEX_OSS_PORT",
11
13
  "CODEX_SAFETY_IDENTIFIER",
12
14
  "CODEX_BROWSER_USE_NODE_PATH",
13
15
  "CODEX_CLI_PATH",
@@ -18,6 +20,9 @@
18
20
  "OPENROUTER_API_KEY",
19
21
  "FIREWORKS_API_KEY",
20
22
  "CHEAPER_INFERENCE_API_KEY",
23
+ "GOOGLE_CLOUD_PROJECT",
24
+ "GOOGLE_CLOUD_LOCATION",
25
+ "GOOGLE_APPLICATION_CREDENTIALS",
21
26
  "AWS_BEARER_TOKEN_BEDROCK",
22
27
  "AWS_ACCESS_KEY_ID",
23
28
  "AWS_SECRET_ACCESS_KEY",
@@ -38,10 +43,10 @@
38
43
  "PYTHONUTF8",
39
44
  "CODEX_SECURITY_PYTHON_COMMAND",
40
45
  "CODEX_SECURITY_GIT",
41
- "CODEX_SECURITY_ENABLE_EXTERNAL_IMPORTS",
42
46
  "CODEX_SECURITY_KNOWLEDGE_BASE",
43
47
  "CODEX_SECURITY_CONFIG_PATH",
44
48
  "CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH",
49
+ "CODEX_SECURITY_SCAN_DIR",
45
50
  "CODEX_SECURITY_PLUGIN_ROOT",
46
51
  "CODEX_SECURITY_SCAN_ROOT",
47
52
  "CODEX_SECURITY_STATE_DIR",
@@ -2,10 +2,17 @@
2
2
  "documentType": "codex-security.findings",
3
3
  "findings": [
4
4
  {
5
- "attackPath": null,
5
+ "attackPath": {
6
+ "dataflow": {
7
+ "summary": "The archive supplies an entry name. The extractor uses that name to select the file it writes."
8
+ },
9
+ "reachability": {
10
+ "summary": "The caller must be able to supply an archive for extraction. The service account must have write access to the destination."
11
+ }
12
+ },
6
13
  "confidence": {
7
14
  "level": "high",
8
- "rationale": "Direct source trace reaches the filesystem write without a containment check."
15
+ "rationale": "The destination passed to the file writer is visible in the reviewed code."
9
16
  },
10
17
  "extensions": {},
11
18
  "findingId": "csf_852f90d6e1177502ff113d4a",
@@ -37,11 +44,13 @@
37
44
  ],
38
45
  "ruleId": "path-traversal.archive-extraction",
39
46
  "severity": {
47
+ "changeConditions": "A filesystem policy that confines writes to a disposable import directory would limit the impact.",
40
48
  "level": "high",
49
+ "rationale": "The caller can alter files outside the import area with the permissions of the extraction service.",
41
50
  "score": 8.1,
42
51
  "scoringSystem": "CVSS:3.1"
43
52
  },
44
- "summary": "An attacker-controlled path reaches a filesystem write without containment validation.",
53
+ "summary": "Archive extraction can overwrite files outside the directory chosen for the import.",
45
54
  "taxonomy": {
46
55
  "category": "path-traversal",
47
56
  "cwe": [
@@ -49,7 +58,10 @@
49
58
  ]
50
59
  },
51
60
  "title": "Unsafe archive extraction can escape the output directory",
52
- "validation": null
61
+ "validation": {
62
+ "method": "Static source review",
63
+ "summary": "The extractor combines the output directory with the entry name and passes the resulting path to the writer. It never checks that the destination stays inside the output directory."
64
+ }
53
65
  }
54
66
  ],
55
67
  "scanId": "scan_example_001",