huawei-cloud-cts-trace-management

Huawei Cloud CTS (Cloud Trace Service)

Step 0: Install skill-quality-cli (idempotent, skip if already installed)

The CLI installs into ~/.local/bin/, which is not always in $PATH (bare skill-quality-cli can fail with exit 127). Export it first, then run the installer (it also persists the PATH export into ~/.bashrc / ~/.profile for future shells):

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

The script detects whether skill-quality-cli is available (via PATH, falling back to the absolute path ~/.local/bin/skill-quality-cli); if not, it deploys the skill's own bundled CLI source (scripts/cli/cli_entry.py + scripts/cli/cli_reporting.py) into ~/.local/bin/ as a local wrapper — no external download, no runtime curl (SC2 supply-chain safe, version pinned to the bundled 1.1.8). It re-exports PATH for the current session and persists it into ~/.bashrc / ~/.profile. Silently skipped when the bundled source is missing — never blocks the business flow. If the bare command is still not found afterwards, call the absolute path: ~/.local/bin/skill-quality-cli.

Overview

This skill operates Huawei Cloud CTS (Cloud Trace Service / Cloud Audit Service) through the hcloud CLI. CTS records operation traces (audit events) of cloud resources for security compliance, fault tracing, and change auditing. The skill covers:

Category	Capabilities
Query	List trackers (huawei_list_cts_trackers), query audit traces (huawei_list_cts_traces), list cloud service operations (huawei_list_cts_operations), list key event notifications (huawei_list_cts_notifications), list trace resources (huawei_list_cts_trace_resources)
Diagnose	Aggregate audit events by user/time/operation (huawei_analyze_cts_traces), evaluate retention & compliance (huawei_analyze_cts_retention)
Manage	Create tracker (huawei_create_cts_tracker), create notification (huawei_create_cts_notification), delete tracker (huawei_delete_cts_tracker)

Always run hcloud CTS <Operation> --cli-region={region} --help before constructing a command to discover the exact parameter names and required flags for the current KooCLI version. Do not answer from general knowledge — follow the procedures in this document.

Critical Warnings

Trap	Why
Tracker required for traces	Audit traces are only recorded after a tracker exists. No tracker → no events. Check ListTrackers first.
OBS bucket prerequisite	A tracker needs an OBS bucket (or LTS log stream) for log delivery. Creation fails if the bucket is missing or lacks permissions.
7-day retention default	Trace data is retained for only 7 days by default. Create an LTS-enabled tracker (--is_lts_enabled=true) or configure OBS delivery for longer retention.
Organization tracker	Cross-account auditing in an organization requires an organization tracker (--is_organization_tracker=true). A normal tracker only covers the current account.

Prerequisites

1. hcloud CLI installed and authenticated — see references/cli-installation-guide.md
2. Authentication — one of:
   • AK/SK credentials — configure the default hcloud profile with your access key and secret key (see references/cli-installation-guide.md, section "Authentication"), or
   • Environment variables HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK (or HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY) — hcloud auto-detects them
3. IAM permissions — CTS ReadOnlyAccess for query/analyze; CTS Administrator (or equivalent cts:* on trackers/notifications) for create/delete — see references/iam-policies.md
4. Region & project: most CTS APIs are region/project scoped. Pass --cli-region={region}; KooCLI fills --project_id from the profile if omitted. ListTraceResources requires --domain_id (account ID).
5. OBS bucket (for OBS delivery) or SMN topic (for notifications) must exist in the target region before create operations.

Quality Reporting Environment Variables

Environment Variable	Required	Description
SKILL_QUALITY_ENDPOINT	No	Report endpoint, default https://skillsapi.developer.myhuaweicloud.com/api/quality/report
SKILL_QUALITY_NAME	No	Skill name (default auto-detected)
SKILL_QUALITY_DISABLE	No	Set to 1 to disable reporting (local debugging)
SKILL_QUALITY_TIMEOUT	No	Report timeout seconds (default 3)

Workflow

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

Write-operation rule: huawei_create_cts_tracker, huawei_create_cts_notification (R2) and huawei_delete_cts_tracker (R1) MUST NOT execute without an explicit user confirmation after the exact command and its effect are previewed.

Core Commands

Service name is CTS (KooCLI metadata directory cts). Region parameter --cli-region={region} is required on every command.

The required --project_id is omitted from the examples below: KooCLI automatically fills it from the active profile when it is not passed (see Prerequisites). Pass it explicitly (--project_id=<your_project_id>) only when your profile has no default project. ListTraceResources is the exception — it requires --domain_id (account ID), shown as a {domain_id} placeholder below; replace it with your own account ID (retrieve it via hcloud IAM KeystoneListProjects --cli-region={region} or the account console). Run each command as a single line (no \ line continuations) so it stays directly copy-pasteable.

All commands below are listed as bare executable hcloud <Service> <Operation> commands (service code CTS). Every execution MUST be wrapped with skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- ... for quality reporting (see "Quality Reporting (Unified CLI)"); the comment line under each command shows the wrapped runtime form. The bare hcloud form is authoritative and directly executable.

Query — Trackers

# 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

Query — Audit Traces

# 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

Query — Operations, Notifications, Trace Resources

# 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

Manage — Create Tracker (R2, preview + confirm)

# 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

Before creating a tracker with OBS delivery, verify the target OBS bucket exists (hcloud OBS ListBuckets --cli-region={region} or CTS CheckObsBuckets) and that the account has permissions — otherwise creation fails.

Manage — Create Notification (R2, preview + confirm)

# 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

Manage — Delete Tracker (R1, preview + confirm)

# 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

Note: DeleteTracker deletes data trackers; the management (system) tracker cannot be deleted — it can only be disabled. Deleting a tracker does not affect traces already collected.

Parameter Confirmation

All parameter names below were verified against hcloud CTS <Operation> --help (KooCLI 7.2.12). Values in {} are placeholders — replace with real values. Do not invent parameter names.

Parameter Validation (Security — mandatory before execution)

Every user-supplied parameter value MUST pass a whitelist/type check before it is passed to hcloud. Illegal input is rejected outright (never forwarded to the CLI, never interpolated into a command):

Parameter	Whitelist / type check	Invalid input handling
--cli-region	string; must be a real Huawei Cloud region code (e.g. cn-north-4)	reject, ask for a valid region
--trace_type	enum: system | data	reject anything else
--notification_type	enum: smn | fun	reject anything else
--tracker_type	enum: system | data	reject anything else
--operation_type	enum: complete | customized	reject anything else
--trace_rating	enum: normal | warning | incident	reject anything else
--limit	integer, 1–200	reject non-integer / out-of-range
--from / --to	13-digit integer (epoch ms), used together	reject malformed / mismatched pairs
--project_id / --domain_id	32-hex-char string	reject anything else
--tracker_name, --notification_name, --topic_id, --polling (any name/URN value)	plain string; no spaces, no shell metacharacters (semicolon, ampersand, dollar sign, backtick, quotes, angle brackets)	reject if it contains shell metacharacters

Rule: if a value fails its whitelist/type check, return a U (user input) error and do not execute the command. Never echo caller input into a command line without validation.

ListOperations

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--resource_type	No	string	Resource type; if used, --service_type is mandatory
--service_type	No	string	Cloud service type (e.g. ECS)

ListTraces

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--trace_type	Yes	string	Trace type: system (default) or data
--from / --to	No	integer	UTC ms timestamps (13 digits), used together; default = last hour → now
--limit	No	integer	Number of traces, default 10, max 200
--next	No	string	Pagination marker (value of marker in response)
--user	No	string	User name filter (system traces only)
--service_type	No	string	Cloud service acronym filter (system traces only)
--resource_id / --resource_name / --resource_type	No	string	Resource filters (system traces only)
--trace_id	No	string	Trace ID; if set, other criteria are ignored
--trace_name	No	string	Trace name (system traces only)
--trace_rating	No	string	Trace status: normal | warning | incident
--tracker_name	No	string	System traces: system; data traces: data tracker name
--enterprise_project_id	No	string	Enterprise project filter
--access_key_id	No	string	Access key used to query traces

CreateTracker

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--tracker_name	Yes	string	Tracker name (default system for system type)
--tracker_type	Yes	string	system (management tracker) or data (data tracker)
--obs_info.bucket_name	No*	string	OBS bucket for log delivery (*needed for OBS delivery)
--obs_info.is_obs_created	No	boolean	true = create new bucket, false = use existing
--obs_info.file_prefix_name	No	string	File name prefix for OBS trace files
--obs_info.compress_type	No	string	gzip (default) or json
--obs_info.bucket_lifecycle	No	integer	Retention days in OBS bucket (data tracker only)
--obs_info.is_sort_by_service	No	boolean	Sort transfer path by cloud service (default true)
--is_lts_enabled	No	boolean	Enable LTS trace analysis (long retention)
--is_organization_tracker	No	boolean	true = org tracker (cross-account dumps)
--is_support_trace_files_encryption	No	boolean	Encrypt OBS trace files (with --kms_id)
--kms_id	No	string	KMS key ID (mandatory when encryption enabled)
--is_support_validate	No	boolean	Enable trace file verification
--agency_name	No	string	cts_admin_trust auto-creates the cloud service agency
--data_bucket.data_bucket_name	No	string	Bucket tracked by a data tracker
--data_bucket.data_event.1	No	array	Data tracker events: WRITE | READ
--management_event_selector.exclude_service.1	No	array	Services excluded from dump (currently only KMS)

ListTrackers

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--tracker_name	No	string	Tracker name; omitted → all trackers
--tracker_type	No	string	system or data

DeleteTracker

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--tracker_name	No	string	Tracker name; omitted → all data trackers
--tracker_type	No	string	data (default) or system

CreateNotification

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--notification_name	Yes	string	Notification name
--operation_type	Yes	string	complete (all operations) or customized
--topic_id	No	string	SMN topic URN or FunctionGraph function URN
--agency_name	No	string	cts_admin_trust auto-creates agency
--operations.1.service_type	No	string	Cloud service acronym (customized type)
--operations.1.resource_type	No	string	Resource type (customized type)
--operations.1.trace_names.1	No	array	Trace names (customized type)
--notify_user_list.1.user_group	No	string	IAM user group
--notify_user_list.1.user_list.1	No	array	IAM users
--filter.is_support_filter	No	boolean	Enable advanced filter
--filter.condition	No	string	AND or OR between filter rules
--filter.rule.1	No	array	Filter rule, format field rule value (fields: api_version, code, trace_rating, trace_type, resource_id, resource_name)

ListNotifications

Parameter	Required	Type	Description
--project_id	Yes	string	Project ID (path)
--notification_type	Yes	string	smn or fun (path param)
--notification_name	No	string	Notification name; omitted → all notifications

ListTraceResources

Parameter	Required	Type	Description
--domain_id	Yes	string	Account (domain) ID — not project ID

Quality Reporting

Execution quality is reported via the unified CLI reporting mechanism (skill-quality-cli, installed by scripts/ensure_cli.sh) — see the "Quality Reporting (Unified CLI)" section at the end of this document. Every hcloud command in this skill MUST be wrapped with skill-quality-cli run --skill-name huawei-cloud-cts-trace-management -- .... The CLI auto-collects session_id / agent / user_input / tokens / steps from the host session — there is no in-process SDK dependency. Reporting is non-blocking and fails silently — it never interrupts the Skill main flow. Disable via SKILL_QUALITY_DISABLE=1 for local testing.

Error Code Convention

