Alibabacloud Sas Overview

SAS Overview Data Query

Retrieves the 5 core modules of the Security Center (SAS) overview dashboard: 1. Security Overview — score, fixed vulns, baseline risk, handled alerts 2. Usage Info — service days, asset scale, uninstalled clients 3. Security Operations — risk governance (AI risk, CSPM, key config, system vulns), security protection (WAF blocks), security response 4. Asset Risk Trend — host/container/cloud product risk ratios + trend chart 5. Billing & Subscription — post-pay switches, subscription validity, bills

Execution Scope: Each module and data item can be queried independently.

Match the scope to the user's request:

- Single data item — e.g., "What is my security score?" → only command 1a

- Single module — e.g., "Show asset risk trend" → all of Module 4

- Full overview — e.g., "SAS overview" → all 5 modules

Architecture: SAS + WAF + BssOpenApi

Observability

User-Agent Template:

AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}

Session-ID Generation Rule:

• Generate a UUID v4 (e.g., 550e8400-e29b-41d4-a716-446655440000) at the start of each skill execution session.
• The same {session-id} MUST be used for ALL aliyun CLI commands within a single session, ensuring all requests from one execution can be correlated in logs.
• Each new skill invocation MUST generate a fresh session-id.

Usage: Pass the full UA string via the --user-agent flag on every aliyun CLI command:

SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
aliyun sas describe-version-config --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/$SESSION_ID"

Prerequisites

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.

Install required CLI plugins:

aliyun plugin install --names aliyun-cli-sas aliyun-cli-waf-openapi aliyun-cli-bssopenapi

Pre-check: Alibaba Cloud Credentials Required

>

Security Rules:

- NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

- NEVER ask the user to input AK/SK directly in the conversation or command line

- NEVER use aliyun configure set with literal credential values

- ONLY use aliyun configure list to check credential status

>

```bash

aliyun configure list

```

Check the output for a valid profile (AK, STS, or OAuth identity).

>

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

3. Return and re-run after aliyun configure list shows a valid profile

Parameters

IMPORTANT: Parameter Confirmation — Before executing any command or API call,

ALL user-customizable parameters (e.g., RegionId, WAF InstanceId, BillingCycle, etc.)

MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

RAM Permissions

See references/ram-policies.md for the full RAM policy JSON.

Required: AliyunYundunSASReadOnlyAccess, AliyunWAFReadOnlyAccess, AliyunBSSReadOnlyAccess.

Core Workflow

Based on the user's query, execute the relevant module(s) below. Each module — and each data item within a module — can be executed independently. For APIs marked multi-region, always query both cn-shanghai and ap-southeast-1, then sum the results.

Module 1: Security Overview

# 1a. Security Score (region-agnostic)
aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: Score field from response as current security score
#
# NOTE: DescribeScreenScoreThread is currently unavailable (CalType not supported).
# Once supported, switch to the command below for score + historical trend:
#   START=$(python3 -c "import time; print(int((time.time()-86400*7)*1000))")
#   END=$(python3 -c "import time; print(int(time.time()*1000))")
#   aliyun sas describe-screen-score-thread \
#     --cal-type home_security_score \
#     --start-time "$START" --end-time "$END" \
#     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
#   Extract: Data.SocreThread[-1] = current score, full SocreThread list = historical trend

# 1b. Fixed Vulnerabilities (multi-region: sum FixTotal)
aliyun sas describe-vul-fix-statistics --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun sas describe-vul-fix-statistics --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}

# 1c. Baseline Risk Statistics (multi-region: sum each Summary field)
aliyun sas get-check-risk-statistics --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun sas get-check-risk-statistics --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: Summary.RiskCheckCnt, Summary.RiskWarningCnt,
#          Summary.HandledCheckTotal, Summary.HandledCheckToday
# Sum each field across regions

# 1d. Handled Alerts (multi-region: sum SuspiciousDealtCount)
aliyun sas get-defence-count --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun sas get-defence-count --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}

Module 2: Usage Info

# 2a. Service Duration + Subscription (region-agnostic)
aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Check IsPaidUser first:
#   IsPaidUser == true  → Extract CreateTime, calculate (now - CreateTime) as days
#   IsPaidUser == false → Service duration not applicable, display N/A
# Extract: ReleaseTime → subscription expiry (pre-pay only)

# 2b. Host Asset Info (multi-region: sum TotalCount and Cores)
aliyun sas describe-cloud-center-instances \
  --region cn-shanghai --machine-types ecs --current-page 1 --page-size 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun sas describe-cloud-center-instances \
  --region ap-southeast-1 --machine-types ecs --current-page 1 --page-size 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: PageInfo.TotalCount (sum across regions) for host count
# Extract: Sum all instances' Cores field for total core count
# Optionally list host details if user requests

# 2c. Uninstalled Clients (multi-region: sum TotalCount)
aliyun sas list-uninstall-aegis-machines --region cn-shanghai --current-page 1 --page-size 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun sas list-uninstall-aegis-machines --region ap-southeast-1 --current-page 1 --page-size 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}

Module 3: Security Operations

3a. Risk Governance (region-agnostic, single API call)

aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Process Suggestions[] by SuggestType:
#   SS_AI_RISK → AI Risk
#     SSI_AISPM_RISK (AI security posture risks)
#     SSI_AI_VUL_RISK (AI application vulnerabilities)
#     SSI_AI_SENSITIVE_RISK (AI application plaintext keys)
#     Aggregate RiskCount by region
#   SS_SAS_CLOUD_HC → CSPM risks (aggregate by HIGH/MEDIUM/LOW and region)
#     Cloud: SSI_SAS_CLOUD_HC_HIGH / MEDIUM / LOW
#     Host:  SSI_SAS_HOST_HC_HIGH / MEDIUM / LOW
#   SS_KEY_CONFIG → Key Config (SubType not fixed; analyze Description for unknown SubTypes)
#     Aggregate RiskCount by region
#   SS_SAS_SYS_VUL → System Vulns (aggregate by HIGH/MEDIUM/LOW and region)
#     SSI_SAS_SYS_VUL_HIGH / SSI_SAS_SYS_VUL_MEDIUM / SSI_SAS_SYS_VUL_LOW
#   SS_SAS_EMG_VUL → Emergency Vulns (unfixed emergency vulnerabilities)
#     SSI_SAS_EMG_VUL
#   SS_SAS_APP_VUL → Application Vulns (aggregate by HIGH/MEDIUM and region)
#     SSI_SAS_APP_VUL_HIGH / SSI_SAS_APP_VUL_MEDIUM
#   SS_PRODUCT_CONNECT → Product Connection (asset protection not enabled)
#     SSI_PRODUCT_CONNECT (Description is JSON array with itemDescKey/itemDescText)
#   SS_SAS_ALARM → Security Response (see Module 3c)
#     SSI_SAS_ALARM_HIGH (emergency) / SSI_SAS_ALARM_MEDIUM (suspicious) / SSI_SAS_ALARM_LOW (reminder)

3b. Security Protection — WAF Blocks (multi-region, two-step, WAF 3.0 only)

WAF Version Requirement: This module uses WAF 3.0 API (Product: waf-openapi, Version: 2021-10-01). WAF 2.0 instances (Version 2019-09-10) are NOT compatible — fields such as InstanceId and WafBlockSum may be missing or structured differently. If the user's WAF instance is 2.0, inform them that this module is not supported for their instance version.

# Step 1: Get WAF Instance ID (per region)
aliyun waf-openapi describe-instance --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun waf-openapi describe-instance --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: InstanceId from each region's response

# Step 2: Query WAF flow chart using each region's InstanceId
START_SEC=$(python3 -c "import time; print(int(time.time()-86400*7))")
aliyun waf-openapi describe-flow-chart \
  --region cn-shanghai \
  --instance-id "<InstanceId from cn-shanghai>" \
  --start-timestamp "$START_SEC" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun waf-openapi describe-flow-chart \
  --region ap-southeast-1 \
  --instance-id "<InstanceId from ap-southeast-1>" \
  --start-timestamp "$START_SEC" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Sum all WafBlockSum values from both regions

3c. Security Response (region-agnostic, same API as 3a)

aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Process Suggestions[] where SuggestType == "SS_SAS_ALARM":
#   SSI_SAS_ALARM_HIGH   → Emergency alarm events count
#   SSI_SAS_ALARM_MEDIUM → Suspicious alarm events count
#   SSI_SAS_ALARM_LOW    → Reminder alarm events count

Module 4: Asset Risk Trend

# 4a. Host Assets (multi-region)
aliyun sas describe-cloud-center-instances \
  --region cn-shanghai --machine-types ecs --current-page 1 --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: PageInfo.TotalCount

aliyun sas describe-field-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: GroupedFields.RiskInstanceCount
# Repeat for ap-southeast-1, sum both

# 4b. Container Assets (multi-region)
aliyun sas describe-container-field-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: ClusterCount, RiskClusterCount
# Repeat for ap-southeast-1, sum both

# 4c. Cloud Product Assets (multi-region)
aliyun sas get-cloud-asset-summary \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Extract: GroupedFields.InstanceCountTotal, GroupedFields.InstanceRiskCountTotal
# Repeat for ap-southeast-1, sum both

# 4d. Trend Chart Data (multi-region)
START_MS=$(python3 -c "import time; print(int((time.time()-86400*7)*1000))")
END_MS=$(python3 -c "import time; print(int(time.time()*1000))")
aliyun sas describe-chart-data \
  --region cn-shanghai \
  --chart-id CID_ASSET_RISK_TREND \
  --report-id -1 \
  --time-start "$START_MS" --time-end "$END_MS" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Returns time series: host / container / cloud risk counts

Module 5: Billing & Subscription

# 5a. Query billing mode (from Module 2a response, can reuse cached result)
aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# Check IsPaidUser field to determine billing mode:
#
# If IsPaidUser == true → Pre-pay (subscription) user:
#   Extract CreateTime → purchase date (convert ms timestamp to YYYY-MM-DD)
#   Extract ReleaseTime → expiry date (convert ms timestamp to YYYY-MM-DD)
#
# If IsPaidUser == false → Post-pay user:
#   Extract PostPayModuleSwitch (JSON string — must parse)
#   Map codes to product names using the table below:
#     POST_HOST → Host and Container Security
#     VUL → Vulnerability Fixing
#     CSPM → CSPM
#     CTDR → Agentic SOC
#     AGENTLESS → Agentless Detection
#     SERVERLESS → Serverless Asset Protection
#     RASP → Application Protection
#     SDK → Malicious File Detection
#     CTDR_STORAGE → Log Management
#     ANTI_RANSOMWARE → Anti-ransomware
#   Value 1 = Enabled, 0 = Disabled

# 5c. Billing Details (try each region, skip on permission error)
BILLING_CYCLE=$(date +%Y-%m)
aliyun bssopenapi query-bill \
  --region cn-shanghai \
  --billing-cycle "$BILLING_CYCLE" --product-code sas \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# If the above returns a permission error, do NOT silently skip — inform the user (see Data Processing Rules §1)

aliyun bssopenapi query-bill \
  --region ap-southeast-1 \
  --billing-cycle "$BILLING_CYCLE" --product-code sas \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# If the above returns a permission error, do NOT silently skip — inform the user (see Data Processing Rules §1)
# Aggregate results from whichever regions succeeded, and explicitly report any skipped regions

Product Code Mapping

Data Processing Rules

1. Multi-region aggregation: APIs requiring regions must query cn-shanghai + ap-southeast-1 separately, then sum the numeric results.

• Permission error handling: If a region returns a permission error (e.g., Forbidden or NoPermission), do NOT silently skip it. You MUST explicitly inform the user which regions succeeded and which failed, including the missing permission. Example: "Data retrieved from cn-shanghai, but ap-southeast-1 returned permission denied (missing sas:DescribeSecureSuggestion). Results only reflect cn-shanghai."

