huaweicloud-devkit 0.1.17

package/plugins/huaweicloud-core/hooks/huaweicloud-safety.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""PreToolUse hook for Huawei Cloud agent safety.
+
+Blocks the highest-risk leakage paths before an agent tool runs:
+- reading local Huawei Cloud credential files
+- dumping cloud credential environment variables
+- directly retrieving cloud secret values
+- running unapproved write operations through hcloud
+
+The MCP server carries the same policy in Node for platforms that do not support
+plugin hooks.
+"""
+
+import json
+import re
+import sys
+
+DENY_PREFIX = "Huawei Cloud safety hook blocked this action: "
+
+CONFIG_FILE_RE = re.compile(r"(\.hcloud|\.huaweicloud|hcloud[/\\](config|credentials)|huaweicloud[/\\](config|credentials))", re.I)
+ENV_DUMP_RE = re.compile(r"(env|printenv|Get-ChildItem\s+Env:|gci\s+Env:|dir\s+Env:).*(HUAWEICLOUD|HWC_|HCLOUD|OS_)", re.I)
+SECRET_READ_RE = re.compile(r"(ShowSecretVersion|GetSecretValue|secret_string|secret_binary)", re.I)
+HCLOUD_RE = re.compile(r"(^|\s)hcloud(\.exe)?\s+", re.I)
+WRITE_OPERATION_RE = re.compile(
+    r"\b(BatchCreate|BatchDelete|Create|Delete|Update|Modify|Resize|Reboot|Stop|Start|Restart|Authorize|Revoke|Add|Remove|Associate|Disassociate|Attach|Detach|Enable|Disable)\w*",
+    re.I,
+)
+READ_OPERATION_RE = re.compile(r"\b(List|Show|Get|Describe|NovaList|NovaShow)\w*", re.I)
+
+
+def deny(reason):
+    json.dump(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": DENY_PREFIX + reason,
+            }
+        },
+        sys.stdout,
+    )
+    sys.exit(0)
+
+
+def allow():
+    sys.exit(0)
+
+
+def command_text(tool_input):
+    if isinstance(tool_input, str):
+        return tool_input
+    if isinstance(tool_input, dict):
+        values = []
+        for key in ("command", "cmd", "script", "args", "arguments"):
+            value = tool_input.get(key)
+            if isinstance(value, list):
+                values.append(" ".join(str(item) for item in value))
+            elif value is not None:
+                values.append(str(value))
+        if values:
+            return "\n".join(values)
+        return json.dumps(tool_input)
+    return json.dumps(tool_input)
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        allow()
+
+    tool_name = data.get("tool_name", "")
+    text = command_text(data.get("tool_input", {}))
+
+    if CONFIG_FILE_RE.search(text):
+        deny("reading Huawei Cloud credential/profile files can expose AK/SK or tokens. Use redacted toolkit tools.")
+    if ENV_DUMP_RE.search(text):
+        deny("dumping cloud credential environment variables is not allowed.")
+    if SECRET_READ_RE.search(text):
+        deny("direct secret value retrieval would put plaintext secrets into the agent context.")
+    if tool_name == "Bash" and HCLOUD_RE.search(text) and WRITE_OPERATION_RE.search(text) and not READ_OPERATION_RE.search(text):
+        deny("unapproved Huawei Cloud write operations must be planned first and explicitly approved by the user.")
+
+    allow()
+
+
+if __name__ == "__main__":
+    main()

package/plugins/huaweicloud-core/safety/policy.json

@@ -0,0 +1,86 @@
+{
+    "version":  "0.1.0",
+    "secretKeyNamePatterns":  [
+                                  "access[_-]?key",
+                                  "secret[_-]?key",
+                                  "security[_-]?token",
+                                  "x[_-]?auth[_-]?token",
+                                  "authorization",
+                                  "password",
+                                  "passwd",
+                                  "token",
+                                  "credential",
+                                  "private[_-]?key",
+                                  "ak",
+                                  "sk"
+                              ],
+    "credentialFilePatterns":  [
+                                   "\\.hcloud",
+                                   "\\.huaweicloud",
+                                   "hcloud[/\\\\](config|credentials)",
+                                   "huaweicloud[/\\\\](config|credentials)"
+                               ],
+    "blockedConfigureSubcommands":  [
+                                        "show",
+                                        "get",
+                                        "list",
+                                        "export",
+                                        "init"
+                                    ],
+    "blockedSecretOperations":  [
+                                    "ShowSecretVersion",
+                                    "DownloadSecret",
+                                    "GetSecretValue"
+                                ],
+    "writeOperationPrefixes":  [
+                                   "Create",
+                                   "BatchCreate",
+                                   "Delete",
+                                   "BatchDelete",
+                                   "Update",
+                                   "Modify",
+                                   "Resize",
+                                   "Reboot",
+                                   "Stop",
+                                   "Start",
+                                   "Restart",
+                                   "Authorize",
+                                   "Revoke",
+                                   "Add",
+                                   "Remove",
+                                   "Associate",
+                                   "Disassociate",
+                                   "Attach",
+                                   "Detach",
+                                    "Enable",
+                                    "Disable",
+                                    "Set",
+                                    "Put",
+                                    "Upload",
+                                    "Install",
+                                    "Publish",
+                                    "Bind",
+                                    "Unbind",
+                                    "Invoke",
+                                    "Execute",
+                                    "Trigger",
+                                    "Deploy"
+                               ],
+    "readOperationPrefixes":  [
+                                  "List",
+                                  "Show",
+                                  "Get",
+                                  "Describe",
+                                  "NovaList",
+                                  "NovaShow"
+                              ],
+    "safeTextReadCommands":  [
+                                 "rg",
+                                 "grep",
+                                 "findstr",
+                                 "git",
+                                 "ls",
+                                 "dir",
+                                 "Get-ChildItem"
+                             ]
+}

package/plugins/huaweicloud-core/skills/huawei-apig/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: huawei-apig
+description: "Use when creating or managing API Gateway (APIG). Covers API creation, throttling, auth (IAM/APP/basic), CORS, publishing, instance management. Triggers: APIG, API gateway, throttling, publish API. NOT for: FunctionGraph triggers (use huawei-functiongraph)."
+version: 1
+---
+
+# Huawei Cloud APIG
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+## Overview
+
+Domain expertise for Huawei Cloud API Gateway (APIG). Covers instance lifecycle, API group/API creation, publishing, and FunctionGraph trigger integration.
+
+Always discover parameters with `hcloud APIG <Operation> --help` before executing.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| API group region-locked | Cannot move across regions |
+| Throttling per-API default | Use app-level quotas for per-user limits |
+| CORS must be explicit | OPTIONS preflight fails until configured |
+| `BASIC` spec has no public IP | Use `PROFESSIONAL` + `elb` provider for public access |
+| Instance creation takes 5-15min | Long-running async operation. State is **Running** (NOT "SUCCESS"). Poll with `ListInstancesV2`, wait for `status == "Running"` |
+| `sl_domain` is from API **Group** | NOT from Instance. Get it from `CreateApiGroupV2` or `ListApiGroupsV2` response |
+| API name must NOT have hyphens | `[a-zA-Z0-9_]+` only. Hyphens cause regex validation failure |
+| VPC params need prefix | `--vpc.name=<n>` / `--subnet.vpc_id=<id>` / `--security_group.name=<n>` with KooCLI 7.x |
+
+## Instance Management
+
+### Check Existing Instances
+
+```bash
+hcloud APIG ListInstancesV2 --cli-region=<r>
+```
+
+### Create Instance
+
+```bash
+hcloud APIG CreateInstanceV2 --help
+```
+
+Key gotchas when creating:
+
+| Param | Note |
+|-------|------|
+| `--spec_id` | `BASIC` (no public access), `PROFESSIONAL` (requires `--loadbalancer_provider`) |
+| `--loadbalancer_provider` | `elb` for public access (supports `AddIngressEipV2`), `lvs` for internal only (supports `AddEipV2`) |
+| `--enterprise_project_id` | **Required** for enterprise accounts. Use `"0"` for default project |
+| `--available_zone_ids` | Use AZ code like `ap-southeast-3a`, NOT UUID from `ListAvailableZonesV2` |
+| `--vpc_id`, `--subnet_id` | Must exist in the target region |
+| `--security_group_id` | **Required**. Create a security group first via `VPC CreateSecurityGroup` (VPC v3 API — no `vpc_id` param needed) |
+
+### Add Public Access (ELB Provider Only)
+
+```bash
+hcloud APIG AddIngressEipV2 \
+  --instance_id=<id> \
+  --bandwidth_charging_mode=bandwidth \
+  --bandwidth_size=5
+```
+
+> `AddIngressEipV2` only works with `elb` provider. `AddEipV2` requires `lvs` provider. Bandwidth minimum is 5 Mbps.
+
+## API Group
+
+```bash
+hcloud APIG CreateApiGroupV2 --instance_id=<id> --name=<n>
+```
+
+| Param | Note |
+|-------|------|
+| `--name` | Group name (required) |
+| `--remark` | Description (optional) |
+
+## API Management
+
+```bash
+hcloud APIG CreateApiV2 --help
+```
+
+## Publishing
+
+```bash
+hcloud APIG BatchPublishOrOfflineApiV2 \
+  --instance_id=<id> \
+  --action=online \
+  --env_id=<env-id> \
+  --apis.1=<api-id>
+```
+
+> The operation is `BatchPublishOrOfflineApiV2`, NOT `PublishApiV2`. The parameter is `apis.1` (1-based array), NOT `api_ids`. For multiple APIs, use `--apis.1`, `--apis.2`, etc.
+
+## Throttling
+
+```bash
+hcloud APIG CreateThrottlingPolicyV2 --name=<n> --api_call_limits=1000
+```
+
+## Common Workflows
+
+| Task | Operation |
+|------|-----------|
+| List instances | `ListInstancesV2` |
+| Create instance | `CreateInstanceV2` |
+| Delete instance | `DeleteInstancesV2` |
+| Add public EIP | `AddIngressEipV2` |
+| Create API group | `CreateApiGroupV2` |
+| Create API | `CreateApiV2` |
+| Update API | `UpdateApiV2` — change auth mode, path, etc. |
+| List APIs | `ListApisV2` |
+| Publish | `BatchPublishOrOfflineApiV2` |
+| List APIs | `ListApisV2` |
+
+## FunctionGraph Integration
+
+To expose a FunctionGraph function via HTTP, you need the complete chain:
+
+```
+APIG Instance → API Group → DEDICATEDGATEWAY Trigger → Publish
+```
+
+After the trigger is created on FunctionGraph side, publish the API in APIG:
+
+```bash
+hcloud APIG BatchPublishOrOfflineApiV2 \
+  --instance_id=<apig-instance-id> \
+  --action=online \
+  --env_id=<env-id> \
+  --apis.1=<api-id-from-trigger>
+```
+
+See `huawei-functiongraph` skill → `references/deploy-workflow.md` for the full end-to-end workflow.
+
+## Cross-Skill References
+
+- **VPC setup**: See `huawei-vpc` for VPC, subnet, security group creation
+- **EIP setup**: See `huawei-vpc` for EIP creation and binding
+- **FunctionGraph**: See `huawei-functiongraph` for DEDICATEDGATEWAY trigger creation
+
+## References
+
+- APIG Docs: https://support.huaweicloud.com/apig/

package/plugins/huaweicloud-core/skills/huawei-billing/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: huawei-billing
+description: "Use when querying bills, costs, resource usage, or billing details on Huawei Cloud (BSS). Triggers: billing, BSS, cost, bill, expense, usage report, resource usage, budget. NOT for: resource management (use huawei-ecs etc.), creating resources."
+version: 1
+---
+
+# Huawei Cloud Billing (BSS)
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud BSS <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for billing queries (BSS). Covers cost tracking, bill details, and budget management. Read-only — no resource modifications.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| Bills delayed ~24h | Yesterday's costs may not appear until the next day |
+| BSS Admin role needed | IAM user must have BSS Administrator or Finance role |
+| Currency conversion varies | Cross-region costs use daily exchange rates |
+
+## Common Workflows
+
+| Task | Operation |
+|------|-----------|
+| List costs | `ListCosts --cli-region=<r> --project_id=<p>` |
+| List customer bills | `ListCustomerBills --cli-region=<r> --project_id=<p>` |
+| List resource usage | `ListResourceUsage --cli-region=<r> --project_id=<p>` |
+| List sub-customers | `ListConsumeSubCustomers --cli-region=<r> --project_id=<p>` |
+| Show account balance | `ShowCustomerAccountBalances --cli-region=<r> --project_id=<p>` |
+| List conversions | `ListConversions --cli-region=<r> --project_id=<p>` |
+
+Discover exact parameters with `--help` before executing any command. All BSS operations are read-only.
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| Access denied | User needs BSS Administrator or Finance role |
+| No data returned | Check time range (bills have ~24h delay). Verify project_id |
+| Enterprise account restrictions | Some APIs require enterprise real-name authentication |
+
+## Cross-Skill References
+
+- **Resource lifecycle**: See `huawei-ecs`, `huawei-obs` for creating billable resources

package/plugins/huaweicloud-core/skills/huawei-cbr/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: huawei-cbr
+description: "Use when creating or managing Cloud Backup and Recovery (CBR) vaults, backups, and restore operations on Huawei Cloud. Triggers: CBR, backup, restore, vault, snapshot, disaster recovery. NOT for: OBS object versioning (use huawei-obs), RDS automated backups (use huawei-rds)."
+version: 1
+---
+
+# Huawei Cloud CBR
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud CBR <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for Cloud Backup and Recovery. Covers vaults, backups, restore operations, policies, and cross-region replication.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| Vault binds single resource type | Server vault != disk vault != file system vault |
+| Restore needs instance stop | Most VM restore requires the target instance to be stopped first |
+| Backup storage incurs charges | Retention policies affect storage costs |
+
+## Common Workflows
+
+| Task | Operation |
+|------|-----------|
+| List vaults | `ListVaults --cli-region=<r> --project_id=<p>` |
+| Create vault | `CreateVault --cli-region=<r> --project_id=<p>` |
+| Create backup policy | `CreatePolicy --cli-region=<r> --project_id=<p>` |
+| Create checkpoint | `CreateCheckpoint --cli-region=<r> --project_id=<p>` |
+| Add resource to vault | `AddVaultResource --cli-region=<r> --project_id=<p>` |
+| Batch update vault | `BatchUpdateVault --cli-region=<r> --project_id=<p>` |
+| Create organization policy | `CreateOrganizationPolicy --cli-region=<r> --project_id=<p>` |
+
+Discover exact parameters with `--help` before executing any command.
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| Backup creation fails | Check instance is running and agent is online |
+| Restore fails | Ensure target instance is stopped before restore |
+| Vault full | Increase vault capacity or adjust retention policy |
+
+## Cross-Skill References
+
+- **ECS**: See `huawei-ecs` for backing up instances
+- **EVS**: See `huawei-ecs` references/evs.md for disk backup

package/plugins/huaweicloud-core/skills/huawei-cce/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: huawei-cce
+description: "Use when creating or managing CCE Kubernetes clusters. Covers cluster creation, node pools, SWR registry, autoscaling. Triggers: CCE, Kubernetes, K8s, cluster, node pool, container, SWR. NOT for: serverless functions (use huawei-functiongraph), serverless containers (use huawei-cce for CCI redirect)."
+version: 1
+---
+
+# Huawei Cloud CCE
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud <Service> <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for CCE (Cloud Container Engine) and SWR (Software Repository for Container). CCE uses two hcloud services: `CCE` for clusters and `SWR` for container images.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| **KooCLI 7.x: CreateCluster/CreateNodePool broken** | OPENAPI_ERROR in KooCLI 7.2.12. Use `CreateAutopilotCluster` for serverless, or Python SDK for VM clusters |
+| Cluster type immutable | Cannot change hybrid/traditional after creation |
+| Master managed by Huawei | No SSH to master. Use kubectl or kubectl-cce |
+| Network model affects pod IP | VPC network gives pods VPC IPs |
+| Addon ops use UID not name | `ShowAddonInstance` returns `metadata.uid` for install/uninstall/update |
+| SWR enterprise instance costs | `postPaid` billing. One-time activation at console required |
+
+## Common Workflows
+
+| Task | Operation | Service |
+|------|-----------|---------|
+| List clusters | `ListClusters` | CCE |
+| Create cluster | `CreateCluster` | CCE |
+| Delete cluster | `DeleteCluster` | CCE |
+| Hibernate cluster | `HibernateCluster` | CCE |
+| List node pools | `ListNodePools` | CCE |
+| Create node pool | `CreateNodePool` | CCE |
+| List nodes | `ListNodes` | CCE |
+| Get kubeconfig | `CreateKubernetesClusterCert` | CCE |
+| List addons | `ListAddonInstances` | CCE |
+| Docker login (SWR) | `CreateAuthorizationToken` | SWR |
+| Create SWR org | `CreateNamespace` | SWR |
+| Create SWR repo | `CreateRepo` | SWR |
+| List repos | `ListReposDetails` | SWR |
+
+## SWR Image Push Workflow
+
+**Prerequisite**: User/agency must have `sts::createServiceBearerToken` IAM permission. Without it, `CreateAuthorizationToken` returns `SVCSTG.SWR.4030170 Insufficient permissions`. Grant via IAM console or attach SWR Admin role.
+
+```bash
+# 1. Docker login to SWR
+hcloud SWR CreateAuthorizationToken --help
+docker login -u <region>@<AK> -p <token> swr.<region>.myhuaweicloud.com
+
+# 2. Tag and push
+docker tag my-app:latest swr.<region>.myhuaweicloud.com/<org>/my-app:latest
+docker push swr.<region>.myhuaweicloud.com/<org>/my-app:latest
+
+# 3. Verify
+hcloud SWR ListReposDetails --cli-region=<r>
+```
+
+> SWR Auth token valid 12h. For CCE node pull access, create long-term credential with `CreateSecret` (valid 1 year).
+
+## Serverless Containers (CCI)
+
+For serverless containers without managing clusters, use CCI (Cloud Container Instance):
+
+- No cluster needed — just namespace + network + workload
+- Key ops: `CCI createCoreV1Namespace`, `CCI createNetworkingCciIoV1beta1NamespacedNetwork`, `CCI createAppsV1NamespacedDeployment`
+- Namespace MUST include `namespace-kubernetes-io/flavor` annotation
+- `limits == requests` strictly enforced (no overcommit)
+
+See `hcloud CCI --help` for full operation list.
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| kubectl connection refused | Verify cluster Running; use `kubectl cce` (no EIP needed) |
+| Node pool creation failed | Check VPC/subnet availability and flavor capacity |
+| Docker push 401 | Re-run `CreateAuthorizationToken` (token expired) |
+| SVCSTG.SWR.4030170 | Missing `sts::createServiceBearerToken` IAM permission. Grant SWR Admin role or add policy |
+| Addon install fails | Use `metadata.uid` from `ShowAddonInstance`, not name |
+| `kubectl cce` not found | Install plugin: `kubectl cce` uses AK/SK, no kubeconfig required |
+
+## Security Considerations
+
+- MUST restrict kubeconfig file permissions (0600)
+- MUST use IAM RBAC for cluster access, not cluster-admin
+- MUST store container images in private SWR repositories
+
+## Cross-Skill References
+
+- **VPC/Subnet**: See `huawei-vpc` for network prerequisites
+- **EIP**: See `huawei-vpc` for cluster public access
+
+## References
+
+- CCE Docs: https://support.huaweicloud.com/cce/
+- SWR Docs: https://support.huaweicloud.com/swr/

package/plugins/huaweicloud-core/skills/huawei-cloud-eye/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: huawei-cloud-eye
+description: "Use when setting up monitoring, alarms, dashboards, or event rules on Huawei Cloud Eye (CES). Triggers: Cloud Eye, CES, monitoring, alarm, metrics, dashboard, event monitoring. NOT for: CTS audit logs (use huawei-cts), AAD anti-DDoS (use huawei-waf-aad)."
+version: 1
+---
+
+# Huawei Cloud Cloud Eye (CES)
+
+**STOP - Do not answer from general knowledge.** Follow the procedure below.
+
+Always run `hcloud CES <Operation> --help` before constructing commands to discover exact parameter names and requirements.
+
+## Overview
+
+Domain expertise for Cloud Eye (CES). Covers metric queries, alarm rules, dashboards, and monitoring agent management.
+
+## Critical Warnings
+
+| Trap | Why |
+|------|-----|
+| Telescope agent required for detailed metrics | Without agent: only basic CPU/network metrics. Memory, disk require agent installation on ECS |
+| Alarm needs SMN topic first | Alarm notifications fail silently without a configured SMN topic |
+| Cost metrics incur charges | Custom metrics and high-frequency alarms have billing implications |
+| CES endpoint may vary by region | Some older regions use different endpoint URLs. Check `https://developer.huaweicloud.com/endpoint?CES` |
+| Metric granularity minimum 300s | Free tier has 5-minute minimum. Higher resolution requires paid tier |
+
+## Prerequisites
+
+- ECS instances need the **Telescope agent** installed for detailed metrics (memory, disk, network)
+- Without agent: only SYS.ECS namespace metrics available (CPU, network bytes, disk read/write)
+- Alarm notifications require an SMN topic (see `huawei-smn-dms`)
+
+## Common Workflows
+
+| Task | Operation |
+|------|-----------|
+| List metrics | `ListMetrics --cli-region=<r> --project_id=<p>` |
+| Get metric data | `BatchListMetricData --cli-region=<r> --project_id=<p>` |
+| List alarms | `ListAlarms --cli-region=<r> --project_id=<p>` |
+| Create alarm | `CreateAlarm` (see below) |
+| Delete alarm | `BatchDeleteAlarmRules --cli-region=<r> --project_id=<p>` |
+| List dashboards | `ListDashboardWidgets --cli-region=<r> --project_id=<p>` |
+| Create dashboard | `CreateDashboard --cli-region=<r> --project_id=<p>` |
+
+## Create Alarm Rule — Param Structure
+
+CES uses **nested object prefixes** for alarm creation. Always verify with `--help`:
+
+```bash
+hcloud CES CreateAlarm --help
+# Key params: --alarm_name, --metric.metric_name, --metric.namespace,
+# --condition.period, --condition.filter, --condition.value,
+# --condition.comparison_operator, --condition.count
+```
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| No metric data | Telescope agent not installed or ECS stopped. Install agent for detailed metrics |
+| Alarm not triggering | Check metric period (minimum 300s), verify condition threshold |
+| CES network timeout in region | Some regions may have CES endpoint issues. Try a different region |
+
+## Security
+
+- MUST use role-based alarm notifications
+- MUST not expose alarm action endpoints publicly
+- SHOULD enable CES alarm history for audit
+
+## Cross-Skill References
+
+- **SMN topics**: See `huawei-smn-dms` for alarm notification setup
+- **ECS monitoring**: See `huawei-ecs` for instance creation