@openai/codex-security 0.8.1 → 0.8.3

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 (396) hide show
  1. package/README.md +45 -57
  2. package/_bundled_plugin/.app.json +4 -0
  3. package/_bundled_plugin/.mcp.json +1 -0
  4. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  5. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  6. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +4 -4
  7. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  8. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  9. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  10. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  11. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  12. package/_bundled_plugin/mcp/native/linux-x64-musl/unix.node +0 -0
  13. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  14. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  15. package/_bundled_plugin/mcp/permission-profile-preflight.mjs +46 -12
  16. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  17. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  18. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  19. package/_bundled_plugin/references/artifact-storage.md +1 -1
  20. package/_bundled_plugin/references/core-scan.md +14 -5
  21. package/_bundled_plugin/references/default-severity-rubric.md +28 -0
  22. package/_bundled_plugin/references/finding-detail-fields.md +1 -0
  23. package/_bundled_plugin/references/threat-model.md +1 -0
  24. package/_bundled_plugin/scripts/deep_scan_workbench.py +23 -112
  25. package/_bundled_plugin/scripts/finalize_scan_contract.py +167 -153
  26. package/_bundled_plugin/scripts/finding_preview.py +5 -29
  27. package/_bundled_plugin/scripts/posix_scan_local_files.py +187 -0
  28. package/_bundled_plugin/scripts/report_projection.py +87 -136
  29. package/_bundled_plugin/scripts/validate_scan_contract.py +2 -6
  30. package/_bundled_plugin/scripts/windows_scan_local_files.py +212 -55
  31. package/_bundled_plugin/scripts/workbench/retained_coverage.py +8 -24
  32. package/_bundled_plugin/scripts/workbench/saved_coverage.py +143 -231
  33. package/_bundled_plugin/scripts/workbench_cli.py +102 -13
  34. package/_bundled_plugin/scripts/workbench_constants.py +9 -0
  35. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +0 -17
  36. package/_bundled_plugin/scripts/workbench_db.py +187 -363
  37. package/_bundled_plugin/scripts/workbench_finding_workflows.py +86 -4
  38. package/_bundled_plugin/scripts/workbench_native_indexes.py +17 -21
  39. package/_bundled_plugin/scripts/workbench_remediation.py +495 -11
  40. package/_bundled_plugin/scripts/workbench_saved_results.py +0 -66
  41. package/_bundled_plugin/scripts/workbench_scan_history.py +22 -25
  42. package/_bundled_plugin/scripts/workbench_scan_start.py +1 -1
  43. package/_bundled_plugin/scripts/workbench_scan_usage.py +25 -52
  44. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  45. package/_bundled_plugin/scripts/workbench_setup.py +239 -0
  46. package/_bundled_plugin/scripts/workbench_source_scopes.py +15 -23
  47. package/_bundled_plugin/scripts/workbench_target.py +120 -35
  48. package/_bundled_plugin/scripts/workbench_validation.py +1 -9
  49. package/_bundled_plugin/shared/workbench-history-repairs.json +7 -0
  50. package/_bundled_plugin/shared/workbench-migrations.json +19 -0
  51. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +1 -1
  52. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +4 -68
  53. package/_bundled_plugin/skills/check-skills/SKILL.md +43 -0
  54. package/_bundled_plugin/skills/check-skills/agents/openai.yaml +4 -0
  55. package/_bundled_plugin/skills/cloud-findings/SKILL.md +2 -0
  56. package/_bundled_plugin/skills/fix-finding/SKILL.md +18 -1
  57. package/_bundled_plugin/skills/publish-findings/SKILL.md +68 -35
  58. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +2 -21
  59. package/_bundled_plugin/skills/resolve-dependency-alert/SKILL.md +18 -0
  60. package/_bundled_plugin/skills/resolve-dependency-alert/agents/openai.yaml +4 -0
  61. package/_bundled_plugin/skills/threat-model-visualize/SKILL.md +83 -0
  62. package/_bundled_plugin/skills/threat-model-visualize/agents/openai.yaml +4 -0
  63. package/_bundled_plugin/skills/threat-model-visualize/assets/context-reference-overview.svg +366 -0
  64. package/_bundled_plugin/skills/threat-model-visualize/assets/context-reference-path.svg +558 -0
  65. package/_bundled_plugin/skills/threat-model-visualize/assets/control-effects.js +85 -0
  66. package/_bundled_plugin/skills/threat-model-visualize/assets/explorer.css +17 -0
  67. package/_bundled_plugin/skills/threat-model-visualize/assets/explorer.html +38 -0
  68. package/_bundled_plugin/skills/threat-model-visualize/assets/explorer.js +372 -0
  69. package/_bundled_plugin/skills/threat-model-visualize/assets/route-paths.js +71 -0
  70. package/_bundled_plugin/skills/threat-model-visualize/assets/source-roles.js +47 -0
  71. package/_bundled_plugin/skills/threat-model-visualize/assets/svg-layout.js +149 -0
  72. package/_bundled_plugin/skills/threat-model-visualize/references/context-explorer.md +21 -0
  73. package/_bundled_plugin/skills/threat-model-visualize/references/view-model.md +49 -0
  74. package/_bundled_plugin/skills/threat-model-visualize/scripts/build_explorer.py +569 -0
  75. package/_bundled_plugin/skills/track-findings/SKILL.md +5 -3
  76. package/_bundled_plugin/skills/triage-finding/references/github-rest-intake.md +22 -68
  77. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -4
  78. package/dist/api.d.ts +6 -1
  79. package/dist/api.d.ts.map +1 -1
  80. package/dist/api.js +414 -163
  81. package/dist/api.js.map +1 -1
  82. package/dist/auth.js +7 -2
  83. package/dist/auth.js.map +1 -1
  84. package/dist/blackduck-findings.d.ts +8 -0
  85. package/dist/blackduck-findings.d.ts.map +1 -0
  86. package/dist/blackduck-findings.js +305 -0
  87. package/dist/blackduck-findings.js.map +1 -0
  88. package/dist/bulk-scan-discovery.d.ts.map +1 -1
  89. package/dist/bulk-scan-discovery.js +51 -36
  90. package/dist/bulk-scan-discovery.js.map +1 -1
  91. package/dist/classify-severity-records.d.ts +5 -0
  92. package/dist/classify-severity-records.d.ts.map +1 -1
  93. package/dist/classify-severity-records.js +6 -8
  94. package/dist/classify-severity-records.js.map +1 -1
  95. package/dist/classify-severity.d.ts +4 -1
  96. package/dist/classify-severity.d.ts.map +1 -1
  97. package/dist/classify-severity.js +28 -9
  98. package/dist/classify-severity.js.map +1 -1
  99. package/dist/cli.d.ts +3 -0
  100. package/dist/cli.d.ts.map +1 -1
  101. package/dist/cli.js +635 -266
  102. package/dist/cli.js.map +1 -1
  103. package/dist/codex-prompt.d.ts +2 -0
  104. package/dist/codex-prompt.d.ts.map +1 -1
  105. package/dist/codex-prompt.js +6 -0
  106. package/dist/codex-prompt.js.map +1 -1
  107. package/dist/component-scan.d.ts.map +1 -1
  108. package/dist/component-scan.js +6 -5
  109. package/dist/component-scan.js.map +1 -1
  110. package/dist/config.d.ts +2 -1
  111. package/dist/config.d.ts.map +1 -1
  112. package/dist/config.js +162 -40
  113. package/dist/config.js.map +1 -1
  114. package/dist/continuum-findings.d.ts +7 -0
  115. package/dist/continuum-findings.d.ts.map +1 -0
  116. package/dist/continuum-findings.js +157 -0
  117. package/dist/continuum-findings.js.map +1 -0
  118. package/dist/contract-values.d.ts +28 -0
  119. package/dist/contract-values.d.ts.map +1 -0
  120. package/dist/contract-values.js +75 -0
  121. package/dist/contract-values.js.map +1 -0
  122. package/dist/contract.d.ts +2 -20
  123. package/dist/contract.d.ts.map +1 -1
  124. package/dist/contract.js +58 -669
  125. package/dist/contract.js.map +1 -1
  126. package/dist/cost-model.d.ts.map +1 -1
  127. package/dist/cost-model.js +1 -4
  128. package/dist/cost-model.js.map +1 -1
  129. package/dist/cost.d.ts +19 -1
  130. package/dist/cost.d.ts.map +1 -1
  131. package/dist/cost.js +2120 -39
  132. package/dist/cost.js.map +1 -1
  133. package/dist/custom-validation-prompt.d.ts +1 -1
  134. package/dist/custom-validation-prompt.d.ts.map +1 -1
  135. package/dist/custom-validation-prompt.js +5 -0
  136. package/dist/custom-validation-prompt.js.map +1 -1
  137. package/dist/custom-validation.d.ts +2 -0
  138. package/dist/custom-validation.d.ts.map +1 -1
  139. package/dist/custom-validation.js +6 -2
  140. package/dist/custom-validation.js.map +1 -1
  141. package/dist/deduplication/deduplication-prompts.d.ts +4 -4
  142. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  143. package/dist/deduplication/deduplication-prompts.js +2 -2
  144. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  145. package/dist/deduplication/deduplication-reviewer.d.ts +14 -11
  146. package/dist/deduplication/deduplication-reviewer.d.ts.map +1 -1
  147. package/dist/deduplication/deduplication-reviewer.js +12 -5
  148. package/dist/deduplication/deduplication-reviewer.js.map +1 -1
  149. package/dist/deduplication/deduplication.js.map +1 -1
  150. package/dist/deduplication/finding-schema.d.ts +19 -1
  151. package/dist/deduplication/finding-schema.d.ts.map +1 -1
  152. package/dist/deduplication/finding-schema.js +25 -0
  153. package/dist/deduplication/finding-schema.js.map +1 -1
  154. package/dist/deduplication/local.d.ts.map +1 -1
  155. package/dist/deduplication/local.js +3 -8
  156. package/dist/deduplication/local.js.map +1 -1
  157. package/dist/deduplication/records.d.ts +11 -3
  158. package/dist/deduplication/records.d.ts.map +1 -1
  159. package/dist/deduplication/records.js +48 -16
  160. package/dist/deduplication/records.js.map +1 -1
  161. package/dist/deep-scan.d.ts +11 -0
  162. package/dist/deep-scan.d.ts.map +1 -1
  163. package/dist/deep-scan.js +235 -4
  164. package/dist/deep-scan.js.map +1 -1
  165. package/dist/default-severity-rubric.d.ts +1 -2
  166. package/dist/default-severity-rubric.d.ts.map +1 -1
  167. package/dist/default-severity-rubric.js +2 -66
  168. package/dist/default-severity-rubric.js.map +1 -1
  169. package/dist/endor-findings.d.ts.map +1 -1
  170. package/dist/endor-findings.js +44 -89
  171. package/dist/endor-findings.js.map +1 -1
  172. package/dist/errors.js +1 -1
  173. package/dist/errors.js.map +1 -1
  174. package/dist/external-findings-import.d.ts.map +1 -1
  175. package/dist/external-findings-import.js +11 -15
  176. package/dist/external-findings-import.js.map +1 -1
  177. package/dist/external-findings-local.d.ts +12 -1
  178. package/dist/external-findings-local.d.ts.map +1 -1
  179. package/dist/external-findings-local.js +411 -184
  180. package/dist/external-findings-local.js.map +1 -1
  181. package/dist/external-findings-publish.d.ts +15 -1
  182. package/dist/external-findings-publish.d.ts.map +1 -1
  183. package/dist/external-findings-publish.js +1238 -226
  184. package/dist/external-findings-publish.js.map +1 -1
  185. package/dist/external-findings-read.d.ts +10 -0
  186. package/dist/external-findings-read.d.ts.map +1 -1
  187. package/dist/external-findings-read.js +71 -51
  188. package/dist/external-findings-read.js.map +1 -1
  189. package/dist/external-findings.d.ts +13 -0
  190. package/dist/external-findings.d.ts.map +1 -1
  191. package/dist/external-findings.js +124 -1
  192. package/dist/external-findings.js.map +1 -1
  193. package/dist/external-import-contract.d.ts +29 -1
  194. package/dist/external-import-contract.d.ts.map +1 -1
  195. package/dist/external-import-contract.js +314 -44
  196. package/dist/external-import-contract.js.map +1 -1
  197. package/dist/external-import-models.d.ts +1 -1
  198. package/dist/external-import-models.d.ts.map +1 -1
  199. package/dist/external-import-models.js.map +1 -1
  200. package/dist/finding-normalization.d.ts +1 -1
  201. package/dist/finding-normalization.d.ts.map +1 -1
  202. package/dist/finding-normalization.js +46 -11
  203. package/dist/finding-normalization.js.map +1 -1
  204. package/dist/finding-retrieval.d.ts +3 -3
  205. package/dist/finding-retrieval.d.ts.map +1 -1
  206. package/dist/finding-retrieval.js.map +1 -1
  207. package/dist/finding-workflow.d.ts +6 -1
  208. package/dist/finding-workflow.d.ts.map +1 -1
  209. package/dist/finding-workflow.js +2 -2
  210. package/dist/finding-workflow.js.map +1 -1
  211. package/dist/git-remote.d.ts +4 -0
  212. package/dist/git-remote.d.ts.map +1 -1
  213. package/dist/git-remote.js +20 -0
  214. package/dist/git-remote.js.map +1 -1
  215. package/dist/github-advisories.d.ts +3 -12
  216. package/dist/github-advisories.d.ts.map +1 -1
  217. package/dist/github-advisories.js +9 -29
  218. package/dist/github-advisories.js.map +1 -1
  219. package/dist/github-dependabot-findings.d.ts.map +1 -1
  220. package/dist/github-dependabot-findings.js +7 -16
  221. package/dist/github-dependabot-findings.js.map +1 -1
  222. package/dist/github-findings.d.ts.map +1 -1
  223. package/dist/github-findings.js +344 -56
  224. package/dist/github-findings.js.map +1 -1
  225. package/dist/github.d.ts +17 -7
  226. package/dist/github.d.ts.map +1 -1
  227. package/dist/github.js +43 -30
  228. package/dist/github.js.map +1 -1
  229. package/dist/host-protocol.d.ts +7 -2
  230. package/dist/host-protocol.d.ts.map +1 -1
  231. package/dist/host-protocol.js +27 -3
  232. package/dist/host-protocol.js.map +1 -1
  233. package/dist/host-records-protocol.d.ts +10 -11
  234. package/dist/host-records-protocol.d.ts.map +1 -1
  235. package/dist/host-records-protocol.js +69 -9
  236. package/dist/host-records-protocol.js.map +1 -1
  237. package/dist/hosted-scan.d.ts +15 -0
  238. package/dist/hosted-scan.d.ts.map +1 -1
  239. package/dist/hosted-scan.js +55 -33
  240. package/dist/hosted-scan.js.map +1 -1
  241. package/dist/index.d.ts +8 -0
  242. package/dist/index.d.ts.map +1 -1
  243. package/dist/index.js +7 -0
  244. package/dist/index.js.map +1 -1
  245. package/dist/inspector-findings.d.ts +9 -0
  246. package/dist/inspector-findings.d.ts.map +1 -0
  247. package/dist/inspector-findings.js +512 -0
  248. package/dist/inspector-findings.js.map +1 -0
  249. package/dist/knowledge-base.js +18 -5
  250. package/dist/knowledge-base.js.map +1 -1
  251. package/dist/local-git-metadata.d.ts +5 -0
  252. package/dist/local-git-metadata.d.ts.map +1 -0
  253. package/dist/local-git-metadata.js +131 -0
  254. package/dist/local-git-metadata.js.map +1 -0
  255. package/dist/multiscan.d.ts.map +1 -1
  256. package/dist/multiscan.js +22 -12
  257. package/dist/multiscan.js.map +1 -1
  258. package/dist/opengrep-findings.d.ts.map +1 -1
  259. package/dist/opengrep-findings.js +34 -20
  260. package/dist/opengrep-findings.js.map +1 -1
  261. package/dist/patch-tui.d.ts +1 -1
  262. package/dist/patch-tui.d.ts.map +1 -1
  263. package/dist/patch-tui.js +94 -36
  264. package/dist/patch-tui.js.map +1 -1
  265. package/dist/private-finding-import.d.ts +246 -0
  266. package/dist/private-finding-import.d.ts.map +1 -0
  267. package/dist/private-finding-import.js +387 -0
  268. package/dist/private-finding-import.js.map +1 -0
  269. package/dist/project-config.d.ts.map +1 -1
  270. package/dist/project-config.js +2 -2
  271. package/dist/project-config.js.map +1 -1
  272. package/dist/provider-profile.d.ts +10 -2
  273. package/dist/provider-profile.d.ts.map +1 -1
  274. package/dist/provider-profile.js +72 -10
  275. package/dist/provider-profile.js.map +1 -1
  276. package/dist/publication.js +7 -1
  277. package/dist/publication.js.map +1 -1
  278. package/dist/reader-selection.d.ts +13 -0
  279. package/dist/reader-selection.d.ts.map +1 -0
  280. package/dist/reader-selection.js +81 -0
  281. package/dist/reader-selection.js.map +1 -0
  282. package/dist/record.d.ts +6 -1
  283. package/dist/record.d.ts.map +1 -1
  284. package/dist/record.js +53 -2
  285. package/dist/record.js.map +1 -1
  286. package/dist/remediation.d.ts +5 -0
  287. package/dist/remediation.d.ts.map +1 -1
  288. package/dist/remediation.js +30 -0
  289. package/dist/remediation.js.map +1 -1
  290. package/dist/result.d.ts +2 -0
  291. package/dist/result.d.ts.map +1 -1
  292. package/dist/result.js +3 -1
  293. package/dist/result.js.map +1 -1
  294. package/dist/runtime.d.ts +5 -3
  295. package/dist/runtime.d.ts.map +1 -1
  296. package/dist/runtime.js +110 -57
  297. package/dist/runtime.js.map +1 -1
  298. package/dist/scan-activity.js +40 -17
  299. package/dist/scan-activity.js.map +1 -1
  300. package/dist/scan-comparison.d.ts +1 -1
  301. package/dist/scan-comparison.d.ts.map +1 -1
  302. package/dist/scan-comparison.js +11 -13
  303. package/dist/scan-comparison.js.map +1 -1
  304. package/dist/scan-dashboard.d.ts +1 -0
  305. package/dist/scan-dashboard.d.ts.map +1 -1
  306. package/dist/scan-dashboard.js +37 -48
  307. package/dist/scan-dashboard.js.map +1 -1
  308. package/dist/scan-executor.d.ts +2 -0
  309. package/dist/scan-executor.d.ts.map +1 -1
  310. package/dist/scan-executor.js.map +1 -1
  311. package/dist/scan-history-renderer.d.ts.map +1 -1
  312. package/dist/scan-history-renderer.js +22 -9
  313. package/dist/scan-history-renderer.js.map +1 -1
  314. package/dist/scan-logs.d.ts.map +1 -1
  315. package/dist/scan-logs.js +5 -5
  316. package/dist/scan-logs.js.map +1 -1
  317. package/dist/scanner-import.d.ts +48 -3
  318. package/dist/scanner-import.d.ts.map +1 -1
  319. package/dist/scanner-import.js +214 -39
  320. package/dist/scanner-import.js.map +1 -1
  321. package/dist/scanner-repository-url.d.ts +14 -0
  322. package/dist/scanner-repository-url.d.ts.map +1 -0
  323. package/dist/scanner-repository-url.js +67 -0
  324. package/dist/scanner-repository-url.js.map +1 -0
  325. package/dist/semgrep-findings.d.ts.map +1 -1
  326. package/dist/semgrep-findings.js +50 -88
  327. package/dist/semgrep-findings.js.map +1 -1
  328. package/dist/semgrep-platform-findings.d.ts +12 -0
  329. package/dist/semgrep-platform-findings.d.ts.map +1 -0
  330. package/dist/semgrep-platform-findings.js +198 -0
  331. package/dist/semgrep-platform-findings.js.map +1 -0
  332. package/dist/severity-rubric.d.ts +20 -0
  333. package/dist/severity-rubric.d.ts.map +1 -0
  334. package/dist/severity-rubric.js +73 -0
  335. package/dist/severity-rubric.js.map +1 -0
  336. package/dist/severity-store.js +15 -5
  337. package/dist/severity-store.js.map +1 -1
  338. package/dist/snyk-findings.d.ts.map +1 -1
  339. package/dist/snyk-findings.js +97 -106
  340. package/dist/snyk-findings.js.map +1 -1
  341. package/dist/sonar-collector.d.ts +16 -0
  342. package/dist/sonar-collector.d.ts.map +1 -0
  343. package/dist/sonar-collector.js +383 -0
  344. package/dist/sonar-collector.js.map +1 -0
  345. package/dist/sonar-findings.d.ts +49 -0
  346. package/dist/sonar-findings.d.ts.map +1 -0
  347. package/dist/sonar-findings.js +288 -0
  348. package/dist/sonar-findings.js.map +1 -0
  349. package/dist/sonar-import.d.ts +111 -0
  350. package/dist/sonar-import.d.ts.map +1 -0
  351. package/dist/sonar-import.js +279 -0
  352. package/dist/sonar-import.js.map +1 -0
  353. package/dist/suggest-owners.d.ts.map +1 -1
  354. package/dist/suggest-owners.js +2 -1
  355. package/dist/suggest-owners.js.map +1 -1
  356. package/dist/targets.d.ts +3 -0
  357. package/dist/targets.d.ts.map +1 -1
  358. package/dist/targets.js +18 -12
  359. package/dist/targets.js.map +1 -1
  360. package/dist/terminal-columns.d.ts +4 -0
  361. package/dist/terminal-columns.d.ts.map +1 -0
  362. package/dist/terminal-columns.js +19 -0
  363. package/dist/terminal-columns.js.map +1 -0
  364. package/dist/validation-records.d.ts +0 -3
  365. package/dist/validation-records.d.ts.map +1 -1
  366. package/dist/validation-records.js +0 -16
  367. package/dist/validation-records.js.map +1 -1
  368. package/dist/veracode-findings.d.ts +7 -0
  369. package/dist/veracode-findings.d.ts.map +1 -0
  370. package/dist/veracode-findings.js +371 -0
  371. package/dist/veracode-findings.js.map +1 -0
  372. package/dist/windows-path.d.ts.map +1 -1
  373. package/dist/windows-path.js +1 -0
  374. package/dist/windows-path.js.map +1 -1
  375. package/dist/wiz-csv.d.ts +2 -2
  376. package/dist/wiz-csv.d.ts.map +1 -1
  377. package/dist/wiz-csv.js +1 -3
  378. package/dist/wiz-csv.js.map +1 -1
  379. package/dist/wiz-findings.d.ts +10 -2
  380. package/dist/wiz-findings.d.ts.map +1 -1
  381. package/dist/wiz-findings.js +88 -49
  382. package/dist/wiz-findings.js.map +1 -1
  383. package/docs/classify-severity-records.md +1 -1
  384. package/docs/cli.md +320 -481
  385. package/docs/dedupe-records.md +27 -4
  386. package/docs/findings-service.md +21 -8
  387. package/docs/hosted-scans.md +16 -1
  388. package/package.json +9 -10
  389. package/schemas/external-findings.schema.json +12 -1
  390. package/schemas/hosted-scan-v2.fixture.json +16 -1
  391. package/_bundled_plugin/scripts/validate_tracking_source.py +0 -82
  392. package/_bundled_plugin/scripts/workbench_local_dedupe.py +0 -136
  393. package/dist/deduplication/records-protocol.d.ts +0 -4
  394. package/dist/deduplication/records-protocol.d.ts.map +0 -1
  395. package/dist/deduplication/records-protocol.js +0 -35
  396. package/dist/deduplication/records-protocol.js.map +0 -1
