alibabacloud-ram-permission-diagnose

RAM 権限の診断と修復

インストール

事前確認：Aliyun CLI >= 3.3.3 が必要です

aliyun version を実行して、バージョンが >= 3.3.3 であることを確認してください。未インストールの場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行して更新するか、 references/cli-installation-guide.md でインストール手順を確認してください。

事前確認：Aliyun CLI プラグインの更新が必要です

[必須] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 [必須] aliyun plugin update を実行して、既存のプラグインが常に最新の状態になるようにしてください。

コアワークフローの開始時（CLI を呼び出す前）に： [必須] AI モードを有効にする — エージェントスキルの実行には AI モードが必要です。 CLI を呼び出す前に、次のコマンドを実行してください：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose"

[必須] すべての終了時点で AI モードを無効にする — どのような理由であっても、最終応答を返す前に、必ず最初に AI モードを無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、または以降 CLI コマンドが実行されないその他すべての状況を含む、すべての終了経路に適用されます。 AI モードはエージェントスキルの呼び出し時にのみ使用し、スキルの実行停止後に有効なままにしてはなりません。

aliyun configure ai-mode disable

[必須] CLI の User-Agent — aliyun CLI の呼び出しには、すべて次を含める必要があります： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose

実行上の制約：ユーザーがコピーするコマンドを生成するのではなく、aliyun CLI コマンドを直接実行する場合は、必ず --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose を末尾に追加してください。Path B の出力でユーザーに提示するコマンドや、Path C のコンソール案内には、このフラグを追加しないでください。

概要

RAM 権限エラーが検出された場合は、次の手順を実行します：

1. 簡易分析 — 生のエラーフィールドを解析し（ツール呼び出しなし）、簡潔な概要を出力して、分析の深さをユーザーに選択してもらいます
2. 詳細分析 — (ユーザーが Path B を選択した場合のみ) 必要に応じてデコードし、権限の不足を分析して、根本原因を分類します
3. 推奨事項の作成 — 最小権限の認可プランを作成します
4. 修復の実行 — 修復オプションを提示し、ユーザーの選択を待ちます

**権限レベル（L0–L3）**は、ワークフロー中の API 呼び出し結果から暗黙的に推定される、エージェント内部のルーティング状態です。診断の深さと利用可能な修復経路を決定します。このレベルをユーザーに伝えたり、説明したりしないでください。レベルの定義については、references/diagnose-flow.md を参照してください。

---

ステップ 1：簡易分析

ツールを呼び出さずに生のエラーフィールドを解析し、その後、分析の深さをユーザーに選択してもらいます。

1a. 生のエラーから情報を抽出

• error_code：例：NoPermission、Forbidden、InvalidSecurityToken
• missing_action：例：ecs:StopInstance
• principal_type：SubUser / AssumedRoleUser / RootUser（AuthPrincipalType から取得）
• principal_display_name：UserId または role:session（AuthPrincipalDisplayName から取得）
• no_permission_type：ImplicitDeny または ExplicitDeny（NoPermissionType から取得）
• policy_type：例：AccountLevelIdentityBasedPolicy、AssumeRolePolicy（PolicyType から取得）
• encoded_message：EncodedDiagnosticMessage がある場合は保持し、必要に応じてステップ 2 で使用します

1b. 簡潔な概要を出力

抽出したフィールドに基づいて、影響を受けているユーザー、不足しているアクション、根本原因の初期推定を簡潔にまとめて出力します。

1c. 深度の選択肢を提示し、選択を待つ

以下を提示し、ユーザーが選択するまで待機してください。選択されるまで先に進まないでください。

• A. クイックパス (推奨条件：ImplicitDeny ＋ すべての主要フィールドが存在 ＋ 一般的なサービス) — ステップ 2 を省略し、生のフィールドと組み込みのナレッジから直接推奨事項を生成します
• B. 詳細パス (推奨条件：ExplicitDeny、フィールドの欠落、または不慣れなサービス) — より正確な結果を得るため、ステップ 2 の分析をすべて実行します。

  2 つのオプションの権限が必要です：ram:DecodeDiagnosticMessage（エンコードされたエラーをデコード）とシステムポリシー AliyunRAMReadOnlyAccess（ギャップ分析）。権限がない場合、特定の機能は制限されますが、フローは続行されます。

