@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
@@ -0,0 +1,148 @@
1
+ """Normalize legacy finding details for scan contract validation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ from typing import Any
7
+
8
+ import report_projection
9
+
10
+
11
+ def _filter_unknown_legacy_evidence_refs(section: dict[str, Any], evidence_ids: set[str]) -> None:
12
+ for refs_field in ("evidenceRefs", "evidence_refs"):
13
+ refs = section.get(refs_field)
14
+ if isinstance(refs, list):
15
+ section[refs_field] = [
16
+ ref for ref in refs if isinstance(ref, str) and ref.strip() and ref in evidence_ids
17
+ ]
18
+
19
+
20
+ def _normalize_legacy_string_list_fields(section: dict[str, Any], fields: tuple[str, ...]) -> None:
21
+ for field in fields:
22
+ if field not in section:
23
+ continue
24
+ value = section[field]
25
+ if isinstance(value, str):
26
+ normalized = [value] if value.strip() else []
27
+ elif isinstance(value, list):
28
+ normalized = [item for item in value if isinstance(item, str) and item.strip()]
29
+ else:
30
+ normalized = []
31
+ if normalized:
32
+ section[field] = normalized
33
+ else:
34
+ section.pop(field)
35
+
36
+
37
+ def _remove_unsupported_legacy_scalar_fields(
38
+ section: dict[str, Any], fields: tuple[str, ...]
39
+ ) -> None:
40
+ for field in fields:
41
+ if field in section and (not isinstance(section[field], str) or section[field] == ""):
42
+ section.pop(field)
43
+
44
+
45
+ def _legacy_sealed_findings_for_validation(findings: dict[str, Any]) -> dict[str, Any]:
46
+ compatible = copy.deepcopy(findings)
47
+ finding_items = compatible.get("findings")
48
+ if not isinstance(finding_items, list):
49
+ return compatible
50
+ for finding in finding_items:
51
+ if not isinstance(finding, dict):
52
+ continue
53
+ canonical_evidence = finding.get("codeEvidence")
54
+ canonical_evidence = canonical_evidence if isinstance(canonical_evidence, list) else []
55
+ evidence_ids = {
56
+ evidence["id"]
57
+ for evidence in canonical_evidence
58
+ if isinstance(evidence, dict) and isinstance(evidence.get("id"), str) and evidence["id"]
59
+ }
60
+ legacy_evidence = finding.get("code_evidence")
61
+ if isinstance(legacy_evidence, list):
62
+ compatible_legacy_evidence = []
63
+ for evidence in report_projection.code_evidence_rows(legacy_evidence):
64
+ evidence_id = evidence.get("id")
65
+ if not isinstance(evidence_id, str) or not evidence_id.strip():
66
+ continue
67
+ if evidence_id in evidence_ids:
68
+ continue
69
+ evidence_ids.add(evidence_id)
70
+ compatible_legacy_evidence.append(evidence)
71
+ finding["code_evidence"] = compatible_legacy_evidence
72
+ elif "code_evidence" in finding:
73
+ finding.pop("code_evidence")
74
+ for section_name, list_fields in (
75
+ ("rootCause", ("evidenceRefs", "evidence_refs")),
76
+ ("root_cause", ("evidenceRefs", "evidence_refs")),
77
+ (
78
+ "validation",
79
+ (
80
+ "assertions",
81
+ "counterEvidence",
82
+ "evidence",
83
+ "evidenceRefs",
84
+ "evidence_refs",
85
+ "limitations",
86
+ ),
87
+ ),
88
+ (
89
+ "attackPath",
90
+ (
91
+ "assumptions",
92
+ "blindspots",
93
+ "controls",
94
+ "evidenceRefs",
95
+ "evidence_refs",
96
+ "limitations",
97
+ "preconditions",
98
+ "steps",
99
+ ),
100
+ ),
101
+ ):
102
+ section = finding.get(section_name)
103
+ if not isinstance(section, dict):
104
+ continue
105
+ _normalize_legacy_string_list_fields(section, list_fields)
106
+ _filter_unknown_legacy_evidence_refs(section, evidence_ids)
107
+ legacy_root_cause = finding.get("root_cause")
108
+ if isinstance(legacy_root_cause, dict):
109
+ _remove_unsupported_legacy_scalar_fields(
110
+ legacy_root_cause, ("summary", "code", "language")
111
+ )
112
+ elif (
113
+ "root_cause" in finding
114
+ and legacy_root_cause is not None
115
+ and (not isinstance(legacy_root_cause, str) or legacy_root_cause == "")
116
+ ):
117
+ finding.pop("root_cause")
118
+ validation = finding.get("validation")
119
+ if isinstance(validation, dict):
120
+ _remove_unsupported_legacy_scalar_fields(
121
+ validation, ("method", "status", "summary", "disposition", "result")
122
+ )
123
+ attack_path = finding.get("attackPath")
124
+ if not isinstance(attack_path, dict):
125
+ continue
126
+ _remove_unsupported_legacy_scalar_fields(attack_path, ("summary",))
127
+ for field in ("dataFlow", "data_flow", "dataflow", "reachability"):
128
+ detail = attack_path.get(field)
129
+ if isinstance(detail, dict):
130
+ detail_scalar_fields = ("summary", "source", "sink", "outcome")
131
+ if field == "reachability":
132
+ detail_scalar_fields += ("attacker", "entrypoint")
133
+ _remove_unsupported_legacy_scalar_fields(detail, detail_scalar_fields)
134
+ _normalize_legacy_string_list_fields(
135
+ detail, ("evidenceRefs", "evidence_refs", "transformations")
136
+ )
137
+ _filter_unknown_legacy_evidence_refs(detail, evidence_ids)
138
+ if field == "reachability":
139
+ _normalize_legacy_string_list_fields(detail, ("preconditions",))
140
+ elif not isinstance(detail, str) or detail == "":
141
+ attack_path.pop(field, None)
142
+ for field in ("impact", "likelihood"):
143
+ detail = attack_path.get(field)
144
+ if isinstance(detail, dict):
145
+ _remove_unsupported_legacy_scalar_fields(detail, ("level", "rationale", "why"))
146
+ elif detail is not None and (not isinstance(detail, str) or detail == ""):
147
+ attack_path.pop(field)
148
+ return compatible
@@ -14,6 +14,7 @@ from pathlib import Path, PurePosixPath
14
14
 
15
15
 
16
16
  def descriptor_relative_writes_available() -> bool:
17
+ """Return whether the platform supports the descriptor-relative operations used for writes."""
17
18
  # os.replace accepts src_dir_fd/dst_dir_fd wherever descriptor-relative
18
19
  # os.rename is supported, but Python lists only os.rename in supports_dir_fd.
19
20
  required_operations = (os.mkdir, os.open, os.rename, os.stat, os.unlink)
@@ -24,6 +25,7 @@ def descriptor_relative_writes_available() -> bool:
24
25
 
25
26
  @contextmanager
26
27
  def managed_fd(descriptor: int) -> Iterator[int]:
28
+ """Yield the descriptor and close it when the context exits, including on error."""
27
29
  try:
28
30
  yield descriptor
29
31
  finally:
@@ -34,6 +36,7 @@ def managed_fd(descriptor: int) -> Iterator[int]:
34
36
  def stage_file(
35
37
  parent_fd: int, filename: str, payload: bytes, owner_read_write: bool
36
38
  ) -> Iterator[int]:
39
+ """Yield a synced file descriptor for a new staging entry, removing the entry on exit if it still matches."""
37
40
  descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
38
41
  try:
39
42
  with os.fdopen(descriptor, "wb", closefd=False) as handle:
@@ -56,6 +59,7 @@ def stage_file(
56
59
 
57
60
 
58
61
  def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:
62
+ """Rename a directory entry atomically while requiring the destination to be absent."""
59
63
  import ctypes
60
64
 
61
65
  libc = ctypes.CDLL(None, use_errno=True)
@@ -87,6 +91,7 @@ def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:
87
91
 
88
92
 
89
93
  def publish_new_file(parent_fd: int, source: str, destination: str) -> None:
94
+ """Publish the staged name without overwriting the destination, using an exclusive rename if linking is unavailable."""
90
95
  try:
91
96
  os.link(
92
97
  source, destination, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False
@@ -118,6 +123,12 @@ def stage_write(
118
123
  check_parent: Callable[[Path], None],
119
124
  contract_error: type[ValueError],
120
125
  ) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
126
+ """Stage payload under the open parent directory and yield a callable that publishes it.
127
+
128
+ Call the publisher inside the context. It returns file metadata and the
129
+ change time in nanoseconds. With compare_existing, matching bytes can
130
+ reuse an existing file when replacements are allowed.
131
+ """
121
132
  name = PurePosixPath(relative_path).name
122
133
  # Stage through the held parent so a replacement path cannot redirect the write.
123
134
  try:
@@ -0,0 +1,21 @@
1
+ import { createReadStream } from "node:fs";
2
+ import { pipeline } from "node:stream/promises";
3
+
4
+ // The Python usage collector uses the plugin's required Node runtime to read
5
+ // cold rollouts without requiring a separate Python compression dependency.
6
+ try {
7
+ const path = process.argv[2];
8
+ if (!path) throw new Error("A Codex rollout path is required.");
9
+ // Native Node decoding can stop after the first frame. Rollouts may contain
10
+ // concatenated frames, and an incomplete later frame must remain an error.
11
+ const { createZstdDecompress } =
12
+ await import("../mcp/session-decompression.mjs");
13
+ await pipeline(
14
+ createReadStream(path),
15
+ createZstdDecompress(),
16
+ process.stdout,
17
+ );
18
+ } catch (error) {
19
+ console.error(error instanceof Error ? error.message : String(error));
20
+ process.exitCode = 1;
21
+ }
@@ -14,6 +14,13 @@ from typing import Any
14
14
  SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}
15
15
  CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
16
16
  REPORTABLE_SEVERITIES = {"critical", "high", "medium", "low"}
17
+ THREAT_MODEL_SECTIONS = (
18
+ ("Assets", "assets"),
19
+ ("Trust Boundaries", "trustBoundaries"),
20
+ ("Attacker Capabilities", "attackerCapabilities"),
21
+ ("Security Objectives", "securityObjectives"),
22
+ ("Assumptions", "assumptions"),
23
+ )
17
24
  DISPOSITION_LABELS = {
18
25
  "reported": "Reported",
19
26
  "no_issue_found": "No issue found",
@@ -31,6 +38,14 @@ class ReportProjectionError(ValueError):
31
38
  """Raised when a canonical scan cannot be projected into a valid report."""
32
39
 
33
40
 
41
+ def markdown_threat_model_content(model: dict[str, Any]) -> str | None:
42
+ """Return nonblank authored content for a Markdown model, otherwise None."""
43
+ content = model.get("content")
44
+ if model.get("format") == "markdown" and isinstance(content, str) and content.strip():
45
+ return content
46
+ return None
47
+
48
+
34
49
  def _escape_markdown(value: str) -> str:
35
50
  # Locate whole URLs before matching code spans: a URL can contain backticks.
36
51
  urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]
@@ -135,6 +150,7 @@ def _has_deep_child_metadata(finding: dict[str, Any]) -> bool:
135
150
 
136
151
 
137
152
  def uses_deep_presentation(coverage: dict[str, Any], findings: list[dict[str, Any]]) -> bool:
153
+ """Select deep-report formatting for repository scans in deep mode and scoped scans with deep-child metadata."""
138
154
  if coverage.get("mode") == "deep_repository":
139
155
  return True
140
156
  if coverage.get("mode") != "scoped_path":
@@ -167,15 +183,6 @@ def _deep_title_parts(finding: dict[str, Any], report_id: str) -> tuple[str, str
167
183
  return normalized, None
168
184
 
169
185
 
170
- def _deep_finding_groups(
171
- findings: list[dict[str, Any]], writeup_paths: list[str | None]
172
- ) -> list[list[tuple[int, dict[str, Any], str | None]]]:
173
- groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
174
- for number, (finding, report_path) in enumerate(zip(findings, writeup_paths, strict=True), 1):
175
- groups.setdefault(_deep_candidate_id(finding), []).append((number, finding, report_path))
176
- return list(groups.values())
177
-
178
-
179
186
  def _deep_group_levels(
180
187
  group: list[tuple[int, dict[str, Any], str | None]],
181
188
  field: str,
@@ -242,6 +249,7 @@ def _bullet_section(heading: str, items: list[str]) -> list[str]:
242
249
 
243
250
 
244
251
  def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:
252
+ """Yield evidence objects with nonblank code in their original order."""
245
253
  for items in catalogs:
246
254
  if isinstance(items, list):
247
255
  yield from (
@@ -254,6 +262,7 @@ def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:
254
262
 
255
263
 
256
264
  def embedded_code_evidence(section: dict[str, Any]) -> Iterator[dict[str, Any]]:
265
+ """Collect code evidence from both supported field spellings."""
257
266
  return code_evidence_rows(section.get("codeEvidence"), section.get("code_evidence"))
258
267
 
259
268
 
@@ -282,6 +291,7 @@ def _section_code_evidence(
282
291
 
283
292
 
284
293
  def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:
294
+ """Return the first recorded root-cause field name and its merged detail, or (None, None) if absent."""
285
295
  keys = [key for key in ("rootCause", "root_cause") if key in value]
286
296
  if not keys:
287
297
  return None, None
@@ -743,6 +753,16 @@ def _linked_finding_section(number: int, finding: dict[str, Any], report_path: s
743
753
  def build_report_markdown(
744
754
  manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
745
755
  ) -> str:
756
+ """Render findings and review coverage as a Markdown report ending in a newline.
757
+
758
+ Args:
759
+ manifest: Scan metadata, target, and scope.
760
+ findings_document: Canonical findings for the scan.
761
+ coverage: Review coverage for older manifests. Newer scans supply review state inline.
762
+
763
+ Raises:
764
+ ReportProjectionError: Reportable findings share a writeup path.
765
+ """
746
766
  scan = manifest["scan"]
747
767
  if "review" in scan and "coverageRef" not in scan:
748
768
  from review_state import review_state
@@ -759,19 +779,23 @@ def build_report_markdown(
759
779
  ),
760
780
  key=_finding_sort_key,
761
781
  )
762
- writeup_paths = [_writeup_report_path(finding) for finding in findings]
763
- duplicate_writeup_paths = sorted(
764
- path
765
- for path, count in Counter(path for path in writeup_paths if path is not None).items()
766
- if count > 1
767
- )
782
+ numbered_findings = [
783
+ (number, finding, _writeup_report_path(finding))
784
+ for number, finding in enumerate(findings, 1)
785
+ ]
786
+ writeup_counts = Counter(path for _, _, path in numbered_findings if path is not None)
787
+ duplicate_writeup_paths = sorted(path for path, count in writeup_counts.items() if count > 1)
768
788
  if duplicate_writeup_paths:
769
789
  raise ReportProjectionError(
770
790
  "reportable findings have duplicate writeup reportPath values: "
771
791
  + ", ".join(duplicate_writeup_paths)
772
792
  )
773
793
  deep_presentation = uses_deep_presentation(coverage, findings)
774
- deep_finding_groups = _deep_finding_groups(findings, writeup_paths) if deep_presentation else []
794
+ deep_finding_groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
795
+ if deep_presentation:
796
+ for entry in numbered_findings:
797
+ _, finding, _ = entry
798
+ deep_finding_groups.setdefault(_deep_candidate_id(finding), []).append(entry)
775
799
  hardening_portfolio_path = _hardening_portfolio_path(scan)
776
800
  include_paths = [
777
801
  _path_text(path) for path in coverage.get("includePaths", scope.get("includePaths", []))
@@ -840,8 +864,8 @@ def build_report_markdown(
840
864
  "",
841
865
  ]
842
866
  )
843
- content = threat_model.get("content")
844
- if threat_model.get("format") == "markdown" and isinstance(content, str) and content.strip():
867
+ content = markdown_threat_model_content(threat_model)
868
+ if content is not None:
845
869
  lines.append(content)
846
870
  else:
847
871
  lines.append(
@@ -850,18 +874,38 @@ def build_report_markdown(
850
874
  "No explicit canonical threat-model summary was recorded.",
851
875
  )
852
876
  )
853
- for heading, key in (
854
- ("Assets", "assets"),
855
- ("Trust Boundaries", "trustBoundaries"),
856
- ("Attacker Capabilities", "attackerCapabilities"),
857
- ("Security Objectives", "securityObjectives"),
858
- ("Assumptions", "assumptions"),
859
- ):
877
+ for heading, key in THREAT_MODEL_SECTIONS:
860
878
  values = _strings(threat_model.get(key))
861
879
  if values:
862
880
  lines.extend(["", f"### {heading}", "", *(f"- {value}" for value in values)])
881
+ reviews = scan.get("reviewState", {}).get("reviews")
882
+ if isinstance(reviews, list) and any(
883
+ isinstance(review, dict) and isinstance(review.get("threatModel"), dict)
884
+ for review in reviews
885
+ ):
886
+ lines.extend(
887
+ [
888
+ "",
889
+ (
890
+ "Other reviews recorded different threat models. See the `threatModel` fields "
891
+ "in `scan.reviewState.reviews` in the [scan manifest](scan-manifest.json)."
892
+ ),
893
+ ]
894
+ )
863
895
  lines.extend(["", "## Findings", ""])
896
+ informational_count = sum(
897
+ finding["severity"]["level"] == "informational" for finding in findings_document["findings"]
898
+ )
899
+ informational_note = ""
900
+ if informational_count:
901
+ noun = "finding" if informational_count == 1 else "findings"
902
+ informational_note = (
903
+ f"This report omits details for {informational_count} informational {noun}. "
904
+ "See `findings.json` or export the findings as SARIF or CSV."
905
+ )
864
906
  if findings:
907
+ if informational_note:
908
+ lines.extend([informational_note, ""])
865
909
  if deep_presentation:
866
910
  lines.extend(
867
911
  [
@@ -869,7 +913,7 @@ def build_report_markdown(
869
913
  "| --- | --- | --- | --- | --- |",
870
914
  ]
871
915
  )
872
- lines.extend(_deep_group_row(group) for group in deep_finding_groups)
916
+ lines.extend(_deep_group_row(group) for group in deep_finding_groups.values())
873
917
  else:
874
918
  lines.extend(
875
919
  [
@@ -877,9 +921,7 @@ def build_report_markdown(
877
921
  "| --- | --- | --- | --- |",
878
922
  ]
879
923
  )
880
- for number, (finding, report_path) in enumerate(
881
- zip(findings, writeup_paths, strict=True), 1
882
- ):
924
+ for number, finding, report_path in numbered_findings:
883
925
  title = _cell(finding["title"])
884
926
  finding_link = f"[{title}](#finding-{number})"
885
927
  writeup_link = f"[Open report]({report_path})" if report_path else "inline below"
@@ -899,9 +941,7 @@ def build_report_markdown(
899
941
  "| low | Evidence is incomplete and the item is retained only for explicit follow-up. |",
900
942
  ]
901
943
  )
902
- for number, (finding, report_path) in enumerate(
903
- zip(findings, writeup_paths, strict=True), 1
904
- ):
944
+ for number, finding, report_path in numbered_findings:
905
945
  if report_path is not None:
906
946
  lines.extend(["", *_linked_finding_section(number, finding, report_path)])
907
947
  else:
@@ -912,18 +952,15 @@ def build_report_markdown(
912
952
  "canceled",
913
953
  "interrupted",
914
954
  }
915
- lines.extend(
916
- [
917
- "### No findings",
918
- "",
919
- (
920
- "No findings were retained before the scan stopped. "
921
- "The scan did not complete. No vulnerability conclusion can be drawn."
922
- if stopped
923
- else "No findings were reported."
924
- ),
925
- ]
955
+ heading = "### No reportable findings" if informational_note else "### No findings"
956
+ message = informational_note or (
957
+ "No findings were retained before the scan stopped."
958
+ if stopped
959
+ else "No findings were reported."
926
960
  )
961
+ if stopped:
962
+ message += " The scan did not complete. No vulnerability conclusion can be drawn."
963
+ lines.extend([heading, "", message])
927
964
  if hardening_portfolio_path is not None:
928
965
  lines.extend(
929
966
  [
@@ -1009,6 +1046,7 @@ def generate_report_markdown(
1009
1046
  findings: dict[str, Any],
1010
1047
  coverage: dict[str, Any],
1011
1048
  ) -> bytes:
1049
+ """Return the Markdown report for the scan as UTF-8 bytes ready to write."""
1012
1050
  return build_report_markdown(manifest, findings, coverage).encode("utf-8")
1013
1051
 
1014
1052
 
@@ -8,17 +8,23 @@ from typing import Any
8
8
 
9
9
 
10
10
  def uses_legacy_review(scan: dict[str, Any]) -> bool:
11
+ """Return whether the manifest points to separate coverage or predates inline review metadata."""
11
12
  return "coverageRef" in scan or ("reviewState" not in scan and "review" not in scan)
12
13
 
13
14
 
14
15
  def review_summary(state: dict[str, Any]) -> dict[str, Any]:
16
+ """Return the excluded path patterns in the compact form stored on the scan manifest."""
15
17
  return {
16
18
  "excludedPaths": [item["pattern"] for item in state.get("explicitExclusions", [])],
17
19
  }
18
20
 
19
21
 
20
22
  def review_state(scan: dict[str, Any]) -> dict[str, Any]:
21
- """Read new manifest metadata using the recovery code's existing representation."""
23
+ """Build the recovery coverage record from inline manifest metadata.
24
+
25
+ Copy the saved review state, deriving exclusions from the summary when needed,
26
+ and attach the inventory strategy and scope for this scan.
27
+ """
22
28
  summary = scan.get("review", {})
