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 权限使用本工具前需要满足两个条件认证MCP Toolbox 使用 Google Cloud 的 Application Default CredentialsADC 完成对 Cloud Storage 的认证与鉴权。服务启动前需先配置好 ADC。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 配置了allowedBucketssource.md则本工具只能读取白名单内的存储桶对白名单外桶的请求会在源码的validateBucket阶段直接拒绝见 internal/sources/cloudstorage/cloudstorage.go。参数说明parametertyperequireddescriptionbucketstringtrue要查询 IAM policy 的 Cloud Storage 存储桶名称。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配置字段参考fieldtyperequireddescriptiontypestringtrue必须为 cloud-storage-get-bucket-iam-policy。sourcestringtrue提供该桶 IAM 策略的 Cloud Storage source 名称。descriptionstringtrue传给 LLM 的工具描述帮助模型判断何时使用该工具。bucketstringfalse固定返回 IAM policy 的存储桶。设置后运行时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 对象包含以下字段fieldtypedescriptionbucketstring被读取 IAM policy 的 Cloud Storage 存储桶名称。bindingsarrayIAM 绑定列表每个绑定包含role、members以及可选的condition字段。单个 binding 的结构来自 cloudstorage.go 的实现{ bucket: my-app-bucket, bindings: [ { role: roles/storage.objectViewer, members: [ serviceAccount:app-saproject.iam.gserviceaccount.com, user:aliceexample.com ] }, { role: roles/storage.objectAdmin, members: [group:data-teamexample.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、Buckettype 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.godescription为空会直接报错若cfg.Bucket ! nil *cfg.Bucket 报 bucket cannot be empty 错误只有当cfg.Bucket nil未配置时才向工具的 manifest 追加名为bucket的字符串参数。也就是说配置了固化桶名后LLM 看到的工具 schema 中将不再出现bucket参数。3. 调用参数解析与分发Invoke是运行时入口cloudstoragegetbucketiampolicy.go将params转为 map通过cloudstoragecommon.ResolveString(t.Cfg.Bucket, mapParams, bucketKey)优先级合并配置的桶名优先未配置时取运行时参数值若解析结果为空返回AgentErrorinvalid or missing bucket parameter; expected a non-empty string——这是故意设计因为缺失桶名属于 Agent 可通过修正入参自行恢复的错误类别调用 source 的GetBucketIAMPolicy(ctx, bucket)出错时交给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 的是两类错误AgentErrorAgent 可自行修正如存储桶不存在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.goTestParseFromYamlCloudStorageGetBucketIAMPolicy验证三种 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考