Explorer view-model contract
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.
python3.12 <skill-directory>/scripts/build_explorer.py MODEL.json --assessment threat-model.md --output index.htmlUse Python 3.12+. Keep the full assessment intact. Optional fields need not be filled solely for completeness.
Map
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.
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.
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.
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.
Scenarios and routes
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.
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.
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.
Sources and controls
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.
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.
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.
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.
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.
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.
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.
Evidence and exports
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.
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.