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 を使用して次を実行します（変数は適宜置き換えてください）。

対象	フラグ
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 エラーが発生した場合は、このオプションを使用しないでください。

ヘルパースクリプト（または、ライブラリが利用できない場合は直接 API を呼び出す方法）を使用して、Google Cloud Recommender 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. 推奨事項を並べ替える：取得した推奨事項を並べ替え、サービスエージェントに関する推奨事項をリストの最後に配置します。
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": "指定された対象リソースが正しくないか、存在しません。"}
• 認証に問題がある場合: {"raw_results": null, "error": "認証されていません。認証してください（例: 'gcloud auth login' を実行）。"}
• 権限が不足している場合: {"raw_results": null, "error": "権限が不足しています。対象スコープで 'roles/recommender.iamViewer' が付与されていることを確認してください。"}
• その他: {"raw_results": null, "error": "取得に失敗しました: {error_details}"} （MCP ツールの失敗についてユーザーに伝えないでください）。

注意事項

• 状態フィルター: 常に ACTIVE の推奨事項を対象にするフィルターを設定してください。
• ロケーション: IAM Recommender のロケーションは常に global です。