@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
@@ -5,15 +5,20 @@ Judge the attacker's actual starting access, the security boundary crossed, and
5
5
  ## Critical
6
6
 
7
7
  Reserve Critical for consequential, strongly supported compromise meeting all three conditions:
8
- - Access: an unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.
9
- - Impact: crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.
10
- - Evidence: demonstrated exploitation or strong source-backed validation establishes the complete attack path.
8
+
9
+ - **Access.** An unauthenticated internet attacker, ordinary external user, or publicly admitted untrusted workload can exploit the interface without employee-only access, an invitation, an approved business relationship, or compromise of a trusted supplier.
10
+ - **Impact.** Crossing an important security boundary enables consequential access to protected data, privileged actions, meaningful code execution, workload escape, or comparable compromise of the affected system.
11
+ - **Evidence.** Demonstrated exploitation or strong source-backed validation establishes the complete attack path.
11
12
 
12
13
  Second-order attacks can qualify: an external attacker plants data that a trusted user or system later processes, causing consequential unauthorized access or privileged actions.
13
14
 
14
15
  ## High
15
16
 
16
- Assign High when a realistic, evidenced path gives a lower-trust attacker a substantial unauthorized capability they did not already possess. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify; unauthenticated internet access is not required. Consequences include sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, or significant repeatable disruption of a critical or shared service. A dangerous function, production label, internal access, or the existence of a privileged credential alone is insufficient: identify the lower-trust actor, boundary crossing, and consequential new capability.
17
+ Assign High when the evidence establishes all three conditions:
18
+
19
+ - **Access.** A lower-trust actor can reach the affected operation. Internal users, partners, invited collaborators, and admitted untrusted workloads can qualify.
20
+ - **Impact.** Crossing the boundary grants a substantial new capability. Examples include access to sensitive customer or business data or reusable credentials, account takeover, meaningful cross-tenant access or actions as another user, control of production workloads or deployments, privileged identities, encryption keys or important isolation boundaries, and significant repeatable disruption of a critical or shared service.
21
+ - **Evidence.** Identify a realistic path from the actor's existing access to the new capability. A dangerous function, production label, internal access, or privileged credential alone leaves that path unproven.
17
22
 
18
23
  ## Medium
19
24
 
@@ -27,13 +27,15 @@ Use `schemas/tools/scan-draft.schema.json` for new drafts and `finding-detail-fi
27
27
 
28
28
  Use `scope` for reviewed context, artifacts, runtime/test status, validation mode, and limitations. Preserve the completed canonical `threatModel`, including source citations and uncertainty; do not reconstruct it from the final findings. A supplied or completed Markdown model is retained as `{ "format": "markdown", "content": "<exact model text>" }`. A historical context file can supply missing content but must not replace a newer canonical model.
29
29
 
30
+ The generated `report.md` counts informational findings and omits their details. Read those findings in `findings.json` or export them as SARIF or CSV.
31
+
30
32
  ## Review State And Pending Work
31
33
 
32
34
  Keep unfinished requested work and essential in-scope proof gaps in `reviewState.deferred`. Retain optional follow-up in `reviewState.openQuestions`. These notes are checkpoint bookkeeping, not measured file coverage, and do not change the scan execution outcome.
33
35
 
34
36
  Standard and diff drafts use `{ surfaces, explicitExclusions, deferred }`. Give surfaces meaningful labels and schema-defined dispositions, preserving saved surface IDs in updates. Retain reasons and evidence for rejected, not-applicable, and follow-up work. Open questions may be strings or `{ question, followUpPrompt? }` objects. An open question does not prevent the configured review from finishing.
35
37
 
36
- Preserve each saved deferred `id` or `candidateId`, use each deferred ID only once, and copy IDs assigned by the draft response into later updates. Close a generic saved task in the final Standard or diff draft with `reviewState.resolvedDeferred: [{ id, reason }]`; keep unfinished tasks deferred and update linked surfaces by ID. Candidate-linked tasks close through findings or terminal dispositions. Deep parents cannot close worker tasks; original checkpoints remain unchanged.
38
+ Preserve each saved deferred `id` or `candidateId`, use each deferred ID only once, and copy IDs assigned by the draft response into later updates. Omitting a saved task from the final draft does not by itself close it. Close a generic saved task in the final Standard or diff draft with `reviewState.resolvedDeferred: [{ id, reason }]`; keep unfinished tasks deferred and update linked surfaces by ID. Candidate-linked tasks close through findings or terminal dispositions. Deep parents cannot close worker tasks; original checkpoints remain unchanged.
37
39
 
38
40
  The workbench assigns IDs to new surfaces and derives a finding's `identity` when omitted. Review notes do not measure file coverage; do not add reviewed-surface tables or file-coverage claims to the report. Omit host-owned target/scope metadata, `reviewState.inventoryStrategy`, `reviewState.receiptRefs`, and each active finding's `findingId`, `occurrenceId` and `fingerprints` from semantic drafts. SDK-authored canonical files follow `scan-contract.md` and the SDK's supplied metadata.
39
41
 
@@ -64,9 +66,9 @@ The plugins bundled in `npm-v0.1.32` through `npm-v0.6.0` preserve the saved `id
64
66
 