2. Timestamps: SAS APIs use millisecond timestamps. WAF APIs use second timestamps. 3. PostPayModuleSwitch: Is a JSON string — must JSON.parse() / json.loads() before reading. 4. Score extraction: Use Score field from DescribeSecureSuggestion response as current score. Note: Score is returned as a string (e.g., "90.0"), not a number — cast to float before comparison or display. Note: DescribeScreenScoreThread is currently unavailable (CalType not supported); once supported, switch to using the last element of Data.SocreThread[] as current score and the full list as historical trend. 5. Security Response: Extracted from DescribeSecureSuggestion where SuggestType == "SS_SAS_ALARM". SubTypes: SSI_SAS_ALARM_HIGH (emergency), SSI_SAS_ALARM_MEDIUM (suspicious), SSI_SAS_ALARM_LOW (reminder). 6. Timestamp formatting: Convert ms timestamps to YYYY-MM-DD HH:mm:ss for display.

Success Verification

See references/verification-method.md for step-by-step verification commands.

Cleanup

This skill is read-only (query operations only). No resources are created, so no cleanup is needed.

Best Practices

1. Always query both cn-shanghai and ap-southeast-1 for multi-region APIs before aggregating. 2. Cache the DescribeVersionConfig response — it is used by both Module 2 and Module 5. 3. Use --cli-query (JMESPath) to extract specific fields and reduce output noise. 4. Set --page-size 1 when only TotalCount is needed (e.g., ListUninstallAegisMachines). 5. WAF DescribeFlowChart requires a valid WAF instance ID — auto-fetch via DescribeInstance first; query both cn-shanghai and ap-southeast-1. 6. Billing queries (QueryBill) require --region — try each region (cn-shanghai, ap-southeast-1) in turn; skip any region that returns a permission error. 7. All timestamps returned by SAS are in milliseconds — divide by 1000 for human-readable conversion.

Reference Links

Acceptance Criteria: alibabacloud-sas-overview

Scenario: SAS Overview Data Query Purpose: Skill testing acceptance criteria

---

Correct CLI Command Patterns

1. Product — SAS commands use sas product code

CORRECT

aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills
aliyun sas describe-cloud-center-instances --region cn-shanghai --machine-types ecs --current-page 1 --page-size 20 --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Wrong: using uppercase API style
aliyun sas DescribeVersionConfig
# Wrong: missing user-agent
aliyun sas describe-version-config
# Wrong: wrong product code
aliyun security-center describe-version-config

2. Multi-Region Aggregation — Must query both cn-shanghai and ap-southeast-1

CORRECT

# Query cn-shanghai
aliyun sas describe-vul-fix-statistics --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills
# Query ap-southeast-1
aliyun sas describe-vul-fix-statistics --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills
# Sum: FixTotal(cn-shanghai) + FixTotal(ap-southeast-1)

INCORRECT

# Wrong: querying only one region
aliyun sas describe-vul-fix-statistics --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills
# Wrong: using default region without specifying
aliyun sas describe-vul-fix-statistics --user-agent AlibabaCloud-Agent-Skills

3. Region-Agnostic APIs — Do not pass region

CORRECT

# No --region flag for region-agnostic APIs
aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent AlibabaCloud-Agent-Skills
aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills
# NOTE: DescribeScreenScoreThread is also region-agnostic, but currently unavailable (CalType not supported)

INCORRECT

# Wrong: passing region to region-agnostic API
aliyun sas describe-secure-suggestion --region cn-shanghai --cal-type home_security_score --user-agent AlibabaCloud-Agent-Skills

4. Time Parameters — Must use millisecond timestamps

CORRECT

# Millisecond timestamps for SAS APIs (e.g. DescribeChartData)
START=$(python3 -c "import time; print(int((time.time()-86400*7)*1000))")
END=$(python3 -c "import time; print(int(time.time()*1000))")

# DescribeChartData must include --report-id -1
aliyun sas describe-chart-data \
  --chart-id CID_ASSET_RISK_TREND --report-id -1 \
  --time-start "$START" --time-end "$END" \
  --user-agent AlibabaCloud-Agent-Skills
# NOTE: DescribeScreenScoreThread also uses ms timestamps, but is currently unavailable

INCORRECT

# Wrong: DescribeChartData without --report-id
aliyun sas describe-chart-data --chart-id CID_ASSET_RISK_TREND --time-start "$START" --time-end "$END"

