threat-model-visualize

# Threat Model Visualize Create a standalone explorer that shows application teams and leadership what can go wrong, how it could happen, why it matters, and where controls would stop or limit it. Use the shared workbench and role palette; do not use Mermaid or run a new scan. A request such as “Visualize the threat model generated in the last scan of X” is sufficient. Resolve the target, latest assessment and snapshot. If the latest artifact is missing, disclose that before using an older fallback. The default input is the existing threat-model artifact, not an automatic import of a complete scan. Keep inputs immutable and do not silently combine snapshots. Do not inspect application code or invent topology, authority, controls, reachability or validation. Capture source-supported deployment context: exposure, trust, tenant and process boundaries, identities, and conditional deployment assumptions. Do not treat repository defaults as proof of deployed configuration. Preserve uncertainty and the distinction between hypotheses, findings, declared controls and observed enforcement. For several explicitly supplied artifacts, pass one derived document to `--assessment`. Label verbatim excerpts with each source’s identity, snapshot and original finding status. Distinguish findings from hypotheses, identify local IDs, and preserve conflicting accounts and the original artifacts. For a **fresh candidate or regeneration**, author a new view model; do not patch or copy a previous candidate model or HTML. Ordinary edits may reuse the existing model. Renderer-only polishing is a display update, not fresh generation. ## 1. Enumerate and validate the source Complete this phase before planning any visualization, choosing display groupings or routes, assigning geometry, or authoring the explorer JSON. Save `source-inventory.md` in the workspace. Validate fidelity to the supplied assessment, not the application implementation; do not run a new assessment to fill gaps. Record the assessment identity, exact file hash and scope. Give inventory rows semantic IDs and supporting source spans or exact quotations, without assigning visual node or edge IDs. Enumerate: - **Components and roles:** actors, inputs, application components, stores, external dependencies, trust boundaries, platform-specific instances and administrative contexts. Distinguish trusted operators, assumed compromise, controlled input, owned assets and enforcing components. - **Relationships and capabilities:** each supported caller → operation → receiver relationship, meaningful return, independently sufficient authority or entry condition, prerequisites and platform/deployment conditions. Enumerate alternatives per operation: an account session and an issued capability may each authorize the same operation. Preserve known logical capabilities when transport or order is unknown; do not import a prerequisite from another entry point. - **Controls and qualifications:** each protective mechanism → enforcing owner → constrained component → protected operation, with conditions and evidence. Record an unmapped enforcer explicitly; configuring or being subject to a restriction does not establish enforcement ownership. Classify existing mechanisms, proposals, security objectives, configuration behavior and caveats separately. Ownership, expanded permissions, disabled protection or documentation advice alone is not an existing safeguard. - **Threat-model coverage:** substantive threats, supplied findings, hypotheses and consequential configurations, linked to the relevant components, relationships and controls. Retain source confidence, potential impact and unresolved questions. Review the inventory against the complete assessment before proceeding. Check that evidence supports the same object, caller, operation and owner; distinguish configuration delivery from protected operations and assets from their managers. Do not transfer a validation rule between different inputs or infer platform endpoints from a group label. Account for every substantive source concern; reconcile aliases and record contradictions without inventing a resolution. Correct unsupported assertions, misclassified controls and unexplained omissions now. Finish the inventory with source-reconciliation corrections and unresolved source gaps. Keep later model-repair notes and review verdicts in `correctness-review.md`, not this source inventory. It is ready for composition when its claims are supported or explicitly unknown and coverage has been reconciled. Source uncertainty may remain; it must not silently become a visual relationship or safeguard. Do not plan the visualization while performing this review. ## 2. Compose from the validated inventory Read the [view-model contract](references/view-model.md) and [presentation guidance](references/context-explorer.md), then build a source-backed JSON model and geometry. The shell supplies interaction, colors and exports. Default to **standard**: compose a readable architecture overview before adding threats. Show the actors and entry points, trust boundaries, application or library components, identity and authorization, stores, and external dependencies needed to explain the assessment. Include administrative, automation and build contexts when relevant. Connect them with meaningful request, data and authority relationships. Match platform relationships to the service endpoints named by the source; do not infer group membership or a UI handoff. Use grouping, clear boundaries, aligned flows and short labels while preserving distinctions that change a threat or control. Do not collapse the whole system into one threat's pipeline or move substantive sources and control owners off-map merely for sparsity. Keep the primary architecture visible in muted colors when a threat is selected. Emphasize its complete source-supported route, including proxies, other transit components, handoffs and meaningful returns. Highlight active transit with fill while retaining its neutral outline; transit alone is not a weakness. Distinguish conditional transitions from ordinary flows. A partial or unmapped view needs an evidence-based scope explanation. Secondary connections may appear under **More connections**, but the basic architecture must stand on its own. Use the validated inventory as the coverage ledger. Map each substantive operation and its supported authority alternatives to selectable relationships and controls, or an explicit source-supported scope exclusion. Showing an actor in another threat does not cover its access to this 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. Prose such as “otherwise authorized” cannot broaden an account-only path. An embedded quotation is not selectable coverage. Label a user-requested subset incomplete. Optional authoring fidelity is `simple` for a more grouped summary, `standard` by default, or `detailed` for useful secondary connections and facets; it does not change claims or require a UI selector. Bind each case's mechanism, priority, prerequisites, impact and evidence to its own substantive source section. Verify that each quotation matches and supports the same object, operation and enforcing owner as the claim. Do not turn ambiguous source language into a more specific existing safeguard. Do not invent a sequence, authority gain or successful transition. Where order is unsupported, show related components with an explicit scope note. Model the actual starting actor or input and least required authority. Trusted operator or administrator activity remains authorized context, even when it changes configuration or consumes resources; make it a threat source only when the assessment explicitly models its abuse or compromise. An added assumption of malicious intent is not source evidence. Classify a caller-controlled value as untrusted input only when the source supports that trust boundary. Keep alternative footholds distinct and scope each selection to its relevant relationships and controls, with other architecture muted. Expose consequential supplied controls and proposals at their actual operations and enforcing owners. Split controls with different owners, operations or effects, including deployment reachability and protocol authentication. If an enforcing owner is unmapped, disclose the gap rather than assigning the control to its recipient. Label proposals **Proposed control** and their effects conditionally as “Would block” or “Would limit.” Show where and why a control acts, its conditions and residual effect; mark the effect unknown when it is not established. Preserve arrival at the decision owner where required; blocking a sensitive result does not necessarily stop ordinary traffic. Do not present a proposal as deployed or validated. ## 3. Adversarial correctness review Finish this review before starting a preview server, opening the explorer in a browser or testing exports. Static build and structural validation may run while review is pending; browser work may not. Try to disprove the saved JSON's claims, not confirm the author's intent. Use a fresh-context reviewer when delegation is available: explicitly disable history inheritance (`fork_turns: "none"` for `spawn_agent`) and send the review task and artifact paths, without the author's conclusions or screenshots. Omitting the history option can inherit the author's work. Wait for that review and its fix verification. Use a separate self-review only if delegation is unavailable or an attempted delegation fails; record the concrete reason and independence limit. Pending review is not grounds for that fallback. Do not inspect application code or perform a new assessment. Have the reviewer read the complete assessment and view-model contract first, retrieving any portions omitted by truncated tool output, and save a compact set of source-derived obligations in `correctness-review.md` before inspecting the inventory or JSON. Include explicitly trusted roles, authorized operations and scope exclusions alongside substantive concerns, least starting authority, supported operation and result/recipient/asset consequence, deployment conditions, and controls with their enforcing owners. Then compare the inventory and actual JSON with those obligations. Neither a validated inventory nor the author's coverage ledger is proof that the JSON preserves the source. Resolve each distinct source/route selection's effective highlighted relationships and applicable controls, including inherited defaults, overrides, grouped members, branches and control effects. Record the source span, starting authority, effective node/edge IDs, operation and consequence, control owners, and any discrepancy in the review. Equivalent selections may share a row if their equivalence and differences are explicit. Check the resolved IDs against their definitions, not only scenario prose: an override can remove a consequence, a source can impose an unnecessary prerequisite, and an owner marker can contradict an unmapped-owner note. Challenge these concrete failure modes: - **Authority and prerequisites:** For each source-supported operation, match every independently sufficient authority or entry condition to an effective selection or justified exclusion. Compare node and edge captions as well as source prose: does a credential become process compromise, or a capability become an account-session requirement? Does a threat source contradict an explicitly trusted role or authorized operation? Is an actor mislabeled as an input, or trusted configuration as hostile? Do not require directory mutation for every file-permission concern. - **Control ownership and operation:** For every control, including descriptive controls without effects, record the enforcer, constrained component, protected operation and the `control.nodes` owner markers. Identify who applies or evaluates the restriction, not who carries its configuration or is subject to it. Runtime restrictions, syscall filtering, mount permissions and token mounting are not application-owned checks merely because they constrain that process. A service's read-only mount does not constrain an independent writer. Split code-owned checks from deployment/runtime restrictions; leave owner markers empty when the actual enforcer is unmapped. Verify each marker against its node definition and evidence. - **Effects and reachability:** Check every asserted outcome, condition and residual against the same named abuse. Ordinary traffic or unrelated residual risks do not establish that the abuse is only limited. For each blocking preview, derive the reached nodes and branches from the actual `step`, `edge`, `arrival` and traffic behavior. Does denying access still show the protected result reached? Preserve arrival at an evidenced decision owner without carrying arrival across a later protected transition. Descriptive or unknown effects must not become barriers. - **Evidence and classification:** Read the cited passage for each substantive claim, including scenario fields and control owners. An exact quotation can come from the wrong row or support only part of the claim. Recheck aliases and parsed-table bindings. Distinguish existing mechanisms, proposals, expected objectives and caveats; authority alone or a disabled protection does not establish a safeguard. - **Selection and coverage:** Check global overview and scope claims as well as selections. Preserve each alternative in source eligibility or reportability conditions; do not narrow "A or B" to "B" or add a prerequisite. Starting from the source concerns and inventory, find capabilities, independent entry points, control conditions or consequential configuration missing from selectable views. Conversely, challenge any highlighted relationship borrowed from unrelated context. Check that group membership and region geometry preserve the stated trust, process and deployment boundaries. Include the supported operation and impact context; do not stop a selection before its material consequence merely because an exploit sequence is unknown. Require a concrete claim or selection, JSON pointer, supporting source span and explanation of the mismatch for each finding. Separate required corrections from optional clarity improvements. Faithful grouping, source-supported exclusions, descriptive controls and explicit source uncertainty are valid; do not demand invented topology, actors, ordering or safeguards to make the diagram more specific. Correct supported findings in the JSON, not only in prose. The reviewer must reread the changed JSON and verify affected selections, including other selections sharing the changed objects or defaults. Before closing review, reconcile every source-derived obligation against the final effective selections; checking only the author's repair list is insufficient. New semantic claims must also pass the source-inventory review. The reviewer records a timestamped `PASS` or `REVISION REQUIRED` (including time zone) in `correctness-review.md`, with the assessment and current JSON hashes, method, selection checks, findings, verified corrections and unresolved limits. `PASS` means no required correction remains; optional improvements and faithfully represented source unknowns may remain. The author checks that the saved JSON hash matches this receipt before proceeding to browser QA. An author-written summary or a request to recheck is not reviewer closure. If required work remains, continue correcting it or deliver a clearly labeled draft with the outstanding findings and browser QA marked incomplete. After browser-driven JSON edits, repeat the affected source/selection checks and obtain an updated review receipt for the delivered hash. Preserve the initial pre-browser receipt alongside later rechecks so their order remains observable. Pure CSS changes need visual QA but do not invalidate an unchanged JSON hash. Report independent review, self-review and browser QA separately; none substitutes for the others. ## 4. Build and inspect the explorer Start browser QA only with the current JSON's `PASS` receipt from phase 3. ```sh python3.12 <skill-directory>/scripts/build_explorer.py <model.json> --assessment <threat-model.md> --output <explorer.html> ``` Choose browser tooling available and permitted in the current environment before starting a preview server. In standalone CLI/CI, check known runtime or dependency locations for an installed headless browser (such as Playwright with Chromium); do not assume a desktop browser host exists. Use that browser for interaction checks, screenshot inspection, offline loading and export verification when policy permits. A missing desktop host does not establish that every browser is unavailable; a policy denial does not authorize a workaround. If no permitted browser is available, deliver the local files and mark browser QA incomplete. Codex’s in-app browser automation does not support `file:` URLs. For browser QA there, use a local HTTP preview; do not try a file URL first. Other browsers may open the standalone HTML directly from disk. When HTTP is needed, bind your own server to `127.0.0.1` on an unused or OS-assigned port, serve only the output directory, and stop it after QA; do not assume another process on a familiar port serves these files. Review the builder’s connector warnings. After moving or resizing a node, align adjacent bends with its ports and check that each connector approaches the node from outside. Rebuild after correcting the authored points. Open the HTML in a browser and inspect the overview, selected scenarios and representative controls at desktop sizes. Check that the architecture, source, route, impact and control remain understandable in context. Inspect representative source and route alternatives and blocked and restored states where mapped. Check readable default-fit text, simple connector routing, text/component collisions, control markers, evidence, navigation, scope and residuals; repack rather than relying on zoom. Prefer minor connector crossings to convoluted detours. Verify offline loading and SVG export. The builder checks structure and exact quotations, not claim truth or visual clarity. Deliver standalone HTML locally by default. Create, update or publish a site only when the user explicitly requests site hosting or publication; a visualization or preview request alone is insufficient. Do not create a site for local or inline previews. For requested hosting, use the Sites workflow and preserve the requested audience. Use visualize integration for an inline preview. Static requests use an SVG or PNG of the same selected state.