huawei-cloud-cts-trace-management

Imported from Jane-o-O-o-O/personal-agent (resources/ecosystem/upstream/huaweicloud-skills/651f29808f5f/skills/monitoring/cts/huawei-cloud-cts-trace-management/SKILL.md). Install upstream with npx skills add Jane-o-O-o-O/personal-agent --skill huawei-cloud-cts-trace-management. Copyright stays with the author.

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 / 云审计服务) through the hcloud CLI. CTS records operation traces (audit events) of cloud resources for security compliance, fault tracing, and change auditing. The skill covers:

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

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

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):

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

ListTraces

CreateTracker

ListTrackers

DeleteTracker

CreateNotification

ListNotifications

ListTraceResources

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

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.

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.