• スキップ — ここで停止し、手動トラブルシューティングへのリンクを出力します

推奨オプションを明確に示し、その理由を簡潔に説明してください。

ユーザーが A を選択した場合：ステップ 3 に進みます。推奨事項にはクイック分析に基づいていることを記載し、ユーザーはいつでも詳細分析を依頼できることを伝えてください。

ユーザーが B を選択した場合：ステップ 2 に進みます。

ユーザーがスキップを選択した場合：エラーの概要、RAM ドキュメント（https://help.aliyun.com/document_detail/93733.html）と RAM コンソール（https://ram.console.aliyun.com/policies）へのリンク、および診断を再開する方法を記載したメモを出力します。

エッジケース — ExplicitDeny でパス A を強制する場合：NoPermissionType = ExplicitDeny で、ユーザーがそれでも A を選択した場合は、詳細分析なしでは該当する Deny ポリシーを特定できないことを説明し、不確実性を明記した限定的な推奨事項を提示してください。

---

ステップ 2：詳細分析

ステップ 1 でユーザーがパス B を選択した場合にのみ実行します。

まず、ステップ 1 の生フィールドを使って分類を試みます。DecodeDiagnosticMessage は補足的なものです。生データだけでは確信を持って分類できない場合に限り、呼び出してください。

生データだけでは根本原因を特定できない場合にデコードします：たとえば、ExplicitDeny が存在する（MatchedPolicies が必要）、AccessDeniedDetail がなかった、または PolicyType が欠落している場合です。NoPermissionType、AuthAction、AuthPrincipalType、PolicyType がすべて利用可能で、明確な根本原因を示している場合は、デコードを省略して直接先へ進んでください。

生エラーから EncodedDiagnosticMessage を転記し、次を呼び出します。

aliyun ram decode-diagnostic-message --encoded-diagnostic-message "<transcribed-value>"

呼び出しが EntityNotExist を返した場合は、元の失敗したコマンドを再実行し、その出力を一時ファイルに保存します（システムの一時ディレクトリを使い、コマンドのコンテキストに基づいたファイル名を付けます。例：/tmp/aliyun_ecs_stopinstance.txt）。ファイルから EncodedDiagnosticMessage を抽出し、デコードを再試行してください。ファイル内にフィールドが見つからない場合は、L0 として記録して続行します。

ギャップ分析の前に SubUser のユーザー名を解決する必要がある場合は、references/diagnose-flow.md → Identity Resolution を参照してください。解決に失敗した場合は、L0 として記録して続行します。

根本原因のカテゴリ：

• MissingAction — ID ポリシーに必要な Action がありません（最も一般的）
• ExplicitDeny — Deny ステートメントがアクセスをブロックしています（ID ポリシーまたは CP 制御ポリシーの場合があります）
• TrustPolicy — ロールの信頼ポリシーで呼び出し元によるロールの引き受けが許可されていません
• STSInsufficient — STS の一時的な認証情報に権限がありません。根本原因は元の Role にあります
• TokenExpired — STS トークンの有効期限が切れています
• SLRMissing — サービスリンクロールが作成されていません
• ResourcePolicy — リソース側のポリシー（例：OSS Bucket Policy）がアクセスを制限しています

ギャップ分析の実行条件と根本原因ごとの対応の詳細については、references/diagnose-flow.md を参照してください。

ギャップ分析（実行条件を満たす場合）：ID にアタッチされている現在のポリシーを照会し、必要な Action と比較します。ListPoliciesForUser（SubUser）、ListPoliciesForRole（AssumedRoleUser）、または ListControlPolicies（RootUser）を使用します。カスタムポリシーの場合は、GetPolicyVersion でポリシードキュメントを取得します。システムポリシーの場合は、組み込みの知識を使い、GetPolicyVersion を呼び出さないでください。

