# Model your agent on the Trust Canvas

> Draw the trust zones, tools and data of an agent, state what guards each edge, and let the engine find the boundaries, chains and chokepoints.

Source: https://keryn.dev/docs/guides/trust-canvas/

## Goal

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](https://keryn.dev/docs/reference/trust-canvas/).

## Before you start

- [Keryn Web](https://keryn.dev/docs/guides/web-app/) 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.

> **Leaves your machine**
> **Nothing.** The engine runs in the tab as WebAssembly. A model you draw or open is not uploaded. Saving or exporting writes a file on your machine.

The canvas is in Keryn Web at `#/trust`, from 0.5.0 on, at [keryn.app](https://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](https://keryn.dev/docs/start/install/) says which channels exist.

## 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](https://keryn.dev/docs/guides/workflows-and-binaries/) reads. See [start from a workflow export](#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](#start-from-a-repository). |
| An organisation | **Open on trust canvas** in the dashboard of a scanned [organisation or portfolio](https://keryn.dev/docs/guides/portfolio/#see-the-organisation-as-one-trust-graph): 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.

> **Note: Next release: workflow start panel**
> With no model to come back to, the canvas opens blank on a start panel, **Understand a workflow**: **Import workflow export**, three workflow samples (an n8n one and two Flowise ones) and links to a repository scan and an organisation scan. The drawn samples (the RAG support copilot and the work-item copilot) are still in the **Samples** menu of the top bar, labelled "Drawn".

### 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.

> **Note: Next release: import fidelity and economics**
> An imported workflow shows a bar under the header, `<platform> import`, with the node and connection counts and **Import fidelity & economics**. Open it for two panels:
>
> - **What survived the import**: the nodes and connections the file declares against those imported. A difference becomes a warning that says to inspect the importer's warnings before relying on the graph. Nodes it could not classify are listed (their wiring is kept), and so are tools whose permissions the export does not establish. For n8n it resolves named connections to node ids and keeps the output and input indexes; for Flowise it resolves node ids and keeps the source and target handles. Parallel edges and cycles are kept, and a connection is labelled with its name where the export has one. The wiring is explicit; authority and node classification can be inferred, and a resource attachment describes configuration, not measured calls.
> - **Execution scenario**: what running the workflow costs, from assumptions you provide. Topology cannot supply how often a node runs, token counts or prices, so the panel starts with none: **Export cost assumptions** writes a template (`keryn.dev/workflow-economics/v1`, one entry per source path, with `executionsPerRun` and `costPerExecution` left empty), and **Import cost assumptions** reads it back. With values, the panel shows visits and cost per node, the cost per run and per month, and says when the total is partial because some nodes have no cost. The three workflow samples carry illustrative assumptions and say so.
>
> This is execution spend. It is not the cost of fixing risks, which is [Plan fixes](#plan-fixes).

## 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.

> **Leaves your machine**
> **Nothing.** The graph is built in the tab (or by the CLI), from what was scanned. Nothing is uploaded.

![The Trust Canvas after "Open on trust canvas" on a scanned repository: a User prompt entry, an agent, the OpenAI provider and an unpinned MCP server, joined by dashed edges because each is inferred rather than read from the code.](https://keryn.dev/screens/trust-canvas-scan-1280-light.webp)

*A scanned repository opened on the trust map. Every edge is dashed because the scan inferred it; the labels mark where to fix, and Findings lists the engine's risks. Taken from keryn.app main-DIcUUbkq.js.*

> **Note: Next release: switching scan graphs**
> With a scan or an organisation in the browser, the canvas shows a bar named "Also available from scans" with a button for the repository (by its subject), one for the organisation (`<name> · organization`), **Scan repository** and **Previous graph**, so you can switch the canvas to a scan's graph without going back to the results. The header's **Trust** link opens the organisation's graph when you come from an organisation.

In the CLI:

```sh
keryn trust-graph . --analyze --out trust/graph.json
```

Inspect the graph format and check that the analysis file was written:

```sh
jq -r '.kind + " " + .schemaVersion' trust/graph.json
test -s trust/graph.analysis.json
```

```text
threat_model_graph 0.1.0
```

`keryn 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](https://keryn.dev/docs/journeys/trust-canvas/#3-derive-the-graph-from-the-scan) runs it on a real repository.

> **Note: Next release: bundled CLI analysis**
> The built CLI now carries the trust-model engine. Until then, `--analyze` worked in a source checkout and failed in a built CLI, because the engine's file was looked up by a path that no longer exists once the CLI is bundled.

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

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](#the-model-as-a-file).

### 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](https://keryn.dev/docs/reference/trust-canvas/#trust-levels-and-zones) 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

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

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.

Diagram: refund tool writes billing database, across a trust boundary. Into a more trusted zone: an inbound boundary.

### 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

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.

Chain: Customer sends (across a trust boundary), POST /chat sends (chokepoint), Support agent calls, issue_refund writes (across a trust boundary), Billing database. One of the three chains. The first and last edges cross a trust boundary. The second edge is the top chokepoint: all three chains pass through it.

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

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](https://keryn.dev/docs/reference/trust-canvas/#chains) explains how those records affect reachability.

### 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 Trust Canvas on the Blast radius lens, started from the trip agent: only the elements the agent can reach within two hops are drawn at full strength, and the banner above the graph says what the lens shows.](https://keryn.dev/screens/trust-canvas-lens-1280-light.webp)

*The Blast radius lens, started from the trip agent of the journey: what it can reach within two hops. Taken from keryn.app main-DIcUUbkq.js.*

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

**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

> **Note: Next release: plan fixes**
> **Plan fixes** is in the top bar, beside the lens switch. It opens the **Economics** tab of the drawer (the drawer's tabs are **Findings**, **Economics** and **Forge**) and answers a different question from the findings: given a limited number of engineer-days, which guards should you build first?
>
> The graph supplies the candidates. Each unguarded chain has a part where a guard can break it (from where the model starts driving actions, as in [Chains](https://keryn.dev/docs/reference/trust-canvas/#chains)), and every edge in that part becomes a proposed guard, titled `Guard <source> → <target>` and counting the chains it would break. A control in front of the model gets no credit for chains behind it. Chains that share an edge are counted once, and fixing a finding that happens to sit in the same file is never assumed to break a chain.
>
> 1. Enter a **Capacity (engineer-days)**, a **Cost per engineer-day** and a **Currency**. If the graph came from a scan that has a remediation estimate (**Scan results → Remediation economics**), its currency, day rate, capacity and optional business scenario are the starting values.
> 2. Enter a **Minimum days** and **Maximum days** for the guards you can estimate. **Find a proposed guard** narrows the list. A guard with no estimate is never free: its chains stay in the remaining set.
> 3. Optionally tick **Include a scenario** under **Optional business scenario** and enter **Loss per incident**, **Successful incidents/year**, **Delay (days)** and **Fraction avoided**. These are your assumptions. Chain counts do not say how often an incident happens or what it costs.
> 4. **Calculate plan**. The plan fits each selected guard's maximum estimate into the capacity and picks, one at a time, the guard that covers the most additional chains per maximum day. That is a greedy plan, not an optimal allocation and not a risk ranking. It reports the proposed fixes, the days and cost, how many guards still need estimates and, with a scenario, the assumed annual loss, the cost of delay, the annual benefit and the payback.
>
> Click a proposed guard to highlight the chains that pass through it and select its edge. **Covered** and **Remaining** draw the chains the plan would break and those it would not, and **Clear highlight** removes the marks. Calculating changes nothing in the model: coverage is proposed, assumes each guard is implemented effectively, and is not a deployed fix or a measured reduction in risk. The **Coverage and assumptions** line under the heading says how many chains were planned over, how many include inferred links or links without provenance, and whether the search was truncated.
>
> **Save graph plan** downloads one JSON file (`keryn.dev/graph-plan/v1`) with the graph, its analysis, your estimates and the receipt. Open it later with the top bar's **Open** and the canvas restores the graph and the plan, ready to recalculate. **Load estimates** updates the current graph only. Moving elements does not reset the plan; any other change to the model does. Estimates are held in the tab, so save the plan before you leave.

> **Note: Next release: Forge query results**
> The **Forge** tab of the drawer shows the result of a Forge query (a `keryn.dev/ksql-result/v1` file) beside the graph: for each hypothesis, the path from source to sink with its tier and basis. A flow that could not be decided is drawn dashed and marked unknown and is never merged into the "no flow" rows. You pick or drop the files; nothing is uploaded. This is an early view.

## 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`.

```json
{
  "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

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](https://keryn.dev/docs/edges/agentic-triage/) never replaces your decision.

## 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.

## Next

- Read a chain in a scan, hop by hop: [read an attack chain](https://keryn.dev/docs/guides/attack-chain/).
- Import an export: [agent workflows](https://keryn.dev/docs/guides/workflows-and-binaries/).
- Vocabulary and the eight verbs: [Trust Canvas reference](https://keryn.dev/docs/reference/trust-canvas/).
