alibabacloud-sas-overview

SAS 概览数据查询

获取 Security Center（SAS）概览仪表板的 5 个核心模块：

1. 安全概览 — 分数、已修复漏洞、基线风险、已处理警报
2. 使用情况信息 — 服务天数、资产规模、未安装客户端
3. 安全运营 — 风险治理（AI 风险、CSPM、关键配置、系统漏洞）、安全防护（WAF 拦截）、安全响应
4. 资产风险趋势 — 主机／容器／云产品风险比率 + 趋势图表
5. 账单与订阅 — 后付费开关、订阅有效期、账单

执行范围：每个模块和数据项都可以单独查询。 根据用户请求匹配范围：

• 单个数据项 — 例如，“我的安全分数是多少？”→ 仅执行命令 1a
• 单个模块 — 例如，“显示资产风险趋势”→ 查询模块 4 的全部内容
• 完整概览 — 例如，“SAS 概览”→ 查询全部 5 个模块

架构：SAS + WAF + BssOpenApi

服务可用性 — 仅检查用户所需的功能

此概览没有通用的付费版前置要求。基础 SAS 查询、付费功能可用性、WAF 可用性和账单权限彼此独立。查询付费功能或完整概览前，请复用 DescribeVersionConfig 检查 Version、IsPostpay、IsTrialVersion、PostPayStatus 和模块开关。不要根据付费版推断所有功能都可用，也不要认为免费版无法执行所有查询。自检方法和功能矩阵请参阅 service-prerequisites.md。切勿自动购买或升级。

执行反馈

使用用户所用的语言回复。查询前，说明已选择的项目、已确认的区域和当前步骤。在模块／区域切换及重试时，报告已完成和正在执行的内容；对于分页，在已知时显示已收集数量／总数。不要编造完成百分比。长时间调用时，告知用户正在等待，但不要声称获得了新结果。结束时列出已完成、失败／未知和不适用的项目，包括部分覆盖情况和后续步骤。进度反馈中切勿打印凭据或原始响应。脚本进度输出到 stderr；stdout 保持为机器可读的 JSON。 示例：“正在查询上海第 2 页：已收集 20/45 台主机；尚未开始查询新加坡。”

可观测性

由清单生成的 User-Agent：每次云端查询都必须使用 AlibabaCloud-Agent-Skills/alibabacloud-sas-overview/<session UUID> skill-version/<manifest version>。 references/manifest.json 中顶层的 version 是此 Skill 的版本（独立于 CLI/API 版本）。发布 Skill 更改时请更新该值；不要在命令中硬编码版本或使用未解析的占位符。

运行任何查询示例前，请先在已安装的 Skill 目录中运行一次：

USER_AGENT=$(python3 scripts/user_agent.py) || exit 2
export USER_AGENT

该辅助程序会根据自身文件定位清单，验证版本为非空字符串，生成新的 UUID v4，并在运行时组装完整的 UA。若清单缺失或无效，初始化将停止；切勿回退到未带版本的 UA。本次会话中的所有调用、分页和重试都必须复用此 USER_AGENT。如果工具使用不同的 shell，请将生成的值显式传入每个 shell；不要为每条命令重新生成。每次新的 Skill 调用都会生成新的 UUID。 此 Skill 及其参考资料中的所有示例都使用 --user-agent "$USER_AGENT"。 库存和重试辅助程序会原样传递该值。CLI 契约检查器每次运行时会使用同一构建器，为所有帮助调用生成一次该值。

本地维护命令（version、configure、plugin）有各自的标志；CLI 3.4.11 中，configure 和 plugin update 不接受 --user-agent。

前置条件

预检查：需要 Aliyun CLI >= 3.3.1 运行 aliyun version，确认版本 >= 3.3.1。如果尚未安装或版本过低， 运行 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，确保所有现有插件始终保持最新。

设置 --auto-plugin-install true 后，首次使用时会自动安装所需插件（sas、waf-openapi、bssopenapi），无需手动运行 aliyun plugin install。

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止运行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户直接在对话或命令行中输入 AK/SK
• 绝不使用包含明文凭证值的 aliyun configure set
• 只能使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否有有效配置（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请在此处停止。

1. 使用账号对应站点的 RAM 控制台：国际站 / 中国站控制台链接。如果站点未知，请先确认；资产所在地域或提示语言不能用于判断站点。
2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回后，待 aliyun configure list 显示有效配置，再重新运行

参数

