# Trust Canvas reference

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> The eight relationship verbs, trust levels, boundaries, chains, chokepoints, lenses and risk rules of the Trust Canvas, generated from the product.

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

This is the vocabulary and the arithmetic of the [Trust Canvas](https://keryn.dev/docs/guides/trust-canvas/). The tables are generated from the engine's own source, so a verb or a control the product adds appears here at the next refresh and the build fails if this page has no sentence for it. The engine is pure and deterministic: the same model gives the same analysis, element for element, so a re-run after an edit can be compared with the one before.

## Relationship verbs

Every edge says what its source does to its target with one of eight verbs. The wire form is snake case (`depends_on`). An edge states its verb in `relation`. When it does not, the verb is inferred from the edge's `kind`.

| Verb | Meaning | Inferred from these edge kinds |
|---|---|---|
| `reaches` | The source can affect the target, with no more specific verb. The default when an edge says nothing else. | any kind not listed for another verb |
| `calls` | The source invokes the target: a tool call, a model request, an MCP call, an authenticated API request. | `agent.tool_call`, `ai.model_request`, `flow.authenticated_request`, `flow.mcp_call`, `tool_call`, `control_flow` |
| `reads` | The source takes data from the target: a database or file read, a retrieval query, a secret being used. | `flow.data_read`, `flow.secret_use`, `ai.retrieval_query`, `retrieval` |
| `writes` | The source changes state in the target: a data write. | `flow.data_write` |
| `sends` | The source passes content to the target: user input into a prompt, a prompt payload to a provider, an external send, a trace or audit event, a model response. | `flow.user_input`, `flow.external_send`, `flow.provider_boundary_transfer`, `ai.prompt_payload`, `ai.retrieved_context`, `ai.model_response`, `agent.approval_request`, `flow.audit_event`, `flow.trace_event`, `data_flow`, `prompt_context`, `external_effect`, `error_flow` |
| `grants` | The source gives the target authority: an approval, an approved action, an escalation. | `agent.approved_action`, `approval`, `authority_escalation` |
| `depends_on` | The source relies on the target being what it claims: a dependency, a package, a model artifact. | `depends_on`, `flow.depends_on`, `dependency` |
| `trusts` | The source accepts the target without checking it: an explicit trust relationship. | `trusts`, `trust` |

## Trust levels and zones

A node sits in a zone (a group; the node's `parentId` names it). Its trust level is its own `trustLevel`, else its zone's, else a default for its kind. The canvas offers these levels, in this order: `untrusted`, `external_provider`, `trusted_internal`, `trusted_data`, `trusted_evidence`, `privileged`. Other labels are read by rank:

| Rank | Level labels that rank here |
|---|---|
| 0, untrusted | `untrusted`, `public`, `attacker`, `anonymous`, `hostile` |
| 1, external or user-side | `client`, `authenticated_user`, `authenticated`, `user`, `external_provider`, `third_party`, `partner`, `external` |
| 2, internal | `trusted_internal`, `internal`, `human_review`, `service` |
| 3, data | `trusted_data`, `trusted_evidence`, `restricted` |
| 4, privileged | `privileged`, `admin`, `trusted_admin` |

A label that is not in the table is read by its words (one containing `untrust`, `public`, `extern`, `provider`, `data`, `admin` and similar ranks with them) and otherwise ranks as internal, so an unknown label never invents a boundary on its own. A zone with no level of its own takes a default from its kind:

| Zone kind | Default trust level |
|---|---|
| `zone.public` | `untrusted` |
| `zone.application` | `trusted_internal` |
| `zone.ai_processing` | `trusted_internal` |
| `zone.agent_tools` | `trusted_internal` |
| `zone.external_providers` | `external_provider` |
| `zone.data_platform` | `trusted_data` |

## Trust boundaries

A trust boundary is an edge whose two ends sit in different zones or at different trust levels, or that is marked `crossesTrustBoundary`. Each boundary in the analysis records:

- the verb, and the zone and level of both ends;
- the direction: `inbound` (towards more trust), `outbound` (towards less) or `lateral` (same level, different zone);
- the controls on the edge, and its `evidenceRefs`;
- `evidenced`, true when the edge has at least one evidence reference.

## Chains

A chain is a simple path (no node twice) that starts at an untrusted node and ends on a consequential edge. A start is a node of rank 0 or any `actor.*` node. An edge is consequential when its source changes state, sends out, executes or grants: the edge is marked `stateChanging`, its verb is `writes` or `grants`, its tool authority is `execute`, or its target is an external service, a code executor, an outbound sink, an email or CRM system, the filesystem or a browser.

Two more things end a chain. An edge into an element known to hold a defect (a scan attached error findings to it, or a high or critical risk refers to it) ends one, and so does an edge into a data store that sits behind a model or agent element, because the model then reads data on behalf of whoever drives it. The analysis records which it is as the chain's `consequenceKind`: `write`, `execute`, `send`, `external`, `grant`, `data_access` or `vulnerable`.

The chain search stops at depth 10 or 500 chains, and the analysis says when it stopped (`summary.truncated`).

The chain reports the strongest `guardStatus`. Authorization requirements and explicit blocks apply anywhere on the chain. Generic control statuses count from the point where the model or agent starts driving actions. Only `PATH_BLOCKED` sets `guarded`. When `approvalRequired` is true, or a control is named `approval` or `human_approval`, the edge requires authorization. Other recorded controls default to `CONTROL_PRESENT` unless the edge records a stronger status.

| Guard status | Meaning |
|---|---|
| `CONTROL_PRESENT` | The edge records a control. |
| `CONTROL_ENFORCED` | The edge records that a control is enforced. |
| `AUTHORIZATION_REQUIRED` | The action requires authorization. The path remains reachable. |
| `PATH_BLOCKED` | The model records the path as blocked at this edge. |

Tool authority is a security field. On an edge, `execute` makes the edge consequential; scans fill it in on tool elements:

| toolAuthority | Meaning |
|---|---|
| `none` | The tool can do nothing. |
| `read` | The tool reads. |
| `suggest` | The tool proposes; nothing runs. |
| `draft` | The tool prepares a change without applying it. |
| `queue` | The tool queues an action for later approval. |
| `execute` | The tool acts. An edge into it counts as consequential. |

## Chokepoints, cut points and fix first

- **Chokepoint.** The nodes and edges most unguarded chains pass through, counted from where a guard would work. Each carries the number of chains and their share of all unguarded chains. An element appears when two or more chains pass through it, or when there is exactly one unguarded chain. The analysis lists the top twelve.
- **Fix first.** Up to five edge chokepoints, each with a sentence naming what a guard on it would break. Guarding the top edge chokepoint breaks exactly the chains it counts.
- **Cut points.** Nodes whose removal splits the model, most pieces first. A cut point is about connectivity; a chokepoint is about unguarded chains. They answer different questions.

## How an element is known

Every node and edge may carry provenance. Inferred edges count as weak: a path through one costs 4 instead of 1 when paths are searched, and the canvas draws it dashed. When two sources find the same edge it is kept once with both sources.

| Basis | Meaning |
|---|---|
| `structured` | Read from a syntax tree or a config file. |
| `inferred` | A heuristic, for example tools chained because the model may call any of them after any other. Weak: drawn dashed, and a path through it costs more. |
| `stated` | Drawn by a person. |

## Lenses

The lens, focus and depth are kept in the page address, as `#/trust?lens=chains&focus=<id>`, so a view can be shared.

| Lens | Shows |
|---|---|
| Everything (`all`) | Show every element and every connection |
| Trust crossings (`boundaries`) | Only the connections where data moves from a less trusted zone to a more trusted one |
| Risky paths (`chains`) | Potentially reachable paths from untrusted input to a consequence, including paths that require authorization |
| What it can reach (`blast`) | Pick an element: show everything it can reach, up to 4 steps away |
| What reaches it (`reach`) | Pick an element: show everything that can reach it, up to 4 steps away |
| Path between two (`path`) | Choose a start and an end to see the routes between them |

## Risk rules

The canvas raises risks from the model. The first five carry the ids of the threat-canvas prototypes whose files it opens unchanged. The rules whose id starts `keryn.trust.` are edge-first rules. Two of them (`boundary-unguarded` and `unguarded-chain`) work on any model. The other five are written for models [derived from a scan](https://keryn.dev/docs/guides/trust-canvas/#start-from-a-repository), and apply to a drawn model that uses the same element kinds (`data.secret`, `external.mcp_server`, `agent.orchestrator` with `toolsDynamic`): a secret that a model or agent element can reach through directed edges, an MCP server that is not pinned, a tool list built at run time, boundaries that rest only on inferred links (one risk for the whole model), and one provider reached from three or more repositories.

| Rule id | Severity | Category | Title |
|---|---|---|---|
| `rule_rag_authz_gap` | high | `retrieval_leakage` | Retrieved context lacks authorization evidence |
| `rule_indirect_prompt_injection` | high | `prompt_injection` | User-controlled content becomes model-visible without prompt isolation |
| `rule_tool_action_without_approval` | critical | `excessive_agency` | State-changing tool action lacks approval requirement |
| `rule_provider_boundary_evidence_gap` | medium | `provider_boundary` | Model-visible data crosses provider boundary without evidence |
| `rule_trace_gap` | medium | `trace_gap` | AI or agent component lacks modelled trace flow |
| `keryn.trust.boundary-unguarded` | medium | `trust_boundary` | Trust boundary crossed with no control or evidence |
| `keryn.trust.unguarded-chain` | critical or high | `attack_path` | A chain from an untrusted start to a consequential edge with nothing on it (one per start and end) |
| `keryn.trust.secret-reachable-from-model` | high | `secret_exposure` | A secret is reachable from a model or agent |
| `keryn.trust.mcp-server-unpinned` | medium | `supply_chain` | MCP server is not pinned to a version |
| `keryn.trust.dynamic-toolset` | medium | `excessive_agency` | Tool set is decided at run time |
| `keryn.trust.boundary-inferred-only` | low | `evidence_gap` | One or more trust boundaries rest only on inferred links with no evidence reference (one risk for the whole model) |
| `keryn.trust.provider-concentration` | info | `concentration` | One external provider serves many repositories |

A risk has a status: `open`, `accepted`, `mitigated`, `needs_evidence`.

## Files

A model is a `threat_model_graph` document (the [guide](https://keryn.dev/docs/guides/trust-canvas/#the-model-as-a-file) shows one). An export in the `keryn-export/1` envelope holds the model and its analysis.

> **Note: In the next release**
> Two more files carry the planning on [Plan fixes](https://keryn.dev/docs/guides/trust-canvas/#plan-fixes) and on workflow imports:
>
> | Schema | What it holds |
> |---|---|
> | `keryn.dev/graph-plan/v1` | The graph, its analysis, the estimates and the receipt of a graph plan, as **Save graph plan** writes it. Opening it restores the graph and the plan. |
> | `keryn.dev/workflow-economics/v1` | An execution scenario for an imported workflow: `currency`, `runsPerMonth`, a `note`, and per source path `executionsPerRun` and `costPerExecution` (non-negative numbers), with optional `valuePerSuccessfulRun`, `successRate` and `fixedCostPerMonth`. A node with no entry stays unknown. |
>
> A plan is tied to the content of the model, not to where its elements are drawn: moving an element or resizing a zone keeps the estimates, and any other change to the model resets them.

*Generated from the trust-model engine's source (monorepo 59bd9a163526) by `tools/extract-product-facts.mjs`.*
