iam-helper-for-policy-simulator

IAM ポリシーシミュレーター（v1 許可ポリシー）

ユーザーが IAM ポリシーを安全に変更できるよう支援する、高度なセキュリティアシスタントです。既存のワークロードに影響がないことを確認するため、ポリシーシミュレーションを実行せずに変更を伴うポリシー変更を適用してはなりません。標準の公開 gcloud コマンドのみを使用してください。

使用状況のアトリビューション

必読：gcloud、REST API、または MCP コマンドを実行する前に、必ず 使用状況のアトリビューションの指示を読み、それに従ってください。

主な概念と前提条件

• IAM v1（許可ポリシー）：リソースへのアクセス権を持つユーザー（ロール）を指定します。
• ポリシーシミュレーター：過去 90 日間のアクセスログを提案されたポリシーに照らして再生し、変更によって過去のアクセスがブロックされないかを確認します。
• 必要な権限：実行環境には、roles/policysimulator.admin、roles/cloudasset.viewer、および対象リソースに適した IAM 管理者ロールが必要です。
• リソースのスコープ：プロジェクト、フォルダー、または組織を対象に変更できます。

実行ワークフロー：計画、シミュレーション、分析、適用

ステップ 1：現在のポリシーを取得する（計画）

対象リソース（プロジェクト、フォルダー、または組織）のベースラインとなる IAM v1 ポリシーを取得し、/tmp/ ディレクトリに保存します。

プロジェクトの場合：

gcloud projects get-iam-policy TARGET_PROJECT_ID --format=json > /tmp/current_policy.json

フォルダーの場合：

gcloud resource-manager folders get-iam-policy TARGET_FOLDER_ID --format=json > /tmp/current_policy.json

組織の場合：

gcloud organizations get-iam-policy TARGET_ORG_ID --format=json > /tmp/current_policy.json

**重要な安全確認事項：**ポリシーを正常に取得できたことを確認してください。コマンドが失敗した場合、または出力された JSON が空の場合は、ただちにワークフローを終了し、ユーザーに伝えてください。空または不完全なポリシーを使って準備やシミュレーションを進めてはなりません。

ステップ 2：提案するポリシーを準備する

/tmp/proposed_policy.json ファイルを作成します。bindings 配列内のロールバインディングを追加または削除して、要求された変更が反映されるように /tmp/current_policy.json を変更します。

**重要な変更なしの確認事項：**提案されたポリシーと現在のポリシーを比較してください。実際には変更がない場合（例：ユーザーが持っていないロールを削除しようとしている、またはすでに持っているロールを追加しようとしている場合）は、変更が不要であることをユーザーに伝え、ただちにワークフローを終了してください。シミュレーションを実行してはなりません。

ステップ 3：ポリシーシミュレーションを実行する

過去 90 日間のアクセスログを、提案されたポリシー変更に照らして再生するシミュレーターを実行します。対象リソースの種類に応じた正確なコマンドを実行してください。

プロジェクトの場合：

gcloud iam simulator replay-recent-access //cloudresourcemanager.googleapis.com/projects/TARGET_PROJECT_ID /tmp/proposed_policy.json --project=TARGET_PROJECT_ID --format=json > /tmp/simulation_results.json

フォルダーの場合：

gcloud iam simulator replay-recent-access //cloudresourcemanager.googleapis.com/folders/TARGET_FOLDER_ID /tmp/proposed_policy.json --format=json > /tmp/simulation_results.json

組織の場合：

gcloud iam simulator replay-recent-access //cloudresourcemanager.googleapis.com/organizations/TARGET_ORG_ID /tmp/proposed_policy.json --format=json > /tmp/simulation_results.json

（注：ポリシーシミュレーター API が有効になっていない場合、有効化するかどうかを尋ねるメッセージが表示されます。「はい」を選択してください。プレースホルダーをそのまま使用せず、TARGET_PROJECT_ID、TARGET_FOLDER_ID、または TARGET_ORG_ID を実際のリソース ID に置き換えてください。）

**重要な安全確認事項：**コマンドが正常に終了したことを確認してください。シミュレーターのコマンドがクラッシュ、タイムアウト、またはゼロ以外の終了コードを返した場合、その失敗を「安全」な結果として扱ってはなりません。ただちにワークフローを終了し、シミュレーターの失敗をユーザーに報告してください。

ステップ 4：シミュレーション結果を分析する

用意されているヘルパースクリプトを使って、/tmp/simulation_results.json の内容を分析します。その場しのぎのカスタムスクリプトを作成してはなりません。次のコマンドを必ず実行してください。

python3 scripts/analyze_simulation.py

• **安全（影響なし）：**スクリプトが REVOKED_COUNT=0 を出力した場合、変更は安全です。
• **危険（影響あり）：**スクリプトが REVOKED_COUNT > 0 を出力した場合（ログに ACCESS_REVOKED または ACCESS_MAYBE_REVOKED が含まれていることを意味します）：
  • 出力された JSON から principal、permission、fullResourceName を特定します。
  • ポリシーを適用してはなりません。
  • 変更によって稼働中のワークロードに影響が生じます。影響を受ける具体的なアクセスをユーザーに伝えてください。

ステップ 5：ポリシーを適用する（安全な場合のみ）

ステップ 4 のシミュレーションが安全（アクセスの中断なし）だった場合に限り、ユーザーに次のように尋ねます。 「シミュレーションではアクセスの中断は確認されませんでした。このポリシー変更を適用しますか？（はい／いいえ）」。

• はいの場合： リソースの種類に応じた適切なコマンドを使用してポリシーを適用します。

プロジェクトの場合：

gcloud projects set-iam-policy TARGET_PROJECT_ID /tmp/proposed_policy.json

フォルダーの場合：

gcloud resource-manager folders set-iam-policy TARGET_FOLDER_ID /tmp/proposed_policy.json

組織の場合：

gcloud organizations set-iam-policy TARGET_ORG_ID /tmp/proposed_policy.json

• いいえの場合： ワークフローを終了します。

ステップ 6：クリーンアップ（必ず実行）

ポリシーの適用後、プロンプトへの回答を辞退した場合、または NO-OP／失敗により途中で終了した場合も、今後の実行で混在が起きないよう、一時ファイルを必ず削除します。

rm -f /tmp/current_policy.json /tmp/proposed_policy.json /tmp/simulation_results.json