@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
@@ -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
  {
@@ -131,8 +133,7 @@ and beneficiaries are nonempty. Candidate-only observations never become
131
133
  beneficiaries, even when selected as the final representative. An incoming
132
134
  observation participating in several reviews appears in each review's metadata.
133
135
 
134
- This is additive metadata: JSON-RPC remains 2.0 and input/result versions remain 1.
135
- Older hosts may ignore it; hosts that require attribution must validate it
136
+ Hosts that use attribution for accounting must validate it
136
137
  and reject missing or unknown identities before executing a review. Persist the
137
138
  request UUID and attribution before provisioning remote execution. The host owns
138
139
  accounting and any partitioning of invocation anchors by origin scan; the CLI
@@ -203,16 +204,11 @@ For failure or an inconclusive review, send an explicit error:
203
204
  A host error ends the review without another submission. Invalid final model
204
205
  answers, missing final decisions, and host errors make the whole batch unresolved;
205
206
  previous successful reviews in that run do not become persistence decisions.
206
- The existing algorithm treats a validated `DISTINCT` as a nonmatch, when
207
+ The CLI treats a validated `DISTINCT` as a nonmatch, when
207
208
  supplied finding content is insufficient to establish a shared correction. If the host considers the review
208
209
  inconclusive, it must return an error rather than manufacture a `DISTINCT` answer.
209
210
  No new `INCONCLUSIVE` model decision is introduced.
210
211
 
211
- The existing screening, independent pair review, contradiction-aware grouping, and
212
- severity-based representative selection are reused. No local review checkpoints
213
- are read or written in records mode. Local saved-scan execution retains its
214
- existing tool-submission validation and workflow checkpoints.
215
-
216
212
  ### Continuing a review
217
213
 
218
214
  A `review.run` request with `supportsContinuation: true` can receive the result
@@ -278,6 +274,30 @@ observation as unique. Cross-run replay/idempotency and reconciliation of remote
278
274
  work whose acceptance is uncertain belong to the host; a new process creates
279
275
  new review IDs and does not resume earlier remote execution.
280
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
+
281
301
  ## Cancellation and protocol failures
282
302
 
283
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,23 @@ 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:
47
+ A scan or workflow selector is required. Use a full scan ID, a unique prefix, or
48
+ `latest` for the current repository. The scan must be complete and its artifacts
49
+ sealed. Reviews that read source also require the local checkout.
41
50
 
42
- ```bash
43
- codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
44
- ```
51
+ Local `latest` verifies the checkout generation and component scope. Non-Git
52
+ targets match by exact path. Git history, including matches across worktrees or
53
+ clones, requires a Git executable outside all saved checkout directories. For a
54
+ legacy Git target without a recorded checkout directory, set `CODEX_SECURITY_GIT`
55
+ to an absolute, trusted Git executable. If a saved checkout contains the
56
+ available Git installation, select the scan by its explicit ID.
57
+
58
+ For older history, use an absolute `PYTHON` path when selecting system Python.
59
+ If Bun cannot locate a trusted Node.js helper, run local deduplication with
60
+ Node.js.
45
61
 
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.
49
- Local `latest` lookup matches the exact checkout path without Git. Matching
50
- across worktrees or clones additionally requires a Git executable outside all
51
- saved scan targets. If an unrelated historical target includes the available
52
- Git installation, use `codex-security dedupe --scan SCAN_ID` with an explicit
53
- saved scan ID instead.
54
62
  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.
63
+ `--all-repositories` to search the whole selected database or service.
57
64
 
58
65
  ```typescript
59
66
  import { deduplicateScan } from "@openai/codex-security";
@@ -67,6 +74,21 @@ const result = await deduplicateScan("scan_example_001", {
67
74
  console.log(result.duplicateGroups);
68
75
  ```
69
76
 
77
+ Both saved-scan APIs accept `onEmbeddingUsage` for the built-in local adapter.
78
+ It receives one observation per processed batch: model, tokenized input count
79
+ (including chunks of long findings), provider-reported input tokens, outcome,
80
+ and duration in milliseconds. `inputTokens: null` means usage was unavailable,
81
+ including responses that omit usage; it does not mean zero tokens. Cached
82
+ embeddings generate no new observations. Observers are best effort: throws,
83
+ rejections, and pending promises do not fail or block embedding work. No finding
84
+ text, vectors, credentials, or endpoint is included.
85
+
86
+ Embedding tokens remain separate from scan model-token and cost totals. A batch
87
+ can contain several HTTP attempts when the local adapter retries, and its
88
+ observation only includes usage from the final response. Remote services and
89
+ custom embedding bindings own their usage reporting; set an observer directly on
90
+ `OpenAiFindingEmbedder` when using it in a custom binding.
91
+
70
92
  For a different embedding provider or model, both saved-scan SDK methods accept
71
93
  an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
72
94
  `{ model, vector }` per input finding, in input order. The adapter owns its
@@ -118,6 +140,7 @@ The CLI and SDK return the same result:
118
140
  {
119
141
  "scanId": "scan_example_001",
120
142
  "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
143
+ "scanRepresentativeFindingIds": ["csf_852f90d6e1177502ff113d4a"],
121
144
  "duplicateGroups": [],
122
145
  "deduplicationStatus": "completed"
123
146
  }
@@ -126,8 +149,12 @@ The CLI and SDK return the same result:
126
149
  `uniqueFindingIds` contains one representative for each selected finding after
127
150
  accepted groups are collapsed. A representative can come from outside the scan.
128
151
  Each group lists its canonical finding first: highest reported severity, then
129
- finding ID to break ties. Group associations are saved before returning success;
130
- the original findings and scan artifacts remain unchanged.
152
+ finding ID to break ties. `scanRepresentativeFindingIds` gives the highest-ranked
153
+ member from the selected scan for each canonical ID in the same order, including
154
+ ungrouped findings. Pass these IDs to severity classification or Linear publication
155
+ for that scan. The SDK also returns them when resuming older saved workflows.
156
+ Dedupe saves the group associations separately from the original findings and
157
+ scan artifacts before returning success.
131
158
 
132
159
  If a model refuses a review, the result uses `completed_with_refusals` and adds
133
160
  `refusals`. Each entry contains `decision: "NO_DECISION"`, `stage`, `model`,
@@ -210,8 +237,8 @@ Empty scans and findings without eligible candidates make no review calls.
210
237
  Other scans can require multiple calls per finding. Completion means the
211
238
  retrieval, review, and group write finished; it does not mean that every pair
212
239
  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.
240
+ `AbortSignal` in the SDK, to cancel. Deep Scan merges its own workers’ findings
241
+ locally.
215
242
 
216
243
  ### Resume a findings workflow
217
244
 
@@ -326,10 +353,25 @@ const receipt = await publishScanToCustom("/path/to/completed-scan", {
326
353
  console.log(receipt.repositoryId, receipt.findingIds);
327
354
  ```
328
355
 
356
+ The Linear and custom publication SDKs return a content-free `telemetry`
357
+ summary and accept `onTelemetry` for outcomes, including preparation failure and
358
+ cancellation. Existing Linear receipts and custom workflow results retain this
359
+ summary. It includes an attempt ID, destination family, duration, outcome, and
360
+ counts of selected, submitted, created, reused, acknowledged, and failed findings.
361
+ Submitted counts describe findings handed to publication, not HTTP attempts.
362
+ `null` denotes unknown counts; in particular, the custom bulk API acknowledges
363
+ IDs without distinguishing creation from upsert. Unknown mutation outcomes are
364
+ `indeterminate`, and dry runs have `outcome: "preview"` and `attempted: false`.
365
+ Reusing a saved custom workflow receipt produces a new attempt summary with no
366
+ submitted findings. Hosts should group repeated receipt snapshots by attempt ID
367
+ and use the latest observation. Callback failures do not change publication
368
+ results, and these callbacks add no network destination or separate files.
369
+
329
370
  ## Compatible endpoint contract
330
371
 
331
- The retained HTTP clients use these endpoints on the supplied base URL,
332
- preserving its base path:
372
+ The HTTP client appends these paths to the configured base URL, preserving any base path.
373
+ It follows redirects within that origin (scheme, host, and port). If the service
374
+ moves to another origin, set `--findings-url` to its new base URL.
333
375
 
334
376
  | Method | Path | Response |
335
377
  | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
@@ -341,8 +383,8 @@ Publication sends `{findings, repositoryId}`. Candidate requests include either
341
383
  `repositoryId` or `allRepositories=true`. Group writes send
342
384
  `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
343
385
  workflow retries. Both POST endpoints must persist their writes before
344
- acknowledging them and return a JSON body. An explicit URL selects this remote
345
- contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
386
+ acknowledging them and return a JSON body. Supply your service’s base URL to use
387
+ these endpoints. With no URL, deduplication uses local SQLite.
346
388
 
347
389
  SDK findings client failures preserve the endpoint's error code and message with
348
390
  the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
@@ -352,20 +394,16 @@ behavior uses the HTTP status and `Retry-After`.
352
394
 
353
395
  ### Local service removal
354
396
 
355
- The `serve` command (including `--port`), `start:server` script,
356
- `dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
357
- dashboard, and findings-service Compose deployment have been removed.
358
- `HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
359
- service. The dashboard storage projection is also removed.
397
+ If you previously used the bundled HTTP service, back up the SQLite state
398
+ directory or service volume. Set `CODEX_SECURITY_STATE_DIR` to the directory
399
+ that contains the existing database to keep using its saved scans, findings,
400
+ and duplicate groups. For clients that need HTTP, configure a service that
401
+ implements the [endpoint contract](#compatible-endpoint-contract).
360
402
 
361
- Existing SQLite databases, migrations, saved scans, findings, and duplicate
362
- groups are retained. No data migration or deletion is performed. Keep any
363
- existing service volume or state directory and back it up before changing
364
- deployments; local deduplication uses the database selected by
365
- `CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
403
+ ### Use SQLite from the SDK
366
404
 
367
- `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
368
- `SqliteFindingsStore`, and their storage types for direct storage users.
405
+ `@openai/codex-security/server` exports `OpenAiFindingEmbedder`,
406
+ `SqliteFindingsStore`, and their storage types.
369
407
 
370
408
  For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
371
409
  static key or `() => string | Promise<string>` as its first argument. It calls
@@ -373,6 +411,8 @@ the callback before each HTTP batch; the caller handles token acquisition.
373
411
  Cancellation prevents a new callback or HTTP request. Direct embedder callers
374
412
  still await a key callback that has already started.
375
413
  Pass `fetch` as the second argument and the full endpoint URL as the third.
414
+ The fourth argument accepts an `AbortSignal`; the fifth accepts an
415
+ `EmbeddingUsageObserver`.
376
416
  By default, the saved-scan deduplication APIs use environment credentials. A
377
417
  custom SDK `embedding` binding can supply an adapter with its own credentials,
378
418
  including an `OpenAiFindingEmbedder` with a renewable key callback.
@@ -7,12 +7,21 @@ separate from the Standard scan API and does not create scan/workbench state.
7
7
 
8
8
  The host prepares an isolated checkout, freezes its HEAD, supplies the original
9
9
  finding evidence and repository instructions, and enforces the requested
10
- sandbox. For verification, the host must first apply the exact candidate patch
11
- to its recorded base. The API does not apply a patch or infer a branch from the
12
- finding. It checks HEAD before and after execution; the host owns checking the
13
- candidate's bytes/digest and verifying that verification did not change them.
10
+ sandbox. For patching, the agent must edit the supplied checkout and leave its
11
+ changes uncommitted so the host can capture the diff. For verification, the
12
+ host must first apply the exact candidate patch to its recorded base. The API
13
+ does not apply a patch or infer a branch from the finding. It checks HEAD
14
+ before dispatch and before accepting a completed execution. The host checks
15
+ the candidate's bytes/digest and verifies that verification did not change them.
16
+
17
+ In this TypeScript host integration, `executor` is your application's
18
+ `RemediationExecutor`. It runs the request in the prepared checkout and returns
19
+ an execution receipt. Substitute the frozen revision, finding evidence, model
20
+ and attempt identity from your host.
14
21
 
15
22
  ```ts
23
+ import { runHostedRemediation } from "@openai/codex-security";
24
+
16
25
  const result = await runHostedRemediation(
17
26
  {
18
27
  version: 1,
@@ -39,6 +48,9 @@ const result = await runHostedRemediation(
39
48
  );
40
49
  ```
41
50
 
51
+ Read `result.verification?.status` and its evidence before marking a finding
52
+ fixed. A completed request can return `still_vulnerable` or `inconclusive`.
53
+
42
54
  Both instruction fields are optional and are distinct from finding data.
43
55
  Reasoning effort is passed through unchanged so the selected model and provider
44
56
  determine which values they support.
@@ -50,8 +62,7 @@ verification are separate operations.
50
62
  Set `verificationMode: "static"` to review attack paths, bypasses, and legitimate
51
63
  behavior from source and diffs, without installing dependencies or executing
52
64
  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.
65
+ `verify` requests when both stages should be static. Use `"standard"` (the default) when runtime checks are appropriate.
55
66
 
56
67
  Static mode treats validation instructions as source-review questions. Missing
57
68
  runtime tooling alone is not a blocker; material proof gaps still produce
@@ -110,20 +121,25 @@ codex-security verify-fix --host
110
121
 
111
122
  Use `--host` alone with either command. The `run` request supplies all settings,
112
123
  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.
124
+ The host executes the model request for either command.
115
125
 
116
126
  The SDK also exports `runHostedRemediationProtocol` for in-process hosts.
117
127
 
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
128
+ Use one JSON object per line. Send one `run` request whose `params` are the
129
+ input above. Respond to `execution.run` with the executor receipt. `execution.progress` notifications use `{ requestId, event }` and are
121
130
  forwarded as `remediation.progress` with `{ id: originalRunId, event }`. Send
122
131
  `cancel` with `{ id: originalRunId }` to receive `execution.cancel`; then return
123
132
  the final execution receipt so usage and session identity survive cancellation.
124
133
  The transport emits one terminal result. Preparation failures are JSON-RPC
125
134
  errors; a mismatched HEAD includes `error.data.reason: "revision_mismatch"`.
126
135
 
136
+ If a completed execution ends at a different commit, the terminal `result` has
137
+ `status: "failed"`, `error.code: "INVALID_RESULT"`, and
138
+ `error.reason: "revision_changed"`. It retains the execution receipt and omits
139
+ the patch or verification outcome. To retry, start a new attempt in a fresh
140
+ checkout at `result.revision`. If Git cannot resolve HEAD after execution, the
141
+ result also fails with `INVALID_RESULT` and omits `error.reason`.
142
+
127
143
  To run the deterministic installed-package smoke check, use a source checkout
128
144
  of this repository and run the following from `sdk/typescript`. The script is
129
145
  not included in the npm package and needs no model credentials:
@@ -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
 
@@ -86,44 +89,6 @@ host's durable run state before starting its first CLI process. Send that saved
86
89
  snapshot with every subsequent attempt for the same run, including attempts in
87
90
  a fresh checkout or container. A configuration change then applies to new runs.
88
91
 
89
- Set `ownerSuggestions: true` to record ownership evidence during the existing
90
- scan execution. The scan agent may include an optional hint on each finding:
91
-
92
- ```json
93
- {
94
- "extensions": {
95
- "ownerSuggestion": {
96
- "email": "alex@example.test",
97
- "commit": "0123456789012345678901234567890123456789",
98
- "reason": "Maintains the affected source."
99
- }
100
- }
101
- }
102
- ```
103
-
104
- Use an observed contributor email and a full supporting commit hash from Git
105
- blame/history for the affected source. Omit the hint when ownership is unclear.
106
- Hints use the scan's existing session and budget; there is no extra ownership
107
- turn or model call. Security findings take priority over optional hints.
108
-
109
- After sealing the scan, the SDK builds `owner-suggestions.json` without inference.
110
- CODEOWNERS declarations take precedence. Other hints must match an observed Git
111
- identity and supporting commit in the finding's evidence. Missing hints abstain;
112
- invalid hints produce per-finding owner errors. Neither invalid hints nor report
113
- failures invalidate sealed findings. A completed receipt includes the artifact
114
- when available, or `ownerSuggestionsError` if finalization fails.
115
-
116
- Hosts run the normal scan request and capture the optional owner report.
117
- Automatic reporting uses `suggestOwnersFromScan`; it does not use the legacy
118
- `ownerCodex` option or send `owner.infer` / `owner.cancel` requests.
119
-
120
- The standalone `suggestOwners` API and `suggest-owners` command can call a
121
- model under their own budget. Both paths use the same CODEOWNERS rules, Git
122
- evidence, identity checks, and report format.
123
-
124
- Report generation works after the scan reaches `maxCostUsd`. It uses the
125
- hints already recorded and never starts another model call to fill gaps.
126
-
127
92
  `ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
128
93
  `{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
129
94
  uses the existing `ScanProgress` type; activity uses `ScanActivity`. Progress may
@@ -206,7 +171,7 @@ the same state. This includes:
206
171
  - The whole `stateDirectory`, including the registered workbench database,
207
172
  journals, and scan inputs; a live database file alone is not a consistent copy.
208
173
  - `outputDirectory`, where the executor records its draft and the CLI later
209
- writes the validated manifest, findings, coverage, and report.
174
+ writes the validated manifest, findings and report.
210
175
  - The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
211
176
  `CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
212
177
  by preflight and scope binding, even though they can live outside the state
@@ -275,6 +240,42 @@ resume, or finalize-only operation: calling `runHostedScan` again registers a ne
275
240
  scan. A provider reporting execution completion does not substitute for a
276
241
  validated, sealed scan receipt.
277
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
+
278
279
  ## Progress, cancellation and artifacts
279
280
 
280
281
  The host sends `execution.progress` notifications with `{requestId, event}`.
@@ -288,8 +289,15 @@ a canceled receipt with the requested checkout, scope, and rubric before startin
288
289
  the executor. Invalid request fields still return a JSON-RPC error.
289
290
  After dispatch the CLI aborts its executor signal, emits
290
291
  `execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
291
- before returning a canceled result. The host must continue reading notifications
292
- 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
293
301
  blocked output terminate the transport even while a write callback is stuck.
294
302
  Input EOF before the terminal response fails the run; EOF while that response is
295
303
  flushing waits for the write callback. A selected successful result is not a