iam-recommendations-simulator

IAM Policy Simulator（バッチ実行ツール）

このスキルは、Google Cloud Policy Simulator を使用して、提案された IAM ポリシー変更の単一バッチをシミュレーションします。複数のバッチを順に処理したり、フォールバックロジックを実行したりすることはなく、提供された入力に対するシミュレーションの実行のみに特化しています。

入力

入力は、シミュレーションの配列を含む JSON オブジェクトである必要があります。

{
  "simulations": [
    {
      "id": "sim_1",
      "resource": "//cloudresourcemanager.googleapis.com/projects/my-project",
      "member": "user:[email protected]",
      "proposed_policy": {
        "bindings": [
          {
            "role": "roles/viewer",
            "members": [
              "user:[email protected]"
            ]
          }
        ],
        "etag": "...",
        "version": 1
      }
    }
  ]
}

各シミュレーションオブジェクトには、次の項目が必要です。

• id：シミュレーションを識別する一意の ID（例：シミュレーション名）。
• resource：対象リソースの完全な名前（// で始まる必要があります）。
• member：プリンシパル（例：user:、serviceAccount:、group:）。
• proposed_policy / proposed_policy_file：提案する IAM ポリシーを表す JSON オブジェクト（proposed_policy）、または既存のローカル JSON ポリシーファイルへのパスを示す文字列（proposed_policy_file、または proposed_policy の文字列パス）。

手順

1. 入力バッチを解析する

ユーザーのリクエストからシミュレーションの入力バッチを特定します。

• 外部ファイル：リクエストでファイルパス（例：batch.json）が指定されている場合は、view_file ツールを使用して内容を読み取ります。ファイルの検索に grep、find、シェルコマンドを使用してはいけません。
• インライン入力：シミュレーションの JSON 配列またはオブジェクトがプロンプト内に直接記載されている場合は、コンテキストから直接解析します。

2. API を確認する

アクティブなプロジェクトで、必要な API が有効になっているか確認します。

• policysimulator.googleapis.com

有効になっていない場合は、自動的に有効化してはいけません。API の有効化には費用が発生する可能性があります。処理を中断し、次のようにユーザーへ明示的に確認してください。「Policy Simulator API（policysimulator.googleapis.com）はこのプロジェクトで有効になっていません。有効化すると費用が発生する可能性があります。この API の有効化を許可しますか？」

重要：API の確認で問題が発生した場合は即時中断する：API ステータスの確認（例：gcloud services list）が、認証情報の不足、権限エラー、またはサンドボックス化されたテスト環境の制約によって失敗した場合、認証情報のデバッグ、認証ログイン、独自の確認スクリプトを試してはいけません。処理を直ちに中断し、API の有効化についてユーザーに明示的に許可を求めてください。

ユーザーから明示的な確認を受け取った後に限り、有効化コマンドを実行してください。

gcloud services enable policysimulator.googleapis.com

3. ポリシーファイルを準備する

入力バッチ内の各シミュレーションについて、次の処理を行います。

1. sim.id（またはインデックス）から、サニタイズ済みのファイル識別子 {sim_id} を作成します。
2. 提案するポリシーについて、次の処理を行います。
   • sim.proposed_policy が JSON オブジェクトの場合は、ネイティブのファイル書き込みツール（または安全なライブラリ）を使用して、/tmp/proposed_policy_SIM_ID.json に書き込みます。PROPOSED_POLICY_PATH を /tmp/proposed_policy_SIM_ID.json に設定します。
   • sim.proposed_policy_file（または文字列パスとしての sim.proposed_policy）が指定されている場合は、そのファイルがディスク上に存在することを確認し、PROPOSED_POLICY_PATH をそのファイルパスに直接設定します。

4. シミュレーションを実行する（フォールバックフロー）

提案されたポリシーをオーバーレイとして使用して、シミュレーションを実行します。

• オーバーレイを構築する：オーバーレイは、リソースの完全な名前を提案されたポリシーの内容に対応付けるマッピングです。

以下のシミュレーション実行方法を順番に試します。最初に成功した方法で停止します。

重要：エラーが発生した場合は即時中断する（同じ認可／権限の理由で失敗する冗長な API 呼び出しを避けるため）：試行した方法（オプション A またはオプション B）のいずれかが、API レベルのエラー（PERMISSION_DENIED、UNAUTHENTICATED、NOT_FOUND、INVALID_ARGUMENT など）またはグループメンバーシップによる阻害要因で失敗した場合、オプション C や API／curl の直接呼び出しを含む、それ以降の方法を試してはいけません。直ちに処理を中断し、これ以上ツールを呼び出さず、「出力形式」に指定されたとおり、ステータスが FAILED または BLOCKED の構造化 JSON 出力を返します。

オプション A：MCP ツール（推奨）

利用可能な場合は、MCP ツールを使用してください。MCP ツールは、Google の内部環境で効率的かつ安全に実行できるよう設計されており、汎用的な CLI コマンドと比べて、認証が簡素化され、統合性も高い場合が多くあります。

利用環境で IAM Policy Simulator MCP ツールが利用できる場合：

• シミュレーションのオーバーレイパラメーターを指定してツールを呼び出します。

オプション B：gcloud CLI（最初の代替手段）

MCP を利用できない場合は、シェルのリダイレクトやパイプを使わずに、シミュレーションの再生コマンドを直接実行してください。

gcloud iam simulator replay-recent-access FULL_RESOURCE_NAME PROPOSED_POLICY_PATH --format=json

JSON 出力をメモリ上に直接取り込みます（必要に応じて、/tmp/raw_result_SIM_ID.json に保存します）。重要：非同期実行： run_command がコマンドをタスクとしてバックグラウンドで実行する場合、タスクログの URI（task-*.log）を読み取ったり表示したりしないでください。ツールの呼び出しを終了してターンを終え、コマンドの完了がシステムから自動通知されるのを待ちます。再生結果を待ったり検索したりする目的で、grep、find、シェルコマンドを使用しないでください。

オプション C：Google Cloud API（最後の代替手段）

このオプションを試すのは、環境で gcloud が物理的に利用できない場合（例：gcloud: command not found）に限ります。API クライアントライブラリは、セットアップと実行に余分な手間がかかるため、CLI ツールが利用できない場合の最後の手段としてのみ使用します。gcloud が利用可能で API エラーが発生した場合は、このオプションを使用しないでください。

Google Cloud Policy Simulator API のクライアントライブラリ（ライブラリが利用できない場合は、v1/projects/{project}/locations/global/replays への直接 REST API 呼び出し）を使用して、次の操作を行います。

1. 再生オペレーションを作成します。
2. オペレーションが完了するまでポーリングします。
3. 再生結果を取得します。

5. 出力の確認と処理

1. コマンドの成功と出力の有効性を確認する：

   • 終了ステータス：シミュレーションコマンドの実行後、終了ステータスを確認します。終了ステータスがゼロ以外の場合は失敗を示します。コマンドが失敗した場合は、次を返します。
     • status：FAILED
     • error：Simulation command failed for SIM_ID. Check logs for details.
   • 有効な JSON：コマンド出力（または /tmp/raw_result_SIM_ID.json）に有効な JSON が含まれていることを確認します。有効でない場合は、次を返します。
     • status：FAILED
     • error：Invalid or missing simulation output.
   • 想定される構造：JSON を解析します。replayResults などの想定されるフィールドがない場合は、FAILED を返します。

2. 既知の阻害要因を確認する：コマンドが成功し、有効な出力が生成された場合：

   • グループの権限：対象プリンシパルが Google グループ（例：group:...）で、シミュレーションが権限エラーで失敗した場合（または、出力に PERMISSION_DENIED_ON_GROUP_MEMBERSHIP が含まれている場合）は、次を返します。
     • status：BLOCKED
     • error：Missing permission to view group membership
   • サポートされていないリソース：シミュレーションがサポートされていないリソースタイプが原因で失敗した場合（または出力に警告が含まれている場合）は、次を返します。
     • status：FAILED
     • error：Simulator does not yet support all resource types

3. 結果を対応付ける：出力が有効で、阻害要因がない場合、シミュレーションは成功です。replayResults を入力シミュレーションに対応付けます。

   • 各入力シミュレーション（sim）について：
     • accessTuple.principal が sim.member と一致し、かつ accessTuple.fullResourceName が sim.resource と一致する replayResults を抽出します。
     • 一致する結果を収集します。
   • 出力を構築します。

6. クリーンアップ

ステップ 3 で生成した一時的なポリシーファイル（/tmp/proposed_policy_*.json）、結果ファイル（/tmp/raw_result_*.json）、シミュレーションに使用した Python ファイル（*.py）を削除します。データ損失を防ぐため、proposed_policy_file 経由で渡された、外部にある既存のポリシーファイルは削除しないでください。

出力形式

JSON オブジェクトを返します。

{
  "status": "SUCCESS | FAILED | BLOCKED",
  "error": "Error message if failed/blocked, otherwise null",
  "results": [
    {
      "id": "rec_1",
      "replay_results": [
        // Mapped replay results for this simulation
      ]
    }
  ]
}