确认参数：使用本会话中已提供或已批准的值。 仅询问所选范围内缺少的必需输入。以下建议默认值 仅供参考，不会自动采用。单地域请求仍只查询单个地域。

参数	必需条件	来源 / 候选值
SAS 地域	查询 SAS 地域项	确认 cn-shanghai 和/或 ap-southeast-1
WAF 地域	查询 WAF 统计数据	确认 cn-hangzhou 和/或 ap-southeast-1
WAF InstanceId	DescribeFlowChart	在同一账号和 WAF 地域中成功执行 DescribeInstance
BillingCycle	查询账单明细	确认 YYYY-MM；根据用户时区，将“本月”解析一次
TimeRangeDays	查询 WAF / 趋势数据	确认一个正整数；候选值为 7 天
账号站点	控制台导航 / 账单	明确选择国际站或中国站；与地域无关

在运行示例前，将 TIME_RANGE_DAYS 和 BILLING_CYCLE 设为已确认的值。 关于必需标志、依赖项检查和时间戳单位，请参阅 query-parameters.md。绝不执行占位值。

RAM 权限

完整的 RAM 策略 JSON 见 references/ram-policies.md。

权限因查询范围而异：SAS 项需要 SAS 读取操作；WAF 统计数据 需要 WAF 读取操作；账单明细必须具有 bss:QueryBill 权限（或 AliyunBSSReadOnlyAccess）。仅进行账单配置时使用 SAS 权限。 使用 python3 scripts/query_permissions.py <items> 可离线列出所选操作。 某项服务被拒绝访问，不应阻止其他独立项目，也不应将其显示为零数据。

服务地域

产品	中国服务地域	中国境外服务地域
SAS	cn-shanghai	ap-southeast-1
WAF 3.0	cn-hangzhou	ap-southeast-1

这些是服务端点，并非任意 ECS 资产地域。请确认要查询的服务地域；不要将 SAS 的上海地域值复制到 WAF 命令中。请分别在每个已确认的 WAF 地域中查询 WAF InstanceId。没有 WAF 实例表示“ 不适用”，而非被拦截请求数为零。端点错误属于查询失败。

核心工作流

根据用户的查询，执行以下相关模块。每个模块以及模块中的每个数据项都可以独立执行。对于标记为多区域的 API，仅查询已确认的区域，然后汇总兼容且已验证的结果。只有在请求了两个区域时，才适用双区域示例。

模块 1：安全概览

# 1a. Security Score (region-agnostic)
aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent "$USER_AGENT"
# Validate the full saved response with: python3 scripts/overview_response.py score < response.json
# Exit 0/status=ok: display score (including zero). Exit 2/status=error: report failure.
# HTTP 200 with Score=null/missing is NOT success; do not substitute zero.
#
# 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 "$USER_AGENT"
#   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 "$USER_AGENT"
aliyun sas describe-vul-fix-statistics --region ap-southeast-1 --user-agent "$USER_AGENT"

# 1c. Baseline Risk Statistics (multi-region: sum each Summary field)
aliyun sas get-check-risk-statistics --region cn-shanghai --user-agent "$USER_AGENT"
aliyun sas get-check-risk-statistics --region ap-southeast-1 --user-agent "$USER_AGENT"
# 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 "$USER_AGENT"
aliyun sas get-defence-count --region ap-southeast-1 --user-agent "$USER_AGENT"

模块 2：使用信息

# 2a. Service Duration + Subscription (region-agnostic)
aliyun sas describe-version-config --user-agent "$USER_AGENT"
# Validate the saved response: python3 scripts/overview_response.py times < response.json
# OpenTime → service opening; PostPayOpenTime → pay-as-you-go opening (ms).
# Report elapsed days separately, regardless of subscription/postpay coexistence.
# ReleaseTime → instance expiry; do not call it pay-as-you-go expiry.
# Missing/zero/invalid dates are unknown with a reason, never fabricated or forced N/A.
# Do not calculate duration from the undocumented legacy CreateTime field.

# 2b. Host Asset Info: fetch EVERY page before summing Cores.
# Run from this skill directory, after confirming the SAS regions.
python3 scripts/host_inventory.py --regions cn-shanghai ap-southeast-1 \
  --user-agent "$USER_AGENT"
# complete=true: total_count and total_cores cover both regions.
# Exit 2 / complete=false: report the failed region/page and partial counts;
# never present partial_cores as a full inventory. Do not add TotalCount per page.
# For host details, use the same page loop and retain each instance by Uuid.

# 2c. Uninstalled Clients (multi-region: sum TotalCount)
aliyun sas list-uninstall-aegis-machines --region cn-shanghai --current-page 1 --page-size 1 --user-agent "$USER_AGENT"
aliyun sas list-uninstall-aegis-machines --region ap-southeast-1 --current-page 1 --page-size 1 --user-agent "$USER_AGENT"

模块 3：安全操作

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

aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent "$USER_AGENT"
# 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）。已安装的插件帮助信息必须报告 API 2021-10-01。请勿混用 WAF 2.0 参数，也不要添加未经验证的版本覆盖；如果插件的默认版本不同，请更新或检查插件。

# Step 1: Get WAF Instance ID (per region)
aliyun waf-openapi describe-instance --region cn-hangzhou --user-agent "$USER_AGENT"
aliyun waf-openapi describe-instance --region ap-southeast-1 --user-agent "$USER_AGENT"
# Extract: InstanceId from each region's response

# Step 2: Query WAF flow chart using each region's InstanceId
START_SEC=$(python3 scripts/query_parameters.py window --days "$TIME_RANGE_DAYS" --unit seconds) || exit 2
aliyun waf-openapi describe-flow-chart \
  --region cn-hangzhou \
  --instance-id "<InstanceId from cn-hangzhou>" \
  --start-timestamp "$START_SEC" \
  --interval 3600 \
  --user-agent "$USER_AGENT"
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 "$USER_AGENT"
# Sum all WafBlockSum values from both regions

3c. 安全响应（不区分区域，与 3a 使用相同的 API）

aliyun sas describe-secure-suggestion --cal-type home_security_score --user-agent "$USER_AGENT"
# 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：资产风险趋势

必需的主机风险输入：对于每个已确认的 SAS 区域，同时获取 DescribeCloudCenterInstances.PageInfo.TotalCount（使用 MachineTypes=ecs）和 DescribeFieldStatistics.GroupedFields.RiskInstanceCount。后一个 API 的 InstanceCount 不能替代所需的 TotalCount，即使其值为零也不行。如果本次会话中存在使用相同账户、区域和筛选条件的已验证响应，请复用；否则执行以下两个调用。仅查询计数时，只需设置 CurrentPage=1, PageSize=1；完整的资产清单分页和 CPU 核心数汇总属于用户请求时执行的模块 2b。

验证两个计数均为非负整数、范围相同，且风险数不大于总数。缺少输入或输入失败意味着主机风险数据不完整；保留其他结果，且不要将整个模块标记为已完成。总数有效且为零时，报告该比率为不适用。计算比率前，先汇总兼容的区域计数。

# 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 "$USER_AGENT"
# Extract: PageInfo.TotalCount

aliyun sas describe-field-statistics \
  --region cn-shanghai \
  --user-agent "$USER_AGENT"
# Extract: GroupedFields.RiskInstanceCount
# Repeat BOTH calls above for ap-southeast-1 when confirmed, then sum each metric.

# 4b. Container Assets (multi-region)
aliyun sas describe-container-field-statistics \
  --region cn-shanghai \
  --user-agent "$USER_AGENT"
# 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 "$USER_AGENT"
# Extract: GroupedFields.InstanceCountTotal, GroupedFields.InstanceRiskCountTotal
# Repeat for ap-southeast-1, sum both

# 4d. Trend Chart Data (multi-region)
START_MS=$(python3 scripts/query_parameters.py window --days "$TIME_RANGE_DAYS" --unit ms) || exit 2
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 "$USER_AGENT"
# 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 "$USER_AGENT"
# Process the full response with: python3 scripts/overview_response.py billing < response.json
# IsPostpay indicates pay-as-you-go independently of subscription/trial evidence.
# Always parse PostPayModuleSwitch when supplied; do not gate it on IsPaidUser.
# Show coexistence, suspended service and unknown fields explicitly.
# See references/billing-semantics.md for the decision table and FAQ.

# 5c. Billing Details (BSS read permission required; failures remain visible)
BILLING_CYCLE=$(python3 scripts/query_parameters.py billing --cycle "$BILLING_CYCLE") || exit 2
aliyun bssopenapi query-bill \
  --region cn-shanghai \
  --billing-cycle "$BILLING_CYCLE" --product-code sas \
  --user-agent "$USER_AGENT"
# 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 "$USER_AGENT"
# If the above returns a permission error, do NOT silently skip — inform the user (see Data Processing Rules §1)
# QueryBill is account-level: verify bill identity/coverage before combining endpoint results.
# Fetch all bill pages if reporting complete details/totals; do not sum duplicate bills.
# Explicitly report any failed requested coverage.

产品代码映射

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

查询失败

通过 scripts/cli_query.py -- aliyun ... 执行工作流 CLI 查询，进行有次数限制的瞬时故障重试（等待 1s/2s，最多尝试 3 次）；host_inventory.py 会在内部执行此操作。权限、参数和不支持的服务错误应立即停止，不要重试。遵循 query-errors.md；报告已耗尽重试次数的项目，并继续执行其他独立的请求查询，明确标注部分结果。

数据处理规则

1. 多地域聚合：分别查询每个已确认的服务地域。仅汇总兼容且已验证的 SAS/WAF 计数；不得盲目累加跨终端地域的账号级账单。
   • 权限错误处理：如果某个地域返回权限错误（例如 Forbidden 或 NoPermission），不得默默跳过。必须明确告知用户哪些地域查询成功、哪些失败，并说明缺少的权限。例如：“已从 cn-shanghai 获取数据，但 ap-southeast-1 返回权限被拒绝（缺少 sas:DescribeSecureSuggestion）。结果仅反映 cn-shanghai。”
2. 时间戳：SAS API 使用毫秒时间戳。WAF API 使用秒时间戳。
3. PostPayModuleSwitch：这是一个 JSON 字符串——读取前必须先执行 JSON.parse() / json.loads()。
4. 分数验证：请求分数时，对完整 JSON 响应运行 scripts/overview_response.py score。缺失、null、空值、非数字或非有限分数都属于错误；保留 RequestId 以便诊断。实际的 0 是有效值。不得根据是否存在建议来推断分数。分数提取：使用 DescribeSecureSuggestion 响应中的 Score 字段作为当前分数。注意：Score 返回的是字符串（例如 "90.0"），而非数字——比较或显示前需将其转换为浮点数。注意：DescribeScreenScoreThread 当前不可用（不支持 CalType）；支持后，改为使用 Data.SocreThread[] 的最后一个元素作为当前分数，并使用完整列表作为历史趋势。
5. 安全响应：从 DescribeSecureSuggestion 中提取，其中 SuggestType == "SS_SAS_ALARM"。子类型：SSI_SAS_ALARM_HIGH（紧急）、SSI_SAS_ALARM_MEDIUM（可疑）、SSI_SAS_ALARM_LOW（提醒）。
6. 时间戳格式：将毫秒时间戳转换为易读日期，并明确标注时区（辅助函数使用 UTC）。

成功验证

仅验证请求的范围，包括每个已确认的地域/页面及所需的业务字段。仅 HTTP/CLI 成功并不足够。根据验证证据/原因，将每项记录为成功、失败、未知或不适用；对该结果清单使用 scripts/verify_overview.py --expected <items>，以检测缺失项和部分完成情况。此检查的是覆盖范围，而非原始 API 语义。各项检查方法请参阅 references/verification-method.md 和 acceptance-criteria.md。

清理

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

最佳实践

1. 报告完整覆盖情况前，先查询每个已确认地域；不要添加未经请求的地域。
2. 缓存 DescribeVersionConfig 响应——Module 2 和 Module 5 都会使用它。
3. 使用 --cli-query（JMESPath）提取特定字段，减少输出噪声。
4. 仅需 TotalCount 时（例如 ListUninstallAegisMachines），设置 --page-size 1。
5. WAF DescribeFlowChart 需要有效的 WAF 实例 ID——先通过 DescribeInstance 自动获取；使用用户确认的 WAF 服务地域 cn-hangzhou 和 ap-southeast-1。切勿复用 SAS 地域，或使用其他 WAF 地域的 InstanceId。
6. 账单详情需要 BSS 读取权限。报告被拒绝的地域/操作及部分覆盖情况；保留独立的 SAS/WAF 结果。切勿将被拒绝的账单查询报告为零支出。
7. SAS 返回的所有时间戳都以毫秒为单位——除以 1000 后再转换为易读时间。

参考链接

文档	内容
references/billing-semantics.md	计费依据与共存常见问题
references/related-apis.md	完整 API 和 CLI 命令参考表
references/ram-policies.md	所需的 RAM 权限和策略
references/verification-method.md	分步验证命令
references/acceptance-criteria.md	正确／错误的 CLI 模式
references/cli-installation-guide.md	CLI 安装指南