@@ -0,0 +1,71 @@
1
+ /* Explicit assessment routes; never infer reachability from graph proximity. */
2
+ (function (root) {
3
+ 'use strict';
4
+ function resolve(model, scenario, routeId, stop = -1, arrival = false) {
5
+ const route = scenario?.routes?.find(r => r.id === routeId) || scenario?.routes?.[0];
6
+ if (!route) return null;
7
+ const edges = new Map(model.edges.map(e => [e.id, e]));
8
+ const stopEdge = stop >= 0 ? scenario.steps[stop]?.edge : null;
9
+ const stopIndex = stopEdge ? route.edges.indexOf(stopEdge) : -1;
10
+ const owner = stopIndex < 0 ? null : edges.get(stopEdge).to;
11
+ const activeEdges = new Set(), activeNodes = new Set();
12
+ const prefix = stopIndex < 0 ? route.edges : route.edges.slice(0, stopIndex + 1);
13
+ for (const id of prefix) {
14
+ const {from, to} = edges.get(id);
15
+ activeEdges.add(id);
16
+ activeNodes.add(from);
17
+ if (id !== stopEdge || arrival) activeNodes.add(to);
18
+ }
19
+ // Arrival displays the owner. Only a prior visit lets it start unrelated work.
20
+ const independent = new Set(activeNodes);
21
+ if (arrival && stopIndex >= 0) {
22
+ const earlierVisit = prefix.slice(0, -1).some(id => edges.get(id).from === owner || edges.get(id).to === owner);
23
+ if (!earlierVisit) independent.delete(owner);
24
+ }
25
+
26
+ const branchStates = (route.branches || []).map(branch => ({branch, active:false, reached:0}));
27
+ // A later branch can reach an earlier branch's origin, or make a visible
28
+ // prerequisite independently reachable. Both node sets grow monotonically.
29
+ let nodeCount;
30
+ do {
31
+ nodeCount = activeNodes.size + independent.size;
32
+ for (const state of branchStates) {
33
+ const {branch} = state;
34
+ const start = edges.get(branch.edges[0]).from;
35
+ const prerequisite = stopIndex >= 0 && branch.beforeStep === stop + 1 && start === owner;
36
+ if (branch.beforeStep !== undefined) {
37
+ if (stopIndex >= 0 && (branch.beforeStep > stop + 1 || (prerequisite && !arrival))) continue;
38
+ } else if (!activeNodes.has(start) ||
39
+ (branch.afterStep !== undefined && stopIndex >= 0 && branch.afterStep >= stop + 1)) continue;
40
+
41
+ // A prerequisite keeps its dependency even when its reply crosses a
42
+ // previously visited relay. Reconsider it if its origin later becomes independent.
43
+ const dependent = prerequisite || (branch.beforeStep === undefined && !independent.has(start));
44
+ let reached = 0;
45
+ for (const id of branch.edges) {
46
+ const {from, to} = edges.get(id);
47
+ if (branch.beforeStep === undefined && from === owner && !independent.has(owner)) break;
48
+ activeEdges.add(id);
49
+ activeNodes.add(from); activeNodes.add(to);
50
+ if (!dependent) { independent.add(from); independent.add(to); }
51
+ reached++;
52
+ }
53
+ state.reached = reached;
54
+ state.active = reached === branch.edges.length;
55
+ }
56
+ } while (activeNodes.size + independent.size !== nodeCount);
57
+
58
+ const unreachedEdges = new Set(), unreachedNodes = new Set();
59
+ for (const id of [...route.edges, ...branchStates.flatMap(({branch}) => branch.edges)]) {
60
+ const {from, to} = edges.get(id);
61
+ if (!activeEdges.has(id)) unreachedEdges.add(id);
62
+ if (!activeNodes.has(from)) unreachedNodes.add(from);
63
+ if (!activeNodes.has(to)) unreachedNodes.add(to);
64
+ }
65
+ const focusNodes = new Set(scenario.focusNodes || []);
66
+ return {route, activeEdges, activeNodes, unreachedEdges, unreachedNodes, focusNodes, branchStates};
67
+ }
68
+ const api = {resolve};
69
+ if (typeof module !== 'undefined' && module.exports) module.exports = api;
70
+ root.RoutePaths = api;
71
+ })(globalThis);
@@ -0,0 +1,47 @@
1
+ /* Scenario origins describe starting authority, never inferred compromise. */
2
+ (function (root) {
3
+ 'use strict';
4
+ const palette = {
5
+ adversary: {fill:'#fbe1e1', ink:'#912d35', colorName:'red', label:'Adversary', badge:'ADVERSARY'},
6
+ 'compromised-component': {fill:'#f1d9e7', ink:'#852653', colorName:'berry', label:'Compromised component', badge:'COMPROMISED'},
7
+ 'untrusted-input': {fill:'#fde9df', ink:'#944324', colorName:'peach', label:'Untrusted input', badge:'UNTRUSTED INPUT'},
8
+ unknown: {fill:'#e9e9ed', ink:'#555568', colorName:'grey', label:'Source uncertain', badge:'SOURCE UNCERTAIN'},
9
+ 'authorized-user': {fill:'#e0edf9', ink:'#285b88', colorName:'blue', label:'Authorized use', badge:'AUTHORIZED USE'}
10
+ };
11
+ const basis = {
12
+ 'scenario-assumption':'Assumed starting condition',
13
+ 'assessment-observed':'Observed in supplied assessment',
14
+ unknown:'Starting condition uncertain'
15
+ };
16
+ function resolve(model, scenario, routeId, sourceId) {
17
+ const route = scenario?.routes?.find(r => r.id === routeId) || scenario?.routes?.[0];
18
+ const allSources = (scenario?.sources || []).filter(s => !s.routeIds || s.routeIds.includes(route?.id));
19
+ const selected = scenario?.sourceMode === 'alternatives' ? allSources.find(s => s.id === sourceId) || allSources[0] : null;
20
+ const sources = selected ? [selected] : allSources;
21
+ const nodes = new Map();
22
+ for (const p of model.participants || []) {
23
+ if (!nodes.has(p.node))
24
+ nodes.set(p.node, {...palette[p.kind], kind:p.kind, items:[], source:false});
25
+ nodes.get(p.node).items.push(p);
26
+ }
27
+ const mapped = new Map();
28
+ for (const s of sources) {
29
+ if (s.node === null) continue;
30
+ if (!mapped.has(s.node)) mapped.set(s.node, []);
31
+ mapped.get(s.node).push(s);
32
+ }
33
+ for (const [id, items] of mapped) {
34
+ const kinds = new Set(items.map(s => s.kind)), kind = kinds.size === 1 ? items[0].kind : 'unknown';
35
+ nodes.set(id, {...palette[kind], ...(kinds.size > 1 ? {label:'Multiple source roles',badge:'MULTIPLE ROLES'} : {}), kind, items, source:true});
36
+ }
37
+ // Explicit source sets describe relationships only; never derive reach from roles.
38
+ const relatedNodes = selected?.relatedNodes ?? scenario?.affectedNodes ?? [];
39
+ const relatedEdges = selected?.relatedEdges ?? scenario?.affectedEdges ?? [];
40
+ const jointRequirement = scenario?.sourceMode === 'combined' && sources.length > 1
41
+ ? 'All listed starting positions are required together.' : '';
42
+ return {sources, allSources, selected, nodes, relatedNodes, relatedEdges, jointRequirement};
43
+ }
44
+ const api = {resolve, palette, basis};
45
+ if (typeof module !== 'undefined' && module.exports) module.exports = api;
46
+ root.SourceRoles = api;
47
+ })(globalThis);
@@ -0,0 +1,149 @@
1
+ 'use strict';
2
+ // Bounded SVG presentation geometry only: authored topology and model data stay unchanged.
3
+ const SvgLayout = (() => {
4
+ const intersects = (a,b) => a.x < b.x+b.w && b.x < a.x+a.w && a.y < b.y+b.h && b.y < a.y+a.h;
5
+ const padded = (r,p=4) => ({x:r.x-p,y:r.y-p,w:r.w+2*p,h:r.h+2*p});
6
+ const distance = (a,b) => Math.hypot(a[0]-b[0],a[1]-b[1]);
7
+ const clean = points => points.filter((p,i)=>!i || distance(p,points[i-1])>1e-6);
8
+ function fallback(text,size) { return {w:[...text].reduce((n,c)=>n+(/[MW@%]/.test(c)?.9:/[il.,:;' ]/.test(c)?.32:.62)*size,0),ascent:size*.8,descent:size*.2}; }
9
+ function lines(text,width,size,weight,measure) {
10
+ const result=[];let line='';
11
+ for(const word of String(text).trim().split(/\s+/)) {
12
+ if(!word)continue;
13
+ if(line && measure(line+' '+word,size,weight).w>width){result.push(line);line='';}
14
+ if(measure(word,size,weight).w>width){
15
+ for(const char of word){if(line && measure(line+char,size,weight).w>width){result.push(line);line='';}line+=char;}
16
+ } else line+=(line?' ':'')+word;
17
+ }
18
+ if(line)result.push(line);return result;
19
+ }
20
+ function sample(points,offset) {
21
+ const p=clean(points),lengths=p.slice(1).map((b,i)=>distance(p[i],b)),total=lengths.reduce((a,b)=>a+b,0);let target=Math.max(0,Math.min(total,offset));
22
+ for(let i=0;i<lengths.length;i++) {
23
+ if(target<=lengths[i] || i===lengths.length-1){const t=target/lengths[i];return [p[i][0]+(p[i+1][0]-p[i][0])*t,p[i][1]+(p[i+1][1]-p[i][1])*t];}target-=lengths[i];
24
+ }
25
+ return p[0];
26
+ }
27
+ function nearestOffset(points,anchor) {
28
+ let best=Infinity,offset=0,answer=0;
29
+ for(let i=1;i<points.length;i++){
30
+ const a=points[i-1],b=points[i],length=distance(a,b);if(!length)continue;
31
+ const t=Math.max(0,Math.min(1,((anchor[0]-a[0])*(b[0]-a[0])+(anchor[1]-a[1])*(b[1]-a[1]))/(length*length)));
32
+ const d=distance(anchor,[a[0]+t*(b[0]-a[0]),a[1]+t*(b[1]-a[1])]);if(d<best){best=d;answer=offset+t*length;}offset+=length;
33
+ }return answer;
34
+ }
35
+ function joints(edges) {
36
+ const points=new Map(),segments=[];
37
+ const add=p=>points.set(p.map(n=>n.toFixed(2)).join(','),{x:p[0]-6,y:p[1]-6,w:12,h:12});
38
+ for(const e of edges){const p=clean(e.points);p.forEach(add);p.slice(1).forEach((b,i)=>segments.push([p[i],b,e.id]));}
39
+ for(let i=0;i<segments.length;i++)for(let j=i+1;j<segments.length;j++){
40
+ const [a,b,id]=segments[i],[c,d,other]=segments[j];if(id===other)continue;
41
+ const rx=b[0]-a[0],ry=b[1]-a[1],sx=d[0]-c[0],sy=d[1]-c[1],cross=rx*sy-ry*sx;if(Math.abs(cross)<1e-8)continue;
42
+ const t=((c[0]-a[0])*sy-(c[1]-a[1])*sx)/cross,u=((c[0]-a[0])*ry-(c[1]-a[1])*rx)/cross;
43
+ if(t>=0 && t<=1 && u>=0 && u<=1)add([a[0]+t*rx,a[1]+t*ry]);
44
+ }return [...points.values()];
45
+ }
46
+ function segmentIntersectsRect(a,b,box) {
47
+ let low=0,high=1;
48
+ for(const [axis,min,max] of [[0,box.x,box.x+box.w],[1,box.y,box.y+box.h]]){
49
+ const delta=b[axis]-a[axis];
50
+ if(Math.abs(delta)<1e-9){if(a[axis]<min || a[axis]>max)return false;continue;}
51
+ const p=(min-a[axis])/delta,q=(max-a[axis])/delta;
52
+ low=Math.max(low,Math.min(p,q));high=Math.min(high,Math.max(p,q));if(low>high)return false;
53
+ }return true;
54
+ }
55
+ function candidates(item,w,h,dense=false) {
56
+ const [ax,ay]=item.anchor,result=[];
57
+ const add=(cx,cy)=>result.push({x:cx-w/2,y:cy-h/2,w,h});
58
+ if(dense){
59
+ if(item.kind==='region'){
60
+ const r=item.region,left=Math.min(r.x+8+w/2,r.x+r.w/2),right=Math.max(r.x+r.w-8-w/2,r.x+r.w/2);
61
+ for(let cx=left;cx<=right+1e-6;cx+=Math.max(4,(right-left)/64))for(let dy=-64;dy<=64;dy+=4){add(cx,r.y+dy);add(cx,r.y+r.h+dy);}
62
+ for(let dy=-64;dy<=r.h+64;dy+=Math.max(4,(r.h+128)/64)){add(r.x+4-w/2,r.y+dy);add(r.x+r.w-4+w/2,r.y+dy);}
63
+ }else for(let dx=-176;dx<=176;dx+=8)for(let dy=-176;dy<=176;dy+=8)add(ax+dx,ay+dy);
64
+ return result;
65
+ }
66
+ if(item.kind==='region'){
67
+ const r=item.region,left=Math.min(r.x+8+w/2,r.x+r.w/2),right=Math.max(r.x+r.w-8-w/2,r.x+r.w/2);
68
+ for(const dy of Array.from({length:23},(_,i)=>i*4-64))for(const dx of [0,12,-12,24,-24,48,-48,72,-72,96,-96,144,-144]) {
69
+ const cx=Math.max(left,Math.min(right,ax+dx)),cy=ay+dy;add(cx,cy);
70
+ }
71
+ for(const cx of [left,(left+right)/2,right]){
72
+ add(cx,r.y-h/2-4);add(cx,r.y+4+h/2);
73
+ for(let dy=-24;dy<=64;dy+=4)add(cx,r.y+r.h+dy);
74
+ }
75
+ // A tight header strip can have no legal top slot. Keep its title attached
76
+ // to the same boundary, with a short annotation leader, rather than cover a node.
77
+ for(let dy=-64;dy<=r.h+64;dy+=16){
78
+ add(r.x+4-w/2,r.y+dy);add(r.x+r.w-4+w/2,r.y+dy);
79
+ }
80
+ }else {
81
+ for(const radius of [0,12,24,40,60,84,112,144])for(const [dx,dy] of [[0,-1],[0,1],[-1,0],[1,0],[-1,-1],[1,-1],[-1,1],[1,1]])add(ax+dx*radius,ay+dy*radius);
82
+ for(const dx of [-96,-72,-48,-32,-16,0,16,32,48,72,96])for(const dy of [-96,-72,-48,-32,-16,-8,0,8,16,32,48,72,96])add(ax+dx,ay+dy);
83
+ if(item.edge){const offset=nearestOffset(item.edge.points,item.anchor);
84
+ for(const along of [0,-24,24,-48,48,-80,80,-120,120]){const point=sample(item.edge.points,offset+along);for(const dy of [-16,16,-28,28,-44,44])add(point[0],point[1]+dy);}
85
+ }
86
+ }return result;
87
+ }
88
+ function plan(items,nodes,edges,canvas,measure=fallback) {
89
+ const obstacles=nodes.map(n=>padded(n,2)),placed=new Map();
90
+ const activeEdges=edges.filter(e=>e.layoutActive!==false).map(e=>({...e,points:e.layoutActivePoints||e.points}));
91
+ const allJoints=joints(edges),activeJoints=joints(activeEdges);
92
+ const segmentsFor=list=>list.flatMap(e=>{const points=clean(e.points);return points.slice(1).map((b,i)=>({id:e.id,a:points[i],b,box:padded({x:Math.min(points[i][0],b[0]),y:Math.min(points[i][1],b[1]),w:Math.abs(b[0]-points[i][0]),h:Math.abs(b[1]-points[i][1])},2.5)}));});
93
+ const segments=segmentsFor(edges),activeSegments=segmentsFor(activeEdges);
94
+ for(const item of [...items].sort((a,b)=>a.priority-b.priority || (a.id<b.id?-1:a.id>b.id?1:0))){
95
+ let best=null;
96
+ // Refine only an unresolved caption: ordinary views keep the cheap pass.
97
+ for(const dense of [false,true,...(item.kind==='edge'?['fine','wrap']:[])]){
98
+ if(dense && best?.conflicts===0)break;
99
+ const refinementOrigin=best?[best.x+best.w/2,best.y+best.h/2]:item.anchor;
100
+ // Whole-word wrapping is a last resort for a short caption whose
101
+ // measured one-line width exceeds a legal local gap by even a fraction.
102
+ const widths=dense==='wrap'?[Math.max(...String(item.text).trim().split(/\s+/).map(word=>measure(word,item.size,item.weight).w))]:item.widths;
103
+ for(const maxWidth of widths){
104
+ if(dense && best?.conflicts===0)break;
105
+ const content=lines(item.text,maxWidth,item.size,item.weight,measure),metrics=content.map(t=>measure(t,item.size,item.weight));if(!content.length)continue;
106
+ const ascent=Math.max(...metrics.map(m=>m.ascent)),descent=Math.max(...metrics.map(m=>m.descent)),lineHeight=Math.max(item.size*1.2,ascent+descent+2);
107
+ const w=item.kind==='control'?maxWidth+24:Math.max(...metrics.map(m=>m.w))+8;
108
+ const h=item.kind==='control'?Math.max(56,40+(content.length-1)*lineHeight+descent+8):ascent+descent+(content.length-1)*lineHeight+8;
109
+ // Only a still-unresolved edge caption gets this 225-slot local nudge.
110
+ const slots=dense==='fine'?Array.from({length:15},(_,i)=>i*2-14).flatMap(dx=>Array.from({length:15},(_,i)=>({x:refinementOrigin[0]+dx-w/2,y:refinementOrigin[1]+i*2-14-h/2,w,h}))):candidates(item,w,h,dense);
111
+ if(dense){const origin=dense==='fine'?refinementOrigin:item.anchor;slots.sort((a,b)=>(a.x+w/2-origin[0])**2+(a.y+h/2-origin[1])**2-(b.x+w/2-origin[0])**2-(b.y+h/2-origin[1])**2);}
112
+ for(const raw of dense?slots.slice(0,2048):slots){
113
+ if(w>canvas.width-8 || h>canvas.height-8)continue;
114
+ const box={...raw,x:Math.max(4,Math.min(raw.x,canvas.width-w-4)),y:Math.max(4,Math.min(raw.y,canvas.height-h-4))};
115
+ if(item.kind==='edge' && distance([box.x+w/2,box.y+h/2],item.anchor)>180)continue;
116
+ const hard=[...obstacles,...(item.kind==='control'?activeJoints:allJoints)].filter(o=>intersects(box,o));
117
+ if(best?.conflicts===0 && hard.length)continue;
118
+ const guard=padded(box,2.5);
119
+ const crossed=segments.filter(s=>(item.kind==='control' || s.id!==item.edge?.id) && intersects(guard,s.box) && segmentIntersectsRect(s.a,s.b,guard));
120
+ // Opaque cards must never hide a route. Short text halos can cross an
121
+ // ordinary stroke when no nearby clear slot exists; this is a preference,
122
+ // separate from actual text/component/junction overlap.
123
+ const blocked=item.kind==='control'?activeSegments.filter(s=>intersects(guard,s.box)&&segmentIntersectsRect(s.a,s.b,guard)):[];
124
+ const conflicts=[...hard,...blocked.map(s=>s.box)],area=conflicts.reduce((n,o)=>n+(Math.min(box.x+w,o.x+o.w)-Math.max(box.x,o.x))*(Math.min(box.y+h,o.y+o.h)-Math.max(box.y,o.y)),0);
125
+ const cost=conflicts.length*1e8+area*1e4+distance([box.x+w/2,box.y+h/2],item.anchor)**2+(content.length-1)*100+(item.kind==='control' && blocked.length?0:crossed.length*2500);
126
+ if(!best || cost<best.cost)best={...box,id:item.id,kind:item.kind,text:item.text,lines:content,size:item.size,weight:item.weight,ascent,descent,lineHeight,cost,edge:item.edge,conflicts:conflicts.length,connectorCrossings:crossed.length};
127
+ if(dense && conflicts.length===0)break;
128
+ }
129
+ }
130
+ }
131
+ if(!best){const content=lines(item.text,item.widths[0],item.size,item.weight,measure);best={id:item.id,kind:item.kind,text:item.text,lines:content,size:item.size,weight:item.weight,ascent:item.size*.8,descent:item.size*.2,lineHeight:item.size*1.2,x:item.anchor[0],y:item.anchor[1],w:item.widths[0],h:content.length*item.size*1.2,conflicts:1};}
132
+ placed.set(item.id,best);obstacles.push(best);
133
+ }return placed;
134
+ }
135
+ function heads(edges,priority=()=>0) {
136
+ const groups=new Map(),result=new Map();
137
+ for(const e of edges){const p=clean(e.points);if(p.length<2)continue;const end=p.at(-1),before=p.at(-2),length=distance(before,end),direction=[(end[0]-before[0])/length,(end[1]-before[1])/length],key=e.to+'|'+end.map(n=>n.toFixed(3)).join(',')+'|'+direction.map(n=>n.toFixed(6)).join(',');const group=groups.get(key)||[];group.push({e,p});groups.set(key,group);}
138
+ for(const group of groups.values()){
139
+ group.sort((a,b)=>priority(b.e)-priority(a.e) || (a.e.id<b.e.id?-1:1));
140
+ for(const item of group){const length=distance(item.p.at(-2),item.p.at(-1));const size=Math.min(9,Math.max(.25,Math.floor(length*.65*4)/4));result.set(item.e.id,{visible:item===group[0],size,shared:group.length,points:item.p});}
141
+ }return result;
142
+ }
143
+ function nodeRows(node,role,measure=fallback) {
144
+ const specs=[...(role?[{key:'role',text:role,size:9,weight:700}]:[]),{key:'title',text:node.title,size:17,weight:600},...(node.subtitle?[{key:'subtitle',text:node.subtitle,size:14,weight:400}]:[])];
145
+ const rows=specs.map(s=>({...s,...measure(s.text,s.size,s.weight)}));const height=rows.reduce((n,r)=>n+r.ascent+r.descent,0)+Math.max(0,rows.length-1)*2+4;let y=node.y+2+Math.max(0,(node.h-height)/2);
146
+ for(const row of rows){row.y=y+row.ascent;y=row.y+row.descent+2;}return {rows,overflow:height>node.h || rows.some(r=>r.w>node.w-20)};
147
+ }
148
+ return {intersects,padded,fallback,lines,plan,heads,nodeRows,clean,joints,sample,nearestOffset,segmentIntersectsRect};
149
+ })();
@@ -0,0 +1,21 @@
1
+ # Explorer presentation
2
+
3
+ The shared shell supplies the scenario rail, map, inspection, evidence, controls, navigation and offline exports. Keep its fixed palette: adversary red, compromised component berry, untrusted input peach, unknown grey, authorized use blue; selected routes use orange and transit keeps a neutral outline. Do not borrow project-specific topology from a reference example.
4
+
5
+ Compose the architecture before the threat overlay. A useful overview explains the ordinary system: who calls it, where trust changes, how services or library components cooperate, where identity and state live, and which external or operational contexts matter. Use source-supported boundary regions and spatial groupings to make those relationships legible. Components needed by distinct assessment cases should remain represented, even when outside the selected path. Do not force every repository into one pipeline or a disconnected grid.
6
+
7
+ Keep the primary architecture visible in muted colors during scenario selection. Paint all inactive connections and labels below active route and control edges, regardless of authoring order; keep nodes and control annotations above the connections. `overviewEdges` is the persistent architecture, not a shortlist for the first threat. **More connections** reveals secondary authored edges; **Clear step** removes only individual step focus. Optional returns, repeated dependency lines and incidental detail can stay in inspection. Keep authentication, state access and administrative relationships when they explain trust, authority or a substantive case. Group components only when selections preserve each member’s callers and controls. Split the group if a highlighted edge or control would give one member another’s access or safeguard; a prose caveat does not correct a misleading selection. Do not fabricate a shortcut to fill a source gap.
8
+
9
+ Keep the map, path and control interaction compact, with conditions and residual effects close to the selected control. Emphasize each selected source’s supported relationships and owners without combining unrelated alternatives. Keep endpoint highlights coherent with the selected edges.
10
+
11
+ Label the group **Proposed controls** and individual badges, markers and legend items **Proposed control**. Use conditional captions such as “Would block” or “Would limit”; retain the actual applicability conditions, residual effects and distinction between blocking a capability and stopping traffic. Avoid repeated “not implemented” badges.
12
+
13
+ Leave room for region headings, component roles and connector captions in the geometry. Keep node titles and subtitles short and size their boxes for the full rendered text; place qualifications in descriptions and evidence. Prefer direct straight connectors or simple right-angle routes with few bends. Minor connector-to-connector crossings are acceptable when endpoints remain clear; do not chase zero crossings with acute angles, zigzags, stair steps or long perimeter detours. A crossing does not imply a junction or handoff. Keep connectors out of unrelated node boxes and label text, and repack components when avoiding them would require an awkward route. Preserve actual destination ports and a useful final straight segment for arrowheads; avoid a tiny terminal bend. Use a nearby slot above or below a short connector gap instead of fitting text between component boxes.
14
+
15
+ The shell measures SVG text, wraps complete captions and tries bounded nearby positions, reserving component boxes, other captions and connector junctions. Opaque control cards must also clear highlighted route interiors, arrowheads and junctions, including arrival and the path before a stop; inactive architecture lines remain a placement preference. Caption placement prefers to avoid unrelated connectors; a short text halo may cross an ordinary connector stroke when nearby space is constrained. This differs from actual text/component overlap, and never permits an opaque card to cover the route. Active captions get space before context captions; a displaced caption stays associated with its own connector or region boundary. It does not reroute relationships, remove text or reduce the font to conceal a collision. Only connections sharing the same destination and final approach share an arrowhead.
16
+
17
+ Inspect actual overview and selected states at desktop widths; mobile usability is a bonus. Favor easy-to-follow connectors over eliminating every crossing. Resolve label collisions, preserve clear stopping markers and readable titles, and repack unused space. A successful build, zoom control or clear layout diagnostic does not prove legibility or correct endpoints. Treat unresolved `#map[data-layout-status="unresolved"]` / `data-layout-issues` entries, text/component overlap and obscured arrowheads as QA failures to resolve before publishing, using better authored spacing when bounded placement is insufficient. A minor connector crossing alone is not a failure. Check component text containment and any conditional stop and its restored state; leave unsupported responses, sequence and deployment behavior unknown.
18
+
19
+ [Overview](../assets/context-reference-overview.svg) and [selected path](../assets/context-reference-path.svg) illustrate the workbench hierarchy, not a required topology or evidence.
20
+
21
+ Open either reference in an SVG-capable viewer. For a PNG-only viewer, use a local SVG renderer. For example, from the skill directory, run `rsvg-convert assets/context-reference-overview.svg -o /path/to/workspace/overview.png`. Use `assets/context-reference-path.svg` for the selected path.
@@ -0,0 +1,49 @@
1
+ # Explorer view-model contract
2
+
3
+ The model author maps the supplied assessment to JSON, exact evidence and explicit geometry. The shell owns visual roles, selection, inspection, control previews and offline HTML/SVG export. The builder validates references, geometry, exact quotes and some control semantics; it cannot verify security claims or layout.
4
+
5
+ ```sh
6
+ python3.12 <skill-directory>/scripts/build_explorer.py MODEL.json --assessment threat-model.md --output index.html
7
+ ```
8
+
9
+ Use Python 3.12+. Keep the full assessment intact. Optional fields need not be filled solely for completeness.
10
+
11
+ ## Map
12
+
13
+ Top-level `brand`, `title`, `subtitle`, `snapshotLabel`, `mapTitle`, `mapDescription`, `overviewTitle`, `overview`, `evidenceBoundary`, `footer`, and optional `scenarioLabel`, `exportNote` are display text. `canvas:{width,height}` uses positive finite units. `nodes`, `edges`, `scenarios`, and `evidence` are arrays with unique nonempty IDs; `regions` is optional. Optional `metadata` must be an array of objects with string `label` and `value`, for example `[{"label":"Fidelity","value":"standard"}]`; omit it or use `[]` if unnecessary. It is not a key-value object. `assessmentSha256` optionally pins the exact bytes of the supplied UTF-8 assessment, including its original line endings; the builder preserves them without normalization.
14
+
15
+ A node `{id,x,y,w,h,title,subtitle,description,evidence:[id]}` uses top-left geometry; `kind` may be `actor`, `asset` or `component`. A region `{id,x,y,w,h,title}` asserts a shared source-supported boundary. An edge `{id,from,to,points:[[x,y],...],label,labelX,labelY}` uses explicit directed geometry; `conditional:true` draws a dashed conditional relationship. Give nodes and lines concise labels, keep shared node captions valid across scenarios, and put detail in descriptions and evidence. Do not conflate meaningful authority boundaries or draw a direct edge merely to omit transit.
16
+
17
+ Optional `overviewEdges:[edgeId,...]` defines the persistent architecture backbone: the overview shows these authored edges, and selecting a scenario retains them in muted colors while adding its selected route or affected relationships, ordered steps, and selected control or stopping barrier. **More connections** reveals additional authored edges; the selection is preserved in the URL and SVG. `[]` is valid only when the source supports no architectural connections; do not use it to hide a known backbone. Omit the field for legacy all-edge display. It only filters visibility; it does not create edges, alter source claims, or suppress a selected stop. Nodes remain available for inspection. Compose an intelligible architecture; a toggle cannot restore components or relationships absent from the model.
18
+
19
+ Measure actual default-fit text and connector readability at desktop sizes. With diagram area W × H, the scale is `min(W/canvas.width, H/canvas.height)`; shell node titles, subtitles and connector labels are 17, 14 and 13 units. Aim for core text around 11 CSS px or larger. Check marker placement as well. Reserve space for measured role/title/subtitle rows and boundary headings. Put labels near a useful segment with room above or below it, and author clear destination ports with a straight terminal leg (roughly 14 units or more for a full-size arrowhead). The renderer can wrap and move captions within bounded nearby slots and share a head on an identical incoming stem. Validation alone cannot make a crowded topology legible. Full text and authored endpoints remain intact. Browser QA must resolve text/component overlap, obscured arrowheads and `data-layout-issues` failures before publishing; minor connector crossings are acceptable under the presentation guidance.
20
+
21
+ ## Scenarios and routes
22
+
23
+ A scenario is `{id,title,priority,status,summary,prerequisites,impact,calibration,evidence:[id],steps:[...]}`. Put the key prerequisite and potential impact in `summary`; use `prerequisites`, `impact` and evidence for fuller qualifications. `priority` is review priority; optional `severity` is a source rating, not inferred. `status` preserves the source's confidence. Each ordered step `{title,description,from,to,edge}` must match the directed edge. Keep order only when supported. Distinguish independent actor actions, separately triggered phases and parallel prerequisites without inventing a continuous causal traversal. Use `steps:[]`, optional `affectedNodes` / `affectedEdges`, and `pathNote` for unordered relationships; no traversal is implied. Supply `focusNodes` as source-supported failure sites, or `[]` when no site is established. Transit gets normal outlines, not a finding.
24
+
25
+ For a documented path, `routes:[{id,label,edges:[edgeId],evidence:[id],branches:[...]}]` selects an explicit continuous directed chain without repeated edges. Each scenario step must appear on every alternative route in order. Branches `{edges:[edgeId],evidence:[id]}` are connected chains beginning on the main route or an earlier branch. Draw secondary calls or returns only when useful to understand this path or its control; describe others in inspection. A route alone does not prove an exploit sequence.
26
+
27
+ If an evidenced branch happens after earlier steps but before a decision, `beforeStep` gives the one-based decision step; its origin must lie on the route at or before that decision. It stays visible at that decision, including a stop, but not behind an earlier barrier. If it starts at the destination of a stopping decision, evidence must support receipt and the effect needs `arrival:true`. A branch dependent on a later action uses `afterStep` and becomes visible only after that action succeeds and its origin is reachable. The annotations are mutually exclusive. Without either, the renderer uses node reachability, not occurrence order. Do not use `beforeStep` for a response after denial; do not infer a response or timing missing from evidence.
28
+
29
+ ## Sources and controls
30
+
31
+ Optional scenario `sources` entries are `{id,node,kind,basis,label,description,authority,evidence:[id]}`. `node` is the actual actor or controlled input, or `null` if unmapped. For a caller, use the caller’s node rather than the receiving service; represent their supported relationship separately. `kind` is `adversary`, `compromised-component`, `untrusted-input`, or `unknown`; `basis` is `scenario-assumption`, `assessment-observed`, or `unknown`. Preserve the actual least authority; an origin may be a recipient, not the initiator. Use `assessment-observed` only for an observed foothold; a hypothetical capability is `scenario-assumption`. Optional `routeIds` restricts a source to listed scenario routes. Multiple sources need `sourceMode:"alternatives"` or `"combined"`. Use combined only when the sources eligible for the selected route are jointly required. Use optional `sourceNote` to explain gaps.
32
+
33
+ Trusted operators and their configuration are not threat sources merely because they can change settings. Represent an authorized operator as a top-level `participants` entry with `kind:"authorized-user"`; omit `sources` or use `[]` when no threat foothold is established. Check each source node, kind and basis against its authority and evidence, including whether compromise is assumed or observed.
34
+
35
+ For alternative sources with no routes and `steps:[]`, optional `relatedNodes` / `relatedEdges` override each corresponding affected set independently; `[]` clears it, omission inherits it. Preserve independently sufficient authorities for each operation. Shared nodes and edges must be valid for every alternative that uses them. An unordered union may retain alternative-specific relationships when their membership is explicit; disclose it in `pathNote` or use source-specific overrides. An account-session-only path cannot represent capability-only access merely because prose says “otherwise authorized.” Optional top-level `participants` entries `{id,node,kind:"authorized-user",label,description,evidence:[id]}` require an actor node. The fixed palette and normal transit outlines are not evidence of security or reachability.
36
+
37
+ Scenario `controls` entries are `{id,kind,title,description,nodes:[id],edges:[id],evidence:[id]}` with `kind` set to `existing` or `proposed`. `nodes` marks enforcing owners even for descriptive controls; it is not a list of protected or constrained components. For an unmapped enforcer, use `nodes:[]`, disclose the owner gap, and describe the affected component/operation through `description` and supported `edges`. Runtime, syscall, mount and token-mount restrictions must not mark the application process as enforcer merely because it is constrained. Split these from code-owned checks and separate controls with different owners or operations. Optional nonempty `sourceIds` and `routeIds` scope it to their intersection; `sourceIds` requires alternative sources. Without an `effect` the control is descriptive and does not stop a route.
38
+
39
+ Optional `effect` contains `outcome`, `basis`, `label`, `reason`, `conditions`, `residual`, and control evidence. If an effect names an `edge`, it must occur on the main chain or a branch of each applicable route. Use `routeIds` or `sourceIds` when the operation applies to a subset. Outcomes: `blocks` prevents the named abuse under those conditions; `limits` requires both a reduced attacker capability and a supported route to the same abuse remaining; `detects` detects without prevention; `does-not-block` leaves the selected abuse unaffected; `unknown` is unestablished. Unrelated risks and authorized traffic do not establish continued abuse. Basis is `declared`, `verified`, `hypothetical`, or `unverified`; proposals require `hypothetical`, and unverified effects cannot block. A supported hypothetical effect does not establish live enforcement.
40
+
41
+ For a `blocks` effect, `traffic:"stops"` is the default; it requires one-based `step`, the matching `edge`, and a marker. Optional `arrival:true` keeps the incoming edge and decision owner reached only when evidence supports receipt; subsequent work stops. `traffic:"continues"` means the named harm is prevented while the displayed ordinary flow continues, not that the abuse continues. Use neutral transport labels and put modified content in the effect; a step is not required. Never claim an unknown rejection response. Independently occurring first and later traversals need distinct edges.
42
+
43
+ A marker `{at,x,y,w}` supplies the label's initial placement; `0 < at < 1`, width at least 180, and an initial 72-unit-high reservation must fit the canvas. The renderer measures the heading and full label and may wrap, resize or move the card to a nearby clear slot without changing font sizes. The marker remains attached to its authored edge location. Stopping effects mark the edge or arrival owner; continuing and nonblocking effects use a hollow ring. Check rendered caption, marker, selected path, conditions and residual against the same source and actor. Selecting an existing control inspects it; selecting a proposal toggles its preview. Existing controls remain active on restoration. Use the first traffic-stopping barrier along the route. Within one step, a barrier that prevents receipt acts before a check made after arrival. Prefer an existing control when both act at the same point.
44
+
45
+ ## Evidence and exports
46
+
47
+ Evidence `{id,label,quote,paths:[string]}` may include paired one-based `startLine,endLine`. The quote must be an exact assessment substring within the stated lines and include each listed path. Use a substantive row or passage that supports the attached claim and qualifications; file paths are assessment references, not inspected code. Unreferenced evidence is not inspectable.
48
+
49
+ Optional deep-link keys are `scenario`, `route`, `source`, `step`, `node`, `control`, `preview`, `panel=controls`, and `context=1` for expanded context. HTML embeds the model, assessment and all assets; SVG exports the displayed map, role key, control and source status. Check selected and restored views and export; no output verifies deployment or exploitation.