仓库文件导航
TrustGraph
面向 AI 智能体产出的策略即代码。根据智能体读了什么,决定它的输出可以去哪里。
试试 playground · 编写策略 · 我们如何确认它有效
问题所在
权限系统决定智能体可以读什么。但智能体一写出新东西,它们就跟丢了。
2025 年 5 月,Invariant Labs 展示了一个编码智能体读取用户的私有仓库,并在读到一条精心构造的 issue 后,把发现的内容发布到一个公开仓库的 pull request 上。每一步都是智能体被允许做的事。读私有代码没问题。开公开 pull request 也没问题。没有任何东西检查后者是否源自前者。
收回访问权限并不能解决这个问题:智能体需要私有代码才能完成工作。缺的是一条规则,规定由它衍生出的东西可以去哪里。每当一个智能体把工作交给另一个智能体,同样的缺口就会出现:限制应当跟随数据走完每一步。
TrustGraph 做什么
你写一个小的策略文件。它规定谁可以读每个来源衍生的任何东西、哪些智能体可以使用它,以及每个动作把输出送到哪里:
version: 1
groups:
hr: [nina]
engineering: [sam, ravi]
leadership: [maya]
agents: [researcher, planner]
sources:
salaries: { readers: [hr], agents: [researcher, planner] }
roadmap: { readers: [hr, engineering, leadership], agents: [planner] }
benchmarks: { readers: [hr, engineering, leadership], agents: [researcher, planner] }
actions:
post_to_engineering: { agents: [planner], audience: [engineering] }
brief_hr: { agents: [planner], audience: [hr] }
brief_leadership:
agents: [planner]
audience: [leadership]
approval: { reviewers: [hr], valid_for: 1h }
TrustGraph 记录每个输出在每一步是由什么构建的,并给出允许、需要批准或拒绝的答复及理由:
| 输出携带的内容 | 它想要 | 答复 |
|---|---|---|
| 规划笔记(来自 salaries )+ roadmap | post_to_engineering | 拒绝。salaries 仅 hr 可读;engineering(ravi、sam)不在其中 |
| 同一份摘要 | brief_hr | 允许 |
| 仅 roadmap | post_to_engineering | 允许 |
| roadmap + benchmarks | brief_leadership | 需要批准。动作 brief_leadership 需要审核者批准 |
完整文件连同其测试,见 examples/policies/handoff.policy.yaml。
规则很小:
readers(output) = 可以读取每个输入的人
只有当接收某个动作的每个人都属于这些读者时,该动作才被允许
批准增加了一项要求。它从不扩大谁可以读某个来源。策略没有点名的任何东西都被拒绝。
决策是确定性的。决策路径中没有模型。
快速开始
需要 Rust 1.90 或更新版本。
cargo install --locked --git https://github.com/skishore23/trustgraph trustgraph-cli
trustgraph policy init # writes trustgraph.policy.yaml
trustgraph policy check trustgraph.policy.yaml
trustgraph policy test trustgraph.policy.yaml
ok: 0 errors, 0 warnings
PASS salary data never reaches engineering
PASS roadmap summary can be posted
2 passed, 0 failed
策略自带测试。每个测试说明智能体读了什么、它试图做什么,以及你期望的答复。
用通俗的英语回读策略,看清策略变化时究竟谁获得了访问权限,并通过模拟器运行它:
trustgraph policy explain trustgraph.policy.yaml
trustgraph policy diff old.policy.yaml new.policy.yaml
trustgraph policy simulate trustgraph.policy.yaml
salaries: output can reach hr (nina). Usable by agent planner.
email_customer: mailer may send to customers (acme) after approval by sales (leo), valid 30m.
WIDENS source salaries: readers gained ravi, sam
文章标题:TrustGraph——随数据穿过 AI 代理的 ACL
正文: 64 次运行,12,936 个事件:994 允许,5,082 拒绝,392 需审批——0 违规
每个命令都支持 --json。examples/policies 中有六个完整示例策略。
## 让代理来编写策略
TrustGraph 假定由代理起草策略,由人批准。每个问题都会一次性报告,附带路径、稳定代码和建议,因此代理可以自行运行 init → check → test → simulate → explain → diff 循环。然后由人审阅纯英文说明和 diff,其中每一处权限放宽都被标记出来。
把你的代理指向 docs/agents/writing-policies.md 或 llms.txt。用代码审查保护策略文件。
## 在你的系统中使用
> 状态。策略 CLI 和 trustgraph serve 已经过安全审查。trustgraph gateway 和 Python 集成是新增的:两轮审查发现并修复了真实漏洞,第三轮正在进行中。可以试用,但还不要把它们放在真实数据前面。
## trustgraph gateway:只要 gateway 独自持有凭证,代理就无法绕过它
把 gateway 放在你的代理和它们使用的 MCP 服务器之间。它持有服务器的凭证,记录每个代理通过这些服务器读取了什么,并在转发调用前对每个动作进行核对。只要 gateway 独自持有上游凭证,且代理没有其他途径访问这些服务器,代理就无法绕过它。gateway.yaml 规定哪个工具读取哪个数据源、哪个工具对应哪个动作,以及每个工具可以携带哪些参数:
trustgraph gateway --policy trustgraph.policy.yaml --operator leo --config gateway.yaml
planner slack__post_message #engineering: error: TrustGraph gateway: post_to_engineering was not forwarded: denied: salaries is readable by hr only; engineering (ravi, sam) is not included (denied)
配置、会话、交接和威胁模型:docs/gateway.md。可运行示例:examples/gateway。
## trustgraph serve
一个基于 HTTP 和 MCP 的本地服务,任何代理栈都可以登记它读取了什么、记录它写了什么,并在行动前询问。每个代理都有自己的 token;由人,也就是操作员,在本地页面上批准请求。
trustgraph serve --policy trustgraph.policy.yaml --operator leo
在行动前询问:
curl -s localhost:8787/v1/check \ -H "Authorization: Bearer $(cat ~/.trustgraph/serve/tokens/mailer.token)" \ -H "Content-Type: application/json" \ -d '{"artifact": "<artifact id>", "action": "email_customer"}'
API、MCP 端点、token、操作员页面、限制和威胁模型见 docs/serve.md。
## 从 Python 使用
标记什么读取数据源、什么执行动作;在一次会话内,读取的内容会跟随写入的内容(SDK 参考):
import trustgraph
client = trustgraph.Client(token_file="~/.trustgraph/serve/tokens/planner.token")
@trustgraph.source("salaries") def read_salaries(): return "nina: 120k, sam: 95k"
@trustgraph.action("post_to_slack", content=lambda args, kwargs: args[0]) def post_to_slack(text): print("posted:", text) # runs only on allow
with client.session(): read_salaries() try: post_to_slack("Q3 headcount plan") except trustgraph.Denied as e: print(e.decision.verdict, e.decision.reason)
deny denied: salaries is readable by hr only; engineering (ravi, sam) is not included
集成,每个都附有交接示例:LangChain / LangGraph、OpenAI Agents SDK 和 Claude Agent SDK。包装器只检查它包装的工具。
Rust crate
trustgraph-policy 解析、测试、解释和对比策略,decide 是一个纯函数(cargo run -p trustgraph-policy --example decide)。trustgraph-engine 是 trustgraph serve 运行的日志化运行时。
我们如何知道它有效
- 统一的决策顺序。允许 / 需审批 / 拒绝的排序位于一个小内核中,策略函数和运行时都调用它。
- 核心规则的有界证明。十个 Kani 测试框架覆盖该内核、审批时间窗口和读者集规则。十个都在 CI 中通过。
- 一个运行真实运行时的模拟器。种子运行通过策略变更、崩溃、日志撕裂写入和审批过期来驱动相同的代码,并针对仅从策略文本计算出的检查,在每一步验证五条安全规则。三个故意破坏的运行时构建必须被捕获,并且确实被捕获了。
这些证明是有界的,覆盖核心规则,而非整个系统。模拟器展示的是在其所进行的运行中不存在违规,而非在所有可能的运行中都不存在。验证范围和复现准确说明了各自覆盖的内容。
它不做什么
- 它只知道你告诉它的内容。如果你的系统没有报告 agent 读取的某个来源,TrustGraph 无法为其负责。
- 它做决定;它不执行动作。除了通过网关之外,你的系统必须在行动前询问,并且仅在允许时才行动。
- 规则是严格的。一个敏感输入会将整个输出限制为该输入的读者。目前还没有“此摘要可以安全分享”的例外。
- 组是文件中的列表。它们不会从身份提供者同步。
它适合放在哪里
诸如 SpiceDB 或 OpenFGA 之类的权限数据库决定你的 agent 可以读取什么。TrustGraph 决定它所写的内容可以流向哪里。两者都用。
仓库
| 路径 | 它是什么 |
|---|---|
| crates/trustgraph-policy | 策略文件:解析、决策、测试、解释、差异、模式、入门 |
| crates/trustgraph-engine | 确定性运行时核心、日志和重放 |
| crates/trustgraph-core | 便于证明的内核及其 Kani 测试框架 |
| crates/trustgraph-framework | 引擎所构建于其上的沿袭图 |
| crates/trustgraph-sim | 种子策略模拟器及其安全检查 |
| crates/trustgraph-cli | trustgraph 命令:policy、serve 和 gateway |
| sdk/python | Python SDK 及其框架集成 |
| examples/policies | 六个示例策略 |
| examples/gateway | 通过网关的交接故事 |
| examples/integrations | 每个集成一个交接示例 |
| docs/agents | 面向 agent 的策略编写指南 |
| web、api、hosted | 公共站点及其 playground 端点 |
开发
cargo fmt --all --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo test --workspace --locked
参见开发和公共站点。