/alibabacloud-governance-evaluation-report

name: alibabacloud-governance-evaluation-report
description: |
  Alibaba Cloud Governance Center evaluation report skill.
  Use for querying governance maturity check results, generating structured risk reports, and account compliance analysis.
  Triggers: "云治理", "成熟度检测", "合规检查", "安全风险", "治理检测", "governance evaluation",
  "maturity check", "compliance report", "risk report", "governance center".

Alibaba Cloud Governance Center Evaluation Report

Guide users to discover governance risks, focus on critical issues, and take remediation actions through a progressive drill-down workflow.

Scenario Description

This skill is a **problem-discovery and resolution guide** — not a comprehensive audit report generator. It operates as a progressive disclosure funnel:

1. **Overview (quick diagnosis)** — Score + pillar distribution + top critical risks → guide user to choose a direction 2. **Pillar analysis (focused drill-down)** — All risks in a specific domain, controlled by severity → guide user to specific items 3. **Detail (deep dive)** — Single check item with full remediation steps → guide user to related items or resources 4. **Resources (action)** — Non-compliant resource listing for targeted remediation

Each layer focuses on **the most important information** and guides the user to the next level. Avoid information overload — keep output concise and actionable.

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

How It Works

**Data Sources** — Three APIs provide all data: 1. `list-evaluation-metadata` — Check item definitions (name, description, pillar, level, remediation) 2. `list-evaluation-results` — Actual results (status, risk, compliance rate, score) 3. `list-evaluation-metric-details` — Non-compliant resource details for a specific check item

**Processing** — The script ([governance_query.py](scripts/governance_query.py)) merges data sources and caches results for 1 hour. It provides 4 query modes: `overview`, `pillar`, `detail`, `resources`.

**Output** — Structured JSON for Agent to generate user-friendly reports. Reports are output directly in the conversation as formatted text, NOT written to files.

---

Prerequisites

> **Pre-check: Aliyun CLI >= 3.3.3 required** > Run `aliyun version` to verify >= 3.3.3. If not installed or version too low, > use a package manager or the pinned, SHA256-verified packages in > [references/cli-installation-guide.md](references/cli-installation-guide.md). > Do not pipe a remotely downloaded installation script directly into a shell. > > Then [MUST] run `aliyun plugin update` to ensure that any existing plugins on your local machine are always up-to-date. > > **[MUST]** run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.

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

Observability

Every Alibaba Cloud API invocation made by this skill must include the complete User-Agent template:

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

For this skill, `{SKILL_NAME}` is `alibabacloud-governance-evaluation-report`, so the concrete form is:

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

Session ID rules:

1. Generate a new session ID once per session (one skill invocation) with `uuid.uuid4().hex`. It must be a 32-char hex UUID v4 value: exactly 32 lowercase hexadecimal characters with no hyphens. 2. Reuse the same session ID for every Alibaba Cloud API call in that invocation, including direct CLI commands, helper-script calls, pagination, and retries. 3. Do not regenerate the session ID between related calls. Generate a new session ID only when a new skill invocation begins. 4. Set `ALIBABA_CLOUD_AGENT_SESSION_ID` to that 32-char hex session ID before running `governance_query.py`. The script validates and reuses the supplied UUID; when the variable is absent, it generates one 32-char hex UUID v4 per process and reuses it. 5. Never derive a session ID from account IDs, credentials, user data, or other sensitive values.

Before running `governance_query.py`, tell the user that it invokes the local `aliyun` executable with their current CLI credentials and sends read-only queries to Alibaba Cloud Governance Center. The script enforces a read-only command allowlist, validates all dynamic arguments, and prints the resolved executable and API action to stderr before each call.

Authentication

Configure CLI authentication (OAuth recommended):

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

RAM Policy

Requires Governance Center read permissions. See [references/ram-policies.md](references/ram-policies.md) for full policy.

Minimum required permissions:

• `governance:ListEvaluationMetadata`
• `governance:ListEvaluationResults`

Or attach system policy: **AliyunGovernanceReadOnlyAccess**

Parameter Confirmation

This skill has minimal user-specific parameters. The following may require confirmation:

| Parameter Name | Required/Optional | Description | Default Value | |----------------|-------------------|-------------|---------------| | `--profile` | Optional | Aliyun CLI profile name | Default profile | | `-c, --category` | Required (pillar mode) | Pillar category name | N/A | | `--id` | Required (detail/resources mode) | Check item metric ID | N/A | | `--keyword` | Optional (detail mode) | Search keyword for check items | N/A | | `--max-results` | Optional (resources mode) | Max results per page | 50 |

Verification

Verify setup before use:

# Test CLI connection
aliyun governance list-evaluation-results \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-governance-evaluation-report/{session-id} \
  --