alibabacloud-governance-evaluation-report

阿里云治理中心评估报告

通过循序渐进的深入探索工作流，引导用户发现治理风险、聚焦关键问题并采取整改措施。

场景说明

此技能是问题发现与解决指南，而非全面的审计报告生成器。它采用逐步展开的漏斗式流程：

1. 概览（快速诊断） — 评分 + 支柱分布 + 最重要的关键风险 → 引导用户选择方向
2. 支柱分析（聚焦深入探索） — 特定领域内的所有风险，按严重程度控制 → 引导用户找到具体项目
3. 详情（深入分析） — 单个检查项的完整整改步骤 → 引导用户查看相关项目或资源
4. 资源（采取行动） — 列出不合规资源，以便有针对性地整改

每一层都聚焦于最重要的信息，并引导用户进入下一层。避免信息过载——保持输出简洁且可执行。

架构：治理中心 API → CLI (aliyun governance) → governance_query.py（合并 + 缓存）→ JSON 输出 → Agent 报告

工作原理

数据来源 — 三个 API 提供所有数据：

1. list-evaluation-metadata — 检查项定义（名称、描述、支柱、级别、整改方案）
2. list-evaluation-results — 实际结果（状态、风险、合规率、评分）
3. list-evaluation-metric-details — 特定检查项的不合规资源详情

处理流程 — 脚本（governance_query.py）合并数据源并缓存结果 1 小时。它提供 4 种查询模式：overview、pillar、detail、resources。

输出 — 结构化 JSON，供 Agent 生成便于用户理解的报告。报告会以格式化文本的形式直接输出在对话中，而不会写入文件。

---

前置条件

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 请使用包管理器，或使用 references/cli-installation-guide.md 中经过 SHA256 验证的固定版本软件包。 请勿将远程下载的安装脚本直接通过管道传入 shell。

然后[必须]运行 aliyun plugin update，确保本机上的所有现有插件始终为最新版本。

[必须] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。

aliyun version                                    # >= 3.3.3
aliyun configure set --auto-plugin-install true   # Enable auto plugin install
python3 --version                                 # Python 3.x

可观测性

此技能发出的每次 Alibaba Cloud API 调用都必须包含完整的 User-Agent 模板：

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

对于此技能，{SKILL_NAME} 为 alibabacloud-governance-evaluation-report，因此具体格式为：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-governance-evaluation-report/{session-id}

Session ID 规则：

1. 每个会话（一次技能调用）使用 uuid.uuid4().hex 生成一个新的 Session ID。它必须是 32 位十六进制 UUID v4 值：恰好包含 32 个小写十六进制字符，且不带连字符。
2. 在该次调用中，对每次 Alibaba Cloud API 调用都重复使用同一个 Session ID，包括直接 CLI 命令、辅助脚本调用、分页和重试。
3. 不要在相关调用之间重新生成 Session ID。仅在新的技能调用开始时生成新的 Session ID。
4. 运行 governance_query.py 前，将 ALIBABA_CLOUD_AGENT_SESSION_ID 设置为该 32 位十六进制 Session ID。脚本会验证并重复使用所提供的 UUID；如果未设置此变量，则每个进程会生成一个 32 位十六进制 UUID v4 并重复使用。
5. 切勿根据账户 ID、凭据、用户数据或其他敏感值推导 Session ID。

运行 governance_query.py 前，请告知用户：该脚本会使用用户当前的 CLI 凭据调用本地 aliyun 可执行文件，并向 Alibaba Cloud Governance Center 发送只读查询。脚本会强制执行只读命令允许列表，验证所有动态参数，并在每次调用前将解析后的可执行文件和 API 操作输出到标准错误。

身份验证

配置 CLI 身份验证（推荐 OAuth）：

# OAuth mode (recommended)
aliyun configure --mode OAuth

RAM 策略

需要 Governance Center 读取权限。完整策略请参阅 references/ram-policies.md。

最低所需权限：

• governance:ListEvaluationMetadata
• governance:ListEvaluationResults

或者附加系统策略：AliyunGovernanceReadOnlyAccess

参数确认

此技能需要的用户专属参数很少。以下参数可能需要确认：

