@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
@@ -6,25 +6,26 @@ Findings API. It performs no authentication, update checks, local Codex launches
6
6
  candidate retrieval, or persistence. The host owns repository authorization,
7
7
  model execution, sessions, credentials, cancellation of remote work, and cleanup.
8
8
 
9
- The SDK equivalent is:
9
+ ## A minimal exchange
10
10
 
11
- ```typescript
12
- import { deduplicateRecords } from "@openai/codex-security";
11
+ To check the connection before dispatching reviews, send an empty batch as
12
+ one line on the CLI's stdin. Keep the pipe open.
13
13
 
14
- const result = await deduplicateRecords(input, {
15
- reviewRunner: {
16
- async run(request, { signal } = {}) {
17
- return await hostReview(request, signal); // Return the structured answer.
18
- },
19
- },
20
- signal: controller.signal,
21
- });
14
+ ```text
15
+ {"jsonrpc":"2.0","id":"run-1","method":"run","params":{"version":1,"observations":[],"candidateRelationships":[]}}
22
16
  ```
23
17
 
24
- `DeduplicateRecordsInput`, `DeduplicateRecordsResult`,
25
- `DeduplicationReviewRequest`, and `DeduplicationReviewRunner` are exported types.
26
- The entry point validates the input structure, unique identities, and candidate
27
- references before any review.
18
+ The CLI writes one line to stdout with the same run ID. With no candidates,
19
+ this exchange makes zero model calls.
20
+
21
+ ```text
22
+ {"jsonrpc":"2.0","id":"run-1","result":{"version":1,"status":"completed","groups":[],"unresolved":[]}}
23
+ ```
24
+
25
+ For a populated batch, supply observations and candidate relationships as below.
26
+ [Answer each review](#review-exchange) using its own request ID, then read the
27
+ [terminal result](#final-response-and-persistence) using your original run ID.
28
+ The [Python host](#runnable-python-fake-host) demonstrates the complete exchange.
28
29
 
29
30
  ## Input and identities
30
31
 
@@ -36,7 +37,8 @@ from -9007199254740991 through 9007199254740991 and are compared without coercio
36
37
  Use strings for larger numeric identifiers. Review IDs are generated strings;
37
38
  request and response ID namespaces are directional.
38
39
 
39
- The host sends:
40
+ The following messages are expanded for reading. Serialize each object to a
41
+ single line before writing it to the pipe. For a populated batch, the host sends:
40
42
 
41
43
  ```json
