@openai/codex-security 0.8.3 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (658) hide show
  1. package/README.md +36 -746
  2. package/_bundled_plugin/.codex-plugin/plugin.json +2 -0
  3. package/_bundled_plugin/.mcp.json +7 -1
  4. package/_bundled_plugin/examples/completed-scan/findings.json +16 -4
  5. package/_bundled_plugin/examples/completed-scan/report.md +11 -8
  6. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +4 -2
  7. package/_bundled_plugin/mcp/fzstd-LICENSE.txt +21 -0
  8. package/_bundled_plugin/mcp/helpers.mjs +2 -11
  9. package/_bundled_plugin/mcp/helpers.mjs.br +0 -0
  10. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +3 -210
  11. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/package.json +1 -0
  20. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +5 -2
  21. package/_bundled_plugin/mcp/server.mjs +2 -11
  22. package/_bundled_plugin/mcp/server.mjs.br +0 -0
  23. package/_bundled_plugin/mcp/session-decompression.mjs +712 -0
  24. package/_bundled_plugin/references/artifact-storage.md +1 -1
  25. package/_bundled_plugin/references/baseline-auditor.md +18 -0
  26. package/_bundled_plugin/references/core-scan.md +5 -42
  27. package/_bundled_plugin/references/default-severity-rubric.md +9 -4
  28. package/_bundled_plugin/references/final-report.md +5 -3
  29. package/_bundled_plugin/references/finding-detail-fields.md +18 -18
  30. package/_bundled_plugin/references/focused-investigator.md +13 -0
  31. package/_bundled_plugin/references/sarif-adapter.md +8 -2
  32. package/_bundled_plugin/references/scan-artifacts.md +21 -12
  33. package/_bundled_plugin/references/scan-contract.md +27 -33
  34. package/_bundled_plugin/references/scan-prologue.md +2 -2
  35. package/_bundled_plugin/references/scan-runtime.md +4 -2
  36. package/_bundled_plugin/references/security-guidance.md +14 -1
  37. package/_bundled_plugin/references/validate-scan-findings.md +3 -0
  38. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +2 -2
  39. package/_bundled_plugin/scripts/check_deep_scan_target.py +97 -0
  40. package/_bundled_plugin/scripts/codex_profile.mjs +7 -1
  41. package/_bundled_plugin/scripts/deep_scan_config.py +20 -1
  42. package/_bundled_plugin/scripts/deep_scan_workbench.py +192 -352
  43. package/_bundled_plugin/scripts/dispatch_inventory_tool +7 -0
  44. package/_bundled_plugin/scripts/filesystem_identity.py +1 -0
  45. package/_bundled_plugin/scripts/finalize_scan_contract.py +182 -230
  46. package/_bundled_plugin/scripts/finding_preview.py +20 -0
  47. package/_bundled_plugin/scripts/launch_codex_security_mcp +55 -16
  48. package/_bundled_plugin/scripts/legacy_findings.py +148 -0
  49. package/_bundled_plugin/scripts/posix_scan_local_files.py +37 -1
  50. package/_bundled_plugin/scripts/read_codex_session.mjs +21 -0
  51. package/_bundled_plugin/scripts/report_projection.py +81 -43
  52. package/_bundled_plugin/scripts/review_state.py +8 -2
  53. package/_bundled_plugin/scripts/servicenow_avit.py +20 -0
  54. package/_bundled_plugin/scripts/snapshot_sqlite.py +9 -2
  55. package/_bundled_plugin/scripts/threat_model_projection.py +22 -26
  56. package/_bundled_plugin/scripts/validate_scan_contract.py +7 -1
  57. package/_bundled_plugin/scripts/windows_scan_local_files.py +582 -20
  58. package/_bundled_plugin/scripts/workbench/__init__.py +1 -1
  59. package/_bundled_plugin/scripts/workbench/handoff.py +100 -23
  60. package/_bundled_plugin/scripts/workbench/retained_coverage.py +30 -51
  61. package/_bundled_plugin/scripts/workbench/retained_records.py +18 -30
  62. package/_bundled_plugin/scripts/workbench/runtime_toml.py +4 -1
  63. package/_bundled_plugin/scripts/workbench/saved_coverage.py +9 -17
  64. package/_bundled_plugin/scripts/workbench/saved_outputs.py +9 -0
  65. package/_bundled_plugin/scripts/workbench/saved_sources.py +47 -40
  66. package/_bundled_plugin/scripts/workbench/storage.py +91 -7
  67. package/_bundled_plugin/scripts/workbench_cli.py +54 -14
  68. package/_bundled_plugin/scripts/workbench_constants.py +12 -0
  69. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +3 -3
  70. package/_bundled_plugin/scripts/workbench_db.py +562 -303
  71. package/_bundled_plugin/scripts/workbench_feedback.py +57 -11
  72. package/_bundled_plugin/scripts/workbench_finding_index.py +1 -0
  73. package/_bundled_plugin/scripts/workbench_finding_workflows.py +4 -0
  74. package/_bundled_plugin/scripts/workbench_native_indexes.py +238 -41
  75. package/_bundled_plugin/scripts/workbench_progress.py +169 -4
  76. package/_bundled_plugin/scripts/workbench_publication.py +16 -13
  77. package/_bundled_plugin/scripts/workbench_remediation.py +155 -2
  78. package/_bundled_plugin/scripts/workbench_saved_results.py +176 -81
  79. package/_bundled_plugin/scripts/workbench_scan_history.py +398 -174
  80. package/_bundled_plugin/scripts/workbench_scan_start.py +224 -31
  81. package/_bundled_plugin/scripts/workbench_scan_usage.py +675 -73
  82. package/_bundled_plugin/scripts/workbench_schema.py +258 -63
  83. package/_bundled_plugin/scripts/workbench_setup.py +14 -2
  84. package/_bundled_plugin/scripts/workbench_source_excerpt.py +13 -0
  85. package/_bundled_plugin/scripts/workbench_source_scopes.py +18 -0
  86. package/_bundled_plugin/scripts/workbench_target.py +594 -136
  87. package/_bundled_plugin/scripts/workbench_target_state.py +1110 -21
  88. package/_bundled_plugin/scripts/workbench_validation.py +43 -3
  89. package/_bundled_plugin/shared/workbench-history-repairs.json +77 -35
  90. package/_bundled_plugin/shared/workbench-migrations.json +100 -0
  91. package/_bundled_plugin/skills/cloud-findings/SKILL.md +5 -5
  92. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +7 -50
  93. package/_bundled_plugin/skills/fix-finding/SKILL.md +2 -1
  94. package/_bundled_plugin/skills/publish-findings/SKILL.md +24 -153
  95. package/_bundled_plugin/skills/publish-findings/agents/openai.yaml +2 -2
  96. package/_bundled_plugin/skills/publish-findings/references/checkmarx-import.md +37 -0
  97. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +3 -3
  98. package/_bundled_plugin/skills/publish-findings/scripts/collect_checkmarx.py +409 -0
  99. package/_bundled_plugin/skills/publish-findings/scripts/collect_continuum.py +224 -0
  100. package/_bundled_plugin/skills/publish-findings/scripts/collector_paths.py +63 -0
  101. package/_bundled_plugin/skills/security-scan/SKILL.md +9 -46
  102. package/_bundled_plugin/skills/security-scan/agents/openai.yaml +2 -2
  103. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +3 -21
  104. package/_bundled_plugin/skills/security-scan/references/managed-scan.md +11 -0
  105. package/_bundled_plugin/skills/security-scan/references/scan-results.md +15 -0
  106. package/_bundled_plugin/skills/security-scan/references/scoped-paths.md +23 -0
  107. package/_bundled_plugin/skills/security-scan/references/sdk-files.md +24 -0
  108. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +22 -1
  109. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -2
  110. package/bin/codex-security.mjs +2 -2
  111. package/dist/api.d.ts +45 -5
  112. package/dist/api.d.ts.map +1 -1
  113. package/dist/api.js +1192 -427
  114. package/dist/api.js.map +1 -1
  115. package/dist/armorcode-findings.d.ts +9 -0
  116. package/dist/armorcode-findings.d.ts.map +1 -0
  117. package/dist/armorcode-findings.js +145 -0
  118. package/dist/armorcode-findings.js.map +1 -0
  119. package/dist/artifact-export.d.ts +2 -0
  120. package/dist/artifact-export.d.ts.map +1 -1
  121. package/dist/artifact-export.js +29 -13
  122. package/dist/artifact-export.js.map +1 -1
  123. package/dist/auth.d.ts +6 -2
  124. package/dist/auth.d.ts.map +1 -1
  125. package/dist/auth.js +37 -18
  126. package/dist/auth.js.map +1 -1
  127. package/dist/batch-cost.d.ts +18 -0
  128. package/dist/batch-cost.d.ts.map +1 -0
  129. package/dist/batch-cost.js +41 -0
  130. package/dist/batch-cost.js.map +1 -0
  131. package/dist/bedrock-oss-pricing.d.ts +6 -0
  132. package/dist/bedrock-oss-pricing.d.ts.map +1 -0
  133. package/dist/bedrock-oss-pricing.js +58 -0
  134. package/dist/bedrock-oss-pricing.js.map +1 -0
  135. package/dist/bedrock-pricing.d.ts +15 -0
  136. package/dist/bedrock-pricing.d.ts.map +1 -0
  137. package/dist/bedrock-pricing.js +117 -0
  138. package/dist/bedrock-pricing.js.map +1 -0
  139. package/dist/blackduck-findings.d.ts +1 -1
  140. package/dist/blackduck-findings.d.ts.map +1 -1
  141. package/dist/blackduck-findings.js +24 -22
  142. package/dist/blackduck-findings.js.map +1 -1
  143. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  144. package/dist/bulk-scan-discovery.js +4 -4
  145. package/dist/bulk-scan-discovery.js.map +1 -1
  146. package/dist/bundled-plugin.d.ts +4 -0
  147. package/dist/bundled-plugin.d.ts.map +1 -0
  148. package/dist/bundled-plugin.js +23 -0
  149. package/dist/bundled-plugin.js.map +1 -0
  150. package/dist/checkmarx-evidence.d.ts +19 -0
  151. package/dist/checkmarx-evidence.d.ts.map +1 -0
  152. package/dist/checkmarx-evidence.js +36 -0
  153. package/dist/checkmarx-evidence.js.map +1 -0
  154. package/dist/checkmarx-findings.d.ts +4 -0
  155. package/dist/checkmarx-findings.d.ts.map +1 -0
  156. package/dist/checkmarx-findings.js +27 -0
  157. package/dist/checkmarx-findings.js.map +1 -0
  158. package/dist/checkmarx-one.d.ts +4 -0
  159. package/dist/checkmarx-one.d.ts.map +1 -0
  160. package/dist/checkmarx-one.js +53 -0
  161. package/dist/checkmarx-one.js.map +1 -0
  162. package/dist/checkmarx-repository.d.ts +12 -0
  163. package/dist/checkmarx-repository.d.ts.map +1 -0
  164. package/dist/checkmarx-repository.js +181 -0
  165. package/dist/checkmarx-repository.js.map +1 -0
  166. package/dist/checkmarx-xml.d.ts +12 -0
  167. package/dist/checkmarx-xml.d.ts.map +1 -0
  168. package/dist/checkmarx-xml.js +196 -0
  169. package/dist/checkmarx-xml.js.map +1 -0
  170. package/dist/classify-scan-severity.d.ts +1 -1
  171. package/dist/classify-scan-severity.d.ts.map +1 -1
  172. package/dist/classify-scan-severity.js +11 -3
  173. package/dist/classify-scan-severity.js.map +1 -1
  174. package/dist/classify-severity-records.d.ts +1 -9
  175. package/dist/classify-severity-records.d.ts.map +1 -1
  176. package/dist/classify-severity-records.js +3 -13
  177. package/dist/classify-severity-records.js.map +1 -1
  178. package/dist/classify-severity.d.ts.map +1 -1
  179. package/dist/classify-severity.js +11 -10
  180. package/dist/classify-severity.js.map +1 -1
  181. package/dist/cli-argument.d.ts +4 -0
  182. package/dist/cli-argument.d.ts.map +1 -0
  183. package/dist/cli-argument.js +17 -0
  184. package/dist/cli-argument.js.map +1 -0
  185. package/dist/cli-help.d.ts +1 -1
  186. package/dist/cli-help.d.ts.map +1 -1
  187. package/dist/cli-help.js +71 -29
  188. package/dist/cli-help.js.map +1 -1
  189. package/dist/cli-hook.d.ts +3 -0
  190. package/dist/cli-hook.d.ts.map +1 -0
  191. package/dist/cli-hook.js +87 -0
  192. package/dist/cli-hook.js.map +1 -0
  193. package/dist/cli-integrations.d.ts +13 -0
  194. package/dist/cli-integrations.d.ts.map +1 -0
  195. package/dist/cli-integrations.js +333 -0
  196. package/dist/cli-integrations.js.map +1 -0
  197. package/dist/cli-mcp.d.ts +15 -0
  198. package/dist/cli-mcp.d.ts.map +1 -0
  199. package/dist/cli-mcp.js +178 -0
  200. package/dist/cli-mcp.js.map +1 -0
  201. package/dist/cli-token-view.d.ts +10 -0
  202. package/dist/cli-token-view.d.ts.map +1 -0
  203. package/dist/cli-token-view.js +41 -0
  204. package/dist/cli-token-view.js.map +1 -0
  205. package/dist/cli.d.ts +16 -8
  206. package/dist/cli.d.ts.map +1 -1
  207. package/dist/cli.js +3382 -2017
  208. package/dist/cli.js.map +1 -1
  209. package/dist/cloud-publish.d.ts.map +1 -1
  210. package/dist/cloud-publish.js +35 -33
  211. package/dist/cloud-publish.js.map +1 -1
  212. package/dist/codex-sdk-environment.d.ts +6 -0
  213. package/dist/codex-sdk-environment.d.ts.map +1 -1
  214. package/dist/codex-sdk-environment.js +19 -0
  215. package/dist/codex-sdk-environment.js.map +1 -1
  216. package/dist/command-words.d.ts +3 -0
  217. package/dist/command-words.d.ts.map +1 -0
  218. package/dist/command-words.js +46 -0
  219. package/dist/command-words.js.map +1 -0
  220. package/dist/component-scan.d.ts +19 -4
  221. package/dist/component-scan.d.ts.map +1 -1
  222. package/dist/component-scan.js +67 -9
  223. package/dist/component-scan.js.map +1 -1
  224. package/dist/config.d.ts +1 -1
  225. package/dist/config.d.ts.map +1 -1
  226. package/dist/config.js +130 -67
  227. package/dist/config.js.map +1 -1
  228. package/dist/continuum-findings.d.ts +1 -1
  229. package/dist/continuum-findings.d.ts.map +1 -1
  230. package/dist/continuum-findings.js +149 -19
  231. package/dist/continuum-findings.js.map +1 -1
  232. package/dist/contract-values.d.ts +2 -0
  233. package/dist/contract-values.d.ts.map +1 -1
  234. package/dist/contract-values.js +12 -9
  235. package/dist/contract-values.js.map +1 -1
  236. package/dist/cost-model.d.ts +13 -1
  237. package/dist/cost-model.d.ts.map +1 -1
  238. package/dist/cost-model.js +66 -112
  239. package/dist/cost-model.js.map +1 -1
  240. package/dist/cost.d.ts +42 -3
  241. package/dist/cost.d.ts.map +1 -1
  242. package/dist/cost.js +484 -149
  243. package/dist/cost.js.map +1 -1
  244. package/dist/custom-publish.d.ts +4 -0
  245. package/dist/custom-publish.d.ts.map +1 -1
  246. package/dist/custom-publish.js +40 -3
  247. package/dist/custom-publish.js.map +1 -1
  248. package/dist/custom-validation-prompt.d.ts +1 -1
  249. package/dist/custom-validation-prompt.d.ts.map +1 -1
  250. package/dist/custom-validation-prompt.js +29 -19
  251. package/dist/custom-validation-prompt.js.map +1 -1
  252. package/dist/deduplication/local.d.ts +4 -2
  253. package/dist/deduplication/local.d.ts.map +1 -1
  254. package/dist/deduplication/local.js +9 -2
  255. package/dist/deduplication/local.js.map +1 -1
  256. package/dist/deduplication/refusal.d.ts.map +1 -1
  257. package/dist/deduplication/refusal.js +26 -5
  258. package/dist/deduplication/refusal.js.map +1 -1
  259. package/dist/deduplication/scan.d.ts +5 -0
  260. package/dist/deduplication/scan.d.ts.map +1 -1
  261. package/dist/deduplication/scan.js +24 -7
  262. package/dist/deduplication/scan.js.map +1 -1
  263. package/dist/deep-config.d.ts +0 -1
  264. package/dist/deep-config.d.ts.map +1 -1
  265. package/dist/deep-config.js +22 -33
  266. package/dist/deep-config.js.map +1 -1
  267. package/dist/deep-scan-defaults.d.ts +2 -0
  268. package/dist/deep-scan-defaults.d.ts.map +1 -1
  269. package/dist/deep-scan-defaults.js +28 -1
  270. package/dist/deep-scan-defaults.js.map +1 -1
  271. package/dist/deep-scan.d.ts +2 -0
  272. package/dist/deep-scan.d.ts.map +1 -1
  273. package/dist/deep-scan.js +44 -19
  274. package/dist/deep-scan.js.map +1 -1
  275. package/dist/default-severity-rubric.d.ts +1 -1
  276. package/dist/default-severity-rubric.d.ts.map +1 -1
  277. package/dist/default-severity-rubric.js +1 -1
  278. package/dist/default-severity-rubric.js.map +1 -1
  279. package/dist/endor-findings.d.ts +3 -1
  280. package/dist/endor-findings.d.ts.map +1 -1
  281. package/dist/endor-findings.js +86 -45
  282. package/dist/endor-findings.js.map +1 -1
  283. package/dist/errors.d.ts +4 -2
  284. package/dist/errors.d.ts.map +1 -1
  285. package/dist/errors.js +15 -4
  286. package/dist/errors.js.map +1 -1
  287. package/dist/executable-path.d.ts +3 -0
  288. package/dist/executable-path.d.ts.map +1 -1
  289. package/dist/executable-path.js +26 -0
  290. package/dist/executable-path.js.map +1 -1
  291. package/dist/external-findings-import.d.ts +5 -3
  292. package/dist/external-findings-import.d.ts.map +1 -1
  293. package/dist/external-findings-import.js +19 -7
  294. package/dist/external-findings-import.js.map +1 -1
  295. package/dist/external-findings-local.d.ts +69 -5
  296. package/dist/external-findings-local.d.ts.map +1 -1
  297. package/dist/external-findings-local.js +537 -108
  298. package/dist/external-findings-local.js.map +1 -1
  299. package/dist/external-findings-publish.d.ts +13 -6
  300. package/dist/external-findings-publish.d.ts.map +1 -1
  301. package/dist/external-findings-publish.js +895 -1142
  302. package/dist/external-findings-publish.js.map +1 -1
  303. package/dist/external-findings-read.d.ts +21 -2
  304. package/dist/external-findings-read.d.ts.map +1 -1
  305. package/dist/external-findings-read.js +130 -68
  306. package/dist/external-findings-read.js.map +1 -1
  307. package/dist/external-findings.d.ts +15 -3
  308. package/dist/external-findings.d.ts.map +1 -1
  309. package/dist/external-findings.js +54 -2
  310. package/dist/external-findings.js.map +1 -1
  311. package/dist/external-import-contract.d.ts +8 -12
  312. package/dist/external-import-contract.d.ts.map +1 -1
  313. package/dist/external-import-contract.js +51 -184
  314. package/dist/external-import-contract.js.map +1 -1
  315. package/dist/external-import-models.d.ts +1 -1
  316. package/dist/external-import-models.d.ts.map +1 -1
  317. package/dist/external-import-models.js.map +1 -1
  318. package/dist/feedback.d.ts.map +1 -1
  319. package/dist/feedback.js +5 -4
  320. package/dist/feedback.js.map +1 -1
  321. package/dist/finding-prompt.d.ts +5 -0
  322. package/dist/finding-prompt.d.ts.map +1 -0
  323. package/dist/finding-prompt.js +32 -0
  324. package/dist/finding-prompt.js.map +1 -0
  325. package/dist/findings-client.d.ts +1 -0
  326. package/dist/findings-client.d.ts.map +1 -1
  327. package/dist/findings-client.js +27 -3
  328. package/dist/findings-client.js.map +1 -1
  329. package/dist/github-advisories.d.ts.map +1 -1
  330. package/dist/github-advisories.js +0 -2
  331. package/dist/github-advisories.js.map +1 -1
  332. package/dist/github-dependabot-findings.d.ts.map +1 -1
  333. package/dist/github-dependabot-findings.js +18 -8
  334. package/dist/github-dependabot-findings.js.map +1 -1
  335. package/dist/github-findings.d.ts +4 -1
  336. package/dist/github-findings.d.ts.map +1 -1
  337. package/dist/github-findings.js +73 -316
  338. package/dist/github-findings.js.map +1 -1
  339. package/dist/hosted-git-remotes.d.ts +5 -0
  340. package/dist/hosted-git-remotes.d.ts.map +1 -0
  341. package/dist/hosted-git-remotes.js +285 -0
  342. package/dist/hosted-git-remotes.js.map +1 -0
  343. package/dist/hosted-git-repository.d.ts +28 -0
  344. package/dist/hosted-git-repository.d.ts.map +1 -0
  345. package/dist/hosted-git-repository.js +222 -0
  346. package/dist/hosted-git-repository.js.map +1 -0
  347. package/dist/hosted-remediation.d.ts +1 -0
  348. package/dist/hosted-remediation.d.ts.map +1 -1
  349. package/dist/hosted-remediation.js +23 -3
  350. package/dist/hosted-remediation.js.map +1 -1
  351. package/dist/hosted-scan-protocol.js +2 -2
  352. package/dist/hosted-scan-protocol.js.map +1 -1
  353. package/dist/hosted-scan.d.ts.map +1 -1
  354. package/dist/hosted-scan.js +16 -11
  355. package/dist/hosted-scan.js.map +1 -1
  356. package/dist/hosted-scanner-http.d.ts +21 -0
  357. package/dist/hosted-scanner-http.d.ts.map +1 -0
  358. package/dist/hosted-scanner-http.js +204 -0
  359. package/dist/hosted-scanner-http.js.map +1 -0
  360. package/dist/import-scan.d.ts.map +1 -1
  361. package/dist/import-scan.js +3 -0
  362. package/dist/import-scan.js.map +1 -1
  363. package/dist/index.d.ts +21 -9
  364. package/dist/index.d.ts.map +1 -1
  365. package/dist/index.js +12 -3
  366. package/dist/index.js.map +1 -1
  367. package/dist/inspector-findings.d.ts.map +1 -1
  368. package/dist/inspector-findings.js +52 -86
  369. package/dist/inspector-findings.js.map +1 -1
  370. package/dist/knowledge-base.d.ts +1 -1
  371. package/dist/knowledge-base.d.ts.map +1 -1
  372. package/dist/knowledge-base.js +102 -32
  373. package/dist/knowledge-base.js.map +1 -1
  374. package/dist/linear.d.ts +11 -0
  375. package/dist/linear.d.ts.map +1 -1
  376. package/dist/linear.js.map +1 -1
  377. package/dist/local-git-metadata.d.ts +5 -2
  378. package/dist/local-git-metadata.d.ts.map +1 -1
  379. package/dist/local-git-metadata.js +8 -5
  380. package/dist/local-git-metadata.js.map +1 -1
  381. package/dist/multiscan.d.ts +10 -4
  382. package/dist/multiscan.d.ts.map +1 -1
  383. package/dist/multiscan.js +217 -102
  384. package/dist/multiscan.js.map +1 -1
  385. package/dist/native-json-findings.d.ts +2 -1
  386. package/dist/native-json-findings.d.ts.map +1 -1
  387. package/dist/native-json-findings.js +12 -2
  388. package/dist/native-json-findings.js.map +1 -1
  389. package/dist/opengrep-findings.d.ts +5 -2
  390. package/dist/opengrep-findings.d.ts.map +1 -1
  391. package/dist/opengrep-findings.js +54 -33
  392. package/dist/opengrep-findings.js.map +1 -1
  393. package/dist/operation-telemetry.d.ts +104 -0
  394. package/dist/operation-telemetry.d.ts.map +1 -0
  395. package/dist/operation-telemetry.js +293 -0
  396. package/dist/operation-telemetry.js.map +1 -0
  397. package/dist/plugin-python-probe.d.ts +4 -0
  398. package/dist/plugin-python-probe.d.ts.map +1 -0
  399. package/dist/plugin-python-probe.js +10 -0
  400. package/dist/plugin-python-probe.js.map +1 -0
  401. package/dist/private-finding-import.d.ts +99 -9
  402. package/dist/private-finding-import.d.ts.map +1 -1
  403. package/dist/private-finding-import.js +116 -152
  404. package/dist/private-finding-import.js.map +1 -1
  405. package/dist/project-config.d.ts.map +1 -1
  406. package/dist/project-config.js +53 -13
  407. package/dist/project-config.js.map +1 -1
  408. package/dist/prompt-files.d.ts +7 -2
  409. package/dist/prompt-files.d.ts.map +1 -1
  410. package/dist/prompt-files.js +42 -20
  411. package/dist/prompt-files.js.map +1 -1
  412. package/dist/provider-profile.d.ts +1 -1
  413. package/dist/provider-profile.d.ts.map +1 -1
  414. package/dist/provider-profile.js +12 -10
  415. package/dist/provider-profile.js.map +1 -1
  416. package/dist/publication-telemetry.d.ts +45 -0
  417. package/dist/publication-telemetry.d.ts.map +1 -0
  418. package/dist/publication-telemetry.js +50 -0
  419. package/dist/publication-telemetry.js.map +1 -0
  420. package/dist/publication.d.ts +1 -1
  421. package/dist/publication.d.ts.map +1 -1
  422. package/dist/publication.js.map +1 -1
  423. package/dist/publish.d.ts +4 -0
  424. package/dist/publish.d.ts.map +1 -1
  425. package/dist/publish.js +42 -2
  426. package/dist/publish.js.map +1 -1
  427. package/dist/record.d.ts +1 -5
  428. package/dist/record.d.ts.map +1 -1
  429. package/dist/record.js +3 -51
  430. package/dist/record.js.map +1 -1
  431. package/dist/remediation.d.ts +1 -4
  432. package/dist/remediation.d.ts.map +1 -1
  433. package/dist/remediation.js +6 -8
  434. package/dist/remediation.js.map +1 -1
  435. package/dist/request-metadata.d.ts +3 -0
  436. package/dist/request-metadata.d.ts.map +1 -1
  437. package/dist/request-metadata.js +9 -0
  438. package/dist/request-metadata.js.map +1 -1
  439. package/dist/result.d.ts +4 -0
  440. package/dist/result.d.ts.map +1 -1
  441. package/dist/result.js +1 -1
  442. package/dist/result.js.map +1 -1
  443. package/dist/retry-windows-rename.d.ts +8 -0
  444. package/dist/retry-windows-rename.d.ts.map +1 -0
  445. package/dist/retry-windows-rename.js +24 -0
  446. package/dist/retry-windows-rename.js.map +1 -0
  447. package/dist/runtime.d.ts +54 -6
  448. package/dist/runtime.d.ts.map +1 -1
  449. package/dist/runtime.js +1084 -256
  450. package/dist/runtime.js.map +1 -1
  451. package/dist/saved-scan-bootstrap.d.ts +7 -1
  452. package/dist/saved-scan-bootstrap.d.ts.map +1 -1
  453. package/dist/saved-scan-bootstrap.js +269 -114
  454. package/dist/saved-scan-bootstrap.js.map +1 -1
  455. package/dist/scan-activity.d.ts.map +1 -1
  456. package/dist/scan-activity.js +141 -56
  457. package/dist/scan-activity.js.map +1 -1
  458. package/dist/scan-archive-path.d.ts +2 -0
  459. package/dist/scan-archive-path.d.ts.map +1 -0
  460. package/dist/scan-archive-path.js +5 -0
  461. package/dist/scan-archive-path.js.map +1 -0
  462. package/dist/scan-comparison.d.ts +10 -5
  463. package/dist/scan-comparison.d.ts.map +1 -1
  464. package/dist/scan-comparison.js +66 -17
  465. package/dist/scan-comparison.js.map +1 -1
  466. package/dist/scan-dashboard.d.ts +7 -6
  467. package/dist/scan-dashboard.d.ts.map +1 -1
  468. package/dist/scan-dashboard.js +92 -43
  469. package/dist/scan-dashboard.js.map +1 -1
  470. package/dist/scan-executor.d.ts +10 -1
  471. package/dist/scan-executor.d.ts.map +1 -1
  472. package/dist/scan-executor.js +24 -2
  473. package/dist/scan-executor.js.map +1 -1
  474. package/dist/scan-history-renderer.d.ts +1 -0
  475. package/dist/scan-history-renderer.d.ts.map +1 -1
  476. package/dist/scan-history-renderer.js +34 -28
  477. package/dist/scan-history-renderer.js.map +1 -1
  478. package/dist/scan-logs.d.ts +12 -0
  479. package/dist/scan-logs.d.ts.map +1 -1
  480. package/dist/scan-logs.js +131 -78
  481. package/dist/scan-logs.js.map +1 -1
  482. package/dist/scan-measurement.d.ts +26 -0
  483. package/dist/scan-measurement.d.ts.map +1 -0
  484. package/dist/scan-measurement.js +77 -0
  485. package/dist/scan-measurement.js.map +1 -0
  486. package/dist/scan-progress.d.ts +1 -0
  487. package/dist/scan-progress.d.ts.map +1 -1
  488. package/dist/scan-progress.js +3 -0
  489. package/dist/scan-progress.js.map +1 -1
  490. package/dist/scan-sessions.d.ts.map +1 -1
  491. package/dist/scan-sessions.js +4 -1
  492. package/dist/scan-sessions.js.map +1 -1
  493. package/dist/scan-settings.d.ts +1 -1
  494. package/dist/scan-settings.d.ts.map +1 -1
  495. package/dist/scan-settings.js +1 -24
  496. package/dist/scan-settings.js.map +1 -1
  497. package/dist/scanner-import.d.ts +25 -13
  498. package/dist/scanner-import.d.ts.map +1 -1
  499. package/dist/scanner-import.js +216 -97
  500. package/dist/scanner-import.js.map +1 -1
  501. package/dist/scanner-repository-url.d.ts +4 -1
  502. package/dist/scanner-repository-url.d.ts.map +1 -1
  503. package/dist/scanner-repository-url.js +10 -6
  504. package/dist/scanner-repository-url.js.map +1 -1
  505. package/dist/security-policy.d.ts +1 -1
  506. package/dist/security-policy.d.ts.map +1 -1
  507. package/dist/security-policy.js +26 -6
  508. package/dist/security-policy.js.map +1 -1
  509. package/dist/semgrep-findings.d.ts +6 -3
  510. package/dist/semgrep-findings.d.ts.map +1 -1
  511. package/dist/semgrep-findings.js +72 -42
  512. package/dist/semgrep-findings.js.map +1 -1
  513. package/dist/semgrep-guardian-findings.d.ts +38 -0
  514. package/dist/semgrep-guardian-findings.d.ts.map +1 -0
  515. package/dist/semgrep-guardian-findings.js +165 -0
  516. package/dist/semgrep-guardian-findings.js.map +1 -0
  517. package/dist/semgrep-platform-collector.d.ts +26 -0
  518. package/dist/semgrep-platform-collector.d.ts.map +1 -0
  519. package/dist/semgrep-platform-collector.js +108 -0
  520. package/dist/semgrep-platform-collector.js.map +1 -0
  521. package/dist/semgrep-platform-findings.d.ts +157 -6
  522. package/dist/semgrep-platform-findings.d.ts.map +1 -1
  523. package/dist/semgrep-platform-findings.js +766 -103
  524. package/dist/semgrep-platform-findings.js.map +1 -1
  525. package/dist/server/api.d.ts +1 -1
  526. package/dist/server/api.d.ts.map +1 -1
  527. package/dist/server/api.js.map +1 -1
  528. package/dist/server/embedding-tokenizer.cdx.json +33 -0
  529. package/dist/server/embedding-tokenizer.d.ts +2 -0
  530. package/dist/server/embedding-tokenizer.d.ts.map +1 -0
  531. package/dist/server/embedding-tokenizer.js +322 -0
  532. package/dist/server/embedding-tokenizer.js.map +6 -0
  533. package/dist/server/embeddings.d.ts +16 -2
  534. package/dist/server/embeddings.d.ts.map +1 -1
  535. package/dist/server/embeddings.js +35 -5
  536. package/dist/server/embeddings.js.map +1 -1
  537. package/dist/session-lines.d.ts +5 -0
  538. package/dist/session-lines.d.ts.map +1 -0
  539. package/dist/session-lines.js +60 -0
  540. package/dist/session-lines.js.map +1 -0
  541. package/dist/severity-review.d.ts +3 -1
  542. package/dist/severity-review.d.ts.map +1 -1
  543. package/dist/severity-review.js +3 -2
  544. package/dist/severity-review.js.map +1 -1
  545. package/dist/skill-authentication.d.ts +1 -0
  546. package/dist/skill-authentication.d.ts.map +1 -1
  547. package/dist/skill-authentication.js +1 -0
  548. package/dist/skill-authentication.js.map +1 -1
  549. package/dist/snyk-findings.d.ts +9 -2
  550. package/dist/snyk-findings.d.ts.map +1 -1
  551. package/dist/snyk-findings.js +90 -70
  552. package/dist/snyk-findings.js.map +1 -1
  553. package/dist/snyk-rest-findings.d.ts +59 -0
  554. package/dist/snyk-rest-findings.d.ts.map +1 -0
  555. package/dist/snyk-rest-findings.js +879 -0
  556. package/dist/snyk-rest-findings.js.map +1 -0
  557. package/dist/snyk-token-origin.d.ts +4 -0
  558. package/dist/snyk-token-origin.d.ts.map +1 -0
  559. package/dist/snyk-token-origin.js +82 -0
  560. package/dist/snyk-token-origin.js.map +1 -0
  561. package/dist/sonar-collector.d.ts.map +1 -1
  562. package/dist/sonar-collector.js +0 -3
  563. package/dist/sonar-collector.js.map +1 -1
  564. package/dist/sonar-findings.d.ts +1 -1
  565. package/dist/sonar-findings.d.ts.map +1 -1
  566. package/dist/sonar-findings.js +2 -4
  567. package/dist/sonar-findings.js.map +1 -1
  568. package/dist/sonar-import.d.ts +3 -0
  569. package/dist/sonar-import.d.ts.map +1 -1
  570. package/dist/sonar-import.js +30 -34
  571. package/dist/sonar-import.js.map +1 -1
  572. package/dist/stored-finding-projection.d.ts +6 -0
  573. package/dist/stored-finding-projection.d.ts.map +1 -0
  574. package/dist/stored-finding-projection.js +104 -0
  575. package/dist/stored-finding-projection.js.map +1 -0
  576. package/dist/stored-findings-publication.d.ts +23 -0
  577. package/dist/stored-findings-publication.d.ts.map +1 -0
  578. package/dist/stored-findings-publication.js +169 -0
  579. package/dist/stored-findings-publication.js.map +1 -0
  580. package/dist/target-drift.d.ts +9 -0
  581. package/dist/target-drift.d.ts.map +1 -0
  582. package/dist/target-drift.js +27 -0
  583. package/dist/target-drift.js.map +1 -0
  584. package/dist/targets.d.ts +8 -1
  585. package/dist/targets.d.ts.map +1 -1
  586. package/dist/targets.js +131 -42
  587. package/dist/targets.js.map +1 -1
  588. package/dist/tenable-findings.d.ts +6 -0
  589. package/dist/tenable-findings.d.ts.map +1 -0
  590. package/dist/tenable-findings.js +122 -0
  591. package/dist/tenable-findings.js.map +1 -0
  592. package/dist/terminal-stream.d.ts +13 -0
  593. package/dist/terminal-stream.d.ts.map +1 -0
  594. package/dist/terminal-stream.js +35 -0
  595. package/dist/terminal-stream.js.map +1 -0
  596. package/dist/trivy-findings.d.ts +19 -0
  597. package/dist/trivy-findings.d.ts.map +1 -0
  598. package/dist/trivy-findings.js +424 -0
  599. package/dist/trivy-findings.js.map +1 -0
  600. package/dist/trivy-import.d.ts +19 -0
  601. package/dist/trivy-import.d.ts.map +1 -0
  602. package/dist/trivy-import.js +151 -0
  603. package/dist/trivy-import.js.map +1 -0
  604. package/dist/trusted-executable.d.ts +6 -0
  605. package/dist/trusted-executable.d.ts.map +1 -1
  606. package/dist/trusted-executable.js +140 -37
  607. package/dist/trusted-executable.js.map +1 -1
  608. package/dist/validation-records.js +1 -1
  609. package/dist/validation-records.js.map +1 -1
  610. package/dist/veracode-findings.d.ts +1 -1
  611. package/dist/veracode-findings.d.ts.map +1 -1
  612. package/dist/veracode-findings.js +19 -6
  613. package/dist/veracode-findings.js.map +1 -1
  614. package/dist/version.d.ts +3 -1
  615. package/dist/version.d.ts.map +1 -1
  616. package/dist/version.js +184 -32
  617. package/dist/version.js.map +1 -1
  618. package/dist/vertex-pricing.d.ts +8 -0
  619. package/dist/vertex-pricing.d.ts.map +1 -0
  620. package/dist/vertex-pricing.js +20 -0
  621. package/dist/vertex-pricing.js.map +1 -0
  622. package/dist/windows-path.d.ts +1 -0
  623. package/dist/windows-path.d.ts.map +1 -1
  624. package/dist/windows-path.js +26 -1
  625. package/dist/windows-path.js.map +1 -1
  626. package/dist/wiz-findings.d.ts +6 -2
  627. package/dist/wiz-findings.d.ts.map +1 -1
  628. package/dist/wiz-findings.js +65 -89
  629. package/dist/wiz-findings.js.map +1 -1
  630. package/docs/classify-severity-records.md +27 -12
  631. package/docs/cli.md +853 -639
  632. package/docs/dedupe-records.md +44 -24
  633. package/docs/findings-service.md +84 -44
  634. package/docs/hosted-remediation.md +27 -11
  635. package/docs/hosted-scans.md +50 -42
  636. package/docs/sdk.md +903 -0
  637. package/docs/telemetry.md +236 -0
  638. package/docs/validate-records.md +78 -44
  639. package/package.json +23 -16
  640. package/schemas/external-findings.schema.json +4 -1
  641. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  642. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  643. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  644. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  645. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  646. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +0 -96
  647. package/dist/external-imports-feature.d.ts +0 -6
  648. package/dist/external-imports-feature.d.ts.map +0 -1
  649. package/dist/external-imports-feature.js +0 -51
  650. package/dist/external-imports-feature.js.map +0 -1
  651. package/dist/finding-normalization.d.ts +0 -5
  652. package/dist/finding-normalization.d.ts.map +0 -1
  653. package/dist/finding-normalization.js +0 -155
  654. package/dist/finding-normalization.js.map +0 -1
  655. package/dist/reader-selection.d.ts +0 -13
  656. package/dist/reader-selection.d.ts.map +0 -1
  657. package/dist/reader-selection.js +0 -81
  658. package/dist/reader-selection.js.map +0 -1
