iam-recommendations-fetcher

IAM 建议检索

此技能提供从 Google Cloud 获取 IAM 建议和洞察的说明。 内容涵盖验证输入目标范围、使用 MCP 工具、gcloud 命令或直接 API 调用获取 建议，以及处理常见 API 错误。

操作流程

1. 验证输入目标

验证输入目标范围。

1. 检查格式：检查目标是否符合以下格式之一：

   • organizations/{org_id}
   • folders/{folder_id}
   • projects/{project_id}

2. 处理有歧义的目标／原始目标：如果用户只提供原始 ID（没有 前缀）：

   • 字母数字（以字母开头）：假设它是项目 ID。 将其格式化为 projects/{project_id}，然后继续。
   • 纯数字：存在歧义（可能是组织、文件夹或 项目编号）。
     • 请用户澄清资源类型：> “目标 ID ‘{provided_id}’ 是组织、文件夹还是项目？”
     • 用户说明后，按相应格式设置目标范围（例如， 添加 organizations/、folders/ 或 projects/ 前缀），然后继续。
     • 如果用户的回复无效或无法澄清，则将其视为错误，并继续执行 处理错误 （目标有误）。

3. 处理项目编号：如果目标是项目，但使用的是纯数字 ID（项目编号），而不是项目 ID（例如， projects/123456789）：

   • gcloud recommender 命令需要项目 ID。尝试使用以下命令将 项目编号解析为项目 ID：gcloud projects list --filter="projectNumber={project_number}" --format="value(projectId)"
   • 如果解析结果为空或因权限错误而失败，则不要尝试描述项目、搜索代码库或 搜索模拟数据。立即返回 处理错误中指定的标准错误 JSON，并停止执行（不要再调用 任何工具）。

4. 记录验证结果：在继续获取步骤之前，明确说明经过验证并格式化的目标 范围（例如，projects/123456789 或 organizations/123456789012），并将其记录在思考／推理中。

2. 获取建议和洞察（回退流程）

按以下顺序尝试检索方式。首次成功后即停止。

重要：遇到错误时立即停止（避免因相同的授权／权限原因重复调用 API，导致调用失败）：如果任何尝试的方法（选项 A 或选项 B）发生 API 级错误（例如 PERMISSION_DENIED、 UNAUTHENTICATED 或资源 NOT_FOUND／不存在），或 CLI 验证 错误（例如不允许使用项目编号），则不要尝试任何其他 选项（包括选项 C 或直接 API／curl 调用）。立即停止，不要再调用任何工具，并返回“处理错误”部分中指定的标准错误 JSON。

选项 A：MCP 工具（首选）

如果有 MCP 工具可用，请使用该工具。MCP 工具专为在 Google 内部环境中高效、安全地 执行而设计，与通用 CLI 命令相比，通常可提供更简便的身份验证和更好的集成。

如果你的上下文中有 IAM Recommender MCP 工具：

• 使用 target 参数调用该工具。

选项 B：gcloud CLI（首选回退方式）

如果 MCP 不可用，请使用 run_command 执行以下命令（相应地替换 变量）：

Target	Flag
projects/{project_id}	--project={project_id}
folders/{folder_id}	--folder={folder_id}
organizations/{organization_id}	--organization={organization_id}

要运行的命令：

GCLOUD_COMMON_FLAGS="--format=json --location=global \
--filter=stateInfo.state=ACTIVE"

# 1. Fetch Recommendations
gcloud recommender recommendations list \
--recommender=google.iam.policy.Recommender $GCLOUD_COMMON_FLAGS {mapped_flag}

# 2. Fetch Insights
gcloud recommender insights list --insight-type=google.iam.policy.Insight
$GCLOUD_COMMON_FLAGS {mapped_flag}

选项 C：Google Cloud API（最终备用方案）

仅当环境中确实无法使用 gcloud（例如，出现 gcloud: command not found）时，才尝试此选项。API 客户端库需要更多设置和执行开销，因此只有在缺少 CLI 工具时才作为最后手段使用。如果 gcloud 可用但发生 API 错误，请勿使用此选项。

通过辅助脚本使用 Google Cloud Recommender API 客户端库（如果无法使用客户端库，则直接调用 API）：