権限が不足している場合：DecodeDiagnosticMessage が失敗した場合（L0）、またはポリシーの照会に失敗した場合（L1）は、その制約をユーザーに伝え、RAM 管理者に依頼するためのすぐに使える権限申請資料を提供します。選択肢は互いに独立した 2 つです。① カスタムポリシーとしてデコード権限（ram:DecodeDiagnosticMessage）を付与する、② システムポリシー AliyunRAMReadOnlyAccess による RAM の読み取りアクセス（ギャップ分析をカバー）を付与する。どちらか一方、または両方を個別に申請できます。その後、待たずにステップ 3 へ進みます。

ステップ 3：推奨事項の作成

推奨事項を作成する前に、呼び出し元のスキルに権限ヒントがあるか確認します（references/diagnose-flow.md → Coverage Check を参照）。

ナレッジソースの優先順位：

1. 組み込みナレッジ — よく利用されるサービス（ECS、OSS、RDS、FC、SLB、VPC、SLS、STS など）では、既知の Action のセマンティクスをそのまま使用します。references/hot-services-ram.md を参照してください。
2. 呼び出し元のスキルヒント — ram-policies.md が見つかった場合は、補足情報として使用します
3. ウェブ検索 — {product} RAM authorization site:help.aliyun.com を検索します。自動生成された Action テーブルより、ビジネス例を含む手動管理のドキュメントを優先します
4. システムポリシーへのフォールバック — AliyunXxxReadOnlyAccess または AliyunXxxFullAccess を、さらに絞り込む必要がある旨を添えて推奨します

カスタムポリシーの命名：サービスとタスクのセマンティクスに基づく名前（例：ai-agent-ecs-permissions）を提案し、ユーザーに一度確認してから、同じセッション内で再利用します。

システムポリシー：単一のコマンドで直接アタッチします。命名は不要です。

信頼ポリシーの根本原因に対処する場合は、推奨事項が異なります。references/diagnose-flow.md → Handling Each Root Cause を参照してください。

推奨事項を提示した後、現在のプランは出発点であり、ユーザーはいつでも追加の調整を依頼できることを簡潔に伝えてください。たとえば、対象リソースの絞り込み、条件の追加、または ID レベルの権限付与ではなく、リソースレベルのポリシー（OSS バケットポリシーなど）の使用を依頼できます。

---

ステップ 4：修復の実行

書き込み操作を実行する前に、変更の概要と利用可能なすべての方法をユーザーに提示し、ユーザーが方法を選択するまで待ってください。選択されるまでは、処理を進めたり、コマンドを出力したりしないでください。

• 対象（ユーザー名またはロール名）
• 変更の概要（ポリシー名、操作、取り消し方法）
• 方法の選択肢（現在のレベルで利用可能なものを必ずすべて提示し、省略しないでください）：
  • A. CLI を直接実行 — エージェントがコマンドを実行します（L2 のみ）
  • B. CLI コマンドを出力 — ユーザーがコピーして、自分のターミナルで実行します（すべてのレベル）
  • C. コンソールで案内 — RAM コンソールでの手順を順に案内します（すべてのレベル）
  • スキップ — 実行しません

書き込み操作の前に必要なクエリ要件と CLI コマンドの例については、references/ram-cli-commands.md および references/diagnose-flow.md を参照してください。

方法 A：Bash 経由でエージェントが実行します。成功した場合は L3 確認済みとなるため、結果と取り消しコマンドを報告します。NoPermission の場合は、自動的に方法 B に切り替えます。

方法 B（L0/L1）：Statement の差分 JSON のみを出力し、既存のポリシーを読み取れなかったため、ユーザー自身で手動マージする必要がある旨を添えます。

方法 B（L2）：次の 2 つのサブオプションを提示します：① Statement の差分のみ、② マージ済みの完全なポリシー JSON。

方法 C：RAM コンソールの入口（https://ram.console.aliyun.com/policies）と、コンソール UI で変更を完了するための手順を順に提示します。

修復後、以前失敗した操作を再試行するようユーザーに提案してください。依頼があれば、代わりに再試行することも申し出てください。