iam-recommendations-fetcher
Fetches raw IAM recommendations and associated security insights from Google Cloud for a specified target scope (Organization, Folder, or Project). Use when you need to retrieve security recommendations before analyzing or applying them. Don't use for applying/acting on recommendations (use the recommendation applier skill) or for general allow policy querying (use the allow policy viewer skill).
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- iam-recommendations-fetcher
- metadata
- { "category": "Identity" }
- description
- Fetches raw IAM recommendations and associated security insights from Google Cloud for a specified target scope (Organization, Folder, or Project). Use when you need to retrieve security recommendations before analyzing or applying them. Don't use for applying/acting on recommendations (use the recommendation applier skill) or for general allow policy querying (use the allow policy viewer skill).
02 资源文件 2
- 参考文档metadata.json626 B
- 参考文档verification.json1.3 KB
03 SKILL.md 正文
IAM Recommendations Retrieval
This skill provides instructions for fetching IAM recommendations and insights from Google Cloud. It covers validating the input target scope, retrieving recommendations using MCP tools, gcloud commands, or direct API calls, and handling common API errors.
Procedures
1. Validate Input Target
Verify the input target scope.
-
Check Format: Check if the target matches one of these formats:
organizations/{org_id}folders/{folder_id}projects/{project_id}
-
Handle Ambiguous/Raw Target: If the user provides only a raw ID (without the prefix):
- Alphanumeric (starts with a letter): Assume it is a Project ID.
Format it as
projects/{project_id}and proceed. - Purely Numeric: It is ambiguous (could be Organization, Folder, or
Project Number).
- Ask the user to clarify the resource type: > "Is the target ID '{provided_id}' an Organization, a Folder, or a Project?"
- Once the user specifies, format the target scope accordingly (e.g.,
prepend
organizations/,folders/, orprojects/) and proceed. - If the user's response is invalid or they cannot clarify, treat it as an error and proceed to Handle Errors (incorrect target).
- Alphanumeric (starts with a letter): Assume it is a Project ID.
Format it as
-
Handle Project Numbers: If the target is a project but uses a purely numeric ID (Project Number) instead of a Project ID (e.g.,
projects/123456789):gcloudrecommender commands require a Project ID. Attempt to resolve the Project Number to a Project ID using:gcloud projects list --filter="projectNumber={project_number}" --format="value(projectId)"- If this resolution returns empty or fails with a permission error, do not attempt to describe the project, search the codebase, or search for mock data. Immediately return the standardized error JSON specified in Handle Errors and stop execution (do not call any more tools).
-
Record Validation: Explicitly state the validated and formatted target scope (e.g.,
projects/123456789ororganizations/123456789012) in your thought/reasoning before proceeding to the fetch step.
2. Fetch Recommendations and Insights (Fallback Flow)
Attempt the following retrieval methods in order. Stop at the first success.
CRITICAL: Fail Fast on Errors (To avoid redundant API calls that will fail
for the same authorization/permission reasons): If any attempted method (Option
A or Option B) fails with an API-level error (such as PERMISSION_DENIED,
UNAUTHENTICATED, or resource NOT_FOUND / does not exist) or a CLI validation
error (such as project number not allowed), do NOT attempt any further
options (including Option C or direct API/curl calls). Stop immediately, do
not call any more tools, and return the standardized error JSON as specified in
the "Handle Errors" section.
Option A: MCP Tool (Preferred)
Use the MCP tool if available. MCP tools are designed for efficient, secure execution within Google's internal environments, often providing streamlined authentication and better integration compared to general-purpose CLI commands.
If an IAM Recommender MCP tool is available in your context:
- Call the tool with the
targetparameter.
Option B: gcloud CLI (First Fallback)
If MCP is unavailable, use run_command to execute the following (replace
variables accordingly):
| Target | Flag |
|---|---|
projects/{project_id} |
--project={project_id} |
folders/{folder_id} |
--folder={folder_id} |
organizations/{organization_id} |
--organization={organization_id} |
Commands to run:
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}
Option C: Google Cloud API (Final Fallback)
Only attempt this option if gcloud is physically unavailable in the
environment (e.g., gcloud: command not found). API client libraries require
more setup and execution overhead, so they are only used as a last resort if CLI
tools are missing. Do NOT use this option if gcloud is available but failed
with an API error.
Use Google Cloud Recommender API client libraries via a helper script (or direct API calls if libraries are unavailable) to:
- Call
list_recommendations(orrecommendations.list) forgoogle.iam.policy.Recommender(filter:stateInfo.state=ACTIVE). - Call
list_insights(orinsights.list) forgoogle.iam.policy.Insight(filter:stateInfo.state=ACTIVE).
3. Determine Output Format and Deliver
CRITICAL: Only proceed to this step if the retrieval in Step 2 was successful. If the retrieval failed, skip this step and go directly to Handle Errors.
Before presenting the results, determine the desired output format.
CRITICAL: If the user's initial prompt already specifies the output format (e.g., "return the raw results in JSON" or "show it in a table"), bypass asking and proceed directly to that format.
Otherwise, ask the user in a dropdown menu, with the options being:
- JSON file
- Markdown table in chat
Based on the choice (either pre-specified or chosen by the user), deliver the output:
Option A: JSON File
- Write the raw results to a file named
iam_recommendations_<target_id>_<timestamp>.json(where<target_id>is the sanitized resource identifier and<timestamp>is formatted asYYYYMMDD_HHMMSS) in the current working directory. - The file content must match the structure shown in Example Execution.
- Respond to the user with the file path.
Option B: Chat Table
- Sort Recommendations: Sort the retrieved recommendations, placing service agent recommendations last in the list.
- Format Table: Format the sorted recommendations into a markdown table.
The table should contain key fields:
- Subtype: The recommender subtype or insight subtype (e.g., indicating if it's for resource-level roles).
- Recommended Action: Summary of the recommendation.
- Rationale: Rationale/justification.
- Associated Insights: The IDs of any linked insights (from
associatedInsights).
- Limit Chat Display: Display only the top 10 recommendations in the chat table.
- Provide Full List: Save the complete list of recommendations and
insights to a markdown file (e.g.,
iam_recommendations_<target_id>_<timestamp>.md, where<target_id>is the sanitized resource identifier and<timestamp>is formatted asYYYYMMDD_HHMMSS) and provide a link for the user to download it. - Format Insights Table: If insights are present, format them in a
separate table in the markdown file (and optionally show a summary in chat
if appropriate, but keep the chat clean). The table should contain key
fields:
- Insight ID: The insight identifier (
INSIGHT_ID). - State: The insight state (
INSIGHT_STATE). - Subtype: The insight subtype (
INSIGHT_SUBTYPE). - Description: Description of the insight (
DESCRIPTION).
- Insight ID: The insight identifier (
- DO NOT provide a JSON file with the raw results if this option is chosen.
4. Example Execution
-
Input Target: projects/my-test-project
-
Mapped Flag: --project=my-test-project
-
Action (Option B): Run
gcloud recommender recommendations list --recommender=google.iam.policy.Recommender --format=json --location=global --filter=stateInfo.state=ACTIVE --project=my-test-project -
Expected Output Structure:
{ "raw_results": { "recommendations": [ { "name": "projects/my-test-project/locations/global/recommenders/ \ google.iam.policy.Recommender/recommendations/123", "content": { ... } } ], "insights": [] }, "error": null }
5. Handle Errors
CRITICAL: If you encounter any of the error conditions below (during validation or fetch), stop immediately. Do not attempt to debug, switch accounts, search the codebase, or verify resource existence. Immediately output the specified JSON structure as your final response and call no further tools.
If all methods fail, return:
- For incorrect target:
{"raw_results": null, "error": "The specified target resource is incorrect or does not exist."} - For authentication issues:
{"raw_results": null, "error": "User is unauthenticated. Please authenticate (e.g., run 'gcloud auth login')."} - For permissions:
{"raw_results": null, "error": "Insufficient permissions. Please ensure you have 'roles/recommender.iamViewer' on the target scope."} - Other:
{"raw_results": null, "error": "Failed to fetch: {error_details}"}(Do not mention MCP tool failures to the user).
Gotchas
- State Filter: Always ensure you are filtering for
ACTIVErecommendations. - Location: The location for IAM Recommender is always global.
04 同仓库更多 Skills
zkrouter
Self-hosted OpenAI-compatible LLM router — smart tier-based routing, ZK-stamped routing decisions, mode overrides, free OpenRouter at install via the Birth bot. Save 60-80% on inference costs by routing to the cheapest capable model across 12+ OpenRouter models.
zk
For custom ZK Solana programs and privacy-preserving applications to prevent double spending. Guide to integrate rent-free nullifier PDAs for double-spend prevention.
zk-omni-messaging
Zero-knowledge omnichain messaging between Robinhood Chain and Solana using CheshireZkOmniMessenger (msgType 4) with nullifier anti-replay and the zk-omni-relayer service.
zerion-wallet-data
Use when the user asks to check a wallet's portfolio, token balances, DeFi positions, PnL, transaction history, or NFTs. Provides interpreted on-chain data across 40+ EVM chains and Solana via x402 pay-per-request or API key — no raw RPC decoding needed.
youtube-clipper
YouTube 视频智能剪辑工具。下载视频和字幕,AI 分析生成精细章节(几分钟级别), 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频,并生成总结文案。 使用场景:当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词:视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video
yield-optimization
Multi-chain yield optimization via yield.xyz (StakeKit). Discover 2,988+ yield opportunities across 75+ blockchains, build deposit/withdrawal transactions with shell scripts, and sign them with a MoonPay wallet. Use when the user wants to earn yield, find the best lending or staking rate, enter/exit a position, or check portfolio balances.