alibabacloud-governance-evaluation-report

Alibaba Cloud Governance Center 評価レポート

段階的に掘り下げるワークフローを通じて、ガバナンス上のリスクの発見、重大な問題への注目、修正措置の実施をユーザーに案内します。

シナリオの説明

このスキルは、問題の発見と解決を案内するガイドであり、包括的な監査レポートの生成ツールではありません。段階的に情報を開示する次のような流れで動作します。

1. 概要（迅速な診断） — スコア＋柱ごとの分布＋重大なリスクの上位項目 → ユーザーに次の方向性を選ぶよう案内
2. 柱の分析（焦点を絞った掘り下げ） — 重要度を基準に制御された、特定ドメインのすべてのリスク → ユーザーに具体的な項目を案内
3. 詳細（深掘り） — 修正手順をすべて含む単一のチェック項目 → ユーザーに関連項目やリソースを案内
4. リソース（対応） — 対象を絞った修正のための、非準拠リソースの一覧

各レイヤーでは、最も重要な情報に焦点を当て、ユーザーを次のレベルへ案内します。情報過多を避け、出力を簡潔で実用的なものにしてください。

アーキテクチャ：Governance Center API → CLI (aliyun governance) → governance_query.py (マージ＋キャッシュ) → JSON 出力 → エージェントレポート

動作の仕組み

データソース — 3 つの API からすべてのデータを取得します。

1. list-evaluation-metadata — チェック項目の定義（名前、説明、柱、レベル、修正方法）
2. list-evaluation-results — 実際の結果（ステータス、リスク、準拠率、スコア）
3. list-evaluation-metric-details — 特定のチェック項目に関する非準拠リソースの詳細

処理 — スクリプト（governance_query.py）がデータソースをマージし、結果を 1 時間キャッシュします。overview、pillar、detail、resources の 4 つのクエリモードを提供します。

出力 — エージェントがユーザーにわかりやすいレポートを生成するための構造化 JSON です。レポートは会話内に整形済みテキストとして直接出力され、ファイルには書き込まれません。

---

前提条件

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが 3.3.3 以上であることを確認してください。未インストールの場合、またはバージョンが古い場合は、 パッケージマネージャー、または references/cli-installation-guide.md にある、バージョンが固定され SHA256 検証済みのパッケージを使用してください。 リモートからダウンロードしたインストールスクリプトを、シェルに直接パイプしないでください。

次に、[MUST] aliyun plugin update を実行し、ローカルマシンにすでにインストールされているプラグインを常に最新の状態にしてください。

[MUST] 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}

セッション ID のルール：

1. セッションごと（スキルの呼び出し 1 回につき）に、uuid.uuid4().hex を使ってセッション ID を 1 回だけ生成します。32 文字の 16 進数 UUID v4 値である必要があります。ハイフンなしの小文字の 16 進数 32 文字ちょうどです。
2. その呼び出し内でのすべての Alibaba Cloud API 呼び出し（CLI コマンドの直接実行、ヘルパースクリプトの呼び出し、ページネーション、再試行を含む）で、同じセッション ID を再利用します。
3. 関連する呼び出しの間でセッション ID を再生成しないでください。新しいセッション ID を生成するのは、新しいスキルの呼び出しが始まるときだけです。
4. governance_query.py を実行する前に、ALIBABA_CLOUD_AGENT_SESSION_ID にその 32 文字の 16 進数セッション ID を設定します。スクリプトは指定された UUID を検証して再利用します。この環境変数が設定されていない場合、スクリプトはプロセスごとに 32 文字の 16 進数 UUID v4 を 1 つ生成して再利用します。
5. アカウント ID、認証情報、ユーザーデータ、その他の機密情報からセッション ID を導出してはいけません。

governance_query.py を実行する前に、ローカルの aliyun 実行ファイルを現在の CLI 認証情報で呼び出し、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 を参照してください。

---

コアワークフロー

IMPORTANT: パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（例：--profile、--category、--id、--keyword、 --max-results など）を必ずユーザーに確認してください。 明示的な承認なしに、デフォルト値を想定または使用しないでください。

IMPORTANT: 出力形式 — レポートは、会話への出力形式を指定するものです。 レポートの内容は、書式設定された Markdown としてチャットメッセージに直接出力してください。 レポートファイル（例：.md、.txt、.html）を作成または書き込まないでください。ファイルの生成は不要です。

スクリプトの場所：scripts/governance_query.py

グローバルオプション

オプション	説明
--refresh	キャッシュを強制的に更新します（デフォルトの TTL：1 時間）

---

Mode 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 を参照してください。

---

Mode 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 を参照してください。

---

Mode 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 を参照してください。詳細形式では、必要に応じてリソース一覧も確認できます。

---

Mode 4: resources — 非準拠リソース

使用する場面：ユーザーが、特定のチェック項目に失敗したリソースを確認したい場合です。

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

オプション：

オプション	説明
--id	必須。チェック項目 ID
--max-results	1 ページあたりの最大結果数（デフォルト：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	overview -r Error	overview
「中リスク以上の問題を表示してください」	overview	overview -r Error,Warning	overview
「セキュリティ上の問題は何ですか？」／「特定の柱のリスク」	pillar	pillar -c Security --risky	pillar
「ネットワークセキュリティのチェック」／「データベースのリスク」	pillar + キーワードフィルター	pillar -c Security --risky を実行してから、キーワードで絞り込み	pillar
「優先度の高い問題を表示してください」	pillar	pillar -c Security -l Critical,High --risky	pillar
「MFA を修正する方法は？」／「チェック項目の詳細を表示してください」	detail	detail --keyword "MFA"	detail
「MFA を設定していないユーザーは誰ですか？」／「準拠していないリソースは何ですか？」	detail + resources	detail --id xxx を実行してから resources --id xxx	detail

デフォルト：ユーザーが柱またはチェック項目を指定していない場合は、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. pillar モードでは --risky フィルターを使用する — 問題を調査する際に準拠項目を非表示にし、ノイズを減らします
4. Risk + Level の順に優先する — まず Critical／High の推奨レベルが付いた Error リスクに注目します
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 のインストール