返回技能市场
法律合规 安全

阿里云治理检测报告

@aliyun/alibabacloud-governance-evaluation-report

查询阿里云账号的云治理成熟度检测结果，自动生成治理检测报告。帮助您快速了解账号在安全、稳定、成本、效率、性能五大领域的合规现状，识别高风险项并提供治理建议。

云Skills门户 热度 57v0.0.2

阿里云治理中心评估报告

通过渐进式下钻工作流，引导用户发现治理风险、聚焦关键问题并采取修复措施。

场景说明

此 skill 是一份问题发现与解决指南，并非综合审计报告生成器。它采用渐进式信息披露漏斗：

  1. 概览（快速诊断） — 得分 + 支柱分布 + 最关键的风险 → 引导用户选择方向
  2. 支柱分析（聚焦下钻） — 特定领域中的所有风险，按严重程度筛选 → 引导用户查看具体检测项
  3. 详情（深度分析） — 单个检测项及完整修复步骤 → 引导用户查看相关检测项或资源
  4. 资源（操作） — 不合规资源列表，用于针对性修复

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

架构: Governance Center API → CLI (aliyun governance) → governance_query.py (merge + cache) → JSON output → Agent report

工作原理

数据源 — 三个 APIs 提供全部数据：

  1. list-evaluation-metadata — 检测项定义（名称、描述、支柱、级别、修复措施）
  2. list-evaluation-results — 实际结果（状态、风险、合规率、得分）
  3. list-evaluation-metric-details — 特定检测项的不合规资源详情

处理 — 该脚本（[governance_query.py](scripts/governance_query.py)）合并多个数据源，并将结果缓存 1 小时。它提供 4 种查询模式：overview、pillar、detail、resources。

输出 — 提供结构化 JSON，供 Agent 生成用户友好的报告。报告以格式化文本直接输出到对话中，禁止写入文件。

---

前提条件

预检查：阿里云 CLI 版本必须不低于 3.3.3
运行 aliyun version，确认版本不低于 3.3.3。如果尚未安装或版本过低，
使用软件包管理器，或使用版本已锁定且通过 SHA256 校验的软件包，详见
[references/cli-installation-guide.md](references/cli-installation-guide.md).
不得将远程下载的安装脚本直接通过管道传入命令行解释器。
然后，[必须] 运行 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

可观测性

此 skill 发起的每次阿里云 API 调用都必须包含完整的 User-Agent 模板：

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

对于此 skill，{SKILL_NAME} 的值为 alibabacloud-governance-evaluation-report，因此具体形式为：

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

会话 ID 规则：

  1. 每个会话（即一次 skill 调用）仅生成一次新的会话 ID，使用以下方法：

    2. uuid.uuid4().hex。该值必须为长度为 32 个字符的十六进制 UUID v4 值：恰好由 32 个 小写十六进制字符组成，且不含连字符。

  2. 在该次调用中，每次调用阿里云 API 时均复用同一个会话 ID，

    3. 包括直接执行 CLI 命令、调用辅助脚本、分页和重试。

  3. 不得在相关调用之间重新生成会话 ID。新的会话

    4. ID 只能在新的 skill 调用开始时生成。

  4. 运行以下脚本前，将 ALIBABA_CLOUD_AGENT_SESSION_ID 设置为上述长度为 32 个字符的十六进制会话 ID：

    5. governance_query.py。该脚本会验证并复用所提供的 UUID；如果 未设置该变量，则每个进程会生成一个长度为 32 个字符的十六进制 UUID v4，并 复用该值。

  5. 严禁将会话 ID 派生自账户 ID、凭证、用户数据或其他

    6. 敏感值。

运行 governance_query.py 前，请告知用户，该脚本会使用用户当前的 CLI 凭证调用本地 aliyun 可执行文件，并向阿里云云治理中心发送只读 查询。该脚本强制实施只读 命令允许列表，验证所有动态参数，并在每次调用前将解析得到的 可执行文件和 API 操作输出到 stderr。

身份认证

配置 CLI 身份认证（推荐使用 OAuth）：

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

RAM 策略

需要云治理中心的读取权限。完整策略请参见 [references/ram-policies.md](references/ram-policies.md)。

所需的最低权限：

  • governance:ListEvaluationMetadata
  • governance:ListEvaluationResults

或者附加系统策略：AliyunGovernanceReadOnlyAccess

参数确认

此 skill 的用户特定参数很少。以下参数可能需要确认：

| 参数名称 | 必填/可选 | 描述 | 默认值 | |----------------|-------------------|-------------|---------------| | --profile | 可选 | 阿里云 CLI 配置文件名称 | 默认配置文件 | | -c, --category | 必填（支柱模式） | 支柱类别名称 | N/A | | --id | 必填（详情/资源模式） | 检查项指标 ID | N/A | | --keyword | 可选（详情模式） | 检查项搜索关键词 | N/A | | --max-results | 可选（资源模式） | 每页最大结果数 | 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](references/verification-method.md)。

---

核心工作流

重要：参数确认 — 执行任何命令或 API 调用之前，
所有用户可自定义的参数（例如 --profile、--category、--id、--keyword、
--max-results 等）必须经用户确认。
未经用户明确批准，不得擅自假定或使用默认值。
重要：输出格式 — 报告仅作为对话输出的格式规范。
始终在聊天消息中直接以格式化 Markdown 输出报告内容。
不得创建或写入报告文件（例如 .md、.txt、.html）。无需生成文件。

脚本位置：[scripts/governance_query.py](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

Options:

| 选项 | 说明 | |--------|-------------| | -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](references/report-format-overview.md)，了解确切的输出格式。

---

模式 2：pillar — 支柱专项报告

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

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

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](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>

Options:

| 选项 | 说明 | |--------|-------------| | --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: Status, Risk, Compliance, NonCompliant
  • Remediation — 修复步骤（手动修复/分析/QuickFix）

报告格式：请阅读 [references/report-format-detail.md](references/report-format-detail.md)，了解确切的输出格式。详情格式还涵盖了需要时的资源列表。

---

模式 4：resources — 不合规资源

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

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

Options:

| 选项 | 说明 | |--------|-------------| | --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 — 资源特有属性

---

模式选择指南

| 用户说…… | 使用模式 | 命令 | 报告格式 | |--------------|----------|---------|---------------| | "Is my account secure?" / "What is my maturity score?" / "Analyze my governance results" | overview | overview | [overview](references/report-format-overview.md) | | "What high-risk items are there?" / "Show all high risks" | overview | overview -r Error | [overview](references/report-format-overview.md) | | "显示中等或更高风险的问题" | overview | overview -r Error,Warning | [overview](references/report-format-overview.md) | | "What security issues exist?" / "Risks in a specific pillar" | pillar | pillar -c Security --risky | [pillar](references/report-format-pillar.md) | | "Network security checks" / "Database risks" | pillar + 关键词筛选 | pillar -c Security --risky，然后按关键词筛选 | [pillar](references/report-format-pillar.md) | | "显示高优先级问题" | pillar | pillar -c Security -l Critical,High --risky | [pillar](references/report-format-pillar.md) | | "How do I fix MFA?" / "Show check-item details" | detail | detail --keyword "MFA" | [detail](references/report-format-detail.md) | | "Which users do not have MFA?" / "What resources are non-compliant?" | detail + resources | detail --id xxx，然后执行 resources --id xxx | [detail](references/report-format-detail.md) |

默认：如果用户未指定支柱或检测项，则使用 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. 按风险 + 级别确定优先级 — 优先关注风险为 Error 且建议级别为 Critical/High 的项
  5. 遵循修复指南 — 修改资源前，使用 detail 模式获取可操作的修复步骤
  6. 始终引导后续步骤 — 每份报告都必须以基于实际数据的后续指导结尾，帮助用户继续探索
  7. 缓存管理 — 仅缓存元数据（24h TTL）；结果始终实时获取。使用 --refresh 强制刷新元数据

参考资料

| 文件 | 内容 | |------|---------| | [report-format-overview.md](references/report-format-overview.md) | 报告格式：整体治理概览 | | [report-format-pillar.md](references/report-format-pillar.md) | 报告格式：支柱 / 关键词聚合分析 | | [report-format-detail.md](references/report-format-detail.md) | 报告格式：单个检测项详情 + 资源 | | [related-apis.md](references/related-apis.md) | CLI 命令和 API 详情 | | [ram-policies.md](references/ram-policies.md) | 所需权限 | | [verification-method.md](references/verification-method.md) | 验证步骤 | | [cli-installation-guide.md](references/cli-installation-guide.md) | CLI 安装 |

qianwen skills install @aliyun/alibabacloud-governance-evaluation-report