@@ -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)
@@ -4,12 +4,20 @@
4
4
  from __future__ import annotations
5
5
 
6
6
  import argparse
7
+ import os
7
8
  import sqlite3
8
9
  from pathlib import Path
9
10
  from urllib.parse import quote
10
11
 
11
12
 
13
+ def readonly_sqlite_uri(path: Path) -> str:
14
+ """Escape the native filename, including separators, without introducing a URI authority."""
15
+ filename = os.fsencode(path) if os.name == "posix" else str(path)
16
+ return f"file:{quote(filename, safe='')}?mode=ro"
17
+
18
+
12
19
  def main() -> None:
20
+ """Back up the read-only source database into a separate destination using SQLite’s backup API."""
13
21
  parser = argparse.ArgumentParser(description=__doc__)
14
22
  parser.add_argument("source", type=Path)
15
23
  parser.add_argument("destination", type=Path)
@@ -20,8 +28,7 @@ def main() -> None:
20
28
  if destination.exists() and destination.samefile(source):
21
29
  parser.error(f"Destination must not be the same file as source: {destination}")
22
30
  destination.parent.mkdir(parents=True, exist_ok=True)
23
- source_uri = f"file:{quote(str(source), safe='')}?mode=ro"
24
- with sqlite3.connect(source_uri, uri=True) as source_connection:
31
+ with sqlite3.connect(readonly_sqlite_uri(source), uri=True) as source_connection:
25
32
  creation_destination = destination.resolve()
