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

云安全中心总览信息

@aliyun/alibabacloud-sas-overview

查询当前账号下云安全中心的总览数据信息，包括：风险治理情况、安全防护事件、资产统计、付费服务、安全分等数据。

云Skills门户 热度 27v0.0.4

SAS 总览数据查询

获取云安全中心（SAS）总览看板的 5 个核心模块：

  1. 安全概览——安全评分、已修复漏洞、基线风险、已处理告警
  2. 使用信息——服务天数、资产规模、未安装客户端
  3. 安全运营——风险治理（AI 风险、CSPM、关键配置、系统漏洞）、安全防护（WAF 拦截）、安全响应
  4. 资产风险趋势——主机/容器/云产品风险占比 + 趋势图
  5. 账单与订阅——按量付费开关、订阅有效期、账单
执行范围：每个模块及其中的每个数据项均可独立查询。
根据用户请求匹配查询范围：
- 单个数据项——例如，“我的安全评分是多少？” → 仅执行命令 1a
- 单个模块——例如，“显示资产风险趋势” → 执行模块 4 的全部内容
- 完整总览——例如，“SAS 总览” → 执行全部 5 个模块

架构：SAS + WAF + BssOpenApi

可观测性

User-Agent 模板：

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

Session-ID 生成规则：

  • 在每次 skill 执行会话开始时生成一个 UUID v4（例如 550e8400-e29b-41d4-a716-446655440000）。
  • 在单个会话中，所有 aliyun CLI 命令必须使用同一个 {session-id}，以确保一次执行发出的所有请求都能在日志中关联起来。
  • 每次新调用 skill 时都必须生成一个全新的 session-id。

用法：在每条 aliyun CLI 命令中，通过 --user-agent 标志传入完整的 UA 字符串：

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

前提条件

预检查：阿里云 CLI 必须为 3.3.1 或更高版本
运行 aliyun version，验证版本是否 >= 3.3.1。如果尚未安装或版本过低，
运行 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，确保所有现有插件始终为最新版本。
设置 --auto-plugin-install true 后，所需插件（sas、waf-openapi、bssopenapi）将在首次使用时自动安装，无需手动执行 aliyun plugin install。
预检查：必须具备阿里云凭据
安全规则：
- 禁止读取、回显或打印 AK/SK 值（例如，严禁执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
- 禁止要求用户直接在对话或命令行中输入 AK/SK
- 禁止使用 aliyun configure set 设置明文凭据值
- 只能使用 aliyun configure list 检查凭据状态
```bash
aliyun configure list
```
检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效配置文件，必须在此停止。
1. 从阿里云控制台获取凭据
2. 在此会话之外配置凭据（通过终端中的 aliyun configure 或 shell 配置文件中的环境变量）
3. 待 aliyun configure list 显示有效配置文件后，返回并重新运行

参数

重要：参数确认——在执行任何命令或 API 调用之前，
所有用户可自定义的参数（例如 RegionId、WAF InstanceId、BillingCycle 等）
都必须与用户确认。未经用户明确批准，不得自行假定或使用默认值。

| 参数 | 是否必需 | 说明 | 默认值 | |-----------|----------|-------------|---------| | 地域 | 是 | 要聚合数据的 SAS 地域 | cn-shanghai, ap-southeast-1 | | WAF 实例 ID | 自动获取 | 通过 WAF DescribeInstance 自动获取，供 DescribeFlowChart 使用 | 自动 | | 账单周期 | 仅账单查询时需要 | 采用 YYYY-MM 格式的账单月份 | 当前月份 | | 时间范围 | 否 | 评分/趋势查询的历史数据天数 | 7（最近 7 天） |

RAM 权限

有关完整的 RAM 策略 JSON，请参阅 [references/ram-policies.md](references/ram-policies.md)。

必须具备：AliyunYundunSASReadOnlyAccess、AliyunWAFReadOnlyAccess、AliyunBSSReadOnlyAccess。

核心工作流

根据用户查询，执行以下相关模块。每个模块及模块内的每个数据项均可独立执行。对于标记为 多地域 的 APIs，始终查询 cn-shanghai 和 ap-southeast-1 两个地域，然后对结果求和。

模块 1：安全概览

# 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}

模块 2：使用信息

# 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}

模块 3：安全运营

3a. 风险治理（不区分地域，单次 API 调用）

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. 安全防护——WAF 拦截（多地域、两步操作、仅限 WAF 3.0）

WAF 版本要求：本模块使用 WAF 3.0 API（产品：waf-openapi，版本：2021-10-01）。WAF 2.0 实例（版本 2019-09-10）不兼容——InstanceId 和 WafBlockSum 等字段可能缺失或采用不同的结构。如果用户的 WAF 实例为 2.0，请告知用户该模块不支持其实例版本。
地域说明：waf-openapi（WAF 3.0）是采用集中式端点的产品——中国站的 RegionId 为 cn-hangzhou（不得使用 cn-shanghai）。此外，这些命令中也不得传入 --version：该参数会强制使用 Location 服务端点解析器，该解析器仅识别 cn-hangzhou/ap-southeast-1，并会在其他 RegionIds 上失败。
# Step 1: Get WAF Instance ID (per region)
aliyun waf-openapi describe-instance --region cn-hangzhou --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-hangzhou \
  --instance-id "<InstanceId from cn-hangzhou>" \
  --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. 安全响应（不区分地域，使用与 3a 相同的 API）

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

模块 4：资产风险趋势

# 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

模块 5：计费与订阅

# 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

产品代码映射

| 产品名称 | 代码 | 状态值 | |:---|:---|:---| | 主机及容器安全 | POST_HOST | 1：已启用，0：已禁用 | | 漏洞修复 | VUL | 1：已启用，0：已禁用 | | CSPM | CSPM | 1：已启用，0：已禁用 | | 智能体 SOC | CTDR | 1：已启用，0：已禁用 | | 无代理检测 | AGENTLESS | 1：已启用，0：已禁用 | | 无服务器资产防护 | SERVERLESS | 1：已启用，0：已禁用 | | 应用防护 | RASP | 1：已启用，0：已禁用 | | 恶意文件检测 | SDK | 1：已启用，0：已禁用 | | 日志管理 | CTDR_STORAGE | 1：已启用，0：已禁用 | | 防勒索 | ANTI_RANSOMWARE | 1：已启用，0：已禁用 |

数据处理规则

  1. 多地域聚合：需要指定地域的 APIs 必须分别查询 cn-shanghai 和 ap-southeast-1，然后对数值结果求和。
  • 权限错误处理：如果某个地域返回权限错误（例如 Forbidden 或 NoPermission），不得静默跳过。必须明确告知用户哪些地域成功、哪些地域失败，并说明缺失的权限。示例："已从 cn-shanghai 获取数据，但 ap-southeast-1 返回权限被拒绝（缺少 sas:DescribeSecureSuggestion）。结果仅反映 cn-shanghai 的数据。"
  1. 时间戳：SAS APIs 使用毫秒时间戳。WAF APIs 使用秒时间戳。
  2. PostPayModuleSwitch：这是一个 JSON 字符串——读取前必须先调用 JSON.parse() / json.loads() 进行解析。
  3. 评分提取：使用 DescribeSecureSuggestion 响应中的 Score 字段作为当前评分。注意：Score 返回的是字符串（例如 "90.0"），而非数字——在比较或显示前将其转换为浮点数。注意：DescribeScreenScoreThread 当前不可用（不支持 CalType）；一旦支持，则改用 Data.SocreThread[] 的最后一个元素作为当前评分，并将完整列表用作历史趋势。
  4. 安全响应：从 DescribeSecureSuggestion 中提取，其中 SuggestType == "SS_SAS_ALARM"。SubTypes：SSI_SAS_ALARM_HIGH（紧急）、SSI_SAS_ALARM_MEDIUM（可疑）、SSI_SAS_ALARM_LOW（提醒）。
  5. 时间戳格式化：将毫秒时间戳转换为 YYYY-MM-DD HH:mm:ss 格式后显示。

成功验证

有关分步验证命令，请参阅 [references/verification-method.md](references/verification-method.md)。

清理

此 skill 为只读（仅执行查询操作）。不会创建任何资源，因此无需清理。

最佳实践

  1. 对多地域 APIs 进行聚合前，始终查询以下两个地域：cn-shanghai 和 ap-southeast-1。
  2. 缓存 DescribeVersionConfig 响应——模块 2 和模块 5 均会使用该响应。
  3. 使用 --cli-query（JMESPath）提取特定字段并减少输出中的无关信息。
  4. 仅需要 TotalCount 时，设置 --page-size 1（例如 ListUninstallAegisMachines）。
  5. WAF DescribeFlowChart 需要有效的 WAF 实例 ID——先通过 DescribeInstance 自动获取；同时查询 cn-shanghai 和 ap-southeast-1。
  6. 账单查询（QueryBill）需要 --region——依次尝试各地域（cn-shanghai、ap-southeast-1）；跳过任何返回权限错误的地域。
  7. SAS 返回的所有时间戳均以毫秒为单位——除以 1000 可转换为人类可读格式。

参考链接

| 文档 | 内容 | |----------|---------| | [references/related-apis.md](references/related-apis.md) | 完整的 API 和 CLI 命令参考表 | | [references/ram-policies.md](references/ram-policies.md) | 所需的 RAM 权限和策略 | | [references/verification-method.md](references/verification-method.md) | 分步验证命令 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 正确/错误的 CLI 模式 | | [references/cli-installation-guide.md](references/cli-installation-guide.md) | CLI 安装指南 |

qianwen skills install @aliyun/alibabacloud-sas-overview