5. WAF Block Stats — Two-step: DescribeInstance then DescribeFlowChart

CORRECT

# Step 1: Auto-fetch WAF Instance ID (per region)
aliyun waf-openapi describe-instance --region cn-shanghai --user-agent AlibabaCloud-Agent-Skills
aliyun waf-openapi describe-instance --region ap-southeast-1 --user-agent AlibabaCloud-Agent-Skills
# Extract InstanceId from each region's response

# Step 2: Query flow chart with each region's InstanceId
START_SEC=$(python3 -c "import time; print(int(time.time()-86400*7))")
aliyun waf-openapi describe-flow-chart \
  --region cn-shanghai \
  --instance-id "<InstanceId from cn-shanghai>" \
  --start-timestamp "$START_SEC" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills
aliyun waf-openapi describe-flow-chart \
  --region ap-southeast-1 \
  --instance-id "<InstanceId from ap-southeast-1>" \
  --start-timestamp "$START_SEC" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills
# Sum WafBlockSum across both regions

INCORRECT

# Wrong: hardcoding or asking user for WAF Instance ID without querying first
aliyun waf-openapi describe-flow-chart --instance-id "manually-provided-id" ...
# Wrong: using sas product for WAF API
aliyun sas describe-flow-chart --instance-id xxx
# Wrong: using millisecond timestamps (WAF uses seconds)
aliyun waf-openapi describe-flow-chart --instance-id xxx --start-timestamp 1710000000000 --interval 3600
# Wrong: skipping DescribeInstance and assuming InstanceId

6. Billing Mode — Branch on IsPaidUser before reading subscription fields

CORRECT

import json
is_paid = response.get("IsPaidUser")

if is_paid:
    # Pre-pay (subscription) user → show CreateTime / ReleaseTime
    create_time = response.get("CreateTime")   # ms timestamp
    release_time = response.get("ReleaseTime") # ms timestamp
else:
    # Post-pay user → parse PostPayModuleSwitch
    post_pay_switch = response.get("PostPayModuleSwitch")  # JSON string
    switch_data = json.loads(post_pay_switch)
    for code, status in switch_data.items():
        print(f"{code}: {'Enabled' if status == 1 else 'Disabled'}")

INCORRECT

# Wrong: always reading CreateTime/ReleaseTime without checking IsPaidUser
create_time = response["CreateTime"]
release_time = response["ReleaseTime"]

# Wrong: always reading PostPayModuleSwitch without checking IsPaidUser
switch_data = json.loads(response["PostPayModuleSwitch"])

# Wrong: treating PostPayModuleSwitch as a dict directly (it's a JSON string)
switch_data = response["PostPayModuleSwitch"]["POST_HOST"]

7. Security Score Extraction — Use DescribeSecureSuggestion Score (DescribeScreenScoreThread currently unavailable)

CORRECT

# Current: use DescribeSecureSuggestion
score = suggestion_response["Score"]

# NOTE: DescribeScreenScoreThread is currently unavailable (CalType not supported).
# Once supported, switch to:
#   score_list = response["Data"]["SocreThread"]
#   current_score = score_list[-1]   # Last element = current score
#   score_trend = score_list          # Full list = historical trend

INCORRECT

# Wrong: using DescribeScreenScoreThread which is currently unavailable
score_list = response["Data"]["SocreThread"]
# Wrong: looking for ScoreValue field
current_score = response["Data"]["ScoreValue"]

8. Service Duration — Must check IsPaidUser before calculating days

CORRECT

is_paid = response.get("IsPaidUser")

if is_paid:
    # Pre-pay user → calculate service duration
    create_time = response.get("CreateTime")  # ms timestamp
    days = (time.time() * 1000 - create_time) / (1000 * 86400)
    print(f"累计使用天数: {int(days)}")
else:
    # Post-pay user → no subscription period
    print("累计使用天数: N/A")

INCORRECT

# Wrong: always calculating days without checking IsPaidUser
create_time = response["CreateTime"]
days = (time.time() * 1000 - create_time) / (1000 * 86400)
# This gives meaningless results for post-pay users

9. User-Agent — Every aliyun command must include --user-agent

CORRECT

aliyun sas describe-version-config --user-agent AlibabaCloud-Agent-Skills

INCORRECT

# Wrong: missing --user-agent
aliyun sas describe-version-config

10. Execution Scope — Only execute modules/items relevant to the user's query

CORRECT

# User asks: "What is my security score?"
# → Execute ONLY Module 1, command 1a (DescribeSecureSuggestion; DescribeScreenScoreThread currently unavailable)

# User asks: "Show me asset risk trends"
# → Execute ONLY Module 4 (all sub-commands: 4a, 4b, 4c, 4d)

# User asks: "How many uninstalled clients?"
# → Execute ONLY Module 2, command 2c (ListUninstallAegisMachines)

# User asks: "Give me the full SAS overview"
# → Execute all 5 modules

INCORRECT

# Wrong: User asks "What is my security score?" but agent runs all 5 modules
# Wrong: User asks "How many uninstalled clients?" but agent runs Modules 1-5
# Wrong: User asks about billing but agent also queries asset risk trends

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies

Required Permissions

The following RAM permissions are required for all APIs used in this skill.

SAS (Security Center)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "yundun-sas:DescribeScreenScoreThread",
        "yundun-sas:DescribeVulFixStatistics",
        "yundun-sas:GetDefenceCount",
        "yundun-sas:GetCheckRiskStatistics",
        "yundun-sas:DescribeVersionConfig",
        "yundun-sas:ListUninstallAegisMachines",
        "yundun-sas:DescribeSecureSuggestion",
        "yundun-sas:DescribeCloudCenterInstances",
        "yundun-sas:DescribeFieldStatistics",
        "yundun-sas:DescribeContainerFieldStatistics",
        "yundun-sas:GetCloudAssetSummary",
        "yundun-sas:DescribeChartData"
      ],
      "Resource": "*"
    }
  ]
}

WAF (Web Application Firewall)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "yundun-waf:DescribeInstance",
        "yundun-waf:DescribeFlowChart"
      ],
      "Resource": "*"
    }
  ]
}

BssOpenApi (Billing)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bss:QueryBill"
      ],
      "Resource": "*"
    }
  ]
}

Recommended System Policy

For read-only access, attach the following managed policies:

Related APIs

SAS (Security Center) — Product: Sas, Version: 2018-12-03

WAF (Web Application Firewall) — Product: waf-openapi, Version: 2021-10-01 (WAF 3.0 only)

Note: This skill only supports WAF 3.0 (Version 2021-10-01). WAF 2.0 (Version 2019-09-10) is NOT compatible.

BssOpenApi (Billing) — Product: BssOpenApi, Version: 2017-12-14

Verification Method

After executing the skill, verify each module's data was retrieved successfully.

Module 1: Security Overview

# Verify security score retrieval
aliyun sas describe-secure-suggestion \
  --cal-type home_security_score \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "Score"
# NOTE: DescribeScreenScoreThread is currently unavailable (CalType not supported).
# Once supported, verify with:
#   START=$(python3 -c "import time; print(int((time.time()-86400*7)*1000))")
#   END=$(python3 -c "import time; print(int(time.time()*1000))")
#   aliyun sas describe-screen-score-thread \
#     --cal-type home_security_score \
#     --start-time "$START" --end-time "$END" \
#     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
#     --cli-query "Data.SocreThread[-1]"

# Verify vulnerability fix count
aliyun sas describe-vul-fix-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "FixTotal"

# Verify baseline risk statistics
aliyun sas get-check-risk-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "Summary.{RiskCheck: RiskCheckCnt, RiskWarning: RiskWarningCnt, HandledTotal: HandledCheckTotal, HandledToday: HandledCheckToday}"

# Verify handled alert count
aliyun sas get-defence-count \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "SuspiciousDealtCount"

Expected: All commands return numeric values without errors.

Module 2: Usage Info

# Verify version config (IsPaidUser + CreateTime for days calculation)
aliyun sas describe-version-config \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "{IsPaidUser: IsPaidUser, CreateTime: CreateTime}"