23
29
  state = copy.deepcopy(scan.get("reviewState", {}))
24
30
  mode = scan.get("mode", "repository")
@@ -48,7 +54,7 @@ def review_state(scan: dict[str, Any]) -> dict[str, Any]:
48
54
 
49
55
 
50
56
  def checkpoint_review_state(state: dict[str, Any]) -> dict[str, Any]:
51
- """Retain unfinished work and candidate outcomes, without a coverage report."""
57
+ """Copy the review data needed for recovery, omitting per-surface risk areas and report metadata."""
52
58
  return {
53
59
  "surfaces": [
54
60
  {key: copy.deepcopy(value) for key, value in item.items() if key != "riskArea"}
@@ -32,6 +32,16 @@ AVIT_FINDING_FIELDS = (
32
32
 
33
33
 
34
34
  def read_template(path: Path) -> tuple[list[str], dict[str, str]]:
35
+ """Read the application defaults for a ServiceNow AVIT export from a UTF-8 CSV.
36
+
37
+ Returns:
38
+ tuple: The original column headings and a mapping of stripped, case-folded
39
+ headings to values from the single application row.
40
+
41
+ Raises:
42
+ ValueError: The file is unreadable, required columns are missing or
43
+ duplicated, or application values are empty or too long.
44
+ """
35
45
  try:
36
46
  with path.open(encoding="utf-8-sig", newline="") as source:
37
47
  rows = (row for row in csv.reader(source, strict=True) if row)
@@ -62,6 +72,11 @@ def _narrative(text: str) -> str:
62
72
 
63
73
 
64
74
  def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: str) -> dict[str, str]:
75
+ """Return AVIT columns for a finding at the selected location with the recorded steps.
76
+
77
+ Use the first recognized CWE as the category, or the finding ID as the
78
+ vulnerability ID when no CWE qualifies. Both narrative fields fit in 1,000 characters.
79
+ """
65
80
  details = (
66
81
  f"{finding['findingId']} | {location['path']}:{location['startLine']}\n"
67
82
  f"{finding['title']}\n{finding['summary']}\n{finding['remediation']}"
@@ -85,6 +100,11 @@ def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: str
85
100
 
86
101
 
87
102
  def render(template: Path, rows: Iterable[dict[str, str]]) -> bytes:
103
+ """Return UTF-8 CSV bytes with the template's header and one row per finding.
104
+
105
+ The template supplies application fields and column order. For nonempty input,
106
+ write the count of findings missing reproduction steps to stderr.
107
+ """
88
108
  headers, row = read_template(template)
89
109
  output = io.StringIO(newline="")
90
110
  writer = csv.writer(output)
@@ -10,6 +10,7 @@ from urllib.parse import quote
10
10
 
11
11
 
12
12
  def main() -> None:
13
+ """Back up the read-only source database into a separate destination using SQLite’s backup API."""
13
14
  parser = argparse.ArgumentParser(description=__doc__)
14
15
  parser.add_argument("source", type=Path)
15
16
  parser.add_argument("destination", type=Path)
@@ -6,7 +6,6 @@ from __future__ import annotations
6
6
  import argparse
7
7
  import json
8
8
  import sys
9
- from collections.abc import Callable
10
9
  from pathlib import Path
11
10
  from typing import Any
12
11
 
@@ -14,14 +13,6 @@ from typing import Any
14
13
  sys.path.insert(0, str(Path(__file__).resolve().parent))
15
14
  import report_projection as report
16
15
 
17
- _STRUCTURED_SECTIONS = (
18
- ("Assets", "assets"),
19
- ("Trust Boundaries", "trustBoundaries"),
20
- ("Attacker Capabilities", "attackerCapabilities"),
21
- ("Security Objectives", "securityObjectives"),
22
- ("Assumptions", "assumptions"),
23
- )
24
-
25
16
 
26
17
  def _is_structured_model(model: dict[str, Any]) -> bool:
27
18
  summary = model.get("summary")
@@ -31,21 +22,18 @@ def _is_structured_model(model: dict[str, Any]) -> bool:
31
22
  and all(
32
23
  isinstance(values := model.get(key, []), list)
33
24
  and all(isinstance(value, str) and value for value in values)
34
- for _, key in _STRUCTURED_SECTIONS
25
+ for _, key in report.THREAT_MODEL_SECTIONS
35
26
  )
36
27
  )
37
28
 
38
29
 
39
- def _markdown_content(model: dict[str, Any]) -> str | None:
40
- content = model.get("content")
41
- if model.get("format") == "markdown" and isinstance(content, str) and content.strip():
42
- return content
43
- return None
44
-
45
-
46
30
  def threat_model_body(model: dict[str, Any]) -> str:
47
- """Keep authored Markdown intact, including summaries from older scans."""
48
- content = _markdown_content(model)
31
+ """Return the authored Markdown body verbatim or render a legacy summary and its sections.
32
+
33
+ Raises:
34
+ ValueError: Required content is absent or the saved model has invalid metadata or sections.
35
+ """
36
+ content = report.markdown_threat_model_content(model)
49
37
  if content is not None:
50
38
  # The structured schema permits legacy metadata as extension fields.
51
39
  if _is_structured_model(model):
@@ -82,7 +70,7 @@ def threat_model_body(model: dict[str, Any]) -> str:
82
70
  sections = [
83
71
  summary if summary.strip() else "No explicit canonical threat-model summary was recorded."
84
72
  ]
85
- for heading, key in _STRUCTURED_SECTIONS:
73
+ for heading, key in report.THREAT_MODEL_SECTIONS:
86
74
  values = model.get(key, [])
87
75
  if not isinstance(values, list):
88
76
  raise ValueError(f"threatModel.{key}: expected an array")
@@ -96,7 +84,7 @@ def threat_model_body(model: dict[str, Any]) -> str:
96
84
  return "\n\n".join(sections)
97
85
 
98
86
 
99
- def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> list[str]:
87
+ def _scope_lines(scope: Any, label: str) -> list[str]:
100
88
  # Older structured models may use these extension names for unrelated data.
101
89
  included = scope.get("includePaths") if isinstance(scope, dict) else None
102
90
  if not isinstance(included, list) or not all(isinstance(path, str) for path in included):
@@ -109,14 +97,19 @@ def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> lis
109
97
  lines.append(f"- {label} exclusions: {excluded_text or 'none'}")
110
98
  summary = scope.get("summary")
111
99
  if isinstance(summary, str) and summary:
112
- lines.append(f"- {label} description: {text(summary, 'not recorded')}")
100
+ lines.append(f"- {label} description: {report._text(summary, 'not recorded')}")
113
101
  return lines
114
102
 
115
103
 
116
104
  def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None = None) -> bytes:
117
- """Render a portable document with authored content and recorded provenance."""
105
+ """Return the saved threat model as UTF-8 Markdown, including its provenance footer.
106
+
107
+ Args:
108
+ model (dict): Authored Markdown or a legacy structured model from a scan.
109
+ provenance (dict | None): Optional saved scan identifiers, scope, and provisional status.
110
+ """
118
111
  body = threat_model_body(model)
119
- if _markdown_content(model) is None:
112
+ if report.markdown_threat_model_content(model) is None:
120
113
  body = "# Threat Model\n\n" + body
121
114
  text = report._text
122
115
  provenance = provenance or {}
@@ -132,10 +125,10 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None
132
125
  if provenance.get(key):
133
126
  footer.append(f"- {label}: {text(str(provenance[key]), 'not recorded')}")
134
127
  footer.append(f"- Model origin: {text(model.get('origin'), 'not recorded')}")
135
- footer.extend(_scope_lines(model.get("scope"), "Model scope", text))
128
+ footer.extend(_scope_lines(model.get("scope"), "Model scope"))
136
129
  scan_scope = provenance.get("scanScope")
137
130
  if isinstance(scan_scope, dict):
138
- footer.extend(_scope_lines(scan_scope, "Scan scope", text))
131
+ footer.extend(_scope_lines(scan_scope, "Scan scope"))
139
132
  if provenance.get("provisional"):
140
133
  footer.extend(["", "This is a provisional model saved before successful completion."])
141
134
  return (body + ("\n" if body.endswith("\n") else "\n\n") + "\n".join(footer) + "\n").encode(
@@ -144,11 +137,14 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None
144
137
 
145
138
 
146
139
  def main() -> int:
140
+ """Render a JSON payload from stdin to UTF-8 Markdown on stdout and return zero on success."""
147
141
  parser = argparse.ArgumentParser(description=__doc__)
148
142
  parser.add_argument("--input-json-stdin", action="store_true", required=True)
149
143
  parser.parse_args()
150
144
  try:
151
145
  payload = json.load(sys.stdin)
146
+ if not isinstance(payload["threatModel"], dict):
147
+ raise ValueError("threatModel must be an object")
152
148
  sys.stdout.buffer.write(
153
149
  render_threat_model(payload["threatModel"], payload.get("provenance"))
154
150
  )