Skip to main content
Glama

代理治理审计器

一个用于审计其他AI代理合规性的ADK代理——它能够发现GCP项目中运行的AI工作负载,包括那些无人登记过的,针对版本化策略包执行11项确定性检查,并生成映射到欧盟《人工智能法案》(第6、9、11、12、13、15、50条)和SOC 2信任服务标准的审计就绪证据包。每项发现都附带不可篡改的证据引用(GCS + SHA-256)。每次写入操作都需人工批准。

每项策略都说明了为何映射到其所声称的条款——并且有两项映射在审查中因过度延伸而被移除,因为过度映射正是让合规报告失去可信度的最快方式。该工具审计的是缺失声明,而非推断违法行为:“未记录风险分类”是可核查的,也是审计师会记录的问题;而“该代理属于附件III高风险类别”则是法律判断,该工具无权作出。

为Gemini Enterprise黑客松而构建——第2赛道(高代码:ADK + 自定义MCP服务器 + Gemini Enterprise Agent Platform上的Agent Runtime)。

为什么

欧盟《人工智能法案》的时间表发生了变化,这让问题变得更加紧迫而非缓解。《欧盟条例(EU)2026/1744》(即“人工智能数字综合法案”,2026年7月27日生效)将附件III高风险义务推迟至2027年12月2日。推迟,但并未取消——而与此同时,第50条透明度义务、第5条禁止性实践以及通用人工智能提供者义务已于今日生效,违规罚款最高可达3500万欧元或全球营业额的7%。

因此,企业大约还有十六个月来为高风险系统建立证据链,而同时已经需要为当前正在运行的代理承担义务。这两者都取决于回答审计师总会问的一个问题——“你们有哪些AI系统,能否证明它们受到治理?”——而诚实的答案通常是*“我们也不完全确定。”*

这个工具就是用来回答这个问题的,并且附带证据。

Related MCP server: EU AI Act Compliance MCP Server

工作原理

上图展示了整体架构。核心设计原则(完整架构文档):

  • LLM绝不决定合规性——代码决定。 通过/未通过由MCP工具代码计算;代理仅负责编排、确定优先级和叙述说明。变更防护机制会在分类阶段试图翻转状态时中止整个运行。

  • 证据驱动,由构造保证。 没有evidence_ref的发现项在数据模型中不可能存在——模式定义会拒绝它。

  • 默认只读。 唯一的写入路径(补救指令)需要人工签发的单次使用批准令牌,并在服务端强制执行,因此服务器绝不信任代理关于“已获人工批准”的声明。

  • 审计器自我审计——它以自身Agent Identity部署,并被自己的扫描发现,在11项检查中通过6项。

一次端到端的审计

设计中有两点是刻意的,而非装饰。分类阶段完全不调用任何MCP工具——真正进行推理的这一步被隔离在流程之外,无法触达外部资源。并且在写入任何内容之前,运行会挂起:此时令牌尚不存在,因此即使代理尝试写入,服务器也会拒绝。

发现机制基于行为,而非名称匹配

这个产品成败的关键问题是*“你是否能发现一个名字不叫agent-something的代理?”* 仅靠名称匹配的答案是“不能”——它会漏掉customer-insights-api,却会把名为agent-proxy的nginx误报为代理。因此,工作负载的分类基于五种信号,每个候选对象都会报告置信度和理由:

信号

观察内容

强度

model_api_calls

服务账号出现在Cloud Audit Logs中,调用了模型API

已确认

agent_runtime

部署在Agent Runtime上——按构造即为代理

已确认

declared_label

带有ai-agent=true标签

已声明

model_env

环境引用了模型或代理框架

可能

name_hint

名称看起来像代理——保留,但降级为最弱信号

可能

第一点正是关键:一个与模型通信的工作负载无法靠一个平淡无奇的名字隐藏自己。演示集群中特意包含了customer-insights-api——一个真实部署的ADK代理,名字不像代理且没有任何标签——正是为了让这一论断可被验证,而非空口断言。

覆盖范围,以及未覆盖的范围

发现机制的触达范围比审计更广,报告会明确说明哪些是哪些:

全面审计

Cloud Run · Agent Runtime——全部11项检查均读取其配置

已发现,尚未审计

Cloud Functions · GKE · Compute——已找到,但其配置无法以相同方式读取

作为未决问题报告

任何与我们发现的工作负载都不匹配、但正在运行推理的身份

完全盲区

调用Google Cloud之外模型的场景、在VM上本地运行模型、跨项目调用,或审计日志被关闭的情况

最后一行是诚实的说明。调用外部提供商的工作负载不会出现在Google的日志中,合规审计师也无法发现这一点——该工具检查的是那些本应被启用的控制措施是否已开启,并在未开启时如实报告。GOV-NET-007正是这样一项检查。

底线保障: 使用模型必然需要身份验证,而身份验证必然产生日志。因此最坏的情况是*“这里有一个我们无法归因的实例——请去查看”*,而绝不会是沉默。

快速开始

所有开发都在容器内进行——Ubuntu 26.04 LTS,预装gcloud、Terraform、Node和固定版本的Python 3.12。你的机器上不会安装任何东西,macOS、Windows(Docker Desktop或WSL2)和Linux上的环境完全一致。

前置条件: Docker正在运行(OrbStack、Docker Desktop或WSL2),并且已克隆此仓库。仅此而已。

1. 构建镜像并进入shell

在仓库根目录打开终端——即包含gov_mcp/、auditor/、infra/文件夹的目录:

cd path/to/agent-governance-auditor      # wherever you cloned it

# Build. First time ~3-5 min; afterwards it's instant (layer cache), so it's
# safe to just always run it.
docker build -t agv-dev docker/

# Start a shell inside the container.
docker run -it --rm \
  -v "$PWD":/workspace \
  -v agv-gcloud:/home/ubuntu/.config/gcloud \
  -v agv-venv:/opt/venv \
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 \
  agv-dev bash
docker run -it --rm `
  -v "${PWD}:/workspace" `
  -v agv-gcloud:/home/ubuntu/.config/gcloud `
  -v agv-venv:/opt/venv `
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 `
  agv-dev bash

这些参数的作用:

参数

说明

-v "$PWD":/workspace

将你的仓库文件夹实时挂载。你可以在宿主机上用任何编辑器修改文件;容器内立即可见变更。不会复制任何内容。

-v agv-gcloud:…/.config/gcloud

将你的gcloud登录凭据保存在Docker卷中,因此只需登录一次——而非每次会话都登录——且不会向宿主机写入任何内容。

-v agv-venv:/opt/venv

在会话之间保留已安装的Python包(并避免使用缓慢的绑定挂载)。

-p 8080 -p 8000 -p 6274 -p 6277

发布端口,使Mac上的浏览器可以访问容器内运行的服务:gov_mcp/server.py在8080,adk web在8000,MCP Inspector的Web UI在6274,以及它所通信的代理在6277(没有代理端口,UI毫无用处)。仅发布端口还不够——容器内绑定到127.0.0.1的服务器从外部无法访问,因此必须传递--host 0.0.0.0。

--rm

退出时删除容器。安全——所有值得保留的内容都在上述两个卷中。

你的提示符变为ubuntu@…:/workspace$。你已进入。

从这里开始,所有操作都在容器内部进行。

2. 一次性设置与身份验证

bash docker/post-create.sh    # creates the python env, installs deps, runs the tests

# BOTH logins are required and they are NOT interchangeable:
#   the first authenticates the gcloud CLI
#   the second writes Application Default Credentials, which Terraform and
#   every google-cloud-* python client read instead
gcloud auth login --no-launch-browser
gcloud auth application-default login --no-launch-browser

gcloud auth application-default print-access-token >/dev/null && echo "ADC OK"

每次登录都会打印一个URL供你在浏览器中打开,并要求你将验证码粘贴回来。在第二个同意页面上,勾选每一个权限框(“全选”)——部分同意会以令人困惑的Scope has changed崩溃告终,而且你需要cloud-platform作用域才能让任何功能正常工作。在打印出ADC OK之前不要继续。

→ 如果同意页面报错:陷阱0b

3. 创建你的沙箱GCP项目

export PROJECT_ID="agent-gov-auditor-$(date +%y%m%d)"   # must be globally unique
gcloud projects create "$PROJECT_ID" --name="agent-governance-auditor"
gcloud config set project "$PROJECT_ID"

gcloud billing accounts list                             # copy your account id
gcloud billing projects link "$PROJECT_ID" --billing-account=XXXXXX-XXXXXX-XXXXXX

# REQUIRED: attribute ADC API calls to your project. User credentials carry no
# project of their own, so without this Terraform gets a 403 SERVICE_DISABLED
# blaming Google's shared ADC client project (764086051850).
gcloud auth application-default set-quota-project "$PROJECT_ID"

gcloud config set run/region us-central1

Terraform运行之前必须关联结算账户——启用API需要它。

→ 如果在命名项目764086051850时遇到403错误:陷阱0c

4. 配置基础设施

创建已启用的API、服务账号(包括那个故意过度授权的“流氓”账号)、证据存储桶、预算、审计日志接收器和Artifact Registry仓库。

cd infra
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: project_id, billing_account_id, region
terraform init
terraform plan
terraform apply

如果 apply 在账单预算上失败,这在某些账户上是意料之中的——预算需要账户级权限,而不是项目级权限。在 Console 中创建一次,然后 terraform import,或者注释掉相关资源。别浪费一个晚上。

→ 如果第一次 apply 就遇到一堵 SERVICE_DISABLED 的墙:gotcha 0e —— 通常重新运行一次就好了

5. 部署一切

一条命令就能在 Terraform 基线之上构建并部署整个环境,按依赖顺序执行,并打印每个阶段的耗时。实测:整个四代理集群耗时 6 分 57 秒。

./scripts/deploy-all.sh

然后在 Gemini Enterprise 应用中打开它(Agents → 3-dot → Preview),发送:

对本项目执行一次治理审计。

运行会在审批门禁处停下。回复 APPROVE 以授权修复,或回复 APPROVE <finding id> 只修复子集,或回复 DECLINE。(GE 和 Agent Runtime Playground 不会为 ADK 的实验性确认原语渲染确认按钮,所以门禁也接受纯文本回复。)

更喜欢终端?或者想不用浏览器直接驱动它:

python scripts/query_agent_runtime.py        # multi-turn chat against the deployed agent

→ 如果部署的代理返回 401 或在门禁处卡住:gotcha 0q 和 0r

6. 拆除、重建、循环

软拆除只会移除部署脚本创建的内容,保留 Terraform 管理的所有资源——这样你可以在几分钟内重新走完整个部署路径,而不需要 20 分钟的项目引导。这也是演示前最好的排练,因为流程完全一致。

./scripts/teardown-workloads.sh     # prompts first; --yes to skip
terraform -chdir=infra plan         # expect NO changes — proves the split is clean
./scripts/deploy-all.sh             # back up in ~6 minutes

移除

保留

GE 应用 + 代理注册

项目、已启用的 API

Agent Runtime 部署

服务账号及其 IAM

指向已删除代理的过期 IAM 绑定

证据与暂存桶

gov-mcp 和四个被审计服务

预算、审计日志接收器

Artifact Registry 及其镜像,以便快速重建

证据是故意不删除的:桶带有 30 天保留策略,会拒绝删除请求。这也是设计上的不可变性——看着删除被拒绝,比任何口头保证都更有说服力。

部署链路

当某个环节失败、需要单独重跑某一步时,这条链路会很有用:

scripts/deploy-all.sh
├─ 1. auditee fleet
│      auditees/deploy-{compliant,legacy,rogue,insights}.sh
│        └─ each sources auditees/common.sh → build_image()
│             └─ gcloud builds submit  (Dockerfile + main.py + requirements.txt)
│                  └─ Artifact Registry
│           then gcloud run deploy, with posture set by FLAGS only
├─ 2. gov_mcp/deploy.sh                  → Cloud Build → Cloud Run (MCP server)
├─ 3. auditor/deploy.sh                  → Agent Runtime + its two IAM bindings
└─ 4. scripts/setup-gemini-enterprise.sh → GE app + agent registration + sharing

关于这条链路,有三件事值得知道:

  • common.sh 是一个被 source 的库,不是脚本。 它定义 PROJECT_ID、REGION、IMAGE 和 build_image()。直接运行它不会有任何效果。

  • 一个镜像,四个部署。 所有四个被审计服务运行的是同一个容器;它们的治理姿态完全由 gcloud run deploy 的标志决定——标签、服务账号、环境变量——这正是审计员检查的内容。所以第一个脚本负责构建,其余的直接复用。

  • build_image() 在镜像已存在时会跳过构建。 编辑 auditees/main.py 后,直接重新部署会推送旧镜像,你的更改会悄无声息地不生效。强制一次:FORCE_BUILD=1 ./auditees/deploy-compliant.sh。

第 2 步和第 3 步也可以单独运行(./auditor/deploy.sh 只重新部署代理),而且每个脚本都是幂等的——重复运行是安全的。

离开再回来: exit 会结束会话并移除容器。重新运行同一条 docker run … 命令就能回来——你的 gcloud 登录状态和已安装的包都还在,因为它们存放在 agv-gcloud 和 agv-venv 卷中,而不是容器里。要彻底清空并从头开始:docker volume rm agv-gcloud agv-venv。

出问题时,先查 gotchas 与 sharp edges 再动手调试——里面记录了我们实际踩过的坑,包括 Scope has changed 认证崩溃、mcp.shared.session 导入错误、gcloud 虚拟环境/VPN 失败,以及为什么某些检查在个人项目上会合理地报告 SKIPPED。

以上是顺利路径。docs/build-plan.md 承载了其余内容:操作规则、我们实际遇到的所有坑,以及每项决策背后的原因记录。

仓库结构

路径

内容

docs/architecture-plan.md

架构与组件规划

docs/build-plan.md

操作规则、坑、决策日志

docs/demo-and-pitch.md

演示脚本、评分标准映射、备好答案、覆盖范围限制

docs/regulatory-timeline.md

欧盟《人工智能法案》目前实际要求什么,附来源

policies/

版本化策略包(YAML——治理规则,可审查且随 git 版本化)

gov_mcp/

gov-mcp——自定义 MCP 服务器(FastMCP、Cloud Run)。命名为 gov_mcp,绝不叫 mcp,以免遮蔽 MCP SDK

auditor/

ADK 应用——SequentialAgent 流水线、带类型的会话状态、Agent Runtime

auditees/

演示集群——四个服务,各自带有刻意设计的姿态

infra/

整个沙箱的 Terraform

evals/

确定性与代理层评估框架——171 个离线测试,8 个在线测试

docker/

开发容器

scripts/

脚本

作用

deploy-all.sh

按顺序构建并部署每个工作负载,带计时

teardown-workloads.sh

软拆除——移除工作负载,保留 Terraform 基线

setup-gemini-enterprise.sh

完全通过 API 创建 GE 应用并注册代理——无需控制台点击,无需 OAuth 客户端

query_agent_runtime.py

从终端与已部署的代理进行多轮对话

verify-report.sh

重新计算报告哈希及其引用的每条证据——不信任审计员

evidence.sh

浏览并美化打印证据存储

construct_auth_uri.py

构建 OAuth 授权 URI——万一 GE 集成以后需要的话

measure_local.py

本地运行流水线,打印墙钟时间与每步 token 消耗——每次迭代只需几秒,而不是 3 分钟的重部署

demo.sh

现场 rogue-agent 演示脚本

测试

pytest evals/ -q              # 171 offline, no GCP needed, free
pytest evals/agent -m live    # 8 end-to-end agent evals (~100s, ~$0.02, needs ADC)

在线测试套件驱动真实的流水线,并断言单元测试在结构上无法验证的事情:运行确实到达了门禁,在人工批准之前没有任何修复被执行,批准 token 从未到达聊天层,并且每一个失败发现都带有有效的证据哈希。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Provides cryptographic signing and verification for AI decisions to generate verifiable, Ed25519-signed receipts for compliance and auditing. It automatically maps AI actions to regulatory frameworks like HIPAA and SOX with high-performance, sub-3ms signing.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides automated EU AI Act compliance tools, including risk classification, role determination, transparency disclosures, content watermarking, deepfake labeling, and security threat detection.
      16
      35
      Apache 2.0