Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Trust Canvas reference

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    This is the vocabulary and the arithmetic of the 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.

    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.

    VerbMeaningInferred from these edge kinds
    reachesThe 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
    callsThe 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
    readsThe 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
    writesThe source changes state in the target: a data write.flow.data_write
    sendsThe 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
    grantsThe source gives the target authority: an approval, an approved action, an escalation.agent.approved_action, approval, authority_escalation
    depends_onThe source relies on the target being what it claims: a dependency, a package, a model artifact.depends_on, flow.depends_on, dependency
    trustsThe source accepts the target without checking it: an explicit trust relationship.trusts, trust

    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:

    RankLevel labels that rank here
    0, untrusteduntrusted, public, attacker, anonymous, hostile
    1, external or user-sideclient, authenticated_user, authenticated, user, external_provider, third_party, partner, external
    2, internaltrusted_internal, internal, human_review, service
    3, datatrusted_data, trusted_evidence, restricted
    4, privilegedprivileged, 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 kindDefault trust level
    zone.publicuntrusted
    zone.applicationtrusted_internal
    zone.ai_processingtrusted_internal
    zone.agent_toolstrusted_internal
    zone.external_providersexternal_provider
    zone.data_platformtrusted_data

    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.

    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 statusMeaning
    CONTROL_PRESENTThe edge records a control.
    CONTROL_ENFORCEDThe edge records that a control is enforced.
    AUTHORIZATION_REQUIREDThe action requires authorization. The path remains reachable.
    PATH_BLOCKEDThe 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:

    toolAuthorityMeaning
    noneThe tool can do nothing.
    readThe tool reads.
    suggestThe tool proposes; nothing runs.
    draftThe tool prepares a change without applying it.
    queueThe tool queues an action for later approval.
    executeThe tool acts. An edge into it counts as consequential.
    • 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.

    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.

    BasisMeaning
    structuredRead from a syntax tree or a config file.
    inferredA 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.
    statedDrawn by a person.

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

    LensShows
    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

    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, 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 idSeverityCategoryTitle
    rule_rag_authz_gaphighretrieval_leakageRetrieved context lacks authorization evidence
    rule_indirect_prompt_injectionhighprompt_injectionUser-controlled content becomes model-visible without prompt isolation
    rule_tool_action_without_approvalcriticalexcessive_agencyState-changing tool action lacks approval requirement
    rule_provider_boundary_evidence_gapmediumprovider_boundaryModel-visible data crosses provider boundary without evidence
    rule_trace_gapmediumtrace_gapAI or agent component lacks modelled trace flow
    keryn.trust.boundary-unguardedmediumtrust_boundaryTrust boundary crossed with no control or evidence
    keryn.trust.unguarded-chaincritical or highattack_pathA chain from an untrusted start to a consequential edge with nothing on it (one per start and end)
    keryn.trust.secret-reachable-from-modelhighsecret_exposureA secret is reachable from a model or agent
    keryn.trust.mcp-server-unpinnedmediumsupply_chainMCP server is not pinned to a version
    keryn.trust.dynamic-toolsetmediumexcessive_agencyTool set is decided at run time
    keryn.trust.boundary-inferred-onlylowevidence_gapOne or more trust boundaries rest only on inferred links with no evidence reference (one risk for the whole model)
    keryn.trust.provider-concentrationinfoconcentrationOne external provider serves many repositories

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

    A model is a threat_model_graph document (the guide shows one). An export in the keryn-export/1 envelope holds the model and its analysis.

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