42
44
  {
@@ -66,6 +68,16 @@ must describe the actual source; it does not authorize additional repository
66
68
  access. Unknown extension fields are preserved. This does not require creating
67
69
  scan manifests or other saved-scan artifacts.
68
70
 
71
+ For an imported observation, set `"kind": "imported"` on its entry alongside
72
+ `id` and `finding`. Supply the actual source in `finding.provenance.source`
73
+ and retain original source references and evidence as extensions. Imported
74
+ findings may omit `ruleId`, `identity`, `taxonomy`, and `remediation`. If
75
+ there is no known repository line, supply an empty `locations` array and
76
+ preserve any file-level evidence in the original source data. All other
77
+ Finding requirements apply. Entries without a kind use the full Finding
78
+ schema. A SAME review must return a merged finding that satisfies the schema
79
+ of the assigned canonical original.
80
+
69
81
  Observation IDs are host-owned, nonempty strings, unique within `observations`.
70
82
  Supply the pending observations and their retrieved neighbors together as original
71
83
  observations. Each `candidateRelationships` entry selects one anchor to process;
@@ -121,8 +133,7 @@ and beneficiaries are nonempty. Candidate-only observations never become
121
133
  beneficiaries, even when selected as the final representative. An incoming
122
134
  observation participating in several reviews appears in each review's metadata.
123
135
 
124
- This is additive metadata: JSON-RPC remains 2.0 and input/result versions remain 1.
125
- Older hosts may ignore it; hosts that require attribution must validate it
136
+ Hosts that use attribution for accounting must validate it
126
137
  and reject missing or unknown identities before executing a review. Persist the
127
138
  request UUID and attribution before provisioning remote execution. The host owns
128
139
  accounting and any partitioning of invocation anchors by origin scan; the CLI
@@ -193,16 +204,11 @@ For failure or an inconclusive review, send an explicit error:
193
204
  A host error ends the review without another submission. Invalid final model
194
205
  answers, missing final decisions, and host errors make the whole batch unresolved;
195
206
  previous successful reviews in that run do not become persistence decisions.
196
- The existing algorithm treats a validated `DISTINCT` as a nonmatch, when
207
+ The CLI treats a validated `DISTINCT` as a nonmatch, when
197
208
  supplied finding content is insufficient to establish a shared correction. If the host considers the review
198
209
  inconclusive, it must return an error rather than manufacture a `DISTINCT` answer.
199
210
  No new `INCONCLUSIVE` model decision is introduced.
200
211
 
201
- The existing screening, independent pair review, contradiction-aware grouping, and
202
- severity-based representative selection are reused. No local review checkpoints
203
- are read or written in records mode. Local saved-scan execution retains its
204
- existing tool-submission validation and workflow checkpoints.
205
-
206
212
  ### Continuing a review
207
213
 
208
214
  A `review.run` request with `supportsContinuation: true` can receive the result
@@ -268,6 +274,30 @@ observation as unique. Cross-run replay/idempotency and reconciliation of remote
268
274
  work whose acceptance is uncertain belong to the host; a new process creates
269
275
  new review IDs and does not resume earlier remote execution.
270
276
 
277
+ ## TypeScript integration
278
+
279
+ The SDK accepts the same input and returns the result directly. In this host
280
+ integration, provide an authorized `reviewRunner` that executes the request
281
+ and returns the structured answer. Pass an `AbortSignal` to support cancellation.
282
+
283
+ ```ts
284
+ import {
285
+ deduplicateRecords,
286
+ type DeduplicateRecordsInput,
287
+ type DeduplicationReviewRunner,
288
+ } from "@openai/codex-security";
289
+
290
+ export function reviewDuplicates(
291
+ input: DeduplicateRecordsInput,
292
+ reviewRunner: DeduplicationReviewRunner,
293
+ signal: AbortSignal,
294
+ ) {
295
+ return deduplicateRecords(input, { reviewRunner, signal });
296
+ }
297
+ ```
298
+
299
+ `DeduplicateRecordsResult` and `DeduplicationReviewRequest` are also exported.
300
+
271
301
  ## Cancellation and protocol failures
272
302
 
273
303
  To cancel the active run, send a notification:
@@ -1,23 +1,31 @@
1
1
  # Findings storage and deduplication
2
2
 
3
- Saved scans and findings persist in the local workbench SQLite database.
4
- Deduplication reads that database directly; no local HTTP service is needed.
5
- The CLI can also publish to and deduplicate against independently operated
6
- compatible endpoints through explicit `--findings-url` settings.
3
+ Choose where the duplicate candidates and groups should live.
7
4
 
8
- For an older service deployment or helper integration, see [compatibility](#compatibility).
5
+ - **Local workbench.** The CLI stores saved scans and findings in SQLite.
6
+ Use this default to search the current checkout's stored findings. New
7
+ embeddings and fresh reviews still need provider access.
8
+ - **Independently operated endpoint.** To search a shared corpus, use a
9
+ [compatible findings endpoint](#compatible-endpoint-contract) that already
10
+ holds your candidates. [Publish the scan](#publish-a-scan) or import its
11
+ findings into the service with the matching `repositoryId` first.
9
12
 
10
13
  ## Deduplicate a scan
11
14
 
12
- Saved-scan deduplication uses local SQLite by default. No findings service or
13
- publication step is required:
15
+ For the local workbench, run:
14
16
 
15
17
  ```bash
16
18
  codex-security dedupe --scan SCAN_ID --json
17
19
  ```
18
20
 
19
- See [local embedding requirements](#local-embeddings-and-backups) for endpoint,
20
- credential, and vector compatibility.
21
+ For a shared corpus, supply the base URL of your endpoint:
22
+
23
+ ```bash
24
+ codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
25
+ ```
26
+
27
+ Replace `SCAN_ID` with the ID of a completed scan, or use `latest` for the
28
+ current repository. For local setup, see [embedding credentials and backups](#local-embeddings-and-backups).
21
29
 
22
30
  The CLI prepares missing or stale embeddings for the local repository's stored
23
31
  findings, searches them, and saves reviewed duplicate groups in the workbench
@@ -36,24 +44,15 @@ select logical findings using their current stored bodies; dedupe does not
36
44
  replace newer bodies with old scan artifacts. A local database does not include
37
45
  findings stored only in a separate Docker volume or remote service.
38
46
 
39
- To retain a centralized findings corpus, publish the scan first, or import its
40
- findings with `repositoryId`, and explicitly select the service:
41
-
42
- ```bash
43
- codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
44
- ```
45
-
46
- A scan or workflow selector is required. `--scan`
47
- accepts a full ID, unique prefix, or `latest` for the current repository. The
48
- scan must be complete, with sealed artifacts and a local checkout available.
47
+ A scan or workflow selector is required. `--scan` also accepts a unique ID
48
+ prefix. The scan must have sealed artifacts and a local checkout available.
49
49
  Local `latest` lookup matches the exact checkout path without Git. Matching
50
50
  across worktrees or clones additionally requires a Git executable outside all
51
51
  saved scan targets. If an unrelated historical target includes the available
52
52
  Git installation, use `codex-security dedupe --scan SCAN_ID` with an explicit
53
53
  saved scan ID instead.
54
54
  By default, candidates come from its manifest's `scan.target.targetId`. Use
55
- `--all-repositories` to search the whole selected database or service. Explicit
56
- `--findings-url` retains the existing remote lookup and publication behavior.
55
+ `--all-repositories` to search the whole selected database or service.
57
56
 
58
57
  ```typescript
59
58
  import { deduplicateScan } from "@openai/codex-security";
@@ -67,6 +66,21 @@ const result = await deduplicateScan("scan_example_001", {
67
66
  console.log(result.duplicateGroups);
68
67
  ```
69
68
 
69
+ Both saved-scan APIs accept `onEmbeddingUsage` for the built-in local adapter.
70
+ It receives one observation per processed batch: model, tokenized input count
71
+ (including chunks of long findings), provider-reported input tokens, outcome,
72
+ and duration in milliseconds. `inputTokens: null` means usage was unavailable,
73
+ including responses that omit usage; it does not mean zero tokens. Cached
74
+ embeddings generate no new observations. Observers are best effort: throws,
75
+ rejections, and pending promises do not fail or block embedding work. No finding
76
+ text, vectors, credentials, or endpoint is included.
77
+
78
+ Embedding tokens remain separate from scan model-token and cost totals. A batch
79
+ can contain several HTTP attempts when the local adapter retries, and its
80
+ observation only includes usage from the final response. Remote services and
81
+ custom embedding bindings own their usage reporting; set an observer directly on
82
+ `OpenAiFindingEmbedder` when using it in a custom binding.
83
+
70
84
  For a different embedding provider or model, both saved-scan SDK methods accept
71
85
  an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
72
86
  `{ model, vector }` per input finding, in input order. The adapter owns its
@@ -210,8 +224,8 @@ Empty scans and findings without eligible candidates make no review calls.
210
224
  Other scans can require multiple calls per finding. Completion means the
211
225
  retrieval, review, and group write finished; it does not mean that every pair
212
226
  in the database was compared. Use Ctrl-C or SIGTERM in the CLI, or an
213
- `AbortSignal` in the SDK, to cancel. This workflow is separate from Deep Scan's
214
- internal reducer.
227
+ `AbortSignal` in the SDK, to cancel. Deep Scan merges its own workers’ findings
228
+ locally.
215
229
 
216
230
  ### Resume a findings workflow
217
231
 
@@ -310,7 +324,10 @@ Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
310
324
  the interactive picker. Custom publication accepts one scan; CSV input and
311
325
  Linear options do not apply. Add `--dry-run` to preview the payload without an
312
326
  HTTP request. Upload failures and incomplete receipts fail the command. Uploads
313
- are not automatically retried because a lost response may have been committed.
327
+ are not automatically retried because the receiver may have committed a request
328
+ whose response was lost. Resuming publication or remote dedupe in a workflow
329
+ without its receipt resends the entire sealed batch. Before resuming, ask the
330
+ receiver to confirm that replaying that exact request is safe.
314
331
 
315
332
  ```typescript
316
333
  import { publishScanToCustom } from "@openai/codex-security";
@@ -323,10 +340,25 @@ const receipt = await publishScanToCustom("/path/to/completed-scan", {
323
340
  console.log(receipt.repositoryId, receipt.findingIds);
324
341
  ```
325
342
 
343
+ The Linear and custom publication SDKs return a content-free `telemetry`
344
+ summary and accept `onTelemetry` for outcomes, including preparation failure and
345
+ cancellation. Existing Linear receipts and custom workflow results retain this
346
+ summary. It includes an attempt ID, destination family, duration, outcome, and
347
+ counts of selected, submitted, created, reused, acknowledged, and failed findings.
348
+ Submitted counts describe findings handed to publication, not HTTP attempts.
349
+ `null` denotes unknown counts; in particular, the custom bulk API acknowledges
350
+ IDs without distinguishing creation from upsert. Unknown mutation outcomes are
351
+ `indeterminate`, and dry runs have `outcome: "preview"` and `attempted: false`.
352
+ Reusing a saved custom workflow receipt produces a new attempt summary with no
353
+ submitted findings. Hosts should group repeated receipt snapshots by attempt ID
354
+ and use the latest observation. Callback failures do not change publication
355
+ results, and these callbacks add no network destination or separate files.
356
+
326
357
  ## Compatible endpoint contract
327
358
 
328
- The retained HTTP clients use these endpoints on the supplied base URL,
329
- preserving its base path:
359
+ The HTTP client appends these paths to the configured base URL, preserving any base path.
360
+ It follows redirects within that origin (scheme, host, and port). If the service
361
+ moves to another origin, set `--findings-url` to its new base URL.
330
362
 
331
363
  | Method | Path | Response |
332
364
  | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
@@ -338,8 +370,8 @@ Publication sends `{findings, repositoryId}`. Candidate requests include either
338
370
  `repositoryId` or `allRepositories=true`. Group writes send
339
371
  `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
340
372
  workflow retries. Both POST endpoints must persist their writes before
341
- acknowledging them and return a JSON body. An explicit URL selects this remote
342
- contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
373
+ acknowledging them and return a JSON body. Supply your service’s base URL to use
374
+ these endpoints. With no URL, deduplication uses local SQLite.
343
375
 
344
376
  SDK findings client failures preserve the endpoint's error code and message with
345
377
  the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
@@ -349,20 +381,16 @@ behavior uses the HTTP status and `Retry-After`.
349
381
 
350
382
  ### Local service removal
351
383
 
352
- The `serve` command (including `--port`), `start:server` script,
353
- `dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
354
- dashboard, and findings-service Compose deployment have been removed.
355
- `HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
356
- service. The dashboard storage projection is also removed.
384
+ If you previously used the bundled HTTP service, back up the SQLite state
385
+ directory or service volume. Set `CODEX_SECURITY_STATE_DIR` to the directory
386
+ that contains the existing database to keep using its saved scans, findings,
387
+ and duplicate groups. For clients that need HTTP, configure a service that
388
+ implements the [endpoint contract](#compatible-endpoint-contract).
357
389
 
358
- Existing SQLite databases, migrations, saved scans, findings, and duplicate
359
- groups are retained. No data migration or deletion is performed. Keep any
360
- existing service volume or state directory and back it up before changing
361
- deployments; local deduplication uses the database selected by
362
- `CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
390
+ ### Use SQLite from the SDK
363
391
 
364
- `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
365
- `SqliteFindingsStore`, and their storage types for direct storage users.
392
+ `@openai/codex-security/server` exports `OpenAiFindingEmbedder`,
393
+ `SqliteFindingsStore`, and their storage types.
366
394
 
367
395
  For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
368
396
  static key or `() => string | Promise<string>` as its first argument. It calls
@@ -370,6 +398,8 @@ the callback before each HTTP batch; the caller handles token acquisition.
370
398
  Cancellation prevents a new callback or HTTP request. Direct embedder callers
371
399
  still await a key callback that has already started.
372
400
  Pass `fetch` as the second argument and the full endpoint URL as the third.
401
+ The fourth argument accepts an `AbortSignal`; the fifth accepts an
402
+ `EmbeddingUsageObserver`.
373
403
  By default, the saved-scan deduplication APIs use environment credentials. A
374
404
  custom SDK `embedding` binding can supply an adapter with its own credentials,
375
405
  including an `OpenAiFindingEmbedder` with a renewable key callback.
@@ -396,13 +426,23 @@ and JSON on stdin. For example, `request.json` selects the existing database:
396
426
  Use an absolute Windows path on Windows. The retained helper commands accept
397
427
  these `payload` fields:
398
428
 
399
- | Command | Payload |
400
- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
401
- | `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
402
- | `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
403
- | `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
404
- | `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
405
- | `list-dedupe-groups` | `findingId`. |
429
+ | Command | Payload |
430
+ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
431
+ | `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
432
+ | `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
433
+ | `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
434
+ | `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
435
+ | `list-dedupe-groups` | `findingId`. |
436
+ | `local-dedupe` | `action: "prepare"` with `findings`, `repositoryPath`, `anchorRepositoryId`, optional `repositoryId`, and `space`; or `action: "embed"` with `entries`, `space`, `model`, and `dimensions`. |
437
+
438
+ Local embedding preparation and cache writes now use the bundled Node helper
439
+ instead of `workbench_db.py local-dedupe`. Each embed entry contains `findingId`,
440
+ the preparation response's `cacheKey`, and an `embedding` with `model` and
441
+ `vector`. Preparation returns `cacheKeys` and `findingsToEmbed`; embedding returns
442
+ an empty object. These operations use Node even when `PYTHON` is configured.
443
+ Explicitly selected external plugins retain their Python workbench route.
444
+ Saved-scan lookup and export still require Python, so the complete saved-scan
445
+ deduplication workflow continues to need it.
406
446
 
407
447
  Retained scan commands such as `workbench_db.py list-findings` keep their existing
408
448
  interface.
@@ -12,7 +12,14 @@ to its recorded base. The API does not apply a patch or infer a branch from the
12
12
  finding. It checks HEAD before and after execution; the host owns checking the
13
13
  candidate's bytes/digest and verifying that verification did not change them.
14
14
 
15
+ In this TypeScript host integration, `executor` is your application's
16
+ `RemediationExecutor`. It runs the request in the prepared checkout and returns
17
+ an execution receipt. Substitute the frozen revision, finding evidence, model
18
+ and attempt identity from your host.
19
+
15
20
  ```ts
21
+ import { runHostedRemediation } from "@openai/codex-security";
22
+
16
23
  const result = await runHostedRemediation(
17
24
  {
18
25
  version: 1,
@@ -39,6 +46,9 @@ const result = await runHostedRemediation(
39
46
  );
40
47
  ```
41
48
 
49
+ Read `result.verification?.status` and its evidence before marking a finding
50
+ fixed. A completed request can return `still_vulnerable` or `inconclusive`.
51
+
42
52
  Both instruction fields are optional and are distinct from finding data.
43
53
  Reasoning effort is passed through unchanged so the selected model and provider
44
54
  determine which values they support.
@@ -50,8 +60,7 @@ verification are separate operations.
50
60
  Set `verificationMode: "static"` to review attack paths, bypasses, and legitimate
51
61
  behavior from source and diffs, without installing dependencies or executing
52
62
  builds, tests, reproducers, or the application. Select it for both `patch` and
53
- `verify` requests when both stages should be static. Omitted or `"standard"`
54
- retains the existing behavior.
63
+ `verify` requests when both stages should be static. Use `"standard"` (the default) when runtime checks are appropriate.
55
64
 
56
65
  Static mode treats validation instructions as source-review questions. Missing
57
66
  runtime tooling alone is not a blocker; material proof gaps still produce
@@ -110,14 +119,12 @@ codex-security verify-fix --host
110
119
 
111
120
  Use `--host` alone with either command. The `run` request supplies all settings,
112
121
  and its `operation` must match the command: `patch` or `verify`, respectively.
113
- Neither command falls back to local inference. Ordinary patching and verification
114
- remain unchanged when `--host` is omitted.
122
+ The host executes the model request for either command.
115
123
 
116
124
  The SDK also exports `runHostedRemediationProtocol` for in-process hosts.
117
125
 
118
- Use the existing newline-delimited host transport: send one `run` request whose
119
- `params` are the input above; respond to `execution.run` with the executor
120
- receipt. `execution.progress` notifications use `{ requestId, event }` and are
126
+ Use one JSON object per line. Send one `run` request whose `params` are the
127
+ input above. Respond to `execution.run` with the executor receipt. `execution.progress` notifications use `{ requestId, event }` and are
121
128
  forwarded as `remediation.progress` with `{ id: originalRunId, event }`. Send
122
129
  `cancel` with `{ id: originalRunId }` to receive `execution.cancel`; then return
123
130
  the final execution receipt so usage and session identity survive cancellation.
@@ -2,7 +2,7 @@
2
2
 
3
3
  `codex-security scan --host` runs one scan using newline-delimited JSON-RPC on
4
4
  stdin/stdout. Use the flag alone. It performs no login, update check, local
5
- inference, or model fallback. Ordinary local scans keep their existing behavior.
5
+ inference, or model fallback.
6
6
 
7
7
  For hosted patch generation and verification, use the separate
8
8
  [hosted remediation API](hosted-remediation.md).
@@ -22,6 +22,9 @@ accepted output independently from inference. Findings ingestion and
22
22
  deduplication consume that accepted output separately. CLI workbench state
23
23
  remains scan-domain state; there is no hosted-attempt replay store.
24
24
 
25
+ In this TypeScript integration, `host` is your application's executor and
26
+ receipt store. Substitute your authorized model, checkout and frozen revision.
27
+
25
28
  ```ts
26
29
  import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
27
30
 
@@ -74,43 +77,17 @@ Standard scan lifecycle. Omit `scope` for the entire repository, or pass literal
74
77
  repository-relative folders/files. Model settings come from the frozen input;
75
78
  local profiles and other local scan options are not accepted.
76
79
 
77
- Set `ownerSuggestions: true` to record ownership evidence during the existing
78
- scan execution. The scan agent may include an optional hint on each finding:
80
+ To supply grading rules, pass `severityRubric` with the Markdown text in
81
+ `markdown`, a positive integer `revision`, and the lowercase `sha256` digest of
82
+ the exact UTF-8 text, including any trailing newline. The SDK verifies the digest
83
+ before dispatch, includes the rubric in the model prompt, and echoes the snapshot
84
+ in `execution.run` and the terminal scan receipt. Omit the field to use the
85
+ existing Standard scan grading rules.
79
86
 
80
- ```json
81
- {
82
- "extensions": {
83
- "ownerSuggestion": {
84
- "email": "alex@example.test",
85
- "commit": "0123456789012345678901234567890123456789",
86
- "reason": "Maintains the affected source."
87
- }
88
- }
89
- }
90
- ```
91
-
92
- Use an observed contributor email and a full supporting commit hash from Git
93
- blame/history for the affected source. Omit the hint when ownership is unclear.
94
- Hints use the scan's existing session and budget; there is no extra ownership
95
- turn or model call. Security findings take priority over optional hints.
96
-
97
- After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
98
- CODEOWNERS declarations take precedence. Other hints must match an observed Git
99
- identity and supporting commit in the finding's evidence. Missing hints abstain;
100
- invalid hints produce per-finding owner errors. Neither invalid hints nor report
101
- failures invalidate sealed findings. A completed receipt includes the artifact
102
- when available, or `ownerSuggestionsError` if finalization fails.
103
-
104
- Hosts run the normal scan request and capture the optional owner report.
105
- Automatic reporting uses `suggestOwnersFromScan`; it does not use the legacy
106
- `ownerCodex` option or send `owner.infer` / `owner.cancel` requests.
107
-
108
- The standalone `suggestOwners` API and `suggest-owners` command can call a
109
- model under their own budget. Both paths use the same CODEOWNERS rules, Git
110
- evidence, identity checks, and report format.
111
-
112
- Report generation works after the scan reaches `maxCostUsd`. It uses the
113
- hints already recorded and never starts another model call to fill gaps.
87
+ When a logical run spans multiple attempts, save the selected snapshot in the
88
+ host's durable run state before starting its first CLI process. Send that saved
89
+ snapshot with every subsequent attempt for the same run, including attempts in
90
+ a fresh checkout or container. A configuration change then applies to new runs.
114
91
 
115
92
  `ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
116
93
  `{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
@@ -194,7 +171,7 @@ the same state. This includes:
194
171
  - The whole `stateDirectory`, including the registered workbench database,
195
172
  journals, and scan inputs; a live database file alone is not a consistent copy.
196
173
  - `outputDirectory`, where the executor records its draft and the CLI later
197
- writes the validated manifest, findings, coverage, and report.
174
+ writes the validated manifest, findings and report.
198
175
  - The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
199
176
  `CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
200
177
  by preflight and scope binding, even though they can live outside the state
@@ -263,6 +240,42 @@ resume, or finalize-only operation: calling `runHostedScan` again registers a ne
263
240
  scan. A provider reporting execution completion does not substitute for a
264
241
  validated, sealed scan receipt.
265
242
 
243
+ ## Optional owner suggestions
244
+
245
+ Set `ownerSuggestions: true` to record ownership evidence during the existing
246
+ scan execution. The scan agent may include an optional hint on each finding:
247
+
248
+ ```json
249
+ {
250
+ "extensions": {
251
+ "ownerSuggestion": {
252
+ "email": "alex@example.test",
253
+ "commit": "0123456789012345678901234567890123456789",
254
+ "reason": "Maintains the affected source."
255
+ }
256
+ }
257
+ }
258
+ ```
259
+
260
+ Use an observed contributor email and a full supporting commit hash from Git
261
+ blame/history for the affected source. Omit the hint when ownership is unclear.
262
+ The scan collects hints within its session and budget. Findings take priority
263
+ over optional hints.
264
+
265
+ After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
266
+ CODEOWNERS declarations take precedence. Other hints must match an observed Git
267
+ identity and supporting commit in the finding's evidence. Missing hints abstain;
268
+ invalid hints produce per-finding owner errors. Neither invalid hints nor report
269
+ failures invalidate sealed findings. A completed receipt includes the artifact
270
+ when available, or `ownerSuggestionsError` if finalization fails.
271
+
272
+ Read the owner report from the completed receipt. Finalization uses
273
+ `suggestOwnersFromScan` and can run after the scan reaches `maxCostUsd`.
274
+
275
+ The standalone `suggestOwners` API and `suggest-owners` command can call a
276
+ model under their own budget. Both paths use the same CODEOWNERS rules, Git
277
+ evidence, identity checks, and report format.
278
+
266
279
  ## Progress, cancellation and artifacts
267
280
 
268
281
  The host sends `execution.progress` notifications with `{requestId, event}`.
@@ -271,10 +284,20 @@ with `{id: <original run RPC id>, event}`. Invalid optional event payloads are
271
284
  ignored; mismatched request IDs are rejected. Stdout contains JSON-RPC only.
272
285
 
273
286
  Send `{"jsonrpc":"2.0","method":"cancel","params":{"id":"run"}}` with the
274
- original run request ID. The CLI aborts its executor signal, emits
287
+ original run request ID. If canceled during checkout verification, the CLI returns
288
+ a canceled receipt with the requested checkout, scope, and rubric before starting
289
+ the executor. Invalid request fields still return a JSON-RPC error.
290
+ After dispatch the CLI aborts its executor signal, emits
275
291
  `execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
276
- before returning a canceled result. The host must continue reading notifications
277
- while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
292
+ before returning a canceled result. For a registered scan, the durable lifecycle
293
+ and final scan receipt record cancellation even if the executor reports failure.
294
+ The `execution` field retains that failure, its diagnostics, and any usage.
295
+ A caller deadline expiring after registration records a failed scan, including
296
+ when the executor acknowledges the deadline with a canceled execution.
297
+ If the executor reports `acceptance_unknown`, the local scan records `failed`
298
+ and the host receives `acceptance_unknown` for reconciliation.
299
+
300
+ The host must continue reading notifications while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
278
301
  blocked output terminate the transport even while a write callback is stuck.
279
302
  Input EOF before the terminal response fails the run; EOF while that response is
280
303
  flushing waits for the write callback. A selected successful result is not a