26
33
  try:
27
34
  creation_destination.touch(mode=0o600, exist_ok=False)
@@ -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
  )
@@ -15,7 +15,11 @@ import finalize_scan_contract as FINALIZER
15
15
 
16
16
 
17
17
  def validate_contract(scan_dir: Path) -> dict[str, Any]:
18
- """Return validated canonical documents for one sealed scan."""
18
+ """Validate the sealed artifacts and return the manifest, original findings, and review summary.
19
+
20
+ Legacy finding records are adapted for validation only. ContractError propagates
21
+ when a required artifact, digest, schema, or evidence check fails.
22
+ """
19
23
 
20
24
  scan_dir = FINALIZER._require_scan_directory(scan_dir.expanduser().resolve(strict=True))
21
25
  schema_dir = Path(__file__).resolve().parents[1] / "schemas"
@@ -46,6 +50,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
46
50
 
47
51
 
48
52
  def receipt(validated: dict[str, Any]) -> dict[str, Any]:
53
+ """Return the CLI success payload with paths to the validated manifest, findings, and report."""
49
54
  scan_dir = Path(validated["scanDir"])
50
55
  scan = validated["manifest"]["scan"]
51
56
  return {
@@ -58,6 +63,7 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:
58
63
 
59
64
 
60
65
  def main(argv: list[str] | None = None) -> int:
66
+ """Print the validation receipt on success or report a validation error to stderr and return 2."""
61
67
  parser = argparse.ArgumentParser(description=__doc__)
62
68
  parser.add_argument("--scan-dir", required=True, type=Path)
63
69
  args = parser.parse_args(argv)