1. 对 google.iam.policy.Recommender 调用 list_recommendations（或 recommendations.list）（过滤条件：stateInfo.state=ACTIVE）。
2. 对 google.iam.policy.Insight 调用 list_insights（或 insights.list）（过滤条件：stateInfo.state=ACTIVE）。

3. 确定输出格式并交付

重要：仅当第 2 步成功检索到结果时，才继续此步骤。如果检索失败，请跳过此步骤，直接前往处理错误。

在呈现结果之前，确定所需的输出格式。

重要：如果用户在最初的提示中已指定输出格式（例如“以 JSON 返回原始结果”或“以表格展示”），则跳过询问，直接采用该格式。

否则，通过下拉菜单询问用户，并提供以下选项：

1. JSON 文件
2. 聊天中的 Markdown 表格

根据用户预先指定或选择的格式，交付输出：

选项 A：JSON 文件

1. 将原始结果写入当前工作目录中的文件，文件名为 iam_recommendations_<target_id>_<timestamp>.json（其中 <target_id> 是 经过清理的资源标识符，<timestamp> 的格式为 YYYYMMDD_HHMMSS）。
2. 文件内容必须符合执行示例所示的结构。
3. 向用户提供文件路径。

选项 B：聊天表格

1. 排序建议：对检索到的建议排序，将服务 Agent 的建议放在列表末尾。
2. 设置表格格式：将排序后的建议整理成 Markdown 表格。表格应包含以下关键字段：
   • 子类型：建议程序子类型或见解子类型（例如，说明是否适用于资源级角色）。
   • 建议操作：建议摘要。
   • 理由：理由/依据。
   • 关联见解：任何关联见解的 ID（来自 associatedInsights）。
3. 限制聊天显示内容：在聊天表格中仅显示前 10 条建议。
4. 提供完整列表：将完整的建议和见解列表保存到 Markdown 文件中（例如， iam_recommendations_<target_id>_<timestamp>.md，其中 <target_id> 是经过清理的资源标识符，<timestamp> 的格式为 YYYYMMDD_HHMMSS），并提供下载链接。
5. 设置见解表格格式：如果存在见解，请在 Markdown 文件中将其整理到单独的表格中（也可酌情在聊天中显示摘要，但请保持聊天内容简洁）。表格应包含以下关键字段：
   • 见解 ID：见解标识符（INSIGHT_ID）。
   • 状态：见解状态（INSIGHT_STATE）。
   • 子类型：见解子类型（INSIGHT_SUBTYPE）。
   • 描述：见解描述（DESCRIPTION）。
6. 请勿在选择此选项时提供包含原始结果的 JSON 文件。

4. 执行示例

• 输入目标：projects/my-test-project

• 映射的标志：--project=my-test-project

• 操作（选项 B）：运行 gcloud recommender recommendations list --recommender=google.iam.policy.Recommender --format=json --location=global --filter=stateInfo.state=ACTIVE --project=my-test-project

• 预期输出结构：

  {
    "raw_results": {
      "recommendations": [
        {
          "name": "projects/my-test-project/locations/global/recommenders/ \
          google.iam.policy.Recommender/recommendations/123",
          "content": { ... }
        }
      ],
      "insights": []
    },
    "error": null
  }
  

5. 处理错误

重要：如果遇到以下任何错误情况（验证或获取期间），请立即停止。不要尝试调试、切换账号、搜索代码库或验证资源是否存在。立即将指定的 JSON 结构作为最终回复输出，且不要调用其他工具。

如果所有方法都失败，则返回：

• 目标不正确：{"raw_results": null, "error": "The specified target resource is incorrect or does not exist."}
• 身份验证问题：{"raw_results": null, "error": "User is unauthenticated. Please authenticate (e.g., run 'gcloud auth login')."}
• 权限问题：{"raw_results": null, "error": "Insufficient permissions. Please ensure you have 'roles/recommender.iamViewer' on the target scope."}
• 其他问题：{"raw_results": null, "error": "Failed to fetch: {error_details}"} （不要向用户提及 MCP 工具失败）。

注意事项

• 状态筛选器：始终确保筛选的是 ACTIVE 建议。
• 位置：IAM Recommender 的位置始终为 global。