# Verify host asset info (multi-region)
aliyun sas describe-cloud-center-instances \
  --region cn-shanghai --machine-types ecs --current-page 1 --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "PageInfo.TotalCount"
aliyun sas describe-cloud-center-instances \
  --region ap-southeast-1 --machine-types ecs --current-page 1 --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "PageInfo.TotalCount"

# Verify uninstalled clients count
aliyun sas list-uninstall-aegis-machines \
  --region cn-shanghai \
  --current-page 1 --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "TotalCount"

Expected:

• IsPaidUser is true or false
• If IsPaidUser == true (pre-pay): CreateTime is a non-zero ms timestamp → calculate (now - CreateTime) as days
• If IsPaidUser == false (post-pay): CreateTime not meaningful → display N/A for service duration
• Asset counts are numeric. TotalCount is numeric.

Module 3: Security Operations

3a. Risk Governance

# Verify risk governance suggestions (includes AI risk, CSPM, key config, system vulns)
aliyun sas describe-secure-suggestion \
  --cal-type home_security_score \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "Suggestions[].{Type: SuggestType, SubType: Detail[].SubType}"
# Verify SS_SAS_SYS_VUL appears in output with SubTypes:
#   SSI_SAS_SYS_VUL_HIGH, SSI_SAS_SYS_VUL_MEDIUM, SSI_SAS_SYS_VUL_LOW

Expected: Returns array of suggestions with SuggestType and SubType fields, including SS_SAS_SYS_VUL for system vulnerabilities.

3b. Security Protection — WAF

# Verify WAF Instance ID retrieval (multi-region)
aliyun waf-openapi describe-instance \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "InstanceId"
aliyun waf-openapi describe-instance \
  --region ap-southeast-1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "InstanceId"

# Verify WAF flow chart (use InstanceId from above, per region)
aliyun waf-openapi describe-flow-chart \
  --region cn-shanghai \
  --instance-id "<InstanceId from cn-shanghai>" \
  --start-timestamp "$(python3 -c 'import time; print(int(time.time()-86400*7))')" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
aliyun waf-openapi describe-flow-chart \
  --region ap-southeast-1 \
  --instance-id "<InstanceId from ap-southeast-1>" \
  --start-timestamp "$(python3 -c 'import time; print(int(time.time()-86400*7))')" \
  --interval 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}

Expected: WAF DescribeInstance returns a valid InstanceId. DescribeFlowChart returns flow data with WafBlockSum fields.

3c. Security Response

Currently N/A — no verification needed.

Module 4: Asset Risk Trend

# Verify host assets (ECS)
aliyun sas describe-cloud-center-instances \
  --region cn-shanghai \
  --machine-types ecs --current-page 1 --page-size 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "PageInfo.TotalCount"

aliyun sas describe-field-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "GroupedFields.RiskInstanceCount"

# Verify container assets
aliyun sas describe-container-field-statistics \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "{Clusters: ClusterCount, RiskClusters: RiskClusterCount}"

# Verify cloud product assets
aliyun sas get-cloud-asset-summary \
  --region cn-shanghai \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "GroupedFields.{Total: InstanceCountTotal, Risk: InstanceRiskCountTotal}"

Expected: All commands return valid numeric counts.

Module 5: Billing & Subscription

# Verify billing mode and subscription status
aliyun sas describe-version-config \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id} \
  --cli-query "{IsPaidUser: IsPaidUser, CreateTime: CreateTime, ReleaseTime: ReleaseTime, PostPaySwitch: PostPayModuleSwitch}"

# Verify billing details (try each region, skip on permission error)
BILLING_CYCLE=$(date +%Y-%m)
aliyun bssopenapi query-bill \
  --region cn-shanghai \
  --billing-cycle "$BILLING_CYCLE" --product-code sas \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/{session-id}
# If permission denied, skip and try next region

Expected:

• IsPaidUser is true or false
• If true (pre-pay): CreateTime and ReleaseTime are non-zero ms timestamps
• If false (post-pay): PostPayModuleSwitch is a parseable JSON string

Quick Full Check

Run all verification commands together. If all return data without errors, the skill is working correctly.