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 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true，以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

在 Core Workflow 开始时（执行任何 CLI 调用之前）： [MUST] 启用 AI-Mode — Agent Skill 执行需要 AI-mode。 在执行任何 CLI 调用之前运行以下命令：

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

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在发送最终回复之前，务必先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不会再执行 CLI 命令的其他情况。 AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后不得保持启用状态。

aliyun configure ai-mode disable

[MUST] 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. 深度分析 — （仅当用户选择路径 B 时） 根据需要解码，执行权限差距分析，并对根本原因进行分类
3. 生成建议 — 制定最小权限授权方案
4. 执行修复 — 提供修复选项并等待用户选择

**权限级别（L0–L3）**是 Agent 的内部路由状态，根据流程中的 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 分析，以获得更准确的结果。

  需要两项可选权限：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 身份对应的 UserName，请参阅 references/diagnose-flow.md → Identity Resolution。如果解析失败，则标记为 L0 并继续。

根本原因类别：

• MissingAction — 身份策略缺少所需的 Action（最常见）
• ExplicitDeny — Deny 语句阻止访问（可能位于身份策略或 CP 控制策略中）
• TrustPolicy — 角色信任策略不允许调用者扮演该角色
• STSInsufficient — STS 临时凭证缺少权限；根本原因在凭证来源 Role 上
• TokenExpired — STS 令牌已过期
• SLRMissing — 尚未创建服务关联角色
• ResourcePolicy — 资源端策略（例如，OSS Bucket Policy）限制了访问

有关差距分析的触发规则和各根本原因的处理详情，请参阅 references/diagnose-flow.md。

差距分析（触发时）：查询关联到该身份的当前策略，然后与所需 Action 进行比对。使用 ListPoliciesForUser（SubUser）、ListPoliciesForRole（AssumedRoleUser）或 ListControlPolicies（RootUser）。对于自定义策略，使用 GetPolicyVersion 获取策略文档。系统策略：使用内置知识，不要调用 GetPolicyVersion。

权限不足时：如果 DecodeDiagnosticMessage 失败（L0）或策略查询失败（L1），请告知用户这一限制，并提供可直接使用的权限申请材料，供 RAM 管理员参考——两种互相独立的选项：① 将解码权限 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。

给出建议后，添加简短说明：当前方案只是起点；用户随时可以要求进一步细化，例如限定到特定资源、添加条件，或改用资源级策略（如 OSS 存储桶策略），而不是身份级授权。

---

步骤 4：执行修复

执行任何写操作前，先向用户展示变更摘要和所有可用路径，然后等待用户选择路径 — 用户选择前不得继续操作或输出任何命令：

• 目标（用户或角色名称）
• 变更摘要（策略名称、操作、撤销方法）
• 路径选项（始终列出当前级别所有可用选项 — 不得跳过任何选项）：
  • A. 直接执行 CLI — Agent 现在运行命令 (仅限 L2)
  • B. 输出 CLI 命令 — 用户复制并在自己的终端中运行 (所有级别)
  • C. 控制台指导 — 在 RAM 控制台中逐步操作 (所有级别)
  • 跳过 — 不执行

有关写操作前的查询要求以及完整的 CLI 命令示例，请参见 references/ram-cli-commands.md 和 references/diagnose-flow.md。

路径 A：Agent 通过 Bash 执行。成功后 → 确认为 L3；报告结果和撤销命令。遇到 NoPermission → 自动切换到路径 B。

路径 B（L0/L1）：仅输出增量 Statement JSON，并注明无法读取现有策略，用户必须手动合并。

路径 B（L2）：提供两个子选项：① 仅提供增量 Statement；② 提供完整的合并后策略 JSON。

路径 C：提供 RAM 控制台入口（https://ram.console.aliyun.com/policies）和逐步操作说明，指导用户在控制台 UI 中完成变更。

修复后，建议用户重试之前失败的操作。如用户提出请求，可代为重试。