65
67
  On builds containing `e6c7b28` (after `npm-v0.6.0`), first establish the corrected `identity` from independent evidence. Use this procedure only if no checkpoint has already saved the corrected identity alongside the original. If both identities are active, leave the scan unsealed and report the conflict. [Finding recovery change #1310](https://github.com/openai/codex-security/pull/1310)
66
68
 
67
- Submit the revision with its corrected identity through `record_codex_security_scan_draft` with `complete: false`. Put each distinct prior version directly in the revision's `provenance.previousFindings` array. Copy the full saved finding, including its identity, evidence and provenance, omitting only its own `provenance.previousFindings`. The workbench restores nested history for each unambiguous match. Before submitting the final draft, verify in `findings.json` and `coverage.json` that only the corrected identity is active for this finding, its prior versions are in its history, and other findings and independently pending work are intact.
69
+ Submit the revision with its corrected identity through `record_codex_security_scan_draft` with `complete: false`. Put each distinct prior version directly in the revision's `provenance.previousFindings` array. Copy the full saved finding, including its identity, evidence and provenance, omitting only its own `provenance.previousFindings`. The workbench restores nested history for each unambiguous match. Before submitting the final draft, verify in `findings.json` that only the corrected identity is active for this finding, its prior versions are in its history, and other findings are intact. Check independently pending work in the unsealed `scan-manifest.json` under `scan.reviewState`, or in `coverage.json` if the manifest references it.
68
70
 
69
- A finding or a `rejected` or `not_applicable` disposition for the same candidate can resolve a `needs_follow_up` surface. Since `npm-v0.2.0`, `coverage.resolvedDeferred` closes generic tasks by saved ID and reason. Omission alone does not retire a surface or explicit exclusion. There is no general operation to remove either entry by request or to migrate a copy of a 0.1.32 scan for these corrections. If the required correction is unsupported or still absent from the saved result, leave the scan unsealed, preserve its checkpoints and outstanding work, and report which entry still needs correction.
71
+ A finding or a `rejected` or `not_applicable` disposition for the same candidate can resolve a `needs_follow_up` surface. To close a generic task, submit its saved ID and completion reason in `reviewState.resolvedDeferred`. Older draft tools used `coverage.resolvedDeferred` beginning in `npm-v0.2.0`. Omission alone does not retire a surface or explicit exclusion. There is no general operation to remove either entry by request or to migrate a copy of a 0.1.32 scan for these corrections. If the required correction is unsupported or still absent from the saved result, leave the scan unsealed, preserve its checkpoints and outstanding work, and report which entry still needs correction.
70
72
 
71
73
  ## Response
72
74
 
@@ -37,11 +37,11 @@ The workspace **Evidence** section is an artifact navigator, not another source-
37
37
 
38
38
  ## Structured Example
39
39
 
40
- This fictional item-service fixture illustrates the field shape. Its paths, identifiers, snippets and scenario were invented for this example; they are not taken from a scan target or finding. Use the shape with your own validated source evidence.
40
+ This fictional item service illustrates how several sections reference the same code evidence. Use source evidence from your scan when filling these fields.
41
41
 
42
42
  ```json
43
43
  {
44
- "summary": "In this fictional item service, an authenticated caller can change another tenant's item title by supplying its item identifier. The write route never checks tenant ownership.",
44
+ "summary": "An authenticated caller can change another tenant's item title by supplying its item identifier. The write route never checks tenant ownership.",
45
45
  "codeEvidence": [
46
46
  {
47
47
  "id": "request-fields",
@@ -52,7 +52,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
52
52
  "language": "python",
53
53
  "role": "user_input",
54
54
  "code": "def rename_fields(body):\n return body[\"itemId\"], body[\"title\"]",
55
- "explanation": "The fictional request body selects both the item and its replacement title."
55
+ "explanation": "The request body selects both the item and its replacement title."
56
56
  },
57
57
  {
58
58
  "id": "route-forward",
@@ -74,7 +74,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
74
74
  "language": "python",
75
75
  "role": "root_control",
76
76
  "code": "def rename(self, item_id, title):\n self.items[item_id].title = title",
77
- "explanation": "The store updates the selected object without an ownership check. A caller can select another tenant's fictional item."
77
+ "explanation": "The store updates the selected object without an ownership check. A caller can select another tenant's item."
78
78
  },
79
79
  {
80
80
  "id": "item-title",
@@ -96,7 +96,7 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
96
96
  "language": "python",
97
97
  "role": "expected_control",
98
98
  "code": "def read_item(request, store, item_id):\n item = store.items[item_id]\n if item.tenant_id != request.tenant_id:\n raise PermissionError(\"Item belongs to another tenant\")\n return item",
99
- "explanation": "The fictional read route compares the stored owner with the authenticated tenant. The write route needs the same invariant."
99
+ "explanation": "The read route compares the stored owner with the authenticated tenant. The write route needs the same invariant."
100
100
  }
101
101
  ],
102
102
  "rootCause": {
@@ -110,8 +110,8 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
110
110
  ]
111
111
  },
112
112
  "validation": {
113
- "method": "static trace of the fictional fixture",
114
- "summary": "The illustrated request controls the item identifier. Neither the route nor the store checks its owner before replacing the title.",
113
+ "method": "static source trace",
114
+ "summary": "The request supplies the item identifier. Neither the route nor the store checks its owner before replacing the title.",
115
115
  "evidenceRefs": [
116
116
  "request-fields",
117
117
  "route-forward",
@@ -122,11 +122,11 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
122
122
  "The store updates the caller-selected item."
123
123
  ],
124
124
  "limitations": [
125
- "This example is invented to demonstrate the field shape; it is not a scan result."
125
+ "The trace covers the route and store. Runtime middleware was outside the review."
126
126
  ]
127
127
  },
128
128
  "attackPath": {
129
- "summary": "A fictional authenticated caller submits item/rename with another tenant's item identifier and a replacement title.",
129
+ "summary": "An authenticated caller submits `item/rename` with another tenant's item identifier and a replacement title.",
130
130
  "dataflow": {
131
131
  "summary": "request body -> rename_fields() -> rename_item() -> ItemStore.rename() -> item_title()",
132
132
  "source": "caller-selected item identifier and title",
@@ -140,10 +140,10 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
140
140
  ]
141
141
  },
142
142
  "reachability": {
143
- "summary": "The fictional caller needs access to the authenticated rename route and an item identifier belonging to another tenant.",
144
- "attacker": "authenticated caller in the invented service",
143
+ "summary": "The caller needs access to the authenticated rename route and an item identifier belonging to another tenant.",
144
+ "attacker": "authenticated caller",
145
145
  "entrypoint": "item/rename",
146
- "outcome": "unauthorized modification of a fictional item"
146
+ "outcome": "another tenant's item title changes"
147
147
  },
148
148
  "evidenceRefs": [
149
149
  "route-forward",
@@ -152,20 +152,20 @@ This fictional item-service fixture illustrates the field shape. Its paths, iden
152
152
  ],
153
153
  "impact": {
154
154
  "level": "medium",
155
- "why": "The fictional failure permits cross-tenant modification of an item title."
155
+ "why": "The caller can alter another tenant's title. The store operation changes only that field."
156
156
  },
157
157
  "likelihood": {
158
158
  "level": "medium",
159
- "why": "The invented route accepts an item identifier from the caller."
159
+ "why": "The route accepts an item identifier from the caller."
160
160
  },
161
161
  "limitations": [
162
- "No real service, repository, scan target or finding is represented."
162
+ "The trace does not establish how easily callers can learn another tenant's item identifier."
163
163
  ]
164
164
  },
165
- "remediation": "Check the selected item's tenant against the authenticated tenant before writing it; reuse the same ownership check on read and write routes.",
165
+ "remediation": "Check the selected item's tenant against the authenticated tenant before writing it. Reuse the same ownership check on read and write routes.",
166
166
  "remediationTests": [
167
- "Reject a rename when the selected fictional item belongs to another tenant.",
168
- "Allow an owner to rename its own fictional item."
167
+ "Reject a rename when the selected item belongs to another tenant.",
168
+ "Allow an owner to rename its own item."
169
169
  ],
170
170
  "preventiveControls": [
171
171
  "Keep the tenant ownership invariant in a shared item-access operation."
@@ -1,6 +1,6 @@
1
1
  # SARIF Adapter
2
2
 
3
- SARIF is a deterministic export, not the Codex Security source of truth.
3
+ Use SARIF to send saved findings to a code scanning tool. Keep the [sealed scan bundle](scan-contract.md#canonical-documents) for complete finding records.
4
4
 
5
5
  The adapter:
6
6
 
@@ -23,7 +23,13 @@ Lifecycle, rich validation evidence, attack-path context, and coverage are lossy
23
23
 
24
24
  SARIF `executionSuccessful` reflects whether the scan reached a successful terminal status. Stopped scans retain findings and include their concrete limitations as warnings. Coverage describes scope and follow-up work; neither successful execution nor an empty finding set certifies exhaustive review.
25
25
 
26
- Automatic SARIF export during finalization is best-effort so projection errors cannot invalidate a canonical seal. Use the strict adapter entry point when a consumer requires SARIF and should surface export errors.
26
+ When your pipeline requires SARIF, export it explicitly and check the exit status. The command writes the file on success and exits with code `2` on an export error. The scan remains available if automatic SARIF generation failed during finalization.
27
+
28
+ ```bash
29
+ codex-security export /path/to/scan-results --export-format sarif --output results.sarif
30
+ ```
31
+
32
+ See [Export findings](https://github.com/openai/codex-security/blob/main/sdk/typescript/docs/cli.md#export-findings) for the scan selector and source-root options.
27
33
 
28
34
  References:
29
35
 
@@ -34,9 +34,9 @@ Resolve `<python_command>` to the configured Python interpreter (`"$PYTHON"` in
34
34
 
35
35
  Workbench-owned Standard scans submit findings and coverage through `record_codex_security_scan_draft`; SDK-owned Standard scans write unsealed canonical files directly. Workbench-backed diff scans use the compact artifacts described below.
36
36
 
37
- Deep scans run ordinary Standard scan workers. Workers save progress with `complete: false` and submit final results through `record_codex_security_scan_draft`. Their checkpoints and results contain findings and review state, with optional scope and threat-model context. Pending candidates and their evidence are recorded in worker review state. Immutable checkpoints store progress across retries, cancellation, and failure. The coordinator passes completed workers' findings and context to the reducer.
37
+ Deep Scan runs Standard audits. Each worker saves findings and pending review work with `complete: false`, then submits its final result through `record_codex_security_scan_draft`. Worker checkpoints survive retries, cancellation and failure.
38
38
 
39
- Deep reducer inputs, results, and checkpoints contain findings and optional scope and threat-model context. The host writes the parent scan's unsealed `scan-manifest.json` and `findings.json` from the accepted aggregate, and retains accepted worker review state in checkpoints and the parent draft. The parent completes the scan from these artifacts. If the discovery time limit expires before any source review completes, the parent retains the deadline reason and any saved findings or pending review. See `scan-contract.md` for canonical field definitions.
39
+ After each batch the host compares the repairs described in the reports. It checks disputed pairs that share an assigned repair, or cite overlapping code when a repair could not be assigned. It merges such a pair only when one narrow edit covers both reports in full and each supplies supporting code. A finding with an additional faulty operation or insufficient evidence stays separate. Each original finding and its citations stay in the saved union. The host records comparison failures and keeps unresolved reports. It writes the parent’s unsealed `scan-manifest.json` and `findings.json` with the accepted results and their review state. If the deadline arrives before a worker finishes, the parent retains the reason and any saved findings or pending review. See `scan-contract.md` for field definitions.
40
40
 
41
41
  - A workbench-backed diff scan records all candidates once with `record_codex_security_discovery_candidates({ scanId, candidates })` and reads the canonical candidates with `list_codex_security_candidates({ scanId, cursor?, limit? })`.
42
42
  - The writer validates candidates against assigned source paths, merges rows with the same CWE ids, locations, and optional instance, preserves their text, and assigns deterministic `candidate_id` values.
@@ -91,16 +91,25 @@ Standard scans and Deep Standard scan workers include attack-path analysis direc
91
91
 
92
92
  ## Final Report Paths
93
93
 
94
- - Workbench-owned Standard or workbench-backed diff draft: `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, reviewState })`
95
- - Bound Deep Standard worker result: `record_codex_security_scan_draft({ scanId, scope?, threatModel?, findings, reviewState })`; the Deep coordinator writes the aggregated parent draft
96
- - SDK-owned Standard draft: unsealed `scan-manifest.json` and `findings.json` under the SDK-provided scan directory
97
- - Deep, workbench-backed diff, or explicitly requested Standard completed results: `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`
98
- - Final scan report: `<scan_dir>/report.md`
99
- - Detailed vulnerability write-up: `<scan_dir>/findings/<slug>/<slug>.md`
100
- - Per-finding PoC and supporting files: `<scan_dir>/findings/<slug>/poc/...`
101
- - Structural hardening portfolio: `<scan_dir>/hardening/hardening.md`
102
- - Hardening analysis, proposals, and diagrams: `<scan_dir>/hardening/...`
103
- - Final report validation notes, when validation fails: `<scan_dir>/report_validation.md`
94
+ All paths below are relative to the scan directory.
95
+
96
+ | Output | Path |
97
+ | --- | --- |
98
+ | Canonical scan receipt and findings | `scan-manifest.json` and `findings.json` |
99
+ | Readable report | `report.md` |
100
+ | Threat model, when recorded | `threatmodel.md` |
101
+ | Optional detailed finding write-up and supporting files | `findings/<slug>/<slug>.md` and `findings/<slug>/poc/` |
102
+ | Optional structural hardening portfolio | `hardening/hardening.md` and supporting files under `hardening/` |
103
+ | Report validation notes when validation fails | `report_validation.md` |
104
+ | Legacy coverage document | `coverage.json` only when referenced by the manifest's `scan.coverageRef` |
105
+
106
+ The current manifest stores additional excluded paths in `scan.review.excludedPaths`. See the [sealed scan contract](scan-contract.md#canonical-documents) for examples.
107
+
108
+ ### Draft submission and retrieval
109
+
110
+ Workbench-owned Standard scans and workbench-backed diff scans submit drafts through `record_codex_security_scan_draft({ scanId, handoffClaimToken?, scope?, threatModel?, findings, reviewState })`. Bound Deep workers submit their findings and review state through the same tool. The Deep coordinator writes the aggregated parent draft. SDK-owned Standard scans write unsealed manifest and findings files in the SDK-provided scan directory.
111
+
112
+ For Deep, workbench-backed diff, or explicitly requested Standard completed results, call `get_codex_security_completed_scan({ scanId, handoffClaimToken? })`.
104
113
 
105
114
  ## Fix Finding Paths
106
115
 
@@ -4,17 +4,18 @@ This contract defines the canonical machine-readable documents for scans that re
4
4
 
5
5
  ## Canonical Documents
6
6
 
7
- A sealed terminal bundle contains these files under `<scan_dir>`:
7
+ Open the [current example manifest](../examples/completed-scan/scan-manifest.json) alongside its [findings](../examples/completed-scan/findings.json) and [readable report](../examples/completed-scan/report.md).
8
8
 
9
- - `scan-manifest.json`: immutable terminal scan receipt after finalization
10
- - `findings.json`: semantic finding records retained when the scan reached its terminal outcome
11
- - `scan.review`: additional excluded paths, stored in the manifest
9
+ | File or field | What it contains |
10
+ | --- | --- |
11
+ | `scan-manifest.json` | Immutable receipt with scan ID, target, scope, terminal status, seal time, and artifact digests. |
12
+ | `findings.json` | Semantic finding records retained at the terminal outcome. The manifest's `scan.findingsRef` points to this file. See [finding detail fields](finding-detail-fields.md) for optional evidence and analysis. |
13
+ | `scan.review` inside the manifest | Additional excluded paths (`excludedPaths`). |
14
+ | `report.md` | Human-readable report generated from the canonical JSON. The [SARIF adapter](sarif-adapter.md) explains which fields survive export. |
12
15
 
13
- Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
16
+ See [final report paths](scan-artifacts.md#final-report-paths) for the complete directory layout and optional outputs.
14
17
 
15
- Optional structured finding details used by rich consumers are documented in `finding-detail-fields.md`. They remain part of each semantic finding record, not a projection parsed from a readable report.
16
-
17
- The existing `report.md` output remains a readable projection. Generated exports such as SARIF are also downstream projections, not part of the canonical semantic source of truth.
18
+ For a [legacy manifest](../examples/legacy-completed-scan/scan-manifest.json) with `scan.coverageRef`, read the [referenced coverage document](../examples/legacy-completed-scan/coverage.json) alongside the findings. Check for this field before opening a separate coverage file. Keep detailed evidence in scan-local artifacts and reference it from the canonical summaries.
18
19
 
19
20
  Deep-scan SARIF results and CSV rows preserve their existing instance-level presentation and add only the canonical candidate id needed to group child reports. Standard-scan CSV presentation remains unchanged.
20
21
 
@@ -24,7 +25,7 @@ Retention is an explicit consumer decision. Producing a sealed bundle must not s
24
25
 
25
26
  ## Manifest Semantics
26
27
 
27
- A sealed manifest records the terminal timestamp and hashes for the canonical documents and immutable evidence receipts included in that bundle. Readable reports and generated exports are projections and are not included in the canonical seal. Later adapters may read the sealed bundle to create projections, but must not mutate the sealed manifest or canonical documents. Store projections separately. Every sealed manifest includes exactly one artifact record for each canonical JSON document, and artifact paths must not repeat.
28
+ The manifest records the terminal timestamp and a SHA-256 digest for each file listed in `scan.artifacts`. Each path appears exactly once. The current example lists `findings.json` alone. A legacy bundle also lists its referenced coverage file, and scans that retain immutable evidence receipts list those files too. The manifest carries these digests and does not hash itself. Adapters read the sealed files and write reports or exports separately from the seal.
28
29
 
29
30
  Producers should use UTC ISO 8601 timestamps in the native SDK or plugin format. All schema-valid fractional widths remain readable on supported Python versions; parsing uses native microsecond precision. History and finding queries use native date precision and stable ID tie-breakers; ordering beyond millisecond precision is not guaranteed. Stored timestamp text remains unchanged.
30
31
 
@@ -110,20 +111,15 @@ Use CWE taxonomy separately. Do not include file names, line numbers, scan IDs,
110
111
 
111
112
  New scans publish `scan-manifest.json` and `findings.json`. The manifest owns scan identity, mode, and configured scope. `scan.review` contains only `excludedPaths`, used when comparing scans. These values do not measure the percentage of files read.
112
113
 
113
- A Deep parent retains the configured paths and notes from accepted reviews. Worker IDs distinguish each review's surfaces and deferred items; receipt references point to the original evidence. Findings reduction does not clear pending review work. If the discovery deadline arrives before a review finishes, the host preserves valid checkpoint findings and pending work with the deadline reason. See [stopped-result recovery](#stopped-result-recovery).
114
+ A Deep parent retains the configured paths and notes from accepted reviews. Worker IDs distinguish each review's surfaces and deferred items. Receipt references point to the original evidence. Merging duplicate findings preserves pending review work. If the discovery deadline arrives before a review finishes, the host preserves valid checkpoint findings and pending work with the deadline reason. See [stopped-result recovery](#stopped-result-recovery).
114
115
 
115
116
  For file-authored drafts, put `reviewState` inside `scan` in the unsealed manifest. Finalization preserves recovery details in checkpoints and replaces the draft state with the small `scan.review` summary. For tool-authored drafts, pass `reviewState` to `record_codex_security_scan_draft`.
116
117
 
117
- Deep reducers work on findings and do not need review state. Deep workers retain their own checkpoints. Comparison uses the later scan's execution status, configured scope, and additional exclusions before classifying an absent finding as resolved.
118
+ Comparison uses the later scan's execution status, configured scope and additional exclusions before classifying an absent finding as resolved.
118
119
 
119
- - scan mode and inventory strategy
120
- - included and excluded paths
121
- - reviewed surfaces
122
- - detailed receipt references
123
- - explicit exclusions
124
- - deferred work
120
+ ### Scan modes and inventory
125
121
 
126
- `mode` records the requested scan workflow:
122
+ `scan.mode` (or `mode` in a legacy coverage document) records the requested scan workflow:
127
123
 
128
124
  | Mode | Meaning |
129
125
  | ----------------- | ------------------------------------------------------------- |
@@ -135,11 +131,7 @@ Deep reducers work on findings and do not need review state. Deep workers retain
135
131
  | `working_tree` | Staged or unstaged local changes |
136
132
  | `deep_repository` | Exhaustive repeated repository-wide scan |
137
133
 
138
- `inventoryStrategy` records how the producer enumerated the reviewed content, independently of the requested scan workflow:
139
-
140
- The discovery helper's `in_scope_files.txt` input contains one UTF-8 path per line. LF and CRLF separators are accepted; filenames containing CR or LF are unsupported. Other path whitespace and spelling are preserved.
141
-
142
- For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repeated discovery is workflow metadata, not a different inventory strategy.
134
+ In a legacy coverage document, `inventoryStrategy` records how the producer enumerated the reviewed content:
143
135
 
144
136
  | Inventory strategy | Meaning |
145
137
  | ------------------ | --------------------------------------------------------- |
@@ -149,7 +141,11 @@ For a whole-repository Deep scan, keep `inventoryStrategy` as `repository`; repe
149
141
  | `directory` | Deterministic non-Git directory inventory |
150
142
  | `custom` | Producer-defined inventory described by detailed receipts |
151
143
 
152
- Review state lists reviewed surfaces, exclusions, and follow-up work. The manifest records execution status. Existing sealed bundles retain legacy metadata unchanged.
144
+ The discovery helper reads one UTF-8 path per line from `in_scope_files.txt`. It accepts LF and CRLF separators and preserves other whitespace. Filenames containing CR or LF are unsupported. For a whole-repository Deep scan, use `repository` for the inventory strategy and `deep_repository` for the mode.
145
+
146
+ ### Detailed review state in drafts, checkpoints, and legacy coverage
147
+
148
+ These records can list reviewed surfaces, exclusions, and follow-up work. Use the terminal manifest for execution status.
153
149
 
154
150
  Map detailed ledger closure into completed surface summaries in this order:
155
151
 
@@ -163,18 +159,18 @@ Map detailed ledger closure into completed surface summaries in this order:
163
159
 
164
160
  Record each explicit exclusion with a `pattern` and `reason`. Record each deferred unit with a stable `id`, a `reason`, and optional `paths` or `surfaceIds`.
165
161
 
166
- Detailed ledgers remain under the numbered scan artifact directories.
162
+ When retained, detailed ledgers live under the numbered scan artifact directories.
167
163
  Receipt references must point to regular non-symlink files under `artifacts/`.
168
164
  `scan.review` retains additional exclusions for adapters and comparison. Legacy sealed scans continue to reference their original `coverage.json`.
169
165
 
170
166
  ## Canonical Report Semantics
171
167
 
172
- The two canonical JSON files are also the only semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
168
+ In the current format, the manifest and findings are the semantic inputs to final report generation. Producers must not author `report.md`; finalization deterministically projects it after validating the canonical seal. The report remains an unsealed downstream projection and can be regenerated without changing canonical JSON or evidence artifacts.
173
169
 
174
170
  Record report-specific semantics without duplicating data already represented elsewhere:
175
171
 
176
172
  - `scan.scope`: optional narrative `summary`, reviewed artifact names, runtime/test status, validation mode, scan context, and limitations. Include/exclude paths remain the authoritative scope boundaries.
177
- - `scan.threatModel`: structured summary plus assets, trust boundaries, attacker capabilities, security objectives, and assumptions, or `{ "format": "markdown", "content": "<exact model text>" }` for a retained document. Optional model `scope` and `origin` identify the modeled paths and source separately from the scan's scope. The host derives `<scan_dir>/threatmodel.md` from this content; it is an exportable projection, not an independently authored input.
173
+ - `scan.threatModel`: structured summary plus assets, trust boundaries, attacker capabilities, security objectives, and assumptions, or `{ "format": "markdown", "content": "<exact model text>" }` for a retained document. Optional model `scope` and `origin` identify the modeled paths and source separately from the scan's scope. When completed Deep reviews supply different models, the parent retains the first model here and the other models on their worker records in the retained draft or checkpoint review state. The host derives `<scan_dir>/threatmodel.md` from the primary model; it is an exportable projection, not an independently authored input.
178
174
  - finding `validation`: validation method, direct evidence, counterevidence, and the conclusion used by the report.
179
175
  - finding `codeEvidence`: stable, exact source snippets with labels, locations, language, and explanations; `rootCause`, `validation`, and `attackPath` select the snippets they need through `evidenceRefs`.
180
176
  - finding `rootCause`: the violated invariant and the code that breaks it. Do not substitute a path/line restatement for the explanation.
@@ -187,12 +183,10 @@ These fields are optional for compatibility with existing v1 canonical artifacts
187
183
 
188
184
  ## Schemas
189
185
 
190
- New completed findings must match `schemas/tools/scan-draft.schema.json`. Finalization rejects legacy field aliases, malformed optional details, and invalid semantic slugs instead of repairing them. Historical sealed reports are validated through an in-memory compatibility adapter; their saved bytes remain unchanged. Stopped-scan recovery still salvages saved evidence.
186
+ New completed findings must match the [scan draft schema](../schemas/tools/scan-draft.schema.json). Finalization rejects legacy field aliases, malformed optional details, and invalid semantic slugs instead of repairing them. Historical sealed reports are validated through an in-memory compatibility adapter; their saved bytes remain unchanged. Stopped-scan recovery still salvages saved evidence.
191
187
 
192
- - `schemas/scan-manifest.schema.json`
193
- - `schemas/findings.schema.json`
194
- - `schemas/coverage.schema.json` for legacy scans only
188
+ - [Scan manifest schema](../schemas/scan-manifest.schema.json)
189
+ - [Findings schema](../schemas/findings.schema.json)
190
+ - [Coverage schema](../schemas/coverage.schema.json) for legacy scans
195
191
 
196
192
  V1 consumers ignore unknown properties for forward compatibility. Producers must still validate documented fields and should not emit undocumented properties casually.
197
-
198
- Representative valid contract examples live under `examples/completed-scan/`.
@@ -443,7 +443,7 @@
443
443
  "$ref": "codex-security://schemas/definitions/artifact-common.schema.json#/$defs/nonEmptyText"
444
444
  },
445
445
  "uniqueItems": true,
446
- "description": "Host-provided source finding references represented by this Deep reduction. Preserve every assigned reference exactly once."
446
+ "description": "IDs of the Standard scan findings grouped into this Deep scan finding."
447
447
  },
448
448
  "sourceFindings": {
449
449
  "type": "array",
@@ -462,7 +462,7 @@
462
462
  "required": ["id", "finding"],
463
463
  "additionalProperties": false
464
464
  },
465
- "description": "Original source payloads retained by the host for lossless semantic merges."
465
+ "description": "Original Standard scan findings retained by the host."
466
466
  },
467
467
  "source": {
468
468
  "description": "The actual finding producer. Use local_plugin only for a finding discovered by this plugin.",
@@ -0,0 +1,97 @@
1
+ """Reject registered Deep Scan targets containing only empty directories."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import errno
6
+ import json
7
+ import os
8
+ import stat
9
+ import sys
10
+ from pathlib import Path
11
+
12
+
13
+ def check_selected_targets(root: Path, selections: list[str], file_paths: list[str]) -> None:
14
+ files = set(file_paths)
15
+
16
+ def check_path(selection: str) -> tuple[Path, bool]:
17
+ relative = Path(selection)
18
+ if (
19
+ not selection
20
+ or relative.anchor
21
+ or ".." in relative.parts
22
+ or (os.name == "nt" and ":" in selection)
23
+ ):
24
+ raise ValueError(f"Scope must be inside repo: {selection}")
25
+ mode = root.lstat().st_mode
26
+ if not stat.S_ISDIR(mode):
27
+ raise ValueError(f"Deep Scan repository is no longer a directory: {root}")
28
+ target = root
29
+ for part in relative.parts:
30
+ target /= part
31
+ info = target.lstat()
32
+ mode = info.st_mode
33
+ if stat.S_ISLNK(mode) or getattr(info, "st_reparse_tag", 0) & 0x20000000:
34
+ raise ValueError(f"Requested scope must not contain symbolic links: {target}")
35
+ if not target.resolve(strict=True).is_relative_to(root):
36
+ raise ValueError(f"Scope must be inside repo: {target}")
37
+ regular = stat.S_ISREG(mode)
38
+ if selection in files and not regular:
39
+ raise ValueError(f"Selected file is no longer a regular file: {selection}")
40
+ if not regular and not stat.S_ISDIR(mode):
41
+ raise OSError(errno.ENOTDIR, "Expected a regular file or directory", str(target))
42
+ return target, regular
43
+
44
+ # Every selection must be valid, even when another file or directory is usable.
45
+ for selection in selections:
46
+ check_path(selection)
47
+
48
+ def has_content(selection: str) -> bool:
49
+ pending = [selection]
50
+ failure = None
51
+ while pending:
52
+ current = pending.pop()
53
+ try:
54
+ target, regular = check_path(current)
55
+ if regular:
56
+ return True
57
+ with os.scandir(target) as entries:
58
+ for entry in entries:
59
+ if not entry.is_dir(follow_symlinks=False):
60
+ return True
61
+ # Preserve link entries as content without traversing their targets.
62
+ if (
63
+ getattr(entry.stat(follow_symlinks=False), "st_reparse_tag", 0)
64
+ & 0x20000000
65
+ ):
66
+ return True
67
+ pending.append(str(Path(entry.path).relative_to(root)))
68
+ except OSError as exc:
69
+ if failure is None:
70
+ failure = exc
71
+ if failure is not None:
72
+ raise failure
73
+ return False
74
+
75
+ failure = None
76
+ for selection in selections:
77
+ try:
78
+ if has_content(selection):
79
+ return
80
+ except OSError as exc:
81
+ if selection in files:
82
+ raise
83
+ if failure is None:
84
+ failure = exc
85
+ if failure is not None:
86
+ raise failure
87
+ raise ValueError("Deep Scan target is empty; no security audit was performed.")
88
+
89
+
90
+ if __name__ == "__main__":
91
+ request = json.load(sys.stdin)
92
+ try:
93
+ check_selected_targets(
94
+ Path(request["targetPath"]), request["includePaths"], request["filePaths"]
95
+ )
96
+ except (OSError, ValueError) as exc:
97
+ sys.exit(str(exc))
@@ -127,8 +127,14 @@ class ProfileThread {
127
127
  );
128
128
  }
129
129
  if (event.type === "thread.started") this.id = event.thread_id;
130
- if (event.type === "turn.completed" && event.usage != null)
130
+ if (event.type === "turn.completed" && event.usage != null) {
131
+ if (
132
+ event.usage.cache_write_input_tokens == null &&
133
+ event.usage.cache_write_tokens == null
134
+ )
135
+ event.usage.cache_write_input_tokens_reported = false;
131
136
  event.usage.cache_write_input_tokens ??= 0;
137
+ }
132
138
  yield event;
133
139
  }
134
140
  } finally {
@@ -34,12 +34,14 @@ CONFIG_KEYS = set(CONFIG_FIELDS.values())
34
34
 
35
35
 
36
36
  def codex_home() -> Path:
37
+ """Expand CODEX_HOME, falling back to ~/.codex when the setting is empty or whitespace."""
37
38
  return Path(
38
39
  os.environ["CODEX_HOME"] if os.environ.get("CODEX_HOME", "").strip() else "~/.codex"
39
40
  ).expanduser()
40
41
 
41
42
 
42
43
  def config_path() -> Path:
44
+ """Return the configured TOML path or the per-user config.toml under the Codex home."""
43
45
  configured = os.environ.get("CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH", "").strip()
44
46
  if configured:
45
47
  return Path(configured).expanduser()
@@ -47,12 +49,27 @@ def config_path() -> Path:
47
49
 
48
50
 
49
51
  def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | float]:
52
+ """Return the numeric deep scan settings for a launch with no project overrides."""
50
53
  return resolve_deep_scan_setup(available_parallelism)["settings"]
51
54
 
52
55
 
53
56
  def resolve_deep_scan_setup(
54
- available_parallelism: int, project_json: str | None = None
57
+ available_parallelism: int = 1, project_json: str | None = None
55
58
  ) -> dict[str, Any]:
59
+ """Resolve project overrides, per-user TOML settings, and bundled defaults in that order.
60
+
61
+ Args:
62
+ available_parallelism (int): Legacy caller argument. Any positive value selects the same settings.
63
+ project_json (str | None): Serialized project configuration with path and settings keys.
64
+
65
+ Returns:
66
+ dict: Numeric settings and a source label for each, plus the paths of the
67
+ supplied project configuration and any existing per-user configuration.
68
+
69
+ Raises:
70
+ SystemExit: A selected setting is invalid or a required TOML file cannot be read.
71
+ json.JSONDecodeError: The supplied project JSON cannot be parsed.
72
+ """
56
73
  project = json.loads(project_json) if project_json is not None else None
57
74
  overrides = project["settings"] if project is not None else {}
58
75
  unknown = sorted(set(overrides) - set(CONFIG_FIELDS))
@@ -106,6 +123,7 @@ def resolve_deep_scan_setup(
106
123
 
107
124
 
108
125
  def require_integer(value: object, label: str, *, minimum: int) -> int:
126
+ """Return an integer at least minimum, accepting integral floats and raising SystemExit for invalid counts."""
109
127
  if isinstance(value, float) and value.is_integer():
110
128
  value = int(value)
111
129
  if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
@@ -121,6 +139,7 @@ def require_integer(value: object, label: str, *, minimum: int) -> int:
121
139
 
122
140
 
123
141
  def require_positive_number(value: object, label: str) -> int | float:
142
+ """Return a duration in hours, raising SystemExit unless it falls in (0, 96]."""
124
143
  if isinstance(value, bool) or not isinstance(value, (int, float)):
125
144
  raise SystemExit(f"{label} must be a positive finite number no greater than 96.")
126
145
  if not 0 < value <= MAX_TIME_HOURS: