MCP Toolbox 之 cloud-storage-get-bucket-iam-policy 工具：只读查询 Cloud Storage 存储桶 IAM 策略绑定

MCP Toolbox 之 cloud-storage-get-bucket-iam-policy 工具：只读查询 Cloud Storage 存储桶 IAM 策略绑定

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

本文讲解 MCP Toolbox 提供的cloud-storage-get-bucket-iam-policy工具：它用于只读返回指定 Cloud Storage 存储桶的 IAM 策略绑定（哪些主体拥有哪些角色），是进行权限审计、访问控制排查与合规检查时的核心工具。读完本文，你将掌握该工具的 YAML 配置方式（动态传参与配置固化两种模式）、运行前置要求、输出结构，以及它在仓库源码中的完整实现链路与错误处理语义。

工具概述

cloud-storage-get-bucket-iam-policy是 MCP Toolbox 的 Cloud Storage 集成中一个用于查看访问控制的工具。它调用 Cloud Storage 的 IAM 接口读取存储桶的 IAM policy，并返回结构化的绑定信息，只读取、不修改任何访问配置，因此可以安全地交给 LLM Agent 在排查"谁有权限访问这个桶"、"某个角色绑定了哪些成员"等问题时使用。

该工具的定位与同族的只读工具（如cloud-storage-get-bucket-metadata、cloud-storage-list-buckets）一样，被标记为只读注解（read-only annotations），源码中通过tools.NewReadOnlyAnnotations生成（见 internal/tools/cloudstorage/cloudstoragegetbucketiampolicy/cloudstoragegetbucketiampolicy.go），便于客户端据此判断工具的安全性。

工作前提：认证与 IAM 权限

使用本工具前需要满足两个条件：

1. 认证：MCP Toolbox 使用 Google Cloud 的 Application Default Credentials（ADC） 完成对 Cloud Storage 的认证与鉴权。服务启动前需先配置好 ADC。
2. IAM 权限：运行 MCP Toolbox 的 IAM 身份必须具备读取目标存储桶 IAM policy的权限（对应storage.buckets.getIamPolicy权限）。常用角色如roles/storage.legacyBucketReader、roles/storage.objectViewer或更高的roles/storage.admin均可满足；具体请参考 Cloud Storage Source 文档 中的 IAM Permissions 一节。

此外，如果 Cloud Storage source 配置了allowedBuckets（source.md），则本工具只能读取白名单内的存储桶；对白名单外桶的请求会在源码的validateBucket阶段直接拒绝（见 internal/sources/cloudstorage/cloudstorage.go）。

参数说明

bucket参数有两种提供方式，决定其是否出现在运行时参数表中：

• 运行时传入：工具配置中不写bucket，则 LLM 在调用时动态提供桶名；
• 配置固化：工具配置中写入bucket，则该参数会从运行时参数 schema 中移除，调用时始终使用配置的桶名。配置值必须是非空字符串，否则工具初始化会直接报错。

配置示例

方式一：动态指定存储桶

适用于需要 Agent 根据上下文灵活选择桶的场景（例如"列出生产项目中所有桶的权限"）：

kind: tool name: get_bucket_iam_policy type: cloud-storage-get-bucket-iam-policy source: my-gcs-source description: Use this tool to inspect IAM bindings for a Cloud Storage bucket.

方式二：固化存储桶

适用于只针对某一个固定应用桶的场景，Agent 无需也不能传入桶名：

kind: tool name: get_app_bucket_iam_policy type: cloud-storage-get-bucket-iam-policy source: my-gcs-source description: Use this tool to inspect IAM bindings for the application bucket. bucket: my-app-bucket

配置字段参考

其中source引用的必须是类型为cloud-storage的 source 配置，例如 internal/prebuiltconfigs/tools/cloud-storage.yaml 中的cloud-storage-source。若引用的 source 不兼容，工具初始化时会在ValidateSource中报 "source is not a compatible type" 错误（见 cloudstoragegetbucketiampolicy.go）。

输出格式

工具返回一个 JSON 对象，包含以下字段：

单个 binding 的结构（来自 cloudstorage.go 的实现）：

{ "bucket": "my-app-bucket", "bindings": [ { "role": "roles/storage.objectViewer", "members": [ "serviceAccount:app-sa@project.iam.gserviceaccount.com", "user:alice@example.com" ] }, { "role": "roles/storage.objectAdmin", "members": ["group:data-team@example.com"], "condition": { "title": "only-on-weekdays", "description": "Temporary access grant", "expression": "request.time.getDayOfWeek() >= 1 && request.time.getDayOfWeek() <= 5" } } ] }

值得注意的几点输出语义（均可从源码 GetBucketIAMPolicy 印证）：

• 每个 binding 中的members会被按字典序排序（sort.Strings），保证输出稳定、便于 Agent 与人工比对；
• 当绑定带条件（condition）时，会输出title、description、expression三个子字段，完整保留条件式绑定信息，避免审计时遗漏带条件的授权；
• 整个bindings数组还会按 role 名排序，进一步保证输出顺序的确定性；
• 该工具不包含版本信息（etag/version），输出刻意精简为"桶名 + 绑定列表"这一 Agent 友好形态。

源码实现原理

1. 工具注册与配置解析

工具类型字符串cloud-storage-get-bucket-iam-policy在包初始化时通过tools.Register注册（cloudstoragegetbucketiampolicy.go），重复注册会触发 panic。配置结构体Config内联了通用ConfigBase，并声明Type、Source（均必填）与可选的Annotations、Bucket：

type Config struct { tools.ConfigBase `yaml:",inline"` Type string `yaml:"type" validate:"required"` Source string `yaml:"source" validate:"required"` Annotations *tools.ToolAnnotations `yaml:"annotations,omitempty"` Bucket *string `yaml:"bucket,omitempty"` }

注意Bucket是指针类型，这是区分"未配置"与"配置为空字符串"的关键设计。

2. 初始化：参数 schema 的动态裁剪

Initialize是"配置固化后隐藏运行时参数"这一行为的实现处（cloudstoragegetbucketiampolicy.go）：

• description为空会直接报错；
• 若cfg.Bucket != nil && *cfg.Bucket == ""，报 "bucket cannot be empty" 错误；
• 只有当cfg.Bucket == nil（未配置）时，才向工具的 manifest 追加名为bucket的字符串参数。也就是说，配置了固化桶名后，LLM 看到的工具 schema 中将不再出现bucket参数。

3. 调用：参数解析与分发

Invoke是运行时入口（cloudstoragegetbucketiampolicy.go）：

1. 将params转为 map；
2. 通过cloudstoragecommon.ResolveString(t.Cfg.Bucket, mapParams, bucketKey)优先级合并：配置的桶名优先，未配置时取运行时参数值；
3. 若解析结果为空，返回AgentError（"invalid or missing 'bucket' parameter; expected a non-empty string"）——这是故意设计，因为缺失桶名属于 Agent 可通过修正入参自行恢复的错误类别；
4. 调用 source 的GetBucketIAMPolicy(ctx, bucket)；
5. 出错时交给cloudstoragecommon.ProcessGCSError分类转换后返回。

4. Source 侧实现：真正的 IAM 读取

真正的 IAM 读取发生在 Cloud Storage source 上（internal/sources/cloudstorage/cloudstorage.go）：先做allowedBuckets校验，然后调用 Go 客户端s.client.Bucket(bucket).IAM().Policy(ctx)拉取策略，再从policy.InternalProto.Bindings逐条提取role、members，并在存在Condition时展开为title/description/expression，最后排序后返回。

工具侧通过compatibleSource接口（GetBucketIAMPolicy(ctx, bucket) (map[string]any, error)）与 source 解耦（cloudstoragegetbucketiampolicy.go），任何实现了该接口的 source 都能被本工具使用，便于测试时用 mock 替换。

错误处理语义

IAM 读取失败的错误会经 cloudstoragecommon/errors.go 的ProcessGCSError分类，最终返回给 Agent 的是两类错误：

• AgentError（Agent 可自行修正）：如存储桶不存在（storage.ErrBucketNotExist→ "cloud storage bucket does not exist"）、资源不存在（HTTP 404 → "cloud storage resource not found"）等；
• ClientServerError（基础设施故障，Agent 无法自愈）：如认证失败（HTTP 401）、权限不足（HTTP 403 → "cloud storage permission denied"）、限流（HTTP 429）等。当凭据缺少读取 IAM policy 的权限时，你会看到这类服务端错误。

这一分类遵循仓库 DEVELOPER.md 中 "Tool Invocation & Error Handling" 的设计原则，确保 LLM 拿到错误后知道该重试、改参还是停止。

测试验证

仓库为这个工具提供了完善的单元测试，可用于理解其行为边界（见 cloudstoragegetbucketiampolicy_test.go）：

• TestParseFromYamlCloudStorageGetBucketIAMPolicy：验证三种 YAML 配置（基础、带authRequired、带固化bucket）的解析结果；
• TestInvokeValidation：验证缺桶名时报AgentError且source 不会被调用；
• TestConfiguredBucketHiddenAndForwarded：固化桶名后 manifest 参数为空、调用时桶名被正确转发；
• TestUnsetBucketRemainsVisible：未固化时 manifest 中保留bucket参数；
• TestEmptyConfiguredBucketRejected：固化空字符串桶名在初始化阶段即被拒绝。

与其他工具的配合

本工具常与 Cloud Storage 桶管理类工具配合使用。仓库预置配置 internal/prebuiltconfigs/tools/cloud-storage.yaml 将其放入cloud-storage-buckets工具组，与list_buckets、create_bucket、get_bucket_metadata、delete_bucket并列。典型的审计场景是：先list_buckets枚举项目内桶，再对每个桶调用本工具检查权限绑定；若发现过度授权，再结合其他变更类工具收紧权限。由于本工具只读且输出稳定排序，非常适合嵌入到周期性的权限巡检流程中。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox