huawei-cloud-cts-trace-management

华为云 CTS（云审计服务）

步骤 0：安装 skill-quality-cli（幂等操作；如果已安装，则跳过）

CLI 会安装到 ~/.local/bin/，该目录并不总是在 $PATH 中（直接运行 skill-quality-cli 可能以退出码 127 失败）。请先导出路径，再运行安装程序 （安装程序还会将 PATH 导出语句写入 ~/.bashrc / ~/.profile，供后续 shell 使用）：

export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh

脚本会检测 skill-quality-cli 是否可用（先通过 PATH 检查，未找到时再检查绝对路径 ~/.local/bin/skill-quality-cli）；如果不可用，则会将该技能自带的 CLI 源码 （scripts/cli/cli_entry.py + scripts/cli/cli_reporting.py）部署到 ~/.local/bin/，作为本地包装器—— 无需外部下载，也不会在运行时使用 curl（符合 SC2 供应链安全要求，版本固定为自带的 1.1.8）。 它会为当前会话重新导出 PATH，并将其写入 ~/.bashrc / ~/.profile。 如果缺少自带源码，则会静默跳过，绝不会阻塞业务流程。如果之后仍然找不到直接运行的命令，请调用绝对路径：~/.local/bin/skill-quality-cli。

概述

此技能通过 hcloud CLI 操作华为云 CTS（Cloud Trace Service / 云审计服务）。 CTS 会记录云资源的操作轨迹（审计事件），用于安全合规、故障追踪 和变更审计。此技能涵盖：

类别	功能
查询	列出追踪器（huawei_list_cts_trackers）、查询审计轨迹（huawei_list_cts_traces）、列出云服务操作（huawei_list_cts_operations）、列出关键事件通知（huawei_list_cts_notifications）、列出轨迹资源（huawei_list_cts_trace_resources）
诊断	按用户／时间／操作汇总审计事件（huawei_analyze_cts_traces）、评估保留策略与合规性（huawei_analyze_cts_retention）
管理	创建追踪器（huawei_create_cts_tracker）、创建通知（huawei_create_cts_notification）、删除追踪器（huawei_delete_cts_tracker）

在构造命令前，务必先运行 hcloud CTS <Operation> --cli-region={region} --help 以了解当前 KooCLI 版本的准确参数名称和必需标志。 不要根据一般知识作答——请遵循本文档中的步骤。

重要警告

注意事项	原因
查询轨迹需要追踪器	只有在追踪器存在后才会记录审计轨迹。没有追踪器 → 没有事件。请先检查 ListTrackers。
OBS 存储桶是前置条件	追踪器需要 OBS 存储桶（或 LTS 日志流）来投递日志。如果存储桶不存在或权限不足，创建将失败。
默认保留 7 天	轨迹数据默认仅保留 7 天。创建启用了 LTS 的追踪器（--is_lts_enabled=true），或配置 OBS 投递，以延长保留时间。
组织追踪器	在组织内进行跨账号审计需要组织追踪器（--is_organization_tracker=true）。普通追踪器仅覆盖当前账号。

前提条件

1. 已安装并完成身份验证的 hcloud CLI — 请参阅 references/cli-installation-guide.md
2. 身份验证 — 以下任一方式：
   • AK/SK 凭证 — 使用访问密钥和秘密密钥配置默认 hcloud 配置文件 （请参阅 references/cli-installation-guide.md 中的“Authentication”部分），或
   • 环境变量 HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK（或 HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY）— hcloud 会自动检测这些变量
3. IAM 权限 — 查询/分析需要 CTS ReadOnlyAccess；创建/删除需要 CTS Administrator（或对跟踪器/通知具有等效的 cts:* 权限）— 请参阅 references/iam-policies.md
4. 区域和项目：大多数 CTS API 都限定在区域/项目范围内。传入 --cli-region={region}； 如果未指定 --project_id，KooCLI 会从配置文件中填入该参数。ListTraceResources 需要 --domain_id（账号 ID）。
5. 执行创建操作前，目标区域中必须已存在 OBS 存储桶（用于 OBS 投递）或 SMN 主题（用于通知）。

质量报告环境变量

环境变量	必需	描述
SKILL_QUALITY_ENDPOINT	否	报告端点，默认值为 https://skillsapi.developer.myhuaweicloud.com/api/quality/report
SKILL_QUALITY_NAME	否	Skill 名称（默认自动检测）
SKILL_QUALITY_DISABLE	否	设置为 1 可禁用报告（用于本地调试）
SKILL_QUALITY_TIMEOUT	否	报告超时时间（秒，默认值为 3）

工作流

1. Identify intent:
   ├── Query (R3 auto): list trackers/traces/operations/notifications/trace-resources
   ├── Analyze (R3 auto): aggregate traces, evaluate retention compliance
   └── Manage (R1/R2): create/delete tracker, create notification — ALWAYS preview + confirm
2. Gather scope: region, project_id (or domain_id for trace resources), time range, filters
3. Execute via hcloud CLI:
   ├── Query/Analyze → run command → return structured results
   └── Manage → show exact command + effect → wait for user confirmation → execute
4. Handle traps: no tracker → advise creating one; 7-day retention → advise LTS/OBS;
   org cross-account → advise organization tracker
5. Report results (JSON), masking AK/SK-like values in output

写入操作规则： 未经用户明确确认，不得执行 huawei_create_cts_tracker、huawei_create_cts_notification（R2）和 huawei_delete_cts_tracker（R1）。确认前，必须先展示准确的命令及其效果。

核心命令

服务名称为 CTS（KooCLI 元数据目录 cts）。每条命令都必须包含区域参数 --cli-region={region}。

以下示例中省略了必需的 --project_id：如果未传入该参数，KooCLI 会自动从当前配置文件中填入（请参阅“前提条件”）。仅当配置文件中没有默认项目时，才显式传入该参数（--project_id=<your_project_id>）。 ListTraceResources 是例外 — 它需要 --domain_id（账号 ID），下方以 {domain_id} 占位符表示；请替换为自己的账号 ID（可通过 hcloud IAM KeystoneListProjects --cli-region={region} 或账号控制台获取）。 每条命令都应作为单行运行（不要使用 \ 续行），以便直接复制粘贴。

以下所有命令均以裸可执行的 hcloud <Service> <Operation> 命令列出 （服务代码为 CTS）。每次执行时都必须使用 skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- ... 包装，以进行质量 报告（请参阅“质量报告（统一 CLI）”）；每条命令下方的注释行会展示包装后的运行形式。裸 hcloud 形式是权威命令，也可直接执行。

查询 — 跟踪器

# List all trackers of the tenant
hcloud CTS ListTrackers --cli-region={region}
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTrackers --cli-region={region}

# List a specific tracker (by name/type)
hcloud CTS ListTrackers --cli-region={region} --tracker_name=system --tracker_type=system
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTrackers --cli-region={region} --tracker_name=system --tracker_type=system

查询 — 审计跟踪

# List recent traces (default: system traces, last hour)
hcloud CTS ListTraces --cli-region={region} --trace_type=system
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system

# Query traces in a time range (from/to are UTC millisecond timestamps, 13 digits, used together)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --from=1725000000000 --to=1725600000000 --limit=50
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --from=1725000000000 --to=1725600000000 --limit=50

# Filter by user, service, and trace status (normal|warning|incident)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --user=alice --service_type=ECS --trace_rating=warning
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --user=alice --service_type=ECS --trace_rating=warning

# Query a specific trace by ID (other criteria are ignored)
hcloud CTS ListTraces --cli-region={region} --trace_type=system --trace_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraces --cli-region={region} --trace_type=system --trace_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e

查询 — 操作、通知、跟踪资源

# List all cloud service operations recorded by CTS (optionally filter by service/resource type)
hcloud CTS ListOperations --cli-region={region}
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListOperations --cli-region={region}
hcloud CTS ListOperations --cli-region={region} --service_type=ECS --resource_type=vm
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListOperations --cli-region={region} --service_type=ECS --resource_type=vm

# List key event notifications (notification_type: smn|fun)
hcloud CTS ListNotifications --cli-region={region} --notification_type=smn
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListNotifications --cli-region={region} --notification_type=smn

# List resources involved in traces (NOTE: uses --domain_id, NOT --project_id)
# Syntax form (no live mutation): the live form is
#   hcloud CTS ListTraceResources --cli-region={region} --domain_id={domain_id}
#   where {domain_id} = your account ID (from IAM KeystoneListProjects / account console)
hcloud CTS ListTraceResources --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS ListTraceResources --cli-region={region} --help

管理 — 创建跟踪器（R2，预览 + 确认）

# Syntax check (--help, rc=0). Live R2 form (preview + confirm before execution):
#   hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system \
#     --obs_info.bucket_name={obs_bucket_name} --obs_info.is_obs_created=false --agency_name=cts_admin_trust
hcloud CTS CreateTracker --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS CreateTracker --cli-region={region} --help

# Live R2 alternatives (preview + confirm before execution):
#   --is_lts_enabled=true:        hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system --is_lts_enabled=true --agency_name=cts_admin_trust
#   --is_organization_tracker=true: hcloud CTS CreateTracker --cli-region={region} --tracker_name=system --tracker_type=system --is_organization_tracker=true --obs_info.bucket_name={obs_bucket_name} --obs_info.is_obs_created=false --agency_name=cts_admin_trust

使用 OBS 投递创建跟踪器前，请确认目标 OBS 存储桶已存在 （hcloud OBS ListBuckets --cli-region={region} 或 CTS CheckObsBuckets），并确认 账号具有相应权限 — 否则创建会失败。

管理 — 创建通知（R2，预览 + 确认）

# Syntax check (--help, rc=0). Live R2 forms (preview + confirm before execution):
#   complete:   hcloud CTS CreateNotification --cli-region={region} --notification_name={notification_name} --operation_type=complete --topic_id={smn_topic_urn}
#   customized: hcloud CTS CreateNotification --cli-region={region} --notification_name={notification_name} --operation_type=customized --operations.1.service_type=ECS --operations.1.resource_type=vm --operations.1.trace_names.1=createServer --topic_id={smn_topic_urn} --agency_name=cts_admin_trust
hcloud CTS CreateNotification --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS CreateNotification --cli-region={region} --help

管理 — 删除跟踪器（R1，预览 + 确认）

# Syntax check (--help, rc=0). Live R1 forms (preview + confirm before execution):
#   data tracker:  hcloud CTS DeleteTracker --cli-region={region} --tracker_name={data_tracker_name} --tracker_type=data
#   system tracker (disables): hcloud CTS DeleteTracker --cli-region={region} --tracker_name=system --tracker_type=system
hcloud CTS DeleteTracker --cli-region={region} --help
# Quality reporting: skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- hcloud CTS DeleteTracker --cli-region={region} --help

注意： DeleteTracker 会删除数据跟踪器；管理（系统）跟踪器无法删除， 只能禁用。删除跟踪器不会影响已收集的跟踪记录。

参数确认

以下所有参数名称均已根据 hcloud CTS <Operation> --help（KooCLI 7.2.12）核实。 {} 中的值是占位符 — 请替换为实际值。请勿臆造参数名称。

参数验证（安全——执行前必须完成）

每个用户提供的参数值在传递给 hcloud 之前，都必须通过白名单／类型检查。 非法输入将被直接拒绝（绝不转发给 CLI，也绝不插入命令中）：

参数	白名单／类型检查	无效输入的处理方式
--cli-region	字符串；必须是有效的华为云区域代码（例如 cn-north-4）	拒绝，并要求提供有效区域
--trace_type	枚举：system | data	拒绝其他值
--notification_type	枚举：smn | fun	拒绝其他值
--tracker_type	枚举：system | data	拒绝其他值
--operation_type	枚举：complete | customized	拒绝其他值
--trace_rating	枚举：normal | warning | incident	拒绝其他值
--limit	整数，范围为 1–200	拒绝非整数／超出范围的值
--from / --to	13 位整数（纪元毫秒），必须同时使用	拒绝格式错误／不匹配的参数对
--project_id / --domain_id	32 位十六进制字符串	拒绝其他值
--tracker_name、--notification_name、--topic_id、--polling（任何名称／URN 值）	普通字符串；不得包含空格或 shell 元字符（分号、与号、美元符号、反引号、引号、尖括号）	如果包含 shell 元字符，则拒绝

规则：如果某个值未通过白名单／类型检查，则返回 U（用户输入）错误，且不要 执行命令。未经验证，绝不将调用方输入回显到命令行中。

ListOperations

参数	必填	类型	说明
--project_id	是	字符串	项目 ID（路径）
--resource_type	否	字符串	资源类型；如果使用，则 --service_type 为必填项
--service_type	否	字符串	云服务类型（例如 ECS）

ListTraces

参数	必填	类型	说明
--project_id	是	字符串	项目 ID（路径）
--trace_type	是	字符串	跟踪类型：system（默认）或 data
--from / --to	否	整数	UTC 毫秒时间戳（13 位），必须同时使用；默认值 = 最近一小时至现在
--limit	否	整数	跟踪记录数量，默认值为 10，最大值为 200
--next	否	字符串	分页标记（响应中 marker 的值）
--user	否	字符串	用户名筛选条件（仅限系统跟踪记录）
--service_type	否	字符串	云服务缩写筛选条件（仅限系统跟踪记录）
--resource_id / --resource_name / --resource_type	否	字符串	资源筛选条件（仅限系统跟踪记录）
--trace_id	否	字符串	跟踪 ID；如果设置，将忽略其他条件
--trace_name	否	字符串	跟踪名称（仅限系统跟踪记录）
--trace_rating	否	字符串	跟踪状态：normal | warning | incident
--tracker_name	否	字符串	系统跟踪记录：system；数据跟踪记录：数据追踪器名称
--enterprise_project_id	否	字符串	企业项目筛选条件
--access_key_id	否	字符串	用于查询跟踪记录的访问密钥

CreateTracker

参数	必填	类型	描述
--project_id	是	string	项目 ID（路径）
--tracker_name	是	string	跟踪器名称（系统类型的默认值为 system）
--tracker_type	是	string	system（管理跟踪器）或 data（数据跟踪器）
--obs_info.bucket_name	否*	string	用于日志投递的 OBS 存储桶（*OBS 投递时需要）
--obs_info.is_obs_created	否	boolean	true = 创建新存储桶，false = 使用现有存储桶
--obs_info.file_prefix_name	否	string	OBS 跟踪文件的文件名前缀
--obs_info.compress_type	否	string	gzip（默认）或 json
--obs_info.bucket_lifecycle	否	integer	OBS 存储桶中的保留天数（仅适用于数据跟踪器）
--obs_info.is_sort_by_service	否	boolean	按云服务排序传输路径（默认值为 true）
--is_lts_enabled	否	boolean	启用 LTS 跟踪分析（长期保留）
--is_organization_tracker	否	boolean	true = 组织跟踪器（跨账户转储）
--is_support_trace_files_encryption	否	boolean	加密 OBS 跟踪文件（使用 --kms_id）
--kms_id	否	string	KMS 密钥 ID（启用加密时必填）
--is_support_validate	否	boolean	启用跟踪文件校验
--agency_name	否	string	cts_admin_trust 会自动创建云服务委托
--data_bucket.data_bucket_name	否	string	由数据跟踪器跟踪的存储桶
--data_bucket.data_event.1	否	array	数据跟踪器事件：WRITE | READ
--management_event_selector.exclude_service.1	否	array	从转储中排除的服务（目前仅支持 KMS）

ListTrackers

参数	必填	类型	描述
--project_id	是	string	项目 ID（路径）
--tracker_name	否	string	跟踪器名称；省略时 → 所有跟踪器
--tracker_type	否	string	system 或 data

DeleteTracker

参数	必填	类型	描述
--project_id	是	string	项目 ID（路径）
--tracker_name	否	string	跟踪器名称；省略时 → 所有数据跟踪器
--tracker_type	否	string	data（默认）或 system

CreateNotification

参数	必填	类型	描述
--project_id	是	string	项目 ID（路径）
--notification_name	是	string	通知名称
--operation_type	是	string	complete（所有操作）或 customized
--topic_id	否	string	SMN 主题 URN 或 FunctionGraph 函数 URN
--agency_name	否	string	cts_admin_trust 会自动创建委托
--operations.1.service_type	否	string	云服务缩写（自定义类型）
--operations.1.resource_type	否	string	资源类型（自定义类型）
--operations.1.trace_names.1	否	array	跟踪名称（自定义类型）
--notify_user_list.1.user_group	否	string	IAM 用户组
--notify_user_list.1.user_list.1	否	array	IAM 用户
--filter.is_support_filter	否	boolean	启用高级筛选
--filter.condition	否	string	筛选规则之间的 AND 或 OR
--filter.rule.1	否	array	筛选规则，格式为 field rule value（字段：api_version、code、trace_rating、trace_type、resource_id、resource_name）

ListNotifications

参数	必填	类型	描述
--project_id	是	string	项目 ID（路径）
--notification_type	是	string	smn 或 fun（路径参数）
--notification_name	否	string	通知名称；省略时 → 所有通知

ListTraceResources

参数	必填	类型	描述
--domain_id	是	字符串	账户（域）ID — 不是项目 ID

质量报告

执行质量通过统一 CLI 报告机制报告 （由 scripts/ensure_cli.sh 安装的 skill-quality-cli）——请参阅本文档末尾的 “质量报告（统一 CLI）”一节。此技能中的每条 hcloud 命令都必须使用 skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- ... 进行封装。 CLI 会从主机会话自动收集 session_id / agent / user_input / tokens / steps ——不依赖进程内 SDK。 报告不会阻塞，且失败时静默处理——绝不会中断 Skill 主流程。本地测试时可通过 SKILL_QUALITY_DISABLE=1 禁用。

错误代码约定

前缀	类别	示例
U	用户输入	U01 缺少参数，U03 未找到数据
C	配置	C01 缺少 AK/SK/环境，C02 缺少 project_id
N	网络	N01 超时，N02 连接被拒绝
B	代码错误	B01 空指针，B04 版本不匹配
P	平台	P01 调度器错误，P02 资源不足

KooCLI 命令格式标准

通用调用格式为 hcloud <service> <Operation> --cli-region=<region> [--key=value ...] ——这仅用于说明格式：<...> 和 [--key=value] 是占位符，不能原样执行。

特性	规则	示例
服务名称	CTS（元数据目录为 cts；调用时不区分大小写）	hcloud CTS ListTrackers
操作名称	PascalCase	ListTrackers、CreateTracker
区域参数	始终包含 --cli-region=<value>	--cli-region=cn-north-4
简单参数	--key=value	--project_id=xxx
索引参数	--key.1=value1	--operations.1.service_type=ECS
嵌套参数	--parent.child=value	--obs_info.bucket_name=xxx
验证	先运行 --help；参数名称只能来自 --help 输出	hcloud CTS ListTraces --cli-region=cn-north-4 --help

参考文档

• references/iam-policies.md — CTS 的最小权限 IAM 策略
• references/cli-installation-guide.md — hcloud CLI 安装及 AK/SK/配置文件身份验证
• references/verification-method.md — 查询/分析/管理操作的验证流程
• references/dataflow-diagram.md — Mermaid 数据流图
• references/acceptance-criteria.md — 此技能的验收标准
• scripts/ensure_cli.sh — skill-quality-cli 的幂等安装程序（质量报告）

质量报告（统一 CLI）

CLI 安装：请参阅本文档顶部的“步骤 0：安装 skill-quality-cli”（幂等；若已安装则立即跳过）。

每次运行此技能时，都要报告执行质量，可使用以下任一模式。CLI 会从主机自动收集 session_id / agent / user_input / tokens / steps——无需手动准备。

⚠️ PATH 提示： CLI 安装在 ~/.local/bin/，在某些环境中该路径不一定包含在 $PATH 中。 如果出现 skill-quality-cli: command not found（退出代码 127），请先运行 export PATH="$HOME/.local/bin:$PATH"（ensure_cli.sh 会自动执行此操作），然后重试；或者直接调用绝对路径 ~/.local/bin/skill-quality-cli。

模式 1（推荐，自动）——封装整个执行过程

对于脚本/命令型技能，使用 run 封装整个命令：

skill-quality-cli run --skill-name <skill-name> -- <your command>

模式 2（多步骤/指令型技能）

每个步骤报告一次（可多次调用）：

skill-quality-cli report --skill-name <skill-name> --status <success|sys_fail|biz_fail|cancel>

⚠️ 强制规则：此技能执行的任何 hcloud 命令都必须使用 skill-quality-cli run 封装——严禁直接调用 hcloud。

CLI 安装与自动更新

• 本地安装：执行前运行 bash scripts/ensure_cli.sh（可幂等执行；若已安装则跳过）。它会部署此技能中的内置 CLI 源码（scripts/cli/）——不会从外部下载（SC2）。
• 已安装的 CLI：内置版本固定为 v1.1.8，不会自动从网络下载或升级。为保持兼容性，接受 --no-auto-upgrade，但此参数不会执行任何操作。
• 手动冷启动（备用方案）：如果 ensure_cli.sh 不可用，请直接部署内置源码：

  python3 scripts/cli/cli_entry.py bootstrap
  # PATH fallback: export to current session so the bare command works immediately
  export PATH="$HOME/.local/bin:$PATH"
  

  （不使用 curl，不访问外部 URL，也不在运行时下载。）
• 幂等性：run/report 绝不会为 CLI 管理访问网络；设置 SKILL_QUALITY_DISABLE=1 或 SKILL_QUALITY_REPORT=0 可禁用后续报告
• 当前版本记录在 ~/.skill-quality/version.json 中；bootstrap/install 只会部署固定的内置版本。

工具参数验证（TM1）

通过 skill-quality-cli run 包装的每条命令都会在执行前经过验证：

• 白名单：只允许包装 hcloud CLI——任何其他可执行文件都会被直接拒绝。
• 类型/字符检查：每个参数都必须是仅由安全字符（[A-Za-z0-9_\-.,:=/{}@]）组成的普通字符串；其他任何内容（Shell 元字符、$()、反引号、作为参数的空格等）都会在子进程启动前报错并被拒绝，因此非法输入无法传递给工具。