参数名称	必填/可选	描述	默认值
--profile	可选	Aliyun CLI 配置文件名称	默认配置文件
-c, --category	必填（pillar 模式）	支柱类别名称	不适用
--id	必填（detail/resources 模式）	检查项指标 ID	不适用
--keyword	可选（detail 模式）	检查项搜索关键词	不适用
--max-results	可选（resources 模式）	每页最大结果数	50

验证

使用前验证设置：

# Test CLI connection
aliyun governance list-evaluation-results \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-governance-evaluation-report/{session-id} \
  --cli-query "Results.TotalScore"

# Test script
export ALIBABA_CLOUD_AGENT_SESSION_ID="{session-id}"
python3 scripts/governance_query.py overview

详细步骤请参阅 references/verification-method.md。

---

核心工作流

重要：参数确认 — 执行任何命令或 API 调用之前， 必须向用户确认所有可自定义参数（例如 --profile、--category、--id、--keyword、 --max-results 等）。 未经用户明确批准，不要假设或使用默认值。

重要：输出格式 — 报告是仅适用于对话输出的格式规范。 始终将报告内容作为格式化 Markdown 直接输出到聊天消息中。 不要创建或写入报告文件（例如 .md、.txt、.html）。无需生成文件。

脚本位置：scripts/governance_query.py

全局选项

选项	描述
--refresh	强制刷新缓存（默认 TTL 为 1 小时）

---

模式 1：overview — 整体成熟度报告

使用场景：用户询问账户整体健康状况、成熟度评分，或希望获取摘要。

python3 scripts/governance_query.py overview
python3 scripts/governance_query.py overview -r Error              # Only high-risk items
python3 scripts/governance_query.py overview -r Error,Warning      # High + medium risk
python3 scripts/governance_query.py --refresh overview             # Force fresh data

选项：

选项	说明
-r, --risk	按风险级别筛选 RiskyItems（逗号分隔：Error、Warning、Suggestion）。PillarSummary 和 RiskDistribution 始终包含完整数据。

输出 JSON 字段：

• TotalScore — 整体成熟度评分（0.0-1.0）
• PillarSummary — 各支柱统计信息（已检查/有风险的数量，始终不受筛选影响）
• RiskDistribution — 按风险级别统计的数量（始终不受筛选影响）
• RiskyItems — 存在风险的项目；若指定了 --risk，则按其筛选，并按严重程度排序
• RiskFilter — 应用的风险筛选值（仅在使用 --risk 时出现）

报告格式：阅读 references/report-format-overview.md，了解确切的输出格式。

---

模式 2：pillar — 特定支柱报告

使用场景：用户询问特定领域（安全性、可靠性、成本等）。

python3 scripts/governance_query.py pillar -c <Category> [options]

选项：

选项	说明
-c, --category	必填。支柱名称（见下文）
--risky	仅显示有风险的项目（排除合规项目）
-l, --level	按建议级别筛选（逗号分隔）
-r, --risk	按实际风险级别筛选（逗号分隔）

类别值：

• Security — 安全性和访问控制
• Reliability — 可靠性和韧性
• CostOptimization — 成本优化
• OperationalExcellence — 运营效率
• Performance — 性能效率

级别值：Critical、High、Medium、Suggestion

风险值：Error、Warning、Suggestion、None

示例：

# All risky items in the Security pillar
python3 scripts/governance_query.py pillar -c Security --risky

# Only Critical/High-priority Error and Warning items
python3 scripts/governance_query.py pillar -c Security -l Critical,High -r Error,Warning --risky

输出 JSON 字段：

• Category、CategoryCN — 支柱名称
• MatchedCount — 匹配的项目数量
• Items — 带状态的检查项目列表

报告格式：阅读 references/report-format-pillar.md，了解确切的输出格式。

---

模式 3：detail — 检查项目详情

使用场景：用户询问某个特定检查项目，或询问如何修复问题。

python3 scripts/governance_query.py detail --id <metric-id>
python3 scripts/governance_query.py detail --keyword <search-term>

选项：

选项	说明
--id	检查项目 ID（例如：apbxftkv5c）
--keyword	按名称/描述搜索（若匹配多项，则显示列表）

示例：

# Query by ID
python3 scripts/governance_query.py detail --id apbxftkv5c

# Search by keyword
python3 scripts/governance_query.py detail --keyword "MFA"

输出 JSON 字段：

• 基本信息：Id、DisplayName、Description、Category
• 状态：Status、Risk、Compliance、NonCompliant
• Remediation — 修复步骤（Manual/Analysis/QuickFix）

报告格式：阅读 references/report-format-detail.md，了解确切的输出格式。必要时，详情格式也会包含资源列表。

---

模式 4：resources — 不合规资源

使用场景：用户希望查看哪些具体资源未通过某项检查。

python3 scripts/governance_query.py resources --id <metric-id>

选项：

选项	说明
--id	必填。检查项目 ID
--max-results	每页最大结果数（默认值：50）

示例：

# List RAM users without MFA enabled
python3 scripts/governance_query.py resources --id apbxftkv5c

# List security groups that expose high-risk ports
python3 scripts/governance_query.py resources --id a9g6pv7r5b

输出 JSON 字段：

• MetricId — 检查项目 ID
• TotalCount — 不合规资源的数量
• Resources[] — 资源列表：
  • ResourceId、ResourceName、ResourceType
  • RegionId、ResourceOwnerId
  • Classification — 风险分类
  • Properties — 特定于资源的属性

---

模式选择指南

用户说……	使用模式	命令	报告格式
“我的账户安全吗？” / “我的成熟度评分是多少？” / “分析我的治理结果”	overview	overview	概览
“有哪些高风险项？” / “显示所有高风险项”	overview	overview -r Error	概览
“显示中风险及以上的问题”	overview	overview -r Error,Warning	概览
“有哪些安全问题？” / “某个特定支柱中的风险”	pillar	pillar -c Security --risky	支柱
“网络安全检查” / “数据库风险”	pillar + 关键词筛选	pillar -c Security --risky 然后按关键词筛选	支柱
“显示高优先级问题”	pillar	pillar -c Security -l Critical,High --risky	支柱
“如何修复 MFA？” / “显示检查项详情”	detail	detail --keyword "MFA"	详情
“哪些用户没有 MFA？” / “哪些资源不合规？”	detail + resources	detail --id xxx 然后 resources --id xxx	详情

默认值：如果用户未指定支柱或检查项，则使用 overview。

报告格式选择：确定查询模式后，在生成输出前读取对应的报告格式参考文件。只读取与用户意图相符的格式文件，不要一次读取所有格式文件。

字段参考

字段	值	说明
Risk	Error（高）> Warning（中）> Suggestion（低）> None（合规）	实际检测到的风险
RecommendationLevel	Critical > High > Medium > Suggestion	建议优先级
Status	Finished / NotApplicable / Failed	检查执行状态
Compliance	0.0 - 1.0	1.0 = 完全合规

缓存与清理

仅元数据（检查项定义）会缓存在本地，结果始终实时获取。

• 缓存位置：~/.governance_cache/metadata.json
• TTL：24 小时（元数据很少变更）
• list-evaluation-results 和 list-evaluation-metric-details 从不缓存

# Force refresh metadata cache
python3 scripts/governance_query.py --refresh overview

# Clear cache manually
rm -rf ~/.governance_cache/

最佳实践

1. 聚焦重点，不要一股脑罗列 — 每个报告层级都应突出最重要的内容，而不是列出所有内容。阅读对应的报告格式参考，了解数量控制规则
2. 遵循漏斗流程 — 从 overview 开始，引导用户查看 pillar，再到 detail。除非用户明确要求查看特定项，否则不要跳过层级
3. 在支柱模式下使用 --risky 筛选器 — 调查问题时隐藏合规项，减少干扰
4. 按 Risk + Level 确定优先级 — 首先关注 Error 风险且建议级别为 Critical / High 的项目
5. 遵循修复指南 — 修改资源前，使用 detail 模式获取可执行的修复步骤
6. 始终引导后续步骤 — 每份报告都必须根据实际数据以后续指引结尾，帮助用户继续探索
7. 缓存管理 — 仅元数据会缓存（TTL 为 24 小时）；结果始终实时获取。使用 --refresh 强制刷新元数据

参考资料

文件	内容
report-format-overview.md	报告格式：整体治理概览
report-format-pillar.md	报告格式：按支柱 / 关键词汇总的分析
report-format-detail.md	报告格式：单项检查详情 + 资源
related-apis.md	CLI 命令和 API 详情
ram-policies.md	所需权限
verification-method.md	验证步骤
cli-installation-guide.md	CLI 安装指南