@openai/codex-security 0.8.3 → 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 (534) hide show
  1. package/README.md +192 -151
  2. package/_bundled_plugin/.mcp.json +5 -1
  3. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  4. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  6. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  7. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  8. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  9. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  10. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/package.json +1 -0
  19. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  20. package/_bundled_plugin/mcp/server.mjs +2 -11
  21. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  22. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  23. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  24. package/_bundled_plugin/references/final-report.md +5 -3
  25. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  26. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  27. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  28. package/_bundled_plugin/references/scan-contract.md +27 -33
  29. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  30. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  31. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  32. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  33. package/_bundled_plugin/scripts/deep_scan_workbench.py +165 -342
  34. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  35. package/_bundled_plugin/scripts/finalize_scan_contract.py +153 -227
  36. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  37. package/_bundled_plugin/scripts/launch_codex_security_mcp +1 -0
  38. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  39. package/_bundled_plugin/scripts/posix_scan_local_files.py +11 -0
  40. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  41. package/_bundled_plugin/scripts/report_projection.py +81 -43
  42. package/_bundled_plugin/scripts/review_state.py +8 -2
  43. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  44. package/_bundled_plugin/scripts/snapshot_sqlite.py +1 -0
  45. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  46. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  47. package/_bundled_plugin/scripts/windows_scan_local_files.py +388 -17
  48. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  49. package/_bundled_plugin/scripts/workbench/handoff.py +47 -0
  50. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  51. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  52. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  53. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  54. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  55. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  56. package/_bundled_plugin/scripts/workbench/storage.py +71 -7
  57. package/_bundled_plugin/scripts/workbench_cli.py +30 -12
  58. package/_bundled_plugin/scripts/workbench_constants.py +10 -0
  59. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  60. package/_bundled_plugin/scripts/workbench_db.py +369 -137
  61. package/_bundled_plugin/scripts/workbench_feedback.py +8 -7
  62. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  63. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  64. package/_bundled_plugin/scripts/workbench_native_indexes.py +12 -12
  65. package/_bundled_plugin/scripts/workbench_progress.py +10 -1
  66. package/_bundled_plugin/scripts/workbench_publication.py +14 -10
  67. package/_bundled_plugin/scripts/workbench_remediation.py +13 -0
  68. package/_bundled_plugin/scripts/workbench_saved_results.py +132 -77
  69. package/_bundled_plugin/scripts/workbench_scan_history.py +117 -55
  70. package/_bundled_plugin/scripts/workbench_scan_start.py +83 -24
  71. package/_bundled_plugin/scripts/workbench_scan_usage.py +644 -68
  72. package/_bundled_plugin/scripts/workbench_schema.py +44 -55
  73. package/_bundled_plugin/scripts/workbench_setup.py +13 -1
  74. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  75. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  76. package/_bundled_plugin/scripts/workbench_target.py +127 -56
  77. package/_bundled_plugin/scripts/workbench_target_state.py +3 -0
  78. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  79. package/_bundled_plugin/shared/workbench-history-repairs.json +19 -23
  80. package/_bundled_plugin/shared/workbench-migrations.json +34 -0
  81. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  82. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  83. package/_bundled_plugin/skills/fix-finding/SKILL.md +1 -1
  84. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -25
  85. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  86. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  87. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +464 -0
  88. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  89. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  90. package/dist/api.d.ts +39 -4
  91. package/dist/api.d.ts.map +1 -1
  92. package/dist/api.js +774 -292
  93. package/dist/api.js.map +1 -1
  94. package/dist/auth.d.ts.map +1 -1
  95. package/dist/auth.js +4 -6
  96. package/dist/auth.js.map +1 -1
  97. package/dist/bedrock-oss-pricing.d.ts +6 -0
  98. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  99. package/dist/bedrock-oss-pricing.js +58 -0
  100. package/dist/bedrock-oss-pricing.js.map +1 -0
  101. package/dist/bedrock-pricing.d.ts +15 -0
  102. package/dist/bedrock-pricing.d.ts.map +1 -0
  103. package/dist/bedrock-pricing.js +117 -0
  104. package/dist/bedrock-pricing.js.map +1 -0
  105. package/dist/blackduck-findings.d.ts.map +1 -1
  106. package/dist/blackduck-findings.js +35 -20
  107. package/dist/blackduck-findings.js.map +1 -1
  108. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  109. package/dist/bulk-scan-discovery.js +4 -4
  110. package/dist/bulk-scan-discovery.js.map +1 -1
  111. package/dist/checkmarx-evidence.d.ts +19 -0
  112. package/dist/checkmarx-evidence.d.ts.map +1 -0
  113. package/dist/checkmarx-evidence.js +36 -0
  114. package/dist/checkmarx-evidence.js.map +1 -0
  115. package/dist/checkmarx-findings.d.ts +4 -0
  116. package/dist/checkmarx-findings.d.ts.map +1 -0
  117. package/dist/checkmarx-findings.js +27 -0
  118. package/dist/checkmarx-findings.js.map +1 -0
  119. package/dist/checkmarx-one.d.ts +4 -0
  120. package/dist/checkmarx-one.d.ts.map +1 -0
  121. package/dist/checkmarx-one.js +53 -0
  122. package/dist/checkmarx-one.js.map +1 -0
  123. package/dist/checkmarx-repository.d.ts +12 -0
  124. package/dist/checkmarx-repository.d.ts.map +1 -0
  125. package/dist/checkmarx-repository.js +181 -0
  126. package/dist/checkmarx-repository.js.map +1 -0
  127. package/dist/checkmarx-xml.d.ts +12 -0
  128. package/dist/checkmarx-xml.d.ts.map +1 -0
  129. package/dist/checkmarx-xml.js +196 -0
  130. package/dist/checkmarx-xml.js.map +1 -0
  131. package/dist/classify-severity-records.d.ts +1 -9
  132. package/dist/classify-severity-records.d.ts.map +1 -1
  133. package/dist/classify-severity-records.js +3 -13
  134. package/dist/classify-severity-records.js.map +1 -1
  135. package/dist/classify-severity.d.ts.map +1 -1
  136. package/dist/classify-severity.js +2 -4
  137. package/dist/classify-severity.js.map +1 -1
  138. package/dist/cli.d.ts +11 -5
  139. package/dist/cli.d.ts.map +1 -1
  140. package/dist/cli.js +1734 -1238
  141. package/dist/cli.js.map +1 -1
  142. package/dist/cloud-publish.js +2 -2
  143. package/dist/cloud-publish.js.map +1 -1
  144. package/dist/component-scan.d.ts +16 -3
  145. package/dist/component-scan.d.ts.map +1 -1
  146. package/dist/component-scan.js +27 -2
  147. package/dist/component-scan.js.map +1 -1
  148. package/dist/config.d.ts.map +1 -1
  149. package/dist/config.js +100 -66
  150. package/dist/config.js.map +1 -1
  151. package/dist/continuum-findings.d.ts.map +1 -1
  152. package/dist/continuum-findings.js +80 -12
  153. package/dist/continuum-findings.js.map +1 -1
  154. package/dist/contract-values.d.ts +2 -0
  155. package/dist/contract-values.d.ts.map +1 -1
  156. package/dist/contract-values.js +12 -9
  157. package/dist/contract-values.js.map +1 -1
  158. package/dist/cost-model.d.ts +13 -1
  159. package/dist/cost-model.d.ts.map +1 -1
  160. package/dist/cost-model.js +66 -112
  161. package/dist/cost-model.js.map +1 -1
  162. package/dist/cost.d.ts +42 -3
  163. package/dist/cost.d.ts.map +1 -1
  164. package/dist/cost.js +483 -104
  165. package/dist/cost.js.map +1 -1
  166. package/dist/custom-publish.d.ts +4 -0
  167. package/dist/custom-publish.d.ts.map +1 -1
  168. package/dist/custom-publish.js +40 -3
  169. package/dist/custom-publish.js.map +1 -1
  170. package/dist/deduplication/local.d.ts +2 -2
  171. package/dist/deduplication/local.d.ts.map +1 -1
  172. package/dist/deduplication/local.js +2 -2
  173. package/dist/deduplication/local.js.map +1 -1
  174. package/dist/deduplication/refusal.d.ts.map +1 -1
  175. package/dist/deduplication/refusal.js +25 -5
  176. package/dist/deduplication/refusal.js.map +1 -1
  177. package/dist/deduplication/scan.d.ts +3 -0
  178. package/dist/deduplication/scan.d.ts.map +1 -1
  179. package/dist/deduplication/scan.js +1 -1
  180. package/dist/deduplication/scan.js.map +1 -1
  181. package/dist/deep-config.d.ts +0 -1
  182. package/dist/deep-config.d.ts.map +1 -1
  183. package/dist/deep-config.js +22 -33
  184. package/dist/deep-config.js.map +1 -1
  185. package/dist/deep-scan-defaults.d.ts +2 -0
  186. package/dist/deep-scan-defaults.d.ts.map +1 -1
  187. package/dist/deep-scan-defaults.js +28 -1
  188. package/dist/deep-scan-defaults.js.map +1 -1
  189. package/dist/deep-scan.d.ts +2 -0
  190. package/dist/deep-scan.d.ts.map +1 -1
  191. package/dist/deep-scan.js +28 -4
  192. package/dist/deep-scan.js.map +1 -1
  193. package/dist/default-severity-rubric.d.ts +1 -1
  194. package/dist/default-severity-rubric.d.ts.map +1 -1
  195. package/dist/default-severity-rubric.js +1 -1
  196. package/dist/default-severity-rubric.js.map +1 -1
  197. package/dist/endor-findings.d.ts +3 -1
  198. package/dist/endor-findings.d.ts.map +1 -1
  199. package/dist/endor-findings.js +103 -45
  200. package/dist/endor-findings.js.map +1 -1
  201. package/dist/errors.d.ts +1 -1
  202. package/dist/errors.d.ts.map +1 -1
  203. package/dist/errors.js +8 -1
  204. package/dist/errors.js.map +1 -1
  205. package/dist/external-findings-import.d.ts +5 -3
  206. package/dist/external-findings-import.d.ts.map +1 -1
  207. package/dist/external-findings-import.js +7 -6
  208. package/dist/external-findings-import.js.map +1 -1
  209. package/dist/external-findings-local.d.ts +7 -5
  210. package/dist/external-findings-local.d.ts.map +1 -1
  211. package/dist/external-findings-local.js +337 -89
  212. package/dist/external-findings-local.js.map +1 -1
  213. package/dist/external-findings-publish.d.ts +8 -6
  214. package/dist/external-findings-publish.d.ts.map +1 -1
  215. package/dist/external-findings-publish.js +1318 -258
  216. package/dist/external-findings-publish.js.map +1 -1
  217. package/dist/external-findings-read.d.ts +20 -2
  218. package/dist/external-findings-read.d.ts.map +1 -1
  219. package/dist/external-findings-read.js +148 -66
  220. package/dist/external-findings-read.js.map +1 -1
  221. package/dist/external-findings.d.ts +15 -3
  222. package/dist/external-findings.d.ts.map +1 -1
  223. package/dist/external-findings.js +42 -1
  224. package/dist/external-findings.js.map +1 -1
  225. package/dist/external-import-contract.d.ts +5 -1
  226. package/dist/external-import-contract.d.ts.map +1 -1
  227. package/dist/external-import-contract.js +23 -9
  228. package/dist/external-import-contract.js.map +1 -1
  229. package/dist/external-import-models.d.ts +1 -1
  230. package/dist/external-import-models.d.ts.map +1 -1
  231. package/dist/external-import-models.js.map +1 -1
  232. package/dist/feedback.d.ts.map +1 -1
  233. package/dist/feedback.js +5 -4
  234. package/dist/feedback.js.map +1 -1
  235. package/dist/finding-prompt.d.ts +5 -0
  236. package/dist/finding-prompt.d.ts.map +1 -0
  237. package/dist/finding-prompt.js +32 -0
  238. package/dist/finding-prompt.js.map +1 -0
  239. package/dist/findings-client.d.ts +1 -0
  240. package/dist/findings-client.d.ts.map +1 -1
  241. package/dist/findings-client.js +27 -3
  242. package/dist/findings-client.js.map +1 -1
  243. package/dist/github-advisories.d.ts.map +1 -1
  244. package/dist/github-advisories.js +0 -2
  245. package/dist/github-advisories.js.map +1 -1
  246. package/dist/github-dependabot-findings.d.ts.map +1 -1
  247. package/dist/github-dependabot-findings.js +15 -4
  248. package/dist/github-dependabot-findings.js.map +1 -1
  249. package/dist/github-findings.d.ts +4 -1
  250. package/dist/github-findings.d.ts.map +1 -1
  251. package/dist/github-findings.js +55 -30
  252. package/dist/github-findings.js.map +1 -1
  253. package/dist/hosted-git-remotes.d.ts +5 -0
  254. package/dist/hosted-git-remotes.d.ts.map +1 -0
  255. package/dist/hosted-git-remotes.js +285 -0
  256. package/dist/hosted-git-remotes.js.map +1 -0
  257. package/dist/hosted-git-repository.d.ts +28 -0
  258. package/dist/hosted-git-repository.d.ts.map +1 -0
  259. package/dist/hosted-git-repository.js +222 -0
  260. package/dist/hosted-git-repository.js.map +1 -0
  261. package/dist/hosted-scan-protocol.js +2 -2
  262. package/dist/hosted-scan-protocol.js.map +1 -1
  263. package/dist/hosted-scan.d.ts.map +1 -1
  264. package/dist/hosted-scan.js +16 -11
  265. package/dist/hosted-scan.js.map +1 -1
  266. package/dist/hosted-scanner-http.d.ts +21 -0
  267. package/dist/hosted-scanner-http.d.ts.map +1 -0
  268. package/dist/hosted-scanner-http.js +204 -0
  269. package/dist/hosted-scanner-http.js.map +1 -0
  270. package/dist/hosted-scanner-v1.d.ts +6 -0
  271. package/dist/hosted-scanner-v1.d.ts.map +1 -0
  272. package/dist/hosted-scanner-v1.js +60 -0
  273. package/dist/hosted-scanner-v1.js.map +1 -0
  274. package/dist/import-scan.d.ts.map +1 -1
  275. package/dist/import-scan.js +3 -0
  276. package/dist/import-scan.js.map +1 -1
  277. package/dist/index.d.ts +18 -7
  278. package/dist/index.d.ts.map +1 -1
  279. package/dist/index.js +10 -2
  280. package/dist/index.js.map +1 -1
  281. package/dist/inspector-findings.d.ts.map +1 -1
  282. package/dist/inspector-findings.js +47 -65
  283. package/dist/inspector-findings.js.map +1 -1
  284. package/dist/knowledge-base.d.ts.map +1 -1
  285. package/dist/knowledge-base.js +68 -5
  286. package/dist/knowledge-base.js.map +1 -1
  287. package/dist/local-git-metadata.d.ts +1 -1
  288. package/dist/local-git-metadata.d.ts.map +1 -1
  289. package/dist/local-git-metadata.js +1 -2
  290. package/dist/local-git-metadata.js.map +1 -1
  291. package/dist/multiscan.d.ts +6 -4
  292. package/dist/multiscan.d.ts.map +1 -1
  293. package/dist/multiscan.js +138 -65
  294. package/dist/multiscan.js.map +1 -1
  295. package/dist/native-json-findings.d.ts +2 -1
  296. package/dist/native-json-findings.d.ts.map +1 -1
  297. package/dist/native-json-findings.js +12 -2
  298. package/dist/native-json-findings.js.map +1 -1
  299. package/dist/opengrep-findings.d.ts +1 -0
  300. package/dist/opengrep-findings.d.ts.map +1 -1
  301. package/dist/opengrep-findings.js +17 -13
  302. package/dist/opengrep-findings.js.map +1 -1
  303. package/dist/operation-telemetry.d.ts +104 -0
  304. package/dist/operation-telemetry.d.ts.map +1 -0
  305. package/dist/operation-telemetry.js +293 -0
  306. package/dist/operation-telemetry.js.map +1 -0
  307. package/dist/plugin-python-probe.d.ts +4 -0
  308. package/dist/plugin-python-probe.d.ts.map +1 -0
  309. package/dist/plugin-python-probe.js +10 -0
  310. package/dist/plugin-python-probe.js.map +1 -0
  311. package/dist/private-finding-import.d.ts +97 -2
  312. package/dist/private-finding-import.d.ts.map +1 -1
  313. package/dist/private-finding-import.js +58 -34
  314. package/dist/private-finding-import.js.map +1 -1
  315. package/dist/provider-profile.d.ts +1 -1
  316. package/dist/provider-profile.d.ts.map +1 -1
  317. package/dist/provider-profile.js +8 -1
  318. package/dist/provider-profile.js.map +1 -1
  319. package/dist/publication-telemetry.d.ts +45 -0
  320. package/dist/publication-telemetry.d.ts.map +1 -0
  321. package/dist/publication-telemetry.js +50 -0
  322. package/dist/publication-telemetry.js.map +1 -0
  323. package/dist/publish.d.ts +4 -0
  324. package/dist/publish.d.ts.map +1 -1
  325. package/dist/publish.js +42 -2
  326. package/dist/publish.js.map +1 -1
  327. package/dist/reader-selection.d.ts +2 -0
  328. package/dist/reader-selection.d.ts.map +1 -1
  329. package/dist/reader-selection.js +8 -0
  330. package/dist/reader-selection.js.map +1 -1
  331. package/dist/remediation.d.ts +1 -4
  332. package/dist/remediation.d.ts.map +1 -1
  333. package/dist/remediation.js +3 -7
  334. package/dist/remediation.js.map +1 -1
  335. package/dist/request-metadata.d.ts +3 -0
  336. package/dist/request-metadata.d.ts.map +1 -1
  337. package/dist/request-metadata.js +9 -0
  338. package/dist/request-metadata.js.map +1 -1
  339. package/dist/result.d.ts +4 -0
  340. package/dist/result.d.ts.map +1 -1
  341. package/dist/result.js +1 -1
  342. package/dist/result.js.map +1 -1
  343. package/dist/retry-windows-rename.d.ts +8 -0
  344. package/dist/retry-windows-rename.d.ts.map +1 -0
  345. package/dist/retry-windows-rename.js +24 -0
  346. package/dist/retry-windows-rename.js.map +1 -0
  347. package/dist/runtime.d.ts +20 -0
  348. package/dist/runtime.d.ts.map +1 -1
  349. package/dist/runtime.js +313 -110
  350. package/dist/runtime.js.map +1 -1
  351. package/dist/saved-scan-bootstrap.d.ts +1 -0
  352. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  353. package/dist/saved-scan-bootstrap.js +18 -15
  354. package/dist/saved-scan-bootstrap.js.map +1 -1
  355. package/dist/scan-activity.d.ts.map +1 -1
  356. package/dist/scan-activity.js +141 -56
  357. package/dist/scan-activity.js.map +1 -1
  358. package/dist/scan-comparison.d.ts +10 -5
  359. package/dist/scan-comparison.d.ts.map +1 -1
  360. package/dist/scan-comparison.js +60 -15
  361. package/dist/scan-comparison.js.map +1 -1
  362. package/dist/scan-dashboard.d.ts +6 -6
  363. package/dist/scan-dashboard.d.ts.map +1 -1
  364. package/dist/scan-dashboard.js +75 -42
  365. package/dist/scan-dashboard.js.map +1 -1
  366. package/dist/scan-executor.d.ts +10 -1
  367. package/dist/scan-executor.d.ts.map +1 -1
  368. package/dist/scan-executor.js +22 -2
  369. package/dist/scan-executor.js.map +1 -1
  370. package/dist/scan-history-renderer.d.ts.map +1 -1
  371. package/dist/scan-history-renderer.js +9 -19
  372. package/dist/scan-history-renderer.js.map +1 -1
  373. package/dist/scan-logs.d.ts +12 -0
  374. package/dist/scan-logs.d.ts.map +1 -1
  375. package/dist/scan-logs.js +106 -77
  376. package/dist/scan-logs.js.map +1 -1
  377. package/dist/scan-measurement.d.ts +26 -0
  378. package/dist/scan-measurement.d.ts.map +1 -0
  379. package/dist/scan-measurement.js +77 -0
  380. package/dist/scan-measurement.js.map +1 -0
  381. package/dist/scan-progress.d.ts +1 -0
  382. package/dist/scan-progress.d.ts.map +1 -1
  383. package/dist/scan-progress.js +3 -0
  384. package/dist/scan-progress.js.map +1 -1
  385. package/dist/scan-sessions.d.ts.map +1 -1
  386. package/dist/scan-sessions.js +4 -1
  387. package/dist/scan-sessions.js.map +1 -1
  388. package/dist/scan-settings.d.ts +1 -1
  389. package/dist/scan-settings.d.ts.map +1 -1
  390. package/dist/scan-settings.js +1 -24
  391. package/dist/scan-settings.js.map +1 -1
  392. package/dist/scanner-import.d.ts +20 -2
  393. package/dist/scanner-import.d.ts.map +1 -1
  394. package/dist/scanner-import.js +200 -8
  395. package/dist/scanner-import.js.map +1 -1
  396. package/dist/scanner-repository-url.d.ts +4 -1
  397. package/dist/scanner-repository-url.d.ts.map +1 -1
  398. package/dist/scanner-repository-url.js +10 -6
  399. package/dist/scanner-repository-url.js.map +1 -1
  400. package/dist/security-policy.d.ts +1 -1
  401. package/dist/security-policy.d.ts.map +1 -1
  402. package/dist/security-policy.js.map +1 -1
  403. package/dist/semgrep-findings.d.ts +6 -3
  404. package/dist/semgrep-findings.d.ts.map +1 -1
  405. package/dist/semgrep-findings.js +107 -43
  406. package/dist/semgrep-findings.js.map +1 -1
  407. package/dist/semgrep-guardian-findings.d.ts +38 -0
  408. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  409. package/dist/semgrep-guardian-findings.js +165 -0
  410. package/dist/semgrep-guardian-findings.js.map +1 -0
  411. package/dist/semgrep-platform-collector.d.ts +26 -0
  412. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  413. package/dist/semgrep-platform-collector.js +108 -0
  414. package/dist/semgrep-platform-collector.js.map +1 -0
  415. package/dist/semgrep-platform-findings.d.ts +207 -6
  416. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  417. package/dist/semgrep-platform-findings.js +983 -103
  418. package/dist/semgrep-platform-findings.js.map +1 -1
  419. package/dist/semgrep-platform-v1.d.ts +6 -0
  420. package/dist/semgrep-platform-v1.d.ts.map +1 -0
  421. package/dist/semgrep-platform-v1.js +83 -0
  422. package/dist/semgrep-platform-v1.js.map +1 -0
  423. package/dist/server/api.d.ts +1 -1
  424. package/dist/server/api.d.ts.map +1 -1
  425. package/dist/server/api.js.map +1 -1
  426. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  427. package/dist/server/embedding-tokenizer.d.ts +2 -0
  428. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  429. package/dist/server/embedding-tokenizer.js +322 -0
  430. package/dist/server/embedding-tokenizer.js.map +6 -0
  431. package/dist/server/embeddings.d.ts +16 -2
  432. package/dist/server/embeddings.d.ts.map +1 -1
  433. package/dist/server/embeddings.js +35 -5
  434. package/dist/server/embeddings.js.map +1 -1
  435. package/dist/session-lines.d.ts +5 -0
  436. package/dist/session-lines.d.ts.map +1 -0
  437. package/dist/session-lines.js +60 -0
  438. package/dist/session-lines.js.map +1 -0
  439. package/dist/severity-review.d.ts +3 -1
  440. package/dist/severity-review.d.ts.map +1 -1
  441. package/dist/severity-review.js +3 -2
  442. package/dist/severity-review.js.map +1 -1
  443. package/dist/skill-authentication.d.ts +1 -0
  444. package/dist/skill-authentication.d.ts.map +1 -1
  445. package/dist/skill-authentication.js +1 -0
  446. package/dist/skill-authentication.js.map +1 -1
  447. package/dist/snyk-findings.d.ts +7 -2
  448. package/dist/snyk-findings.d.ts.map +1 -1
  449. package/dist/snyk-findings.js +93 -70
  450. package/dist/snyk-findings.js.map +1 -1
  451. package/dist/snyk-rest-findings.d.ts +76 -0
  452. package/dist/snyk-rest-findings.d.ts.map +1 -0
  453. package/dist/snyk-rest-findings.js +1051 -0
  454. package/dist/snyk-rest-findings.js.map +1 -0
  455. package/dist/snyk-rest-v1.d.ts +28 -0
  456. package/dist/snyk-rest-v1.d.ts.map +1 -0
  457. package/dist/snyk-rest-v1.js +132 -0
  458. package/dist/snyk-rest-v1.js.map +1 -0
  459. package/dist/snyk-token-origin.d.ts +4 -0
  460. package/dist/snyk-token-origin.d.ts.map +1 -0
  461. package/dist/snyk-token-origin.js +82 -0
  462. package/dist/snyk-token-origin.js.map +1 -0
  463. package/dist/sonar-collector.d.ts.map +1 -1
  464. package/dist/sonar-collector.js +0 -3
  465. package/dist/sonar-collector.js.map +1 -1
  466. package/dist/sonar-import.d.ts.map +1 -1
  467. package/dist/sonar-import.js +2 -4
  468. package/dist/sonar-import.js.map +1 -1
  469. package/dist/target-drift.d.ts +9 -0
  470. package/dist/target-drift.d.ts.map +1 -0
  471. package/dist/target-drift.js +27 -0
  472. package/dist/target-drift.js.map +1 -0
  473. package/dist/targets.d.ts +2 -0
  474. package/dist/targets.d.ts.map +1 -1
  475. package/dist/targets.js +56 -20
  476. package/dist/targets.js.map +1 -1
  477. package/dist/tenable-findings.d.ts +9 -0
  478. package/dist/tenable-findings.d.ts.map +1 -0
  479. package/dist/tenable-findings.js +122 -0
  480. package/dist/tenable-findings.js.map +1 -0
  481. package/dist/terminal-stream.d.ts +13 -0
  482. package/dist/terminal-stream.d.ts.map +1 -0
  483. package/dist/terminal-stream.js +35 -0
  484. package/dist/terminal-stream.js.map +1 -0
  485. package/dist/trivy-findings.d.ts +19 -0
  486. package/dist/trivy-findings.d.ts.map +1 -0
  487. package/dist/trivy-findings.js +435 -0
  488. package/dist/trivy-findings.js.map +1 -0
  489. package/dist/trivy-import.d.ts +19 -0
  490. package/dist/trivy-import.d.ts.map +1 -0
  491. package/dist/trivy-import.js +151 -0
  492. package/dist/trivy-import.js.map +1 -0
  493. package/dist/validation-records.js +1 -1
  494. package/dist/validation-records.js.map +1 -1
  495. package/dist/veracode-findings.d.ts +2 -0
  496. package/dist/veracode-findings.d.ts.map +1 -1
  497. package/dist/veracode-findings.js +49 -11
  498. package/dist/veracode-findings.js.map +1 -1
  499. package/dist/vertex-pricing.d.ts +8 -0
  500. package/dist/vertex-pricing.d.ts.map +1 -0
  501. package/dist/vertex-pricing.js +20 -0
  502. package/dist/vertex-pricing.js.map +1 -0
  503. package/dist/windows-path.d.ts +1 -0
  504. package/dist/windows-path.d.ts.map +1 -1
  505. package/dist/windows-path.js +26 -1
  506. package/dist/windows-path.js.map +1 -1
  507. package/dist/wiz-findings.d.ts +4 -0
  508. package/dist/wiz-findings.d.ts.map +1 -1
  509. package/dist/wiz-findings.js +57 -3
  510. package/dist/wiz-findings.js.map +1 -1
  511. package/docs/classify-severity-records.md +27 -12
  512. package/docs/cli.md +497 -550
  513. package/docs/dedupe-records.md +44 -24
  514. package/docs/findings-service.md +66 -39
  515. package/docs/hosted-remediation.md +14 -7
  516. package/docs/hosted-scans.md +50 -42
  517. package/docs/telemetry.md +236 -0
  518. package/docs/validate-records.md +78 -44
  519. package/package.json +18 -15
  520. package/schemas/external-findings.schema.json +3 -1
  521. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  522. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  523. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  524. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  525. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  526. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  527. package/dist/external-imports-feature.d.ts +0 -6
  528. package/dist/external-imports-feature.d.ts.map +0 -1
  529. package/dist/external-imports-feature.js +0 -51
  530. package/dist/external-imports-feature.js.map +0 -1
  531. package/dist/finding-normalization.d.ts +0 -5
  532. package/dist/finding-normalization.d.ts.map +0 -1
  533. package/dist/finding-normalization.js +0 -155
  534. 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
  {
@@ -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,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
 
@@ -326,10 +340,25 @@ const receipt = await publishScanToCustom("/path/to/completed-scan", {
326
340
  console.log(receipt.repositoryId, receipt.findingIds);
327
341
  ```
328
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
+
329
357
  ## Compatible endpoint contract
330
358
 
331
- The retained HTTP clients use these endpoints on the supplied base URL,
332
- 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.
333
362
 
334
363
  | Method | Path | Response |
335
364
  | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
@@ -341,8 +370,8 @@ Publication sends `{findings, repositoryId}`. Candidate requests include either
341
370
  `repositoryId` or `allRepositories=true`. Group writes send
342
371
  `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
343
372
  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.
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.
346
375
 
347
376
  SDK findings client failures preserve the endpoint's error code and message with
348
377
  the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
@@ -352,20 +381,16 @@ behavior uses the HTTP status and `Retry-After`.
352
381
 
353
382
  ### Local service removal
354
383
 
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.
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).
360
389
 
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.
390
+ ### Use SQLite from the SDK
366
391
 
367
- `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
368
- `SqliteFindingsStore`, and their storage types for direct storage users.
392
+ `@openai/codex-security/server` exports `OpenAiFindingEmbedder`,
393
+ `SqliteFindingsStore`, and their storage types.
369
394
 
370
395
  For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
371
396
  static key or `() => string | Promise<string>` as its first argument. It calls
@@ -373,6 +398,8 @@ the callback before each HTTP batch; the caller handles token acquisition.
373
398
  Cancellation prevents a new callback or HTTP request. Direct embedder callers
374
399
  still await a key callback that has already started.
375
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`.
376
403
  By default, the saved-scan deduplication APIs use environment credentials. A
377
404
  custom SDK `embedding` binding can supply an adapter with its own credentials,
378
405
  including an `OpenAiFindingEmbedder` with a renewable key callback.
@@ -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
 
@@ -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