ADK-Rust工具授权五重机制:ToolPolicy、人工审批、RBAC、Kill Switch与签名审计日志
ADK-Rust工具授权五重机制:ToolPolicy、人工审批、RBAC、Kill Switch与签名审计日志
为什么 AI Agent 的工具授权如此重要
ADK-Rust 工具授权是 AI Agent 安全领域的核心课题。当你的 Agent 拥有删除文件、发送邮件、转账付款这类"真刀真枪"的工具能力时,一旦模型被提示注入攻击或产生幻觉,后果不堪设想。Rust Agent Development Kit(ADK-Rust)内置了五重工具授权机制——从 ToolPolicy 声明式策略、人工审批,到 RBAC 角色控制、Kill Switch 紧急刹车,再到签名审计日志——层层设卡,让每一次工具调用都可控、可审、可追溯。
本文将带你逐层拆解这五道防线,全部机制的实现位于 adk-core/src/policy.rs、adk-core/src/governance.rs 与 adk-auth/src/access_control.rs 等源码中,完整文档见 docs/official_docs/security/tool-authorization.md。
第一重:ToolPolicy——默认拒绝的策略引擎
ToolPolicy 是整条授权链的第一道闸门。它会在每次工具调用的最终参数(所有插件与回调改写之后)上做出裁决,只有三种结果:
| 裁决 | 效果 |
|---|---|
Allow |
调用放行,进入后续关卡 |
Deny { reason } |
工具不执行,模型收到拒绝原因 |
RequireApproval { reason } |
转入人工审批流程 |
它的杀手锏是默认拒绝(default-deny):DeclarativePolicy 按顺序匹配规则,没命中任何规则的调用一律被拒绝——这和企业安全中最可靠的"白名单"思维完全一致。
规则能精确到什么程度?举几个例子:
allow("transfer").when(ArgPredicate::at_most("/amount", 100.0))——100 元以下的转账自动放行;- 金额超过 100 的转账自动进入审批;
for_agent(...)/for_tenant(...)可以把规则绑定到特定 Agent 身份,例如"被隔离的遗留 Agent 一个工具都不能调";- 还能按工具来源(静态挂载 / 某个 MCP 服务器 / 内置工具)做裁决,同名工具换了个 MCP 服务器发布,指纹立刻不同,旧审批自动失效。
多个策略还可以用 StrictestPolicy 组合成"最严格者优先"的多层策略,Deny 严于 RequireApproval,RequireApproval 严于 Allow。
let policy = DeclarativePolicy::builder()
.deny("read_secret", "secrets are never exposed to the model")
.allow_read_only()
.require_approval("transfer", "transfers over 100 need a person")
.build();
📌 策略的完整实现见 adk-core/src/policy.rs。
第二重:人工审批——让关键操作过"人眼"
当策略裁决为 RequireApproval,或 Agent 对某个工具声明了 require_tool_confirmation 时,调用会被挂起(held),等待真人拍板。
这个机制的严谨程度远超"弹窗点一下":
- 指纹绑定:每个审批请求都有
fingerprint,由"执行 Agent + 工具来源 + 声明摘要(SHA-256)+ 工具名 + 规范化参数"共同构成。审批delete_file删除临时文件,绝不自动覆盖同工具、不同参数的调用; - 参数改写即重审:审批人在审批界面把金额从 500 改成 100?改动后的参数会重新过一遍
ToolPolicy和 guardrails; - 超时不静默放行:审批人在超时窗口内(默认 5 分钟)没表态,调用会留在
ApprovalStore里等待,而不是默认通过; - 跨运行持久化:挂起的调用可以跨会话、跨重启存活。
adk-session提供 SQLite、Postgres、Redis、Mongo、Neo4j、Firestore 六种持久化审批存储。
在 Web 端,审批请求通过 SSE 推送到前端弹出对话框,用户点击"允许/拒绝"后回传决策;在 CLI 端,一个简单的终端 ToolConfirmationHandler 就能实现 [y/n] 交互确认。此外还有支持多人审批、委托、升级通知的 ApprovalService 收件箱机制。
📌 审批的核心流程(挂起、恢复、指纹、存储)实现于 adk-core/src/governance.rs,审批数据结构在 adk-core/src/approval.rs。
第三重:RBAC 角色访问控制——企业级用户权限
前两层回答的是"这个调用能不能执行",RBAC 回答的是"这个用户有没有资格"。adk-auth 提供了企业级的角色访问控制:SSO 令牌验证(支持 Google、Azure AD、OIDC)、JWKS 自动刷新、身份提供方(IdP)组到本地角色的映射,再到角色内的允许/拒绝规则(deny 优先)。
let ac = AccessControl::builder()
.role(Role::new("analyst")
.allow(Permission::Tool("search".into()))
.deny(Permission::Tool("delete_file".into())))
.role(Role::new("admin").allow(Permission::AllTools))
.assign("alice@co.com", "admin")
.build()?;
把工具包装后(my_tool.with_access_control(ac)),每次执行前都会校验当前用户的角色与 scope。被拒的调用会以 tool.permission_denied 错误返回给模型,并明确告知缺失的是哪个权限,让模型知道"为什么不行"从而调整策略。
📌 RBAC 架构与实现见 adk-auth/src/ 目录及文档 docs/official_docs/security/access-control.md。
第四重:Kill Switch——组织级紧急刹车
前面三层都是"事前"控制,而 GovernanceControl(Kill Switch)是"事中"的总电源开关。每个 Runner 都持有一个(可通过 Runner::governance() 获取),多个 Runner 可以共享同一个实例。
一旦执行 control.freeze("incident 4012: unexpected payouts"):
| 检查点 | 效果 |
|---|---|
| 运行启动时 | 直接以 governance.frozen 错误终止 |
| 每次模型调用前 | Agent 结束运行,请求根本不会发给模型厂商 |
| 每次工具调用前 | 工具不执行,调用被回答为 not run |
关键细节:
- 冻结错误是
Forbidden且不可重试,避免调用方在冻结的 Runner 上空转重试; - 生产环境可用
GovernanceControl::mirrored构建多副本同步的 Kill Switch:所有实例镜像同一个GovernanceStateStore,任一副本冻结,全集群秒级生效;读取超时未刷新时会"失败关闭(fail closed)"; adk-server暴露了POST /api/admin/freeze和POST /api/admin/unfreeze管理端点,冻结还会暂停后台任务与定时调度,解冻后自动恢复。
一句话:出事故了,一键冻结,全平台的 Agent 立刻停摆,调查完毕再放行。
📌 实现见 adk-core/src/governance.rs,多副本机制见 adk-core/src/governance_state.rs。
第五重:签名审计日志——不可抵赖的操作凭证
授权决策做完还不够,你得能事后证明"当时就是这样裁决的"。ADK-Rust 通过 adk-auth/src/signed_audit/ 提供了一条密码学可验证的审计日志,防篡改能力分五层:
| 层级 | 机制 | 能检测什么 |
|---|---|---|
| 记录 | RFC 8785 (JCS) 规范化 | 任何字段被改动 |
| 链 | prev_hash 链接前一条记录 |
记录被删除、插入或重排 |
| 树 | RFC 9162 Merkle 树 + 包含证明 | 树外记录、前缀被重写 |
| 检查点 | Ed25519 签名的 C2SP 检查点 | 无密钥者的重写 |
| 锚点 | 检查点发布到日志外部 | 连持密钥者都无法悄悄改写 |
开启只需一行:Runner::builder().audit_log(recorder)。之后治理路径上的每个决策都会先落日志再生效——放行的调用、被策略/guardrail/审批/Kill Switch 拒绝的调用、每次审批决定及其来源,甚至 Kill Switch 的冻结/解冻操作(连同操作管理员身份)都在其中。
更妙的是默认 AuditFailureMode::Block:如果审计记录写不进去,工具调用就直接不执行。审计不再是可选的旁路,而是执行的前置条件。验证导出日志可以用 adk-rust audit verify 命令离线完成。
📌 详细文档见 docs/official_docs/security/audit-log.md。
五重机制如何协同:一次调用的完整旅程
这五道防线不是孤立的,而是严格按固定顺序串联(见 adk-core/src/governance.rs 顶部说明):
模型发起工具调用
↓
① Kill Switch:组织冻结中?→ 整个运行直接报错
↓
② ToolPolicy:默认拒绝的策略裁决(Allow / Deny / RequireApproval)
↓
③ 工具 Guardrails:内容筛选,改写参数后重新过策略
↓
④ 人工审批:指纹绑定,参数改动即重审,超时不静默
↓
⑤ RBAC 包装层(ProtectedTool / ScopeGuard)在 execute() 内部
按用户角色与 scope 做最终校验
↓
执行 → 每个决策点都已写入签名审计日志
新手上手建议:先从 ToolPolicy + 关键工具加 require_tool_confirmation 起步,覆盖 90% 场景;上生产再接 adk-auth 的 RBAC 与签名审计,最后把 Kill Switch 挂到运维面板上。五层机制可任意组合,也能叠加 BeforeToolCallback 做程序化审计——它们在 CLI、Web Server 和 A2A 协议下行为一致。
总结
| 机制 | 解决的问题 | 粒度 | 源码位置 |
|---|---|---|---|
| ToolPolicy | 什么工具在什么条件下能跑 | 工具名 + 参数 + 来源 | adk-core/src/policy.rs |
| 人工审批 | 高风险操作要人点头 | 单次调用指纹 | adk-core/src/governance.rs |
| RBAC | 哪个用户有权限 | 用户 × 角色 × 工具 | adk-auth/src/access_control.rs |
| Kill Switch | 出事故一键全停 | 组织/Runner 级 | adk-core/src/governance.rs |
| 签名审计日志 | 事后举证与防篡改 | 每个决策点 | adk-auth/src/signed_audit/ |
ADK-Rust 的设计哲学很清晰:AI Agent 的能力越大,授权链就必须越深。这五重机制覆盖了"事前策略、事中审批、身份控制、紧急止血、事后举证"的完整生命周期,让你可以放心地把真工具、真权限交给 Agent,而不是把它们关在演示代码里。


