Alibabacloud Ram Permission Diagnose

RAM Permission Diagnosis and Repair

Installation

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low,

run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update,

or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

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

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose

Execution constraint: When executing aliyun CLI commands directly (not generating commands for the user to copy), always append --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ram-permission-diagnose. Do not add this flag to commands shown to users in Path B output or Path C console guidance.

Overview

When a RAM permission error is detected, run through these steps:

1. Quick Analysis — parse raw error fields (no tool calls), output a brief summary, ask the user to choose analysis depth 2. Deep Analysis — (only if user selects path B) decode if needed, run gap analysis, classify root cause 3. Generate Recommendations — least-privilege authorization plan 4. Execute Repair — present repair options and wait for user to choose

Permission level (L0–L3) is the agent's internal routing state, inferred implicitly from API call results during the flow. It determines diagnostic depth and available repair paths. Never declare or describe the level to the user. See references/diagnose-flow.md for level definitions.

---

Step 1: Quick Analysis

Parse raw error fields without any tool calls, then let the user decide how deep to go.

1a. Extract from raw error

• error_code: e.g., NoPermission, Forbidden, InvalidSecurityToken
• missing_action: e.g., ecs:StopInstance
• principal_type: SubUser / AssumedRoleUser / RootUser (from AuthPrincipalType)
• principal_display_name: UserId or role:session (from AuthPrincipalDisplayName)
• no_permission_type: ImplicitDeny or ExplicitDeny (from NoPermissionType)
• policy_type: e.g., AccountLevelIdentityBasedPolicy, AssumeRolePolicy (from PolicyType)
• encoded_message: retain EncodedDiagnosticMessage if present, for use in Step 2 if needed

1b. Output brief summary

Based on the extracted fields, output a concise summary: who is affected, what action is missing, initial root cause inference.

1c. Present depth choice and wait for selection

Present the following and wait for the user to select — do not proceed until a choice is made:

• A. Quick path (recommended when: ImplicitDeny + all key fields present + common service) — skip Step 2, generate recommendations directly from raw fields and built-in knowledge
• B. Deep path (recommended when: ExplicitDeny, missing fields, or unfamiliar service) — run full Step 2 analysis for a more precise result.

Requires two optional permissions: ram:DecodeDiagnosticMessage (decode encoded errors) and system policy AliyunRAMReadOnlyAccess (gap analysis). Missing permissions limit specific capabilities but the flow continues.

• Skip — stop here; output manual troubleshooting links

Mark the recommended option clearly and briefly explain why.

If user selects A: proceed to Step 3. Note in the recommendation that it is based on quick analysis; the user can request deep analysis at any time.

If user selects B: proceed to Step 2.

