返回技能市场
开发运维 安全

阿里云 RAM 权限诊断助手

@aliyun/alibabacloud-ram-permission-diagnose

用于阿里云 RAM 权限相关问题的诊断与策略生成。当 Agent 或用户遭遇权限报错（403、NoPermission、AccessDenied 等）时，自动解析报错根因、生成最小权限建议并引导完成授权修复；也支持用户主动描述某个使用场景，直接生成对应的 RAM 策略并授予。

云Skills门户 热度 61v0.0.2

RAM 权限诊断与修复

安装

预检查：阿里云 CLI 版本必须 >= 3.3.3

运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新，
或参阅 references/cli-installation-guide.md 获取安装说明。

预检查：必须更新阿里云 CLI 插件

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

在核心工作流开始时（调用任何 CLI 之前）： [必须] 启用 AI-Mode——AI-mode 是执行 Agent Skill 的必需条件。 调用任何 CLI 之前，请运行以下命令：

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

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

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。不得将此标志添加到路径 B 输出中向用户展示的命令或路径 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，应说明若不进行深度分析就无法识别具体的拒绝策略，并提供范围有限的建议，同时明确注明其中的不确定性。

---

步骤 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 → 身份解析。如果解析失败，则标记为 L0 并继续。

根因类别：

  • MissingAction——身份策略缺少所需操作（最常见）
  • ExplicitDeny——拒绝语句阻止了访问（可能是身份策略或 CP 管控策略）
  • TrustPolicy——角色信任策略不允许调用方扮演该角色
  • STSInsufficient——STS 临时凭证缺少权限；根因在源角色上
  • TokenExpired——STS 令牌已过期
  • SLRMissing——服务关联角色尚未创建
  • ResourcePolicy——资源侧策略（例如 OSS 存储空间策略）正在限制访问

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

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

权限不足时：如果 DecodeDiagnosticMessage 失败（L0）或策略查询失败（L1），请告知用户此限制，并提供可直接使用的权限申请材料，供 RAM 管理员使用——有两个相互独立的选项：① 通过自定义策略授予解码权限（ram:DecodeDiagnosticMessage）；② 通过系统策略 AliyunRAMReadOnlyAccess 授予 RAM 只读访问权限（涵盖差距分析）。可单独申请其中任一项，也可同时申请两项。随后无需等待，继续执行步骤 3。

---

步骤 3：生成建议

生成建议前，检查调用方 skill 的权限提示（参见 references/diagnose-flow.md → 覆盖范围检查）。

知识来源优先级：

  1. 内置知识——对于常用服务（ECS、OSS、RDS、FC、SLB、VPC、SLS、STS 等），直接使用已知的操作语义。参见 references/hot-services-ram.md。
  2. 调用方 skill 提示——如果找到 ram-policies.md，将其用作补充上下文
  3. 网页搜索——搜索 {product} RAM authorization site:help.aliyun.com；相比自动生成的操作表，优先选择包含业务示例的人工维护文档
  4. 系统策略兜底方案——推荐 AliyunXxxReadOnlyAccess 或 AliyunXxxFullAccess，并注明后续还需进一步收紧权限

自定义策略命名：根据服务和任务语义建议一个名称（例如 ai-agent-ecs-permissions），确认一次后，在同一会话中复用该名称。

系统策略：使用一条命令直接附加，无需命名。

对于信任策略根因路径，建议有所不同——参见 references/diagnose-flow.md → 各类根因的处理方式。

展示建议后，补充简短说明：当前方案只是起点；用户可随时请求进一步优化——例如，将范围缩小到特定资源、添加条件，或使用资源级策略（如 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）：仅输出增量语句的 JSON，并注明无法读取现有策略，用户必须手动合并。

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

路径 C：提供 RAM 控制台入口（https://ram.console.aliyun.com/policies），以及在控制台 UI 中完成变更的分步操作说明。

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

qianwen skills install @aliyun/alibabacloud-ram-permission-diagnose