ADK-Rust工具授权五重机制:ToolPolicy、人工审批、RBAC、Kill Switch与签名审计日志

原创2026-10-31 22:51:371,615 阅读

ADK-Rust工具授权五重机制:ToolPolicy、人工审批、RBAC、Kill Switch与签名审计日志

ADK-Rust架构图:展示从应用到服务层的分层设计

为什么 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-Rust 客服 Agent 演示:Agent 执行退款等真实操作前需要经过授权确认

📌 审批的核心流程(挂起、恢复、指纹、存储)实现于 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 错误返回给模型,并明确告知缺失的是哪个权限,让模型知道"为什么不行"从而调整策略。

ADK Studio 可视化界面:可视化编排 Agent、工具与执行流程

📌 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,而不是把它们关在演示代码里。

登录后查看全文
adk-rust