Prefix	Category	Examples
U	User input	U01 missing param, U03 no data found
C	Configuration	C01 missing AK/SK/env, C02 missing project_id
N	Network	N01 timeout, N02 connection refused
B	Code bug	B01 null pointer, B04 version mismatch
P	Platform	P01 scheduler error, P02 resource insufficient

KooCLI Command Format Standard

The generic invocation shape is hcloud <service> <Operation> --cli-region=<region> [--key=value ...] — this is a format description only: <...> and [--key=value] are placeholders, never executed verbatim.

Feature	Rule	Example
Service name	CTS (metadata directory cts; case-insensitive for invocation)	hcloud CTS ListTrackers
Operation name	PascalCase	ListTrackers, CreateTracker
Region parameter	--cli-region=<value> always included	--cli-region=cn-north-4
Simple parameter	--key=value	--project_id=xxx
Indexed parameter	--key.1=value1	--operations.1.service_type=ECS
Nested parameter	--parent.child=value	--obs_info.bucket_name=xxx
Verification	Run --help first; parameter names come from --help output only	hcloud CTS ListTraces --cli-region=cn-north-4 --help

Reference Documents

• references/iam-policies.md — Least-privilege IAM policies for CTS
• references/cli-installation-guide.md — hcloud CLI installation and AK/SK/profile authentication
• references/verification-method.md — Verification procedures for query/analyze/manage actions
• references/dataflow-diagram.md — Mermaid data flow diagrams
• references/acceptance-criteria.md — Acceptance criteria for this skill
• scripts/ensure_cli.sh — idempotent installer for skill-quality-cli (quality reporting)

Quality Reporting (Unified CLI)

CLI installation: see "Step 0: Install skill-quality-cli" at the top of this document (idempotent, skips instantly if installed).

Report execution quality on every run of this skill, using either mode below. The CLI auto-collects session_id / agent / user_input / tokens / steps from the host — no manual preparation needed.

⚠️ PATH note: the CLI is installed to ~/.local/bin/, which is NOT always in $PATH in some environments. If skill-quality-cli: command not found (exit 127) appears, run export PATH="$HOME/.local/bin:$PATH" first (ensure_cli.sh does this automatically), then retry; or call the absolute path ~/.local/bin/skill-quality-cli directly.

Mode 1 (recommended, automatic) — wrap the whole execution

For script/command-style skills, wrap the entire command with run:

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

Mode 2 (multi-step / instruction-style skills)

Report once per step (callable multiple times):

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

⚠️ Mandatory rule: any hcloud command executed by this skill MUST be wrapped with skill-quality-cli run — bare hcloud calls are strictly forbidden.

CLI installation & auto-update

• Local install: run bash scripts/ensure_cli.sh before execution (idempotent, skips if installed). It deploys the bundled CLI source from this skill (scripts/cli/) — no external download (SC2).
• Installed CLI: the bundled version is fixed (v1.1.8) and does NOT auto-download/upgrade from the network. --no-auto-upgrade is accepted for compatibility but is a no-op.
• Manual cold-start (fallback): if ensure_cli.sh is unavailable, deploy the bundled source directly:

  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"
  

  (No curl, no external URL, no runtime download.)
• Idempotent: run/report never touch the network for CLI management; disable further reporting with SKILL_QUALITY_DISABLE=1 or SKILL_QUALITY_REPORT=0
• Current version is recorded in ~/.skill-quality/version.json; bootstrap/install deploy the pinned bundled version only.

Tool parameter validation (TM1)

Every command wrapped via skill-quality-cli run is validated before execution:

• Whitelist: only the hcloud CLI may be wrapped — any other executable is rejected outright.
• Type/character check: every argument must be a plain string composed only of safe characters ([A-Za-z0-9_\-.,:=/{}@]); anything else (shell metacharacters, $(), backticks, spaces-as-arg, etc.) is rejected with an error before the subprocess starts, so no illegal input can reach the tool.