@openai/codex-security 0.2.0 → 0.4.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 (484) hide show
  1. package/README.md +437 -2692
  2. package/_bundled_plugin/.app.json +5 -1
  3. package/_bundled_plugin/.codex-plugin/plugin.json +4 -0
  4. package/_bundled_plugin/.mcp.json +2 -0
  5. package/_bundled_plugin/examples/completed-scan/coverage.json +0 -1
  6. package/_bundled_plugin/examples/completed-scan/report.md +28 -26
  7. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +1 -1
  8. package/_bundled_plugin/mcp/helpers.mjs +1 -0
  9. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +6 -213
  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/permission-profile-preflight.mjs +556 -0
  20. package/_bundled_plugin/mcp/server.mjs +1 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  23. package/_bundled_plugin/preflight/capability-profiles.toml +0 -13
  24. package/_bundled_plugin/references/artifact-storage.md +2 -2
  25. package/_bundled_plugin/references/config-preflight.md +0 -4
  26. package/_bundled_plugin/references/core-scan.md +21 -9
  27. package/_bundled_plugin/references/final-report.md +11 -13
  28. package/_bundled_plugin/references/finding-detail-fields.md +90 -80
  29. package/_bundled_plugin/references/sarif-adapter.md +1 -1
  30. package/_bundled_plugin/references/scan-artifacts.md +1 -2
  31. package/_bundled_plugin/references/scan-contract.md +9 -4
  32. package/_bundled_plugin/references/scan-prologue.md +12 -0
  33. package/_bundled_plugin/references/security-guidance.md +2 -2
  34. package/_bundled_plugin/references/standalone-validation.md +11 -0
  35. package/_bundled_plugin/references/threat-model.md +1 -1
  36. package/_bundled_plugin/schemas/coverage.schema.json +43 -170
  37. package/_bundled_plugin/schemas/definitions/artifact-common.schema.json +2 -24
  38. package/_bundled_plugin/schemas/definitions/discovery-candidate.schema.json +49 -25
  39. package/_bundled_plugin/schemas/findings.schema.json +159 -567
  40. package/_bundled_plugin/schemas/patch-risk-assessment.schema.json +106 -119
  41. package/_bundled_plugin/schemas/scan-manifest.schema.json +78 -220
  42. package/_bundled_plugin/schemas/tools/candidate-attack-paths.schema.json +91 -83
  43. package/_bundled_plugin/schemas/tools/candidate-validations.schema.json +35 -64
  44. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +5 -2
  45. package/_bundled_plugin/schemas/tools/discovery-candidates.schema.json +6 -55
  46. package/_bundled_plugin/schemas/tools/review-items.schema.json +2 -38
  47. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +169 -294
  48. package/_bundled_plugin/scripts/codex_profile.mjs +239 -0
  49. package/_bundled_plugin/scripts/codex_session.mjs +53 -0
  50. package/_bundled_plugin/scripts/config_preflight.py +26 -62
  51. package/_bundled_plugin/scripts/deep_scan_config.py +9 -11
  52. package/_bundled_plugin/scripts/deep_scan_workbench.py +129 -150
  53. package/_bundled_plugin/scripts/finalize_scan_contract.py +321 -237
  54. package/_bundled_plugin/scripts/finding_preview.py +39 -9
  55. package/_bundled_plugin/scripts/generate_in_scope_files.py +27 -77
  56. package/_bundled_plugin/scripts/generate_rank_input.py +115 -926
  57. package/_bundled_plugin/scripts/launch_codex_security_mcp +35 -10
  58. package/_bundled_plugin/scripts/launch_codex_security_mcp.cmd +5 -5
  59. package/_bundled_plugin/scripts/rank_preview.py +42 -918
  60. package/_bundled_plugin/scripts/report_projection.py +150 -183
  61. package/_bundled_plugin/scripts/snapshot_sqlite.py +6 -1
  62. package/_bundled_plugin/scripts/threat_model_projection.py +4 -7
  63. package/_bundled_plugin/scripts/validate_scan_contract.py +4 -34
  64. package/_bundled_plugin/scripts/validate_tracking_source.py +3 -13
  65. package/_bundled_plugin/scripts/windows_scan_local_files.py +48 -3
  66. package/_bundled_plugin/scripts/workbench/handoff.py +25 -50
  67. package/_bundled_plugin/scripts/workbench/runtime_toml.py +22 -0
  68. package/_bundled_plugin/scripts/workbench/storage.py +10 -6
  69. package/_bundled_plugin/scripts/workbench_cli.py +102 -184
  70. package/_bundled_plugin/scripts/workbench_db.py +463 -464
  71. package/_bundled_plugin/scripts/workbench_feedback.py +6 -3
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +19 -1
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +18 -4
  74. package/_bundled_plugin/scripts/workbench_local_dedupe.py +136 -0
  75. package/_bundled_plugin/scripts/workbench_native_indexes.py +27 -14
  76. package/_bundled_plugin/scripts/workbench_progress.py +14 -58
  77. package/_bundled_plugin/scripts/workbench_publication.py +234 -289
  78. package/_bundled_plugin/scripts/workbench_remediation.py +12 -0
  79. package/_bundled_plugin/scripts/workbench_saved_results.py +172 -49
  80. package/_bundled_plugin/scripts/workbench_scan_history.py +57 -57
  81. package/_bundled_plugin/scripts/workbench_scan_start.py +105 -41
  82. package/_bundled_plugin/scripts/workbench_scan_usage.py +194 -42
  83. package/_bundled_plugin/scripts/workbench_schema.py +37 -1151
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +11 -1
  85. package/_bundled_plugin/scripts/workbench_target.py +430 -142
  86. package/_bundled_plugin/scripts/workbench_validation.py +31 -28
  87. package/_bundled_plugin/shared/workbench-history-repairs.json +218 -0
  88. package/_bundled_plugin/shared/workbench-migrations.json +414 -0
  89. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +15 -4
  90. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +54 -0
  92. package/_bundled_plugin/skills/cloud-findings/agents/openai.yaml +4 -0
  93. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +3 -3
  94. package/_bundled_plugin/skills/finding-discovery/SKILL.md +3 -3
  95. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +50 -20
  96. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +8 -14
  97. package/_bundled_plugin/skills/security-scan/SKILL.md +22 -7
  98. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +2 -2
  99. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +15 -1
  100. package/_bundled_plugin/skills/threat-model/SKILL.md +1 -1
  101. package/_bundled_plugin/skills/track-findings/SKILL.md +48 -176
  102. package/_bundled_plugin/skills/track-findings/references/github-security-advisories.md +16 -24
  103. package/_bundled_plugin/skills/track-findings/references/jira.md +15 -61
  104. package/_bundled_plugin/skills/triage-finding/SKILL.md +50 -289
  105. package/_bundled_plugin/skills/triage-finding/agents/openai.yaml +2 -2
  106. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +23 -43
  107. package/_bundled_plugin/skills/triage-finding/references/triage-result-contract.md +7 -1
  108. package/bin/codex-security.mjs +9 -2
  109. package/dist/api.d.ts +63 -10
  110. package/dist/api.d.ts.map +1 -1
  111. package/dist/api.js +1015 -383
  112. package/dist/api.js.map +1 -1
  113. package/dist/artifact-export.d.ts +1 -1
  114. package/dist/artifact-export.d.ts.map +1 -1
  115. package/dist/artifact-export.js +28 -13
  116. package/dist/artifact-export.js.map +1 -1
  117. package/dist/auth.d.ts +2 -6
  118. package/dist/auth.d.ts.map +1 -1
  119. package/dist/auth.js +19 -9
  120. package/dist/auth.js.map +1 -1
  121. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  122. package/dist/bulk-scan-discovery.js +1 -0
  123. package/dist/bulk-scan-discovery.js.map +1 -1
  124. package/dist/classify-severity.d.ts +26 -9
  125. package/dist/classify-severity.d.ts.map +1 -1
  126. package/dist/classify-severity.js +13 -30
  127. package/dist/classify-severity.js.map +1 -1
  128. package/dist/cli-help.d.ts.map +1 -1
  129. package/dist/cli-help.js +17 -13
  130. package/dist/cli-help.js.map +1 -1
  131. package/dist/cli-signals.d.ts +8 -0
  132. package/dist/cli-signals.d.ts.map +1 -0
  133. package/dist/cli-signals.js +28 -0
  134. package/dist/cli-signals.js.map +1 -0
  135. package/dist/cli.d.ts +4 -3
  136. package/dist/cli.d.ts.map +1 -1
  137. package/dist/cli.js +1102 -905
  138. package/dist/cli.js.map +1 -1
  139. package/dist/cloud-publish.d.ts.map +1 -1
  140. package/dist/cloud-publish.js +10 -9
  141. package/dist/cloud-publish.js.map +1 -1
  142. package/dist/codeowners.d.ts +19 -0
  143. package/dist/codeowners.d.ts.map +1 -0
  144. package/dist/codeowners.js +138 -0
  145. package/dist/codeowners.js.map +1 -0
  146. package/dist/codex-sdk-environment.d.ts +1 -0
  147. package/dist/codex-sdk-environment.d.ts.map +1 -1
  148. package/dist/codex-sdk-environment.js +40 -2
  149. package/dist/codex-sdk-environment.js.map +1 -1
  150. package/dist/component-plan.d.ts +2 -5
  151. package/dist/component-plan.d.ts.map +1 -1
  152. package/dist/component-plan.js +39 -31
  153. package/dist/component-plan.js.map +1 -1
  154. package/dist/component-scan.d.ts +6 -5
  155. package/dist/component-scan.d.ts.map +1 -1
  156. package/dist/component-scan.js +25 -36
  157. package/dist/component-scan.js.map +1 -1
  158. package/dist/config.d.ts.map +1 -1
  159. package/dist/config.js +64 -74
  160. package/dist/config.js.map +1 -1
  161. package/dist/contract.d.ts +16 -3
  162. package/dist/contract.d.ts.map +1 -1
  163. package/dist/contract.js +91 -255
  164. package/dist/contract.js.map +1 -1
  165. package/dist/cost-model.d.ts +13 -6
  166. package/dist/cost-model.d.ts.map +1 -1
  167. package/dist/cost-model.js +14 -4
  168. package/dist/cost-model.js.map +1 -1
  169. package/dist/cost.d.ts +10 -2
  170. package/dist/cost.d.ts.map +1 -1
  171. package/dist/cost.js +102 -104
  172. package/dist/cost.js.map +1 -1
  173. package/dist/custom-validation-prompt.d.ts.map +1 -1
  174. package/dist/custom-validation-prompt.js +6 -5
  175. package/dist/custom-validation-prompt.js.map +1 -1
  176. package/dist/custom-validation.d.ts +1 -2
  177. package/dist/custom-validation.d.ts.map +1 -1
  178. package/dist/custom-validation.js +9 -3
  179. package/dist/custom-validation.js.map +1 -1
  180. package/dist/deduplication/checkpointed-review.d.ts +4 -2
  181. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  182. package/dist/deduplication/checkpointed-review.js +23 -9
  183. package/dist/deduplication/checkpointed-review.js.map +1 -1
  184. package/dist/deduplication/codex-review.d.ts +8 -6
  185. package/dist/deduplication/codex-review.d.ts.map +1 -1
  186. package/dist/deduplication/codex-review.js +128 -19
  187. package/dist/deduplication/codex-review.js.map +1 -1
  188. package/dist/deduplication/deduplication-prompts.d.ts +5 -2
  189. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  190. package/dist/deduplication/deduplication-prompts.js +18 -4
  191. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  192. package/dist/deduplication/deduplication-reviewer.d.ts +27 -5
  193. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  194. package/dist/deduplication/deduplication-reviewer.js +58 -48
  195. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  196. package/dist/deduplication/deduplication.d.ts.map +1 -1
  197. package/dist/deduplication/deduplication.js +19 -51
  198. package/dist/deduplication/deduplication.js.map +1 -1
  199. package/dist/deduplication/diagnostics.d.ts +17 -0
  200. package/dist/deduplication/diagnostics.d.ts.map +1 -0
  201. package/dist/deduplication/diagnostics.js +5 -0
  202. package/dist/deduplication/diagnostics.js.map +1 -0
  203. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  204. package/dist/deduplication/finding-schema.js +7 -1
  205. package/dist/deduplication/finding-schema.js.map +1 -1
  206. package/dist/deduplication/local.d.ts +31 -0
  207. package/dist/deduplication/local.d.ts.map +1 -0
  208. package/dist/deduplication/local.js +166 -0
  209. package/dist/deduplication/local.js.map +1 -0
  210. package/dist/deduplication/records-protocol.d.ts +3 -8
  211. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  212. package/dist/deduplication/records-protocol.js +11 -184
  213. package/dist/deduplication/records-protocol.js.map +1 -1
  214. package/dist/deduplication/records.d.ts +186 -11
  215. package/dist/deduplication/records.d.ts.map +1 -1
  216. package/dist/deduplication/records.js +10 -18
  217. package/dist/deduplication/records.js.map +1 -1
  218. package/dist/deduplication/scan.d.ts +9 -3
  219. package/dist/deduplication/scan.d.ts.map +1 -1
  220. package/dist/deduplication/scan.js +158 -39
  221. package/dist/deduplication/scan.js.map +1 -1
  222. package/dist/deep-config.d.ts +2 -1
  223. package/dist/deep-config.d.ts.map +1 -1
  224. package/dist/deep-config.js +4 -4
  225. package/dist/deep-config.js.map +1 -1
  226. package/dist/deep-progress.d.ts +17 -1
  227. package/dist/deep-progress.d.ts.map +1 -1
  228. package/dist/deep-progress.js +19 -17
  229. package/dist/deep-progress.js.map +1 -1
  230. package/dist/deep-scan.d.ts +20 -0
  231. package/dist/deep-scan.d.ts.map +1 -0
  232. package/dist/deep-scan.js +113 -0
  233. package/dist/deep-scan.js.map +1 -0
  234. package/dist/errors.d.ts +2 -0
  235. package/dist/errors.d.ts.map +1 -1
  236. package/dist/errors.js +2 -0
  237. package/dist/errors.js.map +1 -1
  238. package/dist/executable-path.d.ts +2 -0
  239. package/dist/executable-path.d.ts.map +1 -0
  240. package/dist/executable-path.js +12 -0
  241. package/dist/executable-path.js.map +1 -0
  242. package/dist/feedback.d.ts +1 -4
  243. package/dist/feedback.d.ts.map +1 -1
  244. package/dist/feedback.js +54 -22
  245. package/dist/feedback.js.map +1 -1
  246. package/dist/finding-catalogue.d.ts.map +1 -1
  247. package/dist/finding-catalogue.js +4 -8
  248. package/dist/finding-catalogue.js.map +1 -1
  249. package/dist/finding-normalization.d.ts +5 -0
  250. package/dist/finding-normalization.d.ts.map +1 -0
  251. package/dist/finding-normalization.js +120 -0
  252. package/dist/finding-normalization.js.map +1 -0
  253. package/dist/finding-retrieval.d.ts +9 -0
  254. package/dist/finding-retrieval.d.ts.map +1 -1
  255. package/dist/finding-retrieval.js.map +1 -1
  256. package/dist/finding-workflow.d.ts +13 -8
  257. package/dist/finding-workflow.d.ts.map +1 -1
  258. package/dist/finding-workflow.js +14 -6
  259. package/dist/finding-workflow.js.map +1 -1
  260. package/dist/findings-client.d.ts +2 -1
  261. package/dist/findings-client.d.ts.map +1 -1
  262. package/dist/findings-client.js +36 -9
  263. package/dist/findings-client.js.map +1 -1
  264. package/dist/findings-errors.d.ts +16 -0
  265. package/dist/findings-errors.d.ts.map +1 -0
  266. package/dist/findings-errors.js +24 -0
  267. package/dist/findings-errors.js.map +1 -0
  268. package/dist/findings-import.d.ts +1 -1
  269. package/dist/findings-import.d.ts.map +1 -1
  270. package/dist/findings-import.js +12 -30
  271. package/dist/findings-import.js.map +1 -1
  272. package/dist/github.d.ts.map +1 -1
  273. package/dist/github.js +7 -1
  274. package/dist/github.js.map +1 -1
  275. package/dist/host-protocol.d.ts +19 -0
  276. package/dist/host-protocol.d.ts.map +1 -0
  277. package/dist/host-protocol.js +270 -0
  278. package/dist/host-protocol.js.map +1 -0
  279. package/dist/hosted-scan-protocol.d.ts +4 -0
  280. package/dist/hosted-scan-protocol.d.ts.map +1 -0
  281. package/dist/hosted-scan-protocol.js +25 -0
  282. package/dist/hosted-scan-protocol.js.map +1 -0
  283. package/dist/hosted-scan.d.ts +117 -0
  284. package/dist/hosted-scan.d.ts.map +1 -0
  285. package/dist/hosted-scan.js +260 -0
  286. package/dist/hosted-scan.js.map +1 -0
  287. package/dist/import-scan.d.ts.map +1 -1
  288. package/dist/import-scan.js +48 -38
  289. package/dist/import-scan.js.map +1 -1
  290. package/dist/index.d.ts +11 -4
  291. package/dist/index.d.ts.map +1 -1
  292. package/dist/index.js +2 -1
  293. package/dist/index.js.map +1 -1
  294. package/dist/knowledge-base.d.ts +7 -1
  295. package/dist/knowledge-base.d.ts.map +1 -1
  296. package/dist/knowledge-base.js +114 -46
  297. package/dist/knowledge-base.js.map +1 -1
  298. package/dist/linear.d.ts.map +1 -1
  299. package/dist/linear.js +2 -7
  300. package/dist/linear.js.map +1 -1
  301. package/dist/mock-scan.d.ts.map +1 -1
  302. package/dist/mock-scan.js +0 -1
  303. package/dist/mock-scan.js.map +1 -1
  304. package/dist/models.d.ts +0 -2
  305. package/dist/models.d.ts.map +1 -1
  306. package/dist/models.js.map +1 -1
  307. package/dist/multiscan.d.ts +9 -3
  308. package/dist/multiscan.d.ts.map +1 -1
  309. package/dist/multiscan.js +240 -135
  310. package/dist/multiscan.js.map +1 -1
  311. package/dist/owner-evidence.d.ts +10 -2
  312. package/dist/owner-evidence.d.ts.map +1 -1
  313. package/dist/owner-evidence.js +67 -8
  314. package/dist/owner-evidence.js.map +1 -1
  315. package/dist/patch-tui.d.ts.map +1 -1
  316. package/dist/patch-tui.js +3 -2
  317. package/dist/patch-tui.js.map +1 -1
  318. package/dist/project-config.js +3 -3
  319. package/dist/project-config.js.map +1 -1
  320. package/dist/provider-profile.d.ts +21 -0
  321. package/dist/provider-profile.d.ts.map +1 -0
  322. package/dist/provider-profile.js +133 -0
  323. package/dist/provider-profile.js.map +1 -0
  324. package/dist/publication-events.d.ts +6 -8
  325. package/dist/publication-events.d.ts.map +1 -1
  326. package/dist/publication-events.js +25 -50
  327. package/dist/publication-events.js.map +1 -1
  328. package/dist/publication-store.d.ts.map +1 -1
  329. package/dist/publication-store.js +95 -109
  330. package/dist/publication-store.js.map +1 -1
  331. package/dist/publication.d.ts +1 -4
  332. package/dist/publication.d.ts.map +1 -1
  333. package/dist/publication.js +2 -13
  334. package/dist/publication.js.map +1 -1
  335. package/dist/publish.d.ts +1 -5
  336. package/dist/publish.d.ts.map +1 -1
  337. package/dist/publish.js +109 -160
  338. package/dist/publish.js.map +1 -1
  339. package/dist/request-metadata.d.ts +9 -0
  340. package/dist/request-metadata.d.ts.map +1 -0
  341. package/dist/request-metadata.js +13 -0
  342. package/dist/request-metadata.js.map +1 -0
  343. package/dist/runtime.d.ts +20 -6
  344. package/dist/runtime.d.ts.map +1 -1
  345. package/dist/runtime.js +407 -148
  346. package/dist/runtime.js.map +1 -1
  347. package/dist/saved-scan-bootstrap.d.ts +14 -0
  348. package/dist/saved-scan-bootstrap.d.ts.map +1 -0
  349. package/dist/saved-scan-bootstrap.js +261 -0
  350. package/dist/saved-scan-bootstrap.js.map +1 -0
  351. package/dist/saved-scan.d.ts +1 -1
  352. package/dist/saved-scan.d.ts.map +1 -1
  353. package/dist/saved-scan.js +6 -12
  354. package/dist/saved-scan.js.map +1 -1
  355. package/dist/scan-activity.js +11 -8
  356. package/dist/scan-activity.js.map +1 -1
  357. package/dist/scan-comparison.d.ts +28 -15
  358. package/dist/scan-comparison.d.ts.map +1 -1
  359. package/dist/scan-comparison.js +276 -281
  360. package/dist/scan-comparison.js.map +1 -1
  361. package/dist/scan-dashboard.d.ts +3 -0
  362. package/dist/scan-dashboard.d.ts.map +1 -1
  363. package/dist/scan-dashboard.js +345 -77
  364. package/dist/scan-dashboard.js.map +1 -1
  365. package/dist/scan-executor.d.ts +104 -0
  366. package/dist/scan-executor.d.ts.map +1 -0
  367. package/dist/scan-executor.js +62 -0
  368. package/dist/scan-executor.js.map +1 -0
  369. package/dist/scan-history-renderer.d.ts.map +1 -1
  370. package/dist/scan-history-renderer.js +54 -13
  371. package/dist/scan-history-renderer.js.map +1 -1
  372. package/dist/scan-inputs.d.ts +6 -0
  373. package/dist/scan-inputs.d.ts.map +1 -0
  374. package/dist/scan-inputs.js +71 -0
  375. package/dist/scan-inputs.js.map +1 -0
  376. package/dist/scan-logs.d.ts +2 -3
  377. package/dist/scan-logs.d.ts.map +1 -1
  378. package/dist/scan-logs.js +12 -6
  379. package/dist/scan-logs.js.map +1 -1
  380. package/dist/scan-sessions.d.ts +4 -0
  381. package/dist/scan-sessions.d.ts.map +1 -1
  382. package/dist/scan-sessions.js +17 -0
  383. package/dist/scan-sessions.js.map +1 -1
  384. package/dist/scan-skill-paths.d.ts +8 -0
  385. package/dist/scan-skill-paths.d.ts.map +1 -0
  386. package/dist/scan-skill-paths.js +47 -0
  387. package/dist/scan-skill-paths.js.map +1 -0
  388. package/dist/security-policy-cli.d.ts.map +1 -1
  389. package/dist/security-policy-cli.js +7 -27
  390. package/dist/security-policy-cli.js.map +1 -1
  391. package/dist/security-policy.d.ts +9 -5
  392. package/dist/security-policy.d.ts.map +1 -1
  393. package/dist/security-policy.js +33 -14
  394. package/dist/security-policy.js.map +1 -1
  395. package/dist/server/api.d.ts +0 -1
  396. package/dist/server/api.d.ts.map +1 -1
  397. package/dist/server/api.js +0 -1
  398. package/dist/server/api.js.map +1 -1
  399. package/dist/server/embeddings.d.ts +3 -1
  400. package/dist/server/embeddings.d.ts.map +1 -1
  401. package/dist/server/embeddings.js +10 -3
  402. package/dist/server/embeddings.js.map +1 -1
  403. package/dist/server/errors.d.ts +5 -2
  404. package/dist/server/errors.d.ts.map +1 -1
  405. package/dist/server/errors.js +7 -0
  406. package/dist/server/errors.js.map +1 -1
  407. package/dist/server/sqlite-store.d.ts +0 -2
  408. package/dist/server/sqlite-store.d.ts.map +1 -1
  409. package/dist/server/sqlite-store.js +54 -44
  410. package/dist/server/sqlite-store.js.map +1 -1
  411. package/dist/server/storage.d.ts +0 -2
  412. package/dist/server/storage.d.ts.map +1 -1
  413. package/dist/server/storage.js.map +1 -1
  414. package/dist/severity-store.js +19 -24
  415. package/dist/severity-store.js.map +1 -1
  416. package/dist/standalone-validation-prompt.d.ts +2 -0
  417. package/dist/standalone-validation-prompt.d.ts.map +1 -0
  418. package/dist/standalone-validation-prompt.js +10 -0
  419. package/dist/standalone-validation-prompt.js.map +1 -0
  420. package/dist/suggest-owners.d.ts +4 -2
  421. package/dist/suggest-owners.d.ts.map +1 -1
  422. package/dist/suggest-owners.js +11 -5
  423. package/dist/suggest-owners.js.map +1 -1
  424. package/dist/targets.d.ts +11 -0
  425. package/dist/targets.d.ts.map +1 -1
  426. package/dist/targets.js +123 -72
  427. package/dist/targets.js.map +1 -1
  428. package/dist/trusted-executable.d.ts +2 -2
  429. package/dist/trusted-executable.d.ts.map +1 -1
  430. package/dist/trusted-executable.js +8 -6
  431. package/dist/trusted-executable.js.map +1 -1
  432. package/dist/value.js +7 -0
  433. package/dist/value.js.map +1 -1
  434. package/dist/version.js.map +1 -1
  435. package/dist/workbench-arguments.d.ts +3 -0
  436. package/dist/workbench-arguments.d.ts.map +1 -0
  437. package/dist/workbench-arguments.js +15 -0
  438. package/dist/workbench-arguments.js.map +1 -0
  439. package/dist/worker-progress.d.ts +44 -11
  440. package/dist/worker-progress.d.ts.map +1 -1
  441. package/dist/worker-progress.js +48 -49
  442. package/dist/worker-progress.js.map +1 -1
  443. package/docs/cli.md +1788 -0
  444. package/docs/findings-service.md +402 -0
  445. package/docs/hosted-scans.md +242 -0
  446. package/package.json +23 -22
  447. package/schemas/hosted-scan-v2.fixture.json +145 -0
  448. package/_bundled_plugin/schemas/tools/worker-threat-model.schema.json +0 -18
  449. package/_bundled_plugin/scripts/workbench_dashboard.py +0 -159
  450. package/_bundled_plugin/scripts/workbench_findings.py +0 -221
  451. package/_bundled_plugin/scripts/workbench_severity.py +0 -122
  452. package/_bundled_plugin/skills/assess-patch-risk/scripts/validate_patch_risk_assessment.py +0 -163
  453. package/dist/server/dashboard/THIRD_PARTY_NOTICES.txt +0 -276
  454. package/dist/server/dashboard/app.css +0 -2
  455. package/dist/server/dashboard/app.js +0 -66
  456. package/dist/server/dashboard/index.html +0 -18
  457. package/dist/server/dashboard-types.d.ts +0 -48
  458. package/dist/server/dashboard-types.d.ts.map +0 -1
  459. package/dist/server/dashboard-types.js +0 -2
  460. package/dist/server/dashboard-types.js.map +0 -1
  461. package/dist/server/dashboard.d.ts +0 -6
  462. package/dist/server/dashboard.d.ts.map +0 -1
  463. package/dist/server/dashboard.js +0 -59
  464. package/dist/server/dashboard.js.map +0 -1
  465. package/dist/server/index.d.ts +0 -2
  466. package/dist/server/index.d.ts.map +0 -1
  467. package/dist/server/index.js +0 -6
  468. package/dist/server/index.js.map +0 -1
  469. package/dist/server/routes.d.ts +0 -7
  470. package/dist/server/routes.d.ts.map +0 -1
  471. package/dist/server/routes.js +0 -98
  472. package/dist/server/routes.js.map +0 -1
  473. package/dist/server/serve.d.ts +0 -2
  474. package/dist/server/serve.d.ts.map +0 -1
  475. package/dist/server/serve.js +0 -28
  476. package/dist/server/serve.js.map +0 -1
  477. package/dist/server/server.d.ts +0 -10
  478. package/dist/server/server.d.ts.map +0 -1
  479. package/dist/server/server.js +0 -16
  480. package/dist/server/server.js.map +0 -1
  481. package/dist/server/validation.d.ts +0 -17
  482. package/dist/server/validation.d.ts.map +0 -1
  483. package/dist/server/validation.js +0 -53
  484. package/dist/server/validation.js.map +0 -1
@@ -0,0 +1,402 @@
1
+ # Findings storage and deduplication
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.
7
+
8
+ ## Local service removal
9
+
10
+ The `serve` command (including `--port`), `start:server` script,
11
+ `dist/server/index.js` entrypoint, `startFindingsServer` SDK export, browser
12
+ dashboard, and findings-service Compose deployment have been removed.
13
+ `HOST`, `PORT`, and `CODEX_SECURITY_FINDINGS_IMAGE` no longer configure a bundled
14
+ service. The dashboard storage projection is also removed.
15
+
16
+ Existing SQLite databases, migrations, saved scans, findings, and duplicate
17
+ groups are retained. No data migration or deletion is performed. Keep any
18
+ existing service volume or state directory and back it up before changing
19
+ deployments; local deduplication uses the database selected by
20
+ `CODEX_SECURITY_STATE_DIR`, not a separate service volume automatically.
21
+
22
+ `@openai/codex-security/server` continues to export `OpenAiFindingEmbedder`,
23
+ `SqliteFindingsStore`, and their storage types for direct storage users.
24
+
25
+ For direct embedding/storage integrations, `OpenAiFindingEmbedder` accepts a
26
+ static key or `() => string | Promise<string>` as its first argument. It calls
27
+ the callback before each HTTP batch; the caller handles token acquisition.
28
+ Pass `fetch` as the second argument and the full endpoint URL as the third.
29
+ By default, the saved-scan deduplication APIs use environment credentials. A
30
+ custom SDK `embedding` binding can supply an adapter with its own credentials,
31
+ including an `OpenAiFindingEmbedder` with a renewable key callback.
32
+
33
+ Custom publication, explicit remote deduplication, Cloud publication, the
34
+ plugin MCP server, and Codex app-server are unchanged.
35
+
36
+ ## Direct storage helpers
37
+
38
+ Direct callers of the retired Python findings helpers can use the retained Node
39
+ helpers from an installed plugin directory:
40
+
41
+ ```bash
42
+ scripts/launch_codex_security_mcp --helper list-stored-findings < request.json
43
+ ```
44
+
45
+ On Windows, use `scripts\launch_codex_security_mcp.cmd` with the same arguments
46
+ and JSON on stdin. For example, `request.json` selects the existing database:
47
+
48
+ ```json
49
+ {
50
+ "stateDirectory": "/absolute/path/to/state",
51
+ "payload": { "limit": 50, "offset": 0 }
52
+ }
53
+ ```
54
+
55
+ Use an absolute Windows path on Windows. The retained helper commands accept
56
+ these `payload` fields:
57
+
58
+ | Command | Payload |
59
+ | --------------------------- | ------------------------------------------------------------------------------------------------------- |
60
+ | `store-findings` | `entries` containing finding and embedding records; optional `repositoryId`. |
61
+ | `list-stored-findings` | Positive integer `limit` and non-negative integer `offset`. |
62
+ | `find-potential-duplicates` | `findingId` and `scope`: either `{ "repositoryId": "REPOSITORY_ID" }` or `{ "allRepositories": true }`. |
63
+ | `store-dedupe-groups` | `groups`, an array of finding-ID arrays. |
64
+ | `list-dedupe-groups` | `findingId`. |
65
+
66
+ Retained scan commands such as `workbench_db.py list-findings` keep their existing
67
+ interface. The dashboard projection is removed along with the browser dashboard.
68
+
69
+ ## Publish a scan
70
+
71
+ Send a completed scan to an independently operated compatible endpoint:
72
+
73
+ ```bash
74
+ codex-security publish scan --scan SCAN_ID --to custom \
75
+ --findings-url https://findings.example.com --json
76
+ ```
77
+
78
+ `--findings-url` is required. The client appends `/v1/bulk/findings` to this
79
+ base URL, preserving any base path. Custom endpoints must implement that API
80
+ and return the stored finding IDs.
81
+
82
+ Publication sends the complete sealed findings and the manifest's
83
+ `scan.target.targetId` as `repositoryId`. It leaves the scan artifacts unchanged
84
+ and does not forward model credentials. The endpoint is responsible for storing the batch before acknowledging it.
85
+
86
+ Use `--scan` for a saved scan, `--scan-dir` for an external scan directory, or
87
+ the interactive picker. Custom publication accepts one scan; CSV input and
88
+ Linear options do not apply. Add `--dry-run` to preview the payload without an
89
+ HTTP request. Upload failures and incomplete receipts fail the command. Uploads
90
+ are not automatically retried because a lost response may have been committed.
91
+
92
+ ```typescript
93
+ import { publishScanToCustom } from "@openai/codex-security";
94
+
95
+ const receipt = await publishScanToCustom("/path/to/completed-scan", {
96
+ findingsUrl: "https://findings.example.com",
97
+ // dryRun: true,
98
+ // signal: controller.signal,
99
+ });
100
+ console.log(receipt.repositoryId, receipt.findingIds);
101
+ ```
102
+
103
+ ## Compatible endpoint contract
104
+
105
+ The retained HTTP clients use these endpoints on the supplied base URL,
106
+ preserving its base path:
107
+
108
+ | Method | Path | Response |
109
+ | ------ | --------------------------------------- | ------------------------------------------------------------------------ |
110
+ | `POST` | `/v1/bulk/findings` | An array acknowledging all submitted finding IDs; order does not matter. |
111
+ | `GET` | `/v1/finding/{id}/potential-duplicates` | `{finding, potentialDuplicates}` containing complete finding records. |
112
+ | `POST` | `/v1/dedupe-groups` | A successful JSON acknowledgement, such as `{}`. |
113
+
114
+ Publication sends `{findings, repositoryId}`. Candidate requests include either
115
+ `repositoryId` or `allRepositories=true`. Group writes send
116
+ `{groups: [[findingId, ...], ...]}`; repeated membership must be idempotent for
117
+ workflow retries. Both POST endpoints must persist their writes before
118
+ acknowledging them and return a JSON body. An explicit URL selects this remote
119
+ contract instead of local SQLite. This package no longer implements or hosts the HTTP endpoints.
120
+
121
+ SDK findings client failures preserve the endpoint's error code and message with
122
+ the HTTP status. Other responses retain the HTTP-status diagnostic. Retry
123
+ behavior uses the HTTP status and `Retry-After`.
124
+
125
+ ## Deduplicate a scan
126
+
127
+ Saved-scan deduplication uses local SQLite by default. No findings service or
128
+ publication step is required:
129
+
130
+ ```bash
131
+ codex-security dedupe --scan SCAN_ID --json
132
+ ```
133
+
134
+ See [local embedding requirements](#local-embeddings-and-backups) for endpoint,
135
+ credential, and vector compatibility.
136
+
137
+ The CLI prepares missing or stale embeddings for the local repository's stored
138
+ findings, searches them, and saves reviewed duplicate groups in the workbench
139
+ database. Ordinary scans do not generate embeddings automatically. Fresh
140
+ duplicate reviews still need the configured model provider.
141
+
142
+ Local scope uses the scan's `targetId`, which identifies its local checkout.
143
+ Preparation checks this identity against the approved checkout and existing
144
+ target registration before reading findings. A detached scan directory must use
145
+ its original local target (including registered imports); artifacts cannot select
146
+ another checkout's stored corpus. The explicit findings-service mode remains
147
+ available for remotely stored artifacts. Separate clones are not automatically
148
+ combined. `--all-repositories` searches
149
+ the selected local database, including untagged imports. Historical scan IDs
150
+ select logical findings using their current stored bodies; dedupe does not
151
+ replace newer bodies with old scan artifacts. A local database does not include
152
+ findings stored only in a separate Docker volume or remote service.
153
+
154
+ To retain a centralized findings corpus, publish the scan first, or import its
155
+ findings with `repositoryId`, and explicitly select the service:
156
+
157
+ ```bash
158
+ codex-security dedupe --scan SCAN_ID --findings-url https://findings.example.com --json
159
+ ```
160
+
161
+ A scan or workflow selector is required. `--scan`
162
+ accepts a full ID, unique prefix, or `latest` for the current repository. The
163
+ scan must be complete, with sealed artifacts and a local checkout available.
164
+ Local `latest` lookup matches the exact checkout path without Git. Matching
165
+ across worktrees or clones additionally requires a Git executable outside all
166
+ saved scan targets. If an unrelated historical target includes the available
167
+ Git installation, use `codex-security dedupe --scan SCAN_ID` with an explicit
168
+ saved scan ID instead.
169
+ By default, candidates come from its manifest's `scan.target.targetId`. Use
170
+ `--all-repositories` to search the whole selected database or service. Explicit
171
+ `--findings-url` retains the existing remote lookup and publication behavior.
172
+
173
+ ```typescript
174
+ import { deduplicateScan } from "@openai/codex-security";
175
+
176
+ const result = await deduplicateScan("scan_example_001", {
177
+ // findingsUrl: "https://findings.example.com", // Optional remote corpus.
178
+ concurrency: 8,
179
+ // allRepositories: true,
180
+ // signal: controller.signal,
181
+ });
182
+ console.log(result.duplicateGroups);
183
+ ```
184
+
185
+ For a different embedding provider or model, both saved-scan SDK methods accept
186
+ an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
187
+ `{ model, vector }` per input finding, in input order. The adapter owns its
188
+ credentials, tokenization, chunking, and provider request format.
189
+
190
+ ```typescript
191
+ import { deduplicateScan, type FindingEmbedder } from "@openai/codex-security";
192
+
193
+ async function dedupeWithEmbeddings(scanId: string, embedder: FindingEmbedder) {
194
+ return await deduplicateScan(scanId, {
195
+ embedding: {
196
+ embedder,
197
+ model: "example-embedding-model",
198
+ dimensions: 384,
199
+ cacheNamespace: "example-provider:document-v1",
200
+ },
201
+ });
202
+ }
203
+ ```
204
+
205
+ Choose a stable namespace identifying the actual vector space and preprocessing
206
+ version, including any provider or model revision that changes the vectors.
207
+ Changing the namespace, model, or dimensions refreshes cached vectors. Do not
208
+ put credentials in the namespace. The local cache keeps one vector per finding;
209
+ switching spaces replaces it, and concurrent runs with different spaces may
210
+ need a retry. `embedding` cannot be combined with `findingsUrl`, whose service
211
+ owns embedding preparation. Without a binding, the existing OpenAI adapter and
212
+ endpoint setting apply.
213
+
214
+ For a sealed scan directory outside local history, supply the checkout:
215
+
216
+ ```typescript
217
+ import { deduplicateScanDirectory } from "@openai/codex-security";
218
+
219
+ const result = await deduplicateScanDirectory("/path/to/completed-scan", {
220
+ repository: "/path/to/repository",
221
+ // expectedScanId: "scan_example_001",
222
+ // concurrency: 8,
223
+ // allRepositories: true,
224
+ // signal: controller.signal,
225
+ });
226
+ console.log(result.duplicateGroups);
227
+ ```
228
+
229
+ The CLI and SDK return the same result:
230
+
231
+ ```json
232
+ {
233
+ "scanId": "scan_example_001",
234
+ "uniqueFindingIds": ["csf_852f90d6e1177502ff113d4a"],
235
+ "duplicateGroups": [],
236
+ "deduplicationStatus": "completed"
237
+ }
238
+ ```
239
+
240
+ `uniqueFindingIds` contains one representative for each selected finding after
241
+ accepted groups are collapsed. A representative can come from outside the scan.
242
+ Each group lists its canonical finding first: highest reported severity, then
243
+ finding ID to break ties. Group associations are saved before returning success;
244
+ the original findings and scan artifacts remain unchanged.
245
+
246
+ If a model refuses a review, the result uses `completed_with_refusals` and adds
247
+ `refusals`. Each entry contains `decision: "NO_DECISION"`, `stage`, `model`,
248
+ `findingIds`, and `reason`. Screening entries list the anchor first, then its
249
+ candidates. Refused pairs stay separate, including through indirect groups;
250
+ their findings are not confirmed unique. The CLI logs refusals to stderr and
251
+ exits successfully after saving the other accepted groups.
252
+
253
+ ### Reviews, concurrency, and failures
254
+
255
+ By default, deduplication retrieves all candidate neighborhoods, screens them
256
+ with `gpt-5.6-luna` at `xhigh`, then independently reviews nominated pairs with
257
+ `gpt-5.6-sol` at `high`. The host's Codex `model` and `model_reasoning_effort`
258
+ settings override these defaults for both stages. Provider selection uses the
259
+ existing Codex configuration; embedding configuration is separate. Screening
260
+ and pair-review permissions stay attached to their stages regardless of model name.
261
+ Accepted pairs form groups only when no reviewed `DISTINCT` decision or refusal
262
+ contradicts the group. Saved-scan pair reviews return a decision and rationale;
263
+ they do not generate replacement findings. The host chooses representatives
264
+ from the original records. Host-provided records reviews retain their full
265
+ merged-finding contract.
266
+
267
+ Local reviews receive the stored repository associations separately from the
268
+ finding text. When the current document matches a saved scan occurrence, this
269
+ context also includes its recorded revision and working-tree snapshot digest;
270
+ missing occurrence context is omitted rather than inferred from the current
271
+ checkout. A file in the selected checkout can establish that checkout's
272
+ current source; it cannot stand in for another repository or a historical
273
+ revision. Matching paths or snippets alone do not establish a shared maintained
274
+ control across repositories. The review does not gain permission to open other
275
+ checkouts from their stored associations.
276
+
277
+ The default concurrency is 8. Set `--concurrency N` or SDK `concurrency: N` to
278
+ change it; use 1 for serial execution.
279
+
280
+ Reviews run on the SDK/CLI host using its Codex sign-in or environment API key.
281
+ For the built-in OpenAI provider, an available `OPENAI_API_KEY` (or fallback
282
+ `CODEX_API_KEY`) is also used to
283
+ authenticate reviews, even when Codex is already signed in. The built-in
284
+ embedding adapter uses the same key selection. An embedding-only key therefore
285
+ does not select ChatGPT authentication for reviews. A custom SDK embedding
286
+ adapter can own separate embedding credentials while reviews use the host's
287
+ normal Codex authentication. Review credentials are not sent to the findings
288
+ service. Each review receives complete
289
+ original findings and may inspect the approved local checkout. Reviews preserve
290
+ severity and priority rather than reassessing them. The baseline filesystem is
291
+ read-only and excludes credentials and Codex state. Screening denies approval
292
+ requests; pair reviews use Codex's automatic approval reviewer. Web, plugins,
293
+ and inherited MCP servers are disabled. Finding content and linked tickets do
294
+ not authorize access to another target.
295
+
296
+ Reviews are ephemeral and reuse Codex's configured SQLite storage. They do not
297
+ rebuild a temporary copy of the caller's session history for every pair. Explicit
298
+ `sqlite_home` and `CODEX_SQLITE_HOME` settings remain effective, and the native
299
+ state directory is excluded from the review's source access.
300
+
301
+ The CLI reports preparation, review progress, and native warnings on stderr;
302
+ JSON results remain on stdout. The existing `CODEX_SECURITY_LOG_LEVEL=debug`
303
+ (or `LOG_LEVEL=debug`) includes structured review diagnostics with thread,
304
+ turn, and command identifiers, command failures, and native token-usage events.
305
+ Usage counters are cumulative per native thread; do not add every update.
306
+ SDK callers can receive the same events through `onDiagnostic`. Observer
307
+ failures do not interrupt reviews or discard completed results.
308
+
309
+ Models must submit a validated decision. Invalid output and eligible transient
310
+ failures are retried automatically; HTTP retries honor `Retry-After`.
311
+
312
+ Cancellation, authentication/configuration errors, permanent HTTP errors, and
313
+ required-source-access blockers are not retried. Refusals are not retried or
314
+ sent to another model. If candidate retrieval or review still fails, the
315
+ operation fails without posting groups.
316
+ A failed group-write request may already have committed; resubmitting the same
317
+ memberships does not create duplicate groups. Non-cancellation review failures
318
+ throw `DeduplicationReviewError`, with diagnostic text and `metadata` for the
319
+ stage, model, category, attempt count, and reason.
320
+
321
+ Empty scans and findings without eligible candidates make no review calls.
322
+ Other scans can require multiple calls per finding. Completion means the
323
+ retrieval, review, and group write finished; it does not mean that every pair
324
+ in the database was compared. Use Ctrl-C or SIGTERM in the CLI, or an
325
+ `AbortSignal` in the SDK, to cancel. This workflow is separate from Deep Scan's
326
+ internal reducer.
327
+
328
+ ### Resume a findings workflow
329
+
330
+ Use one workflow ID across scanning and local deduplication:
331
+
332
+ ```bash
333
+ codex-security scan /path/to/repository --workflow-id run-001
334
+ codex-security dedupe --workflow-id run-001 --json
335
+ ```
336
+
337
+ Local workflows save review checkpoints and group-write retries without
338
+ publication. A workflow remains bound to its original local database or remote
339
+ URL; use a new workflow ID to switch backends. Cancellation can retain completed
340
+ embedding preparation for retry; sealed scan artifacts remain unchanged.
341
+
342
+ For an explicitly selected remote corpus, use `--findings-url` with a separate
343
+ workflow ID:
344
+
345
+ ```bash
346
+ codex-security scan /path/to/repository --workflow-id remote-001
347
+ codex-security publish scan --workflow-id remote-001 --to custom --findings-url https://findings.example.com
348
+ codex-security dedupe --workflow-id remote-001 --findings-url https://findings.example.com --json
349
+ ```
350
+
351
+ The SDK equivalents are `workflowId` on `ScanOptions`,
352
+ `PublishScanToCustomOptions`, and `DeduplicateScanOptions`. Repeat the sequence
353
+ with the same ID after an interruption. Completed scans, acknowledged uploads,
354
+ and validated reviews are reused. This resumes completed stages, not model
355
+ turns inside an unfinished scan. Normal output-directory checks still apply.
356
+
357
+ A remote workflow can begin by publishing an existing completed scan. Publication
358
+ and dedupe can use its ID instead of `--scan`; an explicit scan must match.
359
+ With both `--workflow-id` and `--findings-url`, dedupe completes publication
360
+ only when its receipt is missing. Changing the bound scan,
361
+ destination, or repository scope requires a different ID. Use one coordinating
362
+ process per workflow. Dry runs do not advance it.
363
+
364
+ Workflow state and checkpoints live in the local workbench database under
365
+ `CODEX_SECURITY_STATE_DIR`, outside the sealed artifacts. Completed reviews are
366
+ reused only when their findings, source checkout and contents, scope, model
367
+ settings, Codex configuration/version, and review contract still match. Source
368
+ changes during review stop the attempt before group writes. Resume to review
369
+ the changed source. You can change concurrency without invalidating checkpoints.
370
+
371
+ Before posting groups, the workflow saves the reviewed result and write payload.
372
+ If acknowledgement is lost, resuming replays that payload without new model
373
+ calls. Membership-based group IDs prevent duplicates. Completed workflows,
374
+ including empty results and `completed_with_refusals`, return their saved result.
375
+ Use a new ID for a fresh review or to retry a refusal after resolving its cause.
376
+
377
+ ### Use a host-provided model backend
378
+
379
+ `codex-security dedupe --records` accepts a JSON-RPC run over stdin and emits
380
+ serial `review.run` requests on stdout. The SDK equivalent is
381
+ `deduplicateRecords(input, { reviewRunner, signal })`. These entry points need
382
+ no saved scan or findings service and perform no local model execution or
383
+ persistence. The host supplies original observations and candidate links.
384
+ See the [records protocol and Python example](dedupe-records.md).
385
+
386
+ ## Local embeddings and backups
387
+
388
+ `CODEX_SECURITY_STATE_DIR` selects the directory containing `workbench.sqlite3`.
389
+ Without an override, the CLI uses its default state directory. Back up the
390
+ entire state directory with no scans or deduplication running. Existing
391
+ append-only migrations retain finding identities and scan history.
392
+
393
+ With the default built-in adapter, new embeddings require `OPENAI_API_KEY` or
394
+ `CODEX_API_KEY`;
395
+ `OPENAI_API_KEY` takes precedence. ChatGPT login alone is insufficient.
396
+ `CODEX_SECURITY_EMBEDDINGS_URL` selects a
397
+ full embeddings endpoint URL (default `https://api.openai.com/v1/embeddings`).
398
+ The endpoint must support the OpenAI embeddings request and response protocol,
399
+ including `text-embedding-3-large`, 1,536-dimensional float vectors, and token
400
+ array inputs. Requests encode the complete finding JSON with `cl100k_base` and
401
+ send the API key as a bearer token. Long inputs are combined without truncation.
402
+ Cached compatible vectors avoid new requests.
@@ -0,0 +1,242 @@
1
+ # Hosted Standard scans (protocol v2)
2
+
3
+ `codex-security scan --host` runs one scan using newline-delimited JSON-RPC on
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.
6
+
7
+ ## Public executor API
8
+
9
+ Use the standalone `runHostedScan(input, { executor, signal, onEvent })`
10
+ function to run one hosted Standard scan. `CodexSecurity.run()` retains its local
11
+ scan behavior; it does not accept a hosted executor. The CLI command is a thin
12
+ JSON-RPC adapter around the same standalone function.
13
+
14
+ The CLI owns scan registration, plugin lifecycle, target checks, finalization,
15
+ report generation and sealed artifact validation. The host owns authorization,
16
+ frozen checkout, execution, durable run state, replay, reconciliation, usage,
17
+ billing and cleanup. It collects authoritative usage before cleanup and persists
18
+ accepted output independently from inference. Findings ingestion and
19
+ deduplication consume that accepted output separately. CLI workbench state
20
+ remains scan-domain state; there is no hosted-attempt replay store.
21
+
22
+ ```ts
23
+ import { runHostedScan, type ScanExecutor } from "@openai/codex-security";
24
+
25
+ const executor: ScanExecutor = {
26
+ async run(request, { signal, onEvent }) {
27
+ // Persist the request identity before dispatch. Mount the matching plugin,
28
+ // checkout, scan state and output directory in the remote executor.
29
+ return await host.executeOnce(request, { signal, onEvent });
30
+ },
31
+ };
32
+ const result = await runHostedScan(
33
+ {
34
+ version: 2,
35
+ repository: "/workspace/repository",
36
+ revision: "0123456789012345678901234567890123456789",
37
+ scope: { paths: ["services/api", "services/web"] },
38
+ outputDirectory: "/scan/output",
39
+ stateDirectory: "/scan/state",
40
+ model: "gpt-5.6-sol",
41
+ reasoningEffort: "high",
42
+ identity: {
43
+ runId: "run-1",
44
+ attemptId: "attempt-1",
45
+ buildId: "runtime-build",
46
+ },
47
+ },
48
+ {
49
+ executor,
50
+ onEvent(event) {
51
+ console.error(event);
52
+ },
53
+ },
54
+ );
55
+
56
+ // These host methods are application code, outside the CLI.
57
+ await host.persistReceipt(result);
58
+ if (result.status === "completed") {
59
+ // Check the frozen identity/scope and artifact paths, hashes, sizes and seals.
60
+ await host.verifyAndAcceptArtifacts(result);
61
+ } else if (result.status === "acceptance_unknown") {
62
+ // Look up the existing attempt/session; do not call runHostedScan again.
63
+ await host.reconcileExecution(result.identity, result.execution);
64
+ }
65
+ // Failed and canceled receipts remain recorded but are not accepted
66
+ // completed scans. Persistence retries reuse this receipt without more inference.
67
+ ```
68
+
69
+ The function creates and closes its scan client internally, reusing the ordinary
70
+ Standard scan lifecycle. Omit `scope` for the entire repository, or pass literal
71
+ repository-relative folders/files. Model settings come from the frozen input;
72
+ local profiles and other local scan options are not accepted.
73
+
74
+ `ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
75
+ `{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
76
+ uses the existing `ScanProgress` type; activity uses `ScanActivity`. Observer
77
+ failures cannot stop execution. Aborting waits for the executor to settle; the
78
+ host must cancel remote work and return its recorded outcome.
79
+
80
+ Preparation errors throw before execution. Execution and finalization return a
81
+ `HostedScanResult` receipt with status `completed`, `failed`,
82
+ `canceled`, or `acceptance_unknown`. The receipt retains the executor's outcome, session
83
+ identity, usage, message and structured error even if artifact finalization
84
+ fails. Only validated artifacts receive hashes and sizes. Repeated invocations
85
+ are separate scans; the host decides whether a new invocation is allowed.
86
+
87
+ Temporary runtime cleanup failures preserve the terminal receipt, including
88
+ its execution outcome, session identity, usage, and validated artifacts. They
89
+ are reported separately through `onEvent` as a failed message activity with
90
+ ID `runtime.cleanup` (a `scan.progress` notification over JSON-RPC). A cleanup
91
+ failure does not change the scan status or require another execution attempt.
92
+
93
+ ## Wire contract
94
+
95
+ Send `{"jsonrpc":"2.0","id":"run","method":"run","params":...}` with the
96
+ parameters below. IDs are strings or safe integers from -9007199254740991 through
97
+ 9007199254740991; send larger numeric identifiers as strings.
98
+
99
+ ```json
100
+ {
101
+ "version": 2,
102
+ "repository": "/workspace/repository",
103
+ "revision": "0123456789012345678901234567890123456789",
104
+ "scope": { "paths": ["services/api", "services/web"] },
105
+ "outputDirectory": "/scan/output",
106
+ "stateDirectory": "/scan/state",
107
+ "model": "gpt-5.6-sol",
108
+ "reasoningEffort": "high",
109
+ "identity": {
110
+ "runId": "example-run",
111
+ "attemptId": "example-attempt",
112
+ "buildId": "exact-runtime-build"
113
+ }
114
+ }
115
+ ```
116
+
117
+ Omit `scope` to scan the entire repository, matching the local CLI default.
118
+ `{"paths":["."]}` also means the repository. An explicit empty list is invalid;
119
+ root cannot be mixed with narrower paths. Each entry is one literal filename or
120
+ directory: `app/[slug]/page.tsx` and `reports/a,b.ts` are not patterns or lists.
121
+ Significant whitespace is preserved; `" service "` and `" "` do not select
122
+ `"service"` or the repository. An explicit empty string is invalid. Paths use the
123
+ ordinary CLI target resolver's filename semantics, with repository-relative
124
+ paths required here. They are normalized, deduplicated and sorted without
125
+ changing filename characters. Preparation also checks the existing output
126
+ contract: scope paths must be valid UTF-8 and cannot contain control characters,
127
+ backslashes, or start with a drive prefix such as `C:`. Incompatible filenames
128
+ fail before executor dispatch, including on POSIX where those files may exist.
129
+ Every selected path must exist and remain inside
130
+ the repository at the frozen revision before any execution request. Missing paths fail the whole
131
+ request; the CLI never skips them or broadens the scope. Canonical path aliases
132
+ are rejected with an actionable correction. Diff, Deep, resume, mock, local
133
+ workflow and post-scan execution are unsupported in this hosted Standard API.
134
+
135
+ The CLI verifies HEAD before path existence, registers the scan with its bundled
136
+ workbench, and sends one `execution.run` request. Its JSON-RPC ID equals the
137
+ required `params.requestId`. Params contain `version: 2`, normalized
138
+ `repository`, `revision`, `scope`, `identity`, registered `scanId`, `prompt`,
139
+ `model`, `reasoningEffort`, and `runtime`:
140
+
141
+ - `pluginRoot` and `pluginVersion`: the matching bundled plugin.
142
+ - `stateDirectory` and `outputDirectory`: writable paths outside the repository.
143
+ - `environment`: explicit runtime paths and interpreter settings, never host
144
+ inference credentials.
145
+
146
+ The CLI and executor must share these filesystem paths or explicitly transfer
147
+ the same state. This includes:
148
+
149
+ - The frozen checkout and matching `pluginRoot` tree, including its executable
150
+ helpers, skills, and MCP server.
151
+ - The whole `stateDirectory`, including the registered workbench database,
152
+ journals, and scan inputs; a live database file alone is not a consistent copy.
153
+ - `outputDirectory`, where the executor records its draft and the CLI later
154
+ writes the validated manifest, findings, coverage, and report.
155
+ - The temporary files named by `CODEX_SECURITY_CONFIG_PATH` and, for path scans,
156
+ `CODEX_SECURITY_TARGET_PATHS_FILE` in `runtime.environment`. These are required
157
+ by preflight and scope binding, even though they can live outside the state
158
+ and output directories. The supplied interpreter paths must also resolve.
159
+
160
+ Keep these paths available throughout the invocation. The CLI removes its
161
+ temporary config/scope files when the invocation closes; caller-owned state
162
+ and output directories remain available. If remote work may outlive an
163
+ `acceptance_unknown` return, the host must preserve the files that work still
164
+ needs before returning that outcome. Use shared mounts or a coordinated transfer
165
+ that preserves the supplied path bindings, not independent copies of mutable
166
+ workbench state.
167
+
168
+ Run the plugin stdio server from
169
+ `pluginRoot/scripts/launch_codex_security_mcp --stdio` with the supplied
170
+ environment. The executor needs the target files, plugin skills and registered
171
+ artifacts, and must expose `record_codex_security_scan_draft`. CLI workbench
172
+ finalization follows the turn. Merely returning model text is insufficient.
173
+ Separately provisioned executors must receive the exact frozen runtime/plugin
174
+ build and preserve state; do not interpret plugin schemas as strict Structured
175
+ Outputs schemas.
176
+
177
+ The execution response `result` has:
178
+
179
+ - Required `requestId` matching the execution request, and `status`:
180
+ `completed`, `failed`, `canceled`, or `acceptance_unknown`.
181
+ - `sessionId`, required for completed execution and optional for other outcomes.
182
+ - Optional `finalResponse`, `message`, and structured `error` with numeric `code`,
183
+ string `message` and optional `data`.
184
+ - Optional opaque host `usage`. Absence means unknown, never zero. The host collects
185
+ it for diagnostics; these observations do not replace authoritative accounting.
186
+
187
+ A transport failure or mismatched receipt is not proof of non-acceptance. The
188
+ CLI stops without resubmitting and leaves reconciliation to the host. The terminal
189
+ result retains `execution` even when scanning fails or is canceled. The runtime's
190
+ `hostProtocolVersion` identifies this protocol as version 2.
191
+ A package-exported example is available at
192
+ `@openai/codex-security/schemas/hosted-scan-v2.fixture.json`. Its `response` is
193
+ the executor's reply; `terminal` is the separate final scan receipt. The example
194
+ hashes and sizes are illustrative and do not validate any real files.
195
+
196
+ | Final scan status | Host handling |
197
+ | ---------------------- | ------------------------------------------------------------------------------------------------ |
198
+ | `completed` | Verify artifact receipts and seals before accepting output. |
199
+ | `failed` or `canceled` | Retain identity, diagnostics and any execution/usage receipt. |
200
+ | `acceptance_unknown` | Reconcile the existing remote attempt and collect usage before cleanup; do not resubmit blindly. |
201
+
202
+ Reconciliation uses the host's durable attempt/session identifiers and provider
203
+ status. Preserve state and output for inspection, and cancel or join remote work
204
+ before releasing resources it still uses. The hosted API has no replay store,
205
+ resume, or finalize-only operation: calling `runHostedScan` again registers a new
206
+ scan. A provider reporting execution completion does not substitute for a
207
+ validated, sealed scan receipt.
208
+
209
+ ## Progress, cancellation and artifacts
210
+
211
+ The host sends `execution.progress` notifications with `{requestId, event}`.
212
+ The CLI forwards valid progress/activity through `scan.progress` notifications
213
+ with `{id: <original run RPC id>, event}`. Invalid optional event payloads are
214
+ ignored; mismatched request IDs are rejected. Stdout contains JSON-RPC only.
215
+
216
+ Send `{"jsonrpc":"2.0","method":"cancel","params":{"id":"run"}}` with the
217
+ original run request ID. The CLI aborts its executor signal, emits
218
+ `execution.cancel` with `{requestId}`, and waits for the host's outcome/usage
219
+ before returning a canceled result. The host must continue reading notifications
220
+ while executing. SIGINT/SIGTERM, output errors/closure, and cancellation with
221
+ blocked output terminate the transport even while a write callback is stuck.
222
+ Input EOF before the terminal response fails the run; EOF while that response is
223
+ flushing waits for the write callback. A selected successful result is not a
224
+ successful delivery. Hosts own deadlines and independently cancel remote work
225
+ and reconcile known execution identities after transport failure.
226
+
227
+ Preparation failures include typed `error.data.reason` for missing, escaping,
228
+ aliased or syntactically invalid paths and revision mismatch. Other failures
229
+ must not be presented as missing paths.
230
+
231
+ The terminal run result includes `version: 2`, `status`, frozen
232
+ identity/revision/normalized scope, output directory, scan ID when registered,
233
+ plugin version when known, `provenance` (CLI/plugin/build identity), optional `execution`,
234
+ and `artifacts`. Each artifact is `{path, sha256, bytes}` over its exact bytes.
235
+ Receipts cover canonical outputs, sealed supplemental files, and preserved
236
+ source files bound by the manifest. Coverage limitations remain diagnostics in
237
+ completed scans; required-output failures return `failed`, and unvalidated files
238
+ never receive artifact receipts. `acceptance_unknown`, failed
239
+ and canceled results are not accepted completed scans.
240
+
241
+ The host verifies receipt paths, hashes, sizes, scope, revision and seals before
242
+ accepting output.