Model your agent on the Trust Canvas
The Trust Canvas is where you draw what can reach what in your system and see which edges an attacker can chain. It is a graph of trust zones, elements and edges, which you draw, open from a workflow export, or derive from a scan of a repository. An engine finds the trust boundaries, the chains from untrusted input to a consequence, and the chokepoints where one guard would break the most of them, and it runs again after every edit. The vocabulary and the arithmetic are on the Trust Canvas reference.
Before you start
Section titled “Before you start”- Keryn Web in a build that has the canvas (
#/trust, the Trust link in the header). - Optionally a workflow export or a model file to open, a scan result to open on the canvas, or the CLI to derive a graph from a repository; or start blank.
The canvas is in Keryn Web at #/trust, from 0.5.0 on, at keryn.app. Keryn 0.5.0 was released as the keryn.app and keryn.dev sites only, and so were 0.5.1 and 0.5.2, so keryn trust-graph is in the CLI built from that source and not yet in an installable binary; the install page says which channels exist.
Start from something
Section titled “Start from something”| Start | How |
|---|---|
| A blank model | Four zones to draw in: untrusted input, agent runtime, data, external services. |
| A sample | A RAG support copilot, or a work-item copilot for Jira and Confluence. |
| A workflow export | n8n, Flowise, Langflow, Dify, Make, Zapier, Copilot Studio, Node-RED, GitHub Actions and the other formats the workflow analyser reads. See start from a workflow export. |
| A repository scan | In Keryn Web, Open on trust canvas in a repository’s results. From the command line, keryn trust-graph. See start from a repository. |
| An organisation | Open on trust canvas in the dashboard of a scanned organisation or portfolio: one zone per repository, with providers and MCP servers shared. |
| A saved model | A threat_model_graph file. Files from the earlier threat-canvas prototypes open unchanged, and fields the canvas does not know are kept when it writes the file back. |
A model says how each element is known: read from a structured source such as a workflow export or a syntax tree, inferred by a heuristic, or stated by a person. Inferred edges are drawn dashed and count as weak; an edge that crosses a trust boundary carries a shield mark and a chokepoint is drawn thick. The canvas opens on the model you last had open, or on the RAG sample the first time, and on the Unguarded chains lens when the model has chains with nothing on them. The Legend in the corner explains every mark.
Start from a workflow export
Section titled “Start from a workflow export”Open an n8n or Flowise export (the folder icon in the top bar, or drop the file on the canvas) and the canvas draws its nodes and connections. Everything stays in the tab.
Start from a repository
Section titled “Start from a repository”You do not have to draw the graph first. A scan already knows a good deal about an agent, and Keryn turns that into a model you can open, correct and keep.
| In the repository | On the canvas |
|---|---|
| A public HTTP route that reaches a model | The route, with an internet user in front of it. A chat app with no route (Streamlit, Gradio and similar) gets an untrusted “User prompt” entry that names the framework. |
| Each LLM call site | An agent element, with the model providers behind it. The SDK, the AI-BOM and the API host names merge into one provider node. |
| Tools the agent can call | A tool element with its authority (read, suggest, queue or execute). A tool that writes, sends, runs code or pays with nothing in its source that names an approval step is execute; one with such a step is queue. |
| MCP servers named in configuration | A server element, pinned or not, with its command but never its arguments or environment. |
| Secrets found in code | A secret element by kind, with file and line, never the value. |
| Prompt files, and data stores from the AI-BOM or from code | Prompt and data elements, read by the call sites near them. |
| Scan findings | Counts and rule ids on the element they sit in, never snippets. |
Every element and edge says how it is known. structured means it was read from a syntax tree or a config file. inferred means a heuristic produced it, for example tools chained because the model may call any of them after any other, or a store linked to a call site by directory. The canvas draws inferred edges dashed, and a path through one costs more when the engine searches for paths. When two sources find the same edge it is kept once, with both sources as corroboration. The output is deterministic and capped at 250 elements, keeping the riskiest, and the document records what it cut. For an organisation, each repository gets its own zone and providers and MCP servers are shared, so reliance on one provider across repositories shows.


In the CLI:
keryn trust-graph . --analyze --out trust/graph.jsonInspect the graph format and check that the analysis file was written:
jq -r '.kind + " " + .schemaVersion' trust/graph.jsontest -s trust/graph.analysis.jsonthreat_model_graph 0.1.0keryn trust-graph [path] scans the directory like keryn scan (the full rule library, no Deep), derives the graph and writes it as a threat_model_graph file to standard output or to --out. --analyze lays the graph out and runs the engine on it, writing the analysis next to the graph as <name>.analysis.json. --envelope writes a keryn-export/1 file holding the graph, and the analysis with --analyze, in place of the bare graph. The scan flags apply. It is not keryn trust, which is the website Trust Scanner. The journey runs it on a real repository.
What a derived graph does not know is the same as what a scan does not know. It sees what the code and configuration say, not who your users are or what a tool’s effect is worth. Correct it on the canvas, then save it.
Model an agent, step by step
Section titled “Model an agent, step by step”The example is a support agent that answers customers, calls a refund tool and can send email. Each step changes what the engine reports. The numbers below come from the engine itself, run on the model in the file at the end.
1. Draw the zones and set their levels
Section titled “1. Draw the zones and set their levels”A zone is a group with a trust level, which you can change in the zone’s panel. A zone you have not set takes the default for its kind: public is untrusted, application, AI processing and agent tools are trusted internal, external providers are external provider and the data platform is trusted data (the reference lists them and the levels you can choose). Authority changes where an edge leaves one zone for another, or joins elements at different levels. For the example: the public internet (untrusted), the agent runtime (trusted internal), the data (trusted data) and external services (external provider).
2. Add the elements
Section titled “2. Add the elements”Add the customer, the chat route, the agent, its refund tool, the billing database, the model provider and the email service, each inside the zone it lives in. Say what a tool can do with its tool authority: none, read, suggest, draft, queue or execute.
3. Connect them with a verb
Section titled “3. Connect them with a verb”An edge says what its source does to its target: reaches, calls, reads, writes, sends, grants, depends on or trusts. Pick the most specific verb. The customer sends a message to the route; the agent calls the refund tool; the tool writes to billing.
4. State what is true on each edge
Section titled “4. State what is true on each edge”For an edge, record whether user-controlled text rides on it, whether the model sees it, whether it changes state, and whether it needs approval. An edge that changes state, or whose tool authority is execute, is consequential: a chain ends on it. Add the controls that are in place and the evidence for them: a file, a review, a test.
5. Read the result
Section titled “5. Read the result”With only steps 1 to 4 drawn, the engine finds:
- 4 trust boundaries, none with a control or evidence;
- 3 chains from the customer to a consequential edge, all unguarded;
- 8 risks: 5 critical, 1 high, 2 medium.
The canvas opens on the Unguarded chains lens when a model has chains with nothing on them, which shows only these chains and what they touch. The findings drawer on the right (its toggle carries a count of what needs attention) lists Fix first: the edges whose guard would break the most chains, each with a sentence. Here it says guarding the edge from the route to the agent breaks 3 of 3 chains, and guarding the call to the refund tool breaks 2 of 3. A cut point, listed under it, is different: an element whose removal would split the graph into pieces. It is about connectivity, where a chokepoint is about unguarded chains. Click either to see what it names on the canvas. That is arithmetic about the graph. You decide which guard fits. A guard in front of the model, such as input validation, does not stop a prompt-injected tool call behind it, which is why the engine counts from where the model starts driving actions.
6. Add the guards you have, and watch the count
Section titled “6. Add the guards you have, and watch the count”Mark the refund call and the email send as needing approval (select the edge and tick Requires approval). The analysis reports that authorization is required and keeps those paths reachable. A path counts as blocked when an edge explicitly records PATH_BLOCKED.
Record authentication on the customer edge and prompt_isolation on the edge into the agent. Attach an evidence reference for the billing write, such as a review or a test. The edge panel records controls on each boundary. The guard status reference explains how those records affect reachability.
7. Look around
Section titled “7. Look around”| Question | Lens |
|---|---|
| Which edges cross a boundary? | Boundaries |
| What can this element affect? | Blast radius (depth 1 to 4) |
| What can affect this element? | Reachers |
| How does A reach B? | Path: select A, shift-click B. Up to five loopless paths, shortest first. |
| Which chains have nothing on them? | Unguarded chains |


The lens bar along the top switches between them, and the lens, the element it starts from and its depth are kept in the page address (#/trust?lens=chains&focus=<id>), so a view can be shared as a link.
- Focus mode. Double-click an element to draw only its neighbourhood, one or two hops, with a breadcrumb back to the whole graph.
- Search. The box in the bar finds an element by label, kind or id, and selects and centres it.
- Hover shows an element’s neighbours and dims the rest. Select an element or an edge and the drawer shows the inspector: what it reaches, what reaches it, the boundaries it crosses, the risks that name it, how it is known (structured, inferred or stated) and the file and line it was read from.
- Zoom is semantic. Zoomed out, the canvas draws regions and dots and only the edges that cross a boundary. Closer, it draws compact cards, then full cards, and edge labels at full zoom. Parallel edges between the same two elements merge into one marked
×n, and the markers that would overlap are thinned. Edges inside one zone are drawn quietly. - A large graph (more than 120 elements) opens on the neighbourhood of its top chokepoint, not as one tangle. A graph that does not fit readably opens on the heaviest window, weighted by entry points, fix-first edges, cut points and high risks, and snapped to whole zones.
8. Save, share, export
Section titled “8. Save, share, export”Save writes the model as a file. Export offers the model and the analysis as JSON, a keryn-export/1 file (the envelope every Keryn surface writes), Mermaid text, a Threat Dragon document where that writer is available, and the current view as SVG or PNG. The export carries no account and no credentials, and nothing is uploaded: you import the file into an account yourself, when you choose. A model whose saved positions overlap, or that was saved by an early prototype, is laid out again when you open it, and the canvas says so.
Plan fixes
Section titled “Plan fixes”The model as a file
Section titled “The model as a file”Positions are optional; the canvas lays out what has none. A zone may state its level in security.trustLevel; one that does not takes the default for its kind, which is what this model relies on. An edge may leave out relation, and the verb is then inferred from its kind.
{ "schemaVersion": "0.1.0", "id": "tm_support_agent", "kind": "threat_model_graph", "title": "Support agent", "groups": [ {"id": "public", "kind": "zone.public", "label": "Public internet", "bounds": {"x": 0, "y": 0, "width": 260, "height": 200}}, {"id": "runtime", "kind": "zone.application", "label": "Agent runtime", "bounds": {"x": 300, "y": 0, "width": 260, "height": 400}}, {"id": "data", "kind": "zone.data_platform", "label": "Data", "bounds": {"x": 600, "y": 0, "width": 260, "height": 200}}, {"id": "external", "kind": "zone.external_providers", "label": "External services", "bounds": {"x": 900, "y": 0, "width": 260, "height": 400}} ], "nodes": [ {"id": "customer", "type": "block", "kind": "actor.internet_user", "label": "Customer", "parentId": "public", "position": {"x": 20, "y": 40}}, {"id": "chat", "type": "block", "kind": "app.route", "label": "POST /chat", "parentId": "runtime", "position": {"x": 320, "y": 40}}, {"id": "agent", "type": "block", "kind": "agent.orchestrator", "label": "Support agent", "parentId": "runtime", "position": {"x": 320, "y": 160}}, {"id": "refund", "type": "block", "kind": "agent.tool", "label": "issue_refund", "parentId": "runtime", "position": {"x": 320, "y": 280}, "security": {"toolAuthority": "execute"}}, {"id": "billing", "type": "block", "kind": "data.relational_db", "label": "Billing database", "parentId": "data", "position": {"x": 620, "y": 40}}, {"id": "model", "type": "block", "kind": "ai.llm_provider", "label": "Model provider", "parentId": "external", "position": {"x": 920, "y": 40}}, {"id": "mail", "type": "block", "kind": "external.service", "label": "Email service", "parentId": "external", "position": {"x": 920, "y": 200}} ], "edges": [ {"id": "e1", "type": "flow", "kind": "flow.user_input", "relation": "sends", "source": {"nodeId": "customer"}, "target": {"nodeId": "chat"}, "security": {"userControlled": true}}, {"id": "e2", "type": "flow", "kind": "ai.prompt_payload", "relation": "sends", "source": {"nodeId": "chat"}, "target": {"nodeId": "agent"}, "security": {"modelVisible": true, "userControlled": true}}, {"id": "e3", "type": "flow", "kind": "ai.model_request", "relation": "calls", "source": {"nodeId": "agent"}, "target": {"nodeId": "model"}, "security": {"modelVisible": true}}, {"id": "e4", "type": "flow", "kind": "agent.tool_call", "relation": "calls", "source": {"nodeId": "agent"}, "target": {"nodeId": "refund"}, "security": {"stateChanging": true}}, {"id": "e5", "type": "flow", "kind": "flow.data_write", "relation": "writes", "source": {"nodeId": "refund"}, "target": {"nodeId": "billing"}, "security": {"stateChanging": true}}, {"id": "e6", "type": "flow", "kind": "flow.external_send", "relation": "sends", "source": {"nodeId": "agent"}, "target": {"nodeId": "mail"}, "security": {"stateChanging": true}} ], "risks": []}What the canvas does not do
Section titled “What the canvas does not do”It does not discover your system. A model derived from a scan is only as complete as the scan, a model imported from an export is only as complete as the export, and one you draw is only as true as you make it. A derived graph says which edges it inferred, and an inferred edge is a lead to confirm, not a fact. Chains are bounded, and the analysis says when a bound was hit. The engine does not know your business: whether a chain matters depends on what the consequence is worth, which is why every result shows the edges behind it and why a verdict from a model never replaces your decision.
What you just proved
Section titled “What you just proved”You turned “what can reach what” from a diagram on a whiteboard into a model the engine checks: the trust boundaries your edges cross, the chains from untrusted starts to consequential edges, and the chokepoints where one guard breaks the most chains. The result is only as true as the model, and it says which parts were read from a source, which were inferred and which you stated.
- Read a chain in a scan, hop by hop: read an attack chain.
- Import an export: agent workflows.
- Vocabulary and the eight verbs: Trust Canvas reference.