If user selects Skip: output error summary, links to RAM documentation (https://help.aliyun.com/document_detail/93733.html) and RAM console (https://ram.console.aliyun.com/policies), and a note on how to restart diagnosis.

Edge case — ExplicitDeny with path A forced: if NoPermissionType = ExplicitDeny and the user still selects A, explain that the specific Deny policy cannot be identified without deep analysis, and provide a limited recommendation with explicit uncertainty noted.

---

Step 2: Deep Analysis

Entered only when the user selects path B in Step 1.

First attempt classification using the raw fields from Step 1. DecodeDiagnosticMessage is a supplement — invoke it only when raw data is insufficient to classify with confidence.

Decode when raw data alone cannot resolve the root cause: e.g., ExplicitDeny is present (need MatchedPolicies), AccessDeniedDetail was absent, or PolicyType is missing. For cases where NoPermissionType, AuthAction, AuthPrincipalType, and PolicyType are all available and point to a clear root cause, skip decode and proceed directly.

Transcribe EncodedDiagnosticMessage from the raw error and call:

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

If the call returns EntityNotExist, re-run the original failing command and save its output to a temp file (use the system temp dir; name the file after the command context, e.g. /tmp/aliyun_ecs_stopinstance.txt). Extract EncodedDiagnosticMessage from the file and retry the decode. If the field is not found in the file, mark as L0 and continue.

If SubUser identity needs UserName resolution before gap analysis, see references/diagnose-flow.md → Identity Resolution. If resolution fails, mark as L0 and continue.

Root cause categories:

• MissingAction — identity policy lacks the required Action (most common)
• ExplicitDeny — a Deny statement blocks access (may be identity policy or CP control policy)
• TrustPolicy — role trust policy does not allow the caller to assume the role
• STSInsufficient — STS temporary credential lacks permission; root cause is on the originating Role
• TokenExpired — STS token has expired
• SLRMissing — service-linked role has not been created
• ResourcePolicy — resource-side policy (e.g., OSS Bucket Policy) is restricting access

For gap analysis trigger rules and per-root-cause handling details, see references/diagnose-flow.md.

Gap analysis (when triggered): query current policies attached to the identity, then compare against the required Action. Use ListPoliciesForUser (SubUser), ListPoliciesForRole (AssumedRoleUser), or ListControlPolicies (RootUser). For Custom policies, fetch the policy document with GetPolicyVersion. System policies: use built-in knowledge, do not call GetPolicyVersion.

When permissions are insufficient: if DecodeDiagnosticMessage fails (L0) or policy queries fail (L1), inform the user of the limitation and provide ready-to-use permission request materials for a RAM admin — two independent options: ① decode permission (ram:DecodeDiagnosticMessage) as a custom policy; ② RAM read access via system policy AliyunRAMReadOnlyAccess (covers gap analysis). Either or both can be requested independently. Then continue to Step 3 without waiting.

---

Step 3: Generate Recommendations

Before generating, check for caller skill permission hints (see references/diagnose-flow.md → Coverage Check).

Knowledge source priority: 1. Built-in knowledge — for popular services (ECS, OSS, RDS, FC, SLB, VPC, SLS, STS, etc.), use known Action semantics directly. Reference references/hot-services-ram.md. 2. Caller skill hints — if ram-policies.md was found, use as supplementary context 3. Web search — search {product} RAM authorization site:help.aliyun.com; prefer manually maintained docs with business examples over auto-generated Action tables 4. System policy fallback — recommend AliyunXxxReadOnlyAccess or AliyunXxxFullAccess with a note to tighten further

Custom policy naming: suggest a name based on service and task semantics (e.g., ai-agent-ecs-permissions), confirm once, reuse in the same session.

System policy: attach directly with a single command, no naming needed.

For the Trust Policy root cause path, recommendations differ — see references/diagnose-flow.md → Handling Each Root Cause.

After presenting the recommendation, add a brief note: the current plan is a starting point; the user can request further refinement at any time — for example, scoping down to specific resources, adding conditions, or using resource-level policies (such as OSS bucket policies) instead of identity-level grants.

---

Step 4: Execute Repair

Before executing any write operation, present the change summary and all available paths to the user, then wait for the user to select a path — do not proceed or output any commands until the user has chosen:

• Target (user or role name)
• Change summary (policy name, action, undo method)
• Path options (always present all that are available for the current level — never skip any):
• A. Direct CLI execution — agent runs commands now (only at L2)
• B. Output CLI commands — user copies and runs in their own terminal (all levels)
• C. Console guidance — step-by-step in RAM console (all levels)
• Skip — do not execute

For pre-query requirements before write operations, and full CLI command examples, see references/ram-cli-commands.md and references/diagnose-flow.md.

Path A: agent executes via Bash. On success → L3 confirmed; report result and undo command. On NoPermission → switch to Path B automatically.

Path B at L0/L1: output incremental Statement JSON only, with a note that existing policies could not be read and the user must merge manually.

Path B at L2: offer two sub-options: ① incremental Statement only, ② complete merged policy JSON.

Path C: provide the RAM console entry (https://ram.console.aliyun.com/policies) and step-by-step instructions for completing the change in the console UI.

After repair, suggest the user retry the previously failed operation. Offer to retry on their behalf if requested.

Diagnose Flow Reference

Detailed decision logic for RAM permission diagnosis. Consult this file when encountering complex or ambiguous scenarios.

---

Identity Resolution

AuthPrincipalType and AuthPrincipalDisplayName are available in the raw error's AccessDeniedDetail — no decode needed. Resolve UserName before gap analysis when identity type is SubUser:

If GetUser fails (insufficient permission): mark as L0, fall back to raw error text.

---

Permission Level (L0–L3)

Levels are implicit routing state — never declare or describe them to the user.

Insufficient permission criteria: ErrorCode NoPermission, Forbidden, or AccessDenied.

If user reports they have updated their own permissions: re-run Step 2 policy query to refresh level state.

---

Root Cause Classification Decision Tree

ExplicitDeny = true?
  ├─ Yes → Explicit Deny path
  │        NoPermissionPolicyType = ControlPolicy?
  │          ├─ Yes → Root cause: CP control policy (out of scope, guide to manual)
  │          ├─ No (AccountLevelIdentityBasedPolicy) → Root cause: own policy Deny (fixable)
  │          └─ Unknown (field absent) → Query both ListPoliciesForUser + ListControlPolicies
  │
  └─ No (or no decoded info) → Missing Action path
       ├─ PolicyType = AssumeRolePolicy → Root cause: role trust policy not allowing caller
       ├─ MissingAction = sts:AssumeRole, PolicyType absent
       │    → Medium confidence: trust policy OR identity policy missing sts:AssumeRole
       │      Describe both; guide user to verify before choosing repair direction
       ├─ PrincipalARN contains AssumedRole/STS token → Root cause: STS credential insufficient
       ├─ ErrorCode = InvalidSecurityToken → Root cause: STS token expired
       ├─ Message contains ServiceLinkedRole → Root cause: SLR missing
       ├─ Error from OSS Bucket Policy etc. → Root cause: resource-side policy
       └─ Other → Root cause: missing Action (most common)

Key principle: When DecodeDiagnosticMessage succeeds and NoPermissionPolicyType has a clear value, treat it as authoritative. Do not append additional verification API calls to check other possible root causes.

---

Gap Analysis Trigger Rules

Identity type → Query API (for root causes that trigger gap analysis):

System policies: Use built-in knowledge to infer coverage — do not call GetPolicyVersion.

---

Repair Pre-Query Rules

---

Coverage Check (for caller skill permission hints)

Before generating recommendations in Step 3:

1. Scan conversation context for the most recent Base directory: <path> injected by a skill invocation 2. If found, try reading <path>/references/ram-policies.md 3. If either file is read, perform a Coverage Check:

• Does the actual missing Action from the error appear covered? (exact match, wildcard, or reasonably implied)
• If clearly NOT covered: include the missing Action in the primary recommendation; add note: "⚠ The Action {missing_action} triggered by this error is not declared in the skill's permission hints file and has been automatically added. Consider notifying the skill maintainer to update references/ram-policies.md."
• Otherwise: use file as supplementary context, normal flow continues

4. If no file found: skip silently, no impact on flow

---

Handling Each Root Cause

Missing Action / own policy Deny: Proceed to Step 3 recommendations → Step 4 repair.

Role trust policy not allowing caller (PolicyType=AssumeRolePolicy or medium-confidence sts:AssumeRole):

• Explain: trust policy of the target role must be updated to add the caller's ARN to Principal
• If role name is known: provide modification command directly (see references/ram-cli-commands.md → Trust Policy section)
• If unknown: provide aliyun ram list-roles and a template for the user to fill in
• Also note: caller's identity policy must also have sts:AssumeRole (see AliyunSTSAssumeRoleAccess)
• For medium-confidence: describe both possible root causes and guide user to verify first

STS credential insufficient:

• Explain: using STS temporary credential; missing permission must be added to the Role that generated the STS
• Provide Role name (from PrincipalARN) and suggested actions; do not auto-repair

STS token expired: Prompt user to re-obtain STS token; provide renewal command.

SLR missing: Provide creation command:

aliyun resourcemanager create-service-linked-role --service-name <service>.aliyuncs.com

CP control policy: Beyond single-account RAM scope; contact ResourceDirectory administrator.

Resource-side policy (OSS Bucket Policy etc.): Explain distinction; provide resource-side modification guidance; do not follow RAM repair flow.

Alibaba Cloud RAM Permission ErrorCode Reference

Insufficient Permission (requires authorization repair)

STS / Token Issues (requires renewal or reconfiguration)

Service-Linked Role Issues (requires creating an SLR)

Permission Level Probing Reference

The following ErrorCodes indicate the identity has permission but the parameter or resource has an issue — they do not indicate insufficient permission. Encountering these codes during probing means the permission exists at that level:

• InvalidParameter, MissingParameter
• EntityNotExist, EntityNotExists
• NotFound, ResourceNotFound
• InvalidInput

The following ErrorCodes explicitly indicate insufficient permission — stop probing and record the level upon encountering them:

• NoPermission, Forbidden, AccessDenied
• Forbidden.RAM, Forbidden.NotSupportRAM

Popular Services RAM Action Reference

Used for Step 3 built-in knowledge priority. The following Actions are grouped by common task scenarios and can be used directly to generate minimum-privilege policies.

ECS (Elastic Compute Service)

Common Action Groups

Recommended System Policies

• Read-only operations: AliyunECSReadOnlyAccess
• Operational access (no create/delete): AliyunECSOperatorAccess
• Full control: AliyunECSFullAccess

---

OSS (Object Storage Service)

Common Action Groups

Recommended System Policies

• Read-only: AliyunOSSReadOnlyAccess
• Full control: AliyunOSSFullAccess

---

RDS (Relational Database Service)

Common Action Groups

Recommended System Policies

• Read-only: AliyunRDSReadOnlyAccess
• Full control: AliyunRDSFullAccess

---

FC (Function Compute)

Common Action Groups

Recommended System Policies

• Read-only: AliyunFCReadOnlyAccess
• Full control: AliyunFCFullAccess

---

SLB (Server Load Balancer)

Common Action Groups

Recommended System Policies

• Read-only: AliyunSLBReadOnlyAccess
• Full control: AliyunSLBFullAccess

---

VPC (Virtual Private Cloud)

Common Action Groups

Recommended System Policies

• Read-only: AliyunVPCReadOnlyAccess
• Full control: AliyunVPCFullAccess

---

SLS (Log Service)

Common Action Groups

Recommended System Policies

• Read-only: AliyunLogReadOnlyAccess
• Full control: AliyunLogFullAccess

RAM-Related aliyun CLI Command Reference

All commands are executed via the aliyun CLI. Credentials must be configured in advance (aliyun configure).

Diagnostic Commands

Decode Encrypted Diagnostic Message

Transcribe EncodedDiagnosticMessage from the error output and call directly:

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

If EntityNotExist is returned (transcription error), re-run the original failing command to a temp file and extract the token:

aliyun <product> <operation> [params] > /tmp/<context>.txt 2>&1
aliyun ram decode-diagnostic-message \
  --encoded-diagnostic-message "$(grep -o 'EncodedDiagnosticMessage:[^ ]*' /tmp/<context>.txt | cut -d: -f2)"

Query Current Identity

aliyun ram get-user

Resolve User Identity (UserId → UserName)

When DecodeDiagnosticMessage returns AuthPrincipalType = SubUser, the AuthPrincipalDisplayName is a numeric UserId that cannot be used directly in RAM APIs. Use the following command to resolve the UserName:

aliyun ims get-user --user-id <UserId>
# Use User.UserName from the response for subsequent RAM operations

List Policies Attached to a User

aliyun ram list-policies-for-user --user-name <username>

List Policies Attached to a Role

aliyun ram list-policies-for-role --role-name <rolename>

Read Policy Content (get current version document)

# First get the policy default version
aliyun ram get-policy --policy-name <policy-name> --policy-type Custom

# Read the policy document for a specific version
aliyun ram get-policy-version \
  --policy-name <policy-name> \
  --policy-type Custom \
  --version-id <version-id>

List Policy Versions

aliyun ram list-policy-versions \
  --policy-name <policy-name> \
  --policy-type Custom

---

System Policy Repair Commands

Attach System Policy to a RAM User

aliyun ram attach-policy-to-user \
  --policy-name <system-policy-name> \
  --policy-type System \
  --user-name <username>

Attach System Policy to a RAM Role

aliyun ram attach-policy-to-role \
  --policy-name <system-policy-name> \
  --policy-type System \
  --role-name <rolename>

Detach System Policy

# Detach from user
aliyun ram detach-policy-from-user \
  --policy-name <system-policy-name> \
  --policy-type System \
  --user-name <username>

# Detach from role
aliyun ram detach-policy-from-role \
  --policy-name <system-policy-name> \
  --policy-type System \
  --role-name <rolename>

---

Custom Policy Repair Commands

Create Custom Policy (first time)

aliyun ram create-policy \
  --policy-name <policy-name> \
  --policy-document '{"Version":"1","Statement":[{"Effect":"Allow","Action":["svc:Action"],"Resource":"acs:svc:*:*:*"}]}'

Attach Custom Policy to a User

aliyun ram attach-policy-to-user \
  --policy-name <policy-name> \
  --policy-type Custom \
  --user-name <username>

Attach Custom Policy to a Role

aliyun ram attach-policy-to-role \
  --policy-name <policy-name> \
  --policy-type Custom \
  --role-name <rolename>

Append New Actions (update policy version)

# Step 1: Get current policy content (check version first)
aliyun ram get-policy --policy-name <policy-name> --policy-type Custom
# Note the DefaultVersion field value, e.g., v3

# Step 2: Read the current version document
aliyun ram get-policy-version \
  --policy-name <policy-name> \
  --policy-type Custom \
  --version-id v3

# Step 3 (if 5 versions already exist): delete the oldest non-default version
aliyun ram delete-policy-version \
  --policy-name <policy-name> \
  --version-id v1

# Step 4: Create new version (complete JSON with existing + new Actions)
aliyun ram create-policy-version \
  --policy-name <policy-name> \
  --policy-document '{"Version":"1","Statement":[...all Actions...]}' \
  --set-as-default true

Detach Custom Policy

# Detach from user
aliyun ram detach-policy-from-user \
  --policy-name <policy-name> \
  --policy-type Custom \
  --user-name <username>

# Detach from role
aliyun ram detach-policy-from-role \
  --policy-name <policy-name> \
  --policy-type Custom \
  --role-name <rolename>

Delete Custom Policy (all versions + the policy itself)

# First delete all non-default versions
aliyun ram delete-policy-version --policy-name <policy-name> --version-id v1
# ...repeat until only the default version remains

# Then delete the policy (automatically removes the last version)
aliyun ram delete-policy --policy-name <policy-name>

---

Role Trust Policy Repair Commands

Use this sequence when root cause is "trust policy not allowing caller":

# Step 1: Get current trust policy content
aliyun ram get-role --role-name <role-name>
# Note the AssumeRolePolicyDocument field

# Step 2: Update trust policy (add caller ARN to Principal.RAM array)
aliyun ram update-role \
  --role-name <role-name> \
  --new-assume-role-policy-document '{"Statement":[{"Action":"sts:AssumeRole","Effect":"Allow","Principal":{"RAM":["acs:ram::<account-id>:root","acs:ram::<account-id>:user/<caller-username>"]}}],"Version":"1"}'

# Undo: restore original Principal by calling UpdateRole again with original JSON
aliyun ram update-role \
  --role-name <role-name> \
  --new-assume-role-policy-document '<original-json>'

If caller identity policy also lacks sts:AssumeRole, attach the system policy:

aliyun ram attach-policy-to-user \
  --policy-name AliyunSTSAssumeRoleAccess \
  --policy-type System \
  --user-name <username>

# Undo
aliyun ram detach-policy-from-user \
  --policy-name AliyunSTSAssumeRoleAccess \
  --policy-type System \
  --user-name <username>

If role name is unknown, list roles first:

aliyun ram list-roles

---

Service-Linked Role Commands

# Create a service-linked role
aliyun resourcemanager create-service-linked-role \
  --service-name <service>.aliyuncs.com

# Check whether a service-linked role exists
aliyun ram get-role --role-name AliyunServiceRole<ServiceName>

---

CP Control Policy Query Commands (ResourceDirectory)

# List all control policies
aliyun resourcemanager list-control-policies

# View a specific control policy's content
aliyun resourcemanager get-control-policy --policy-id <policy-id>

RAM Hints for ram-permission-diagnose Skill

<!-- ram-hints-version: 1 -->

Action Permission Mapping

Diagnostic Operations (read-only)

Repair Operations (write — required for L3)

Recommended System Policies

• Diagnostic only (L1+L2): AliyunRAMReadOnlyAccess
• Full functionality (L1+L2+L3): AliyunRAMFullAccess

Official RAM Documentation

• https://help.aliyun.com/document_detail/28630.html (RAM authorization action list — manually maintained)