/alibabacloud-network-diagnose

name: alibabacloud-network-diagnose
description: "[project] [user] Alibaba Cloud private network connectivity diagnosis tool. Use when ECS ping/telnet fails, same-VPC access fails, cross-VPC access fails, VPN or Express Connect is unreachable, NAT Gateway DNAT/SNAT behaves asymmetrically, or the user suspects security group, network ACL, route table, CEN/TR, VPC Peering, VPN Gateway, VBR, or NAT Gateway blocking. Not for classic network, public internet access, DNS resolution, CDN, SLB, or WAF issues."

Alibaba Cloud Private Network Connectivity Diagnosis

Mandatory First Action

Before reasoning about the cause or running any diagnostic command, execute Step 0 with the skill scripts:

PYTHON=$(bash scripts/detect_python.sh) || exit 1
$PYTHON scripts/net_common.py check-env
$PYTHON scripts/net_common.py parse-input --input "<all user-provided information>"

If `parse-input` returns `workflow_blocked: true` or exits with code `2`, stop and output its `required_action` to the user. Wait for source/destination instance IDs, IP addresses, or VPC IDs and their region. Do not continue diagnosis, infer a local target, or inspect the execution environment. In particular, do not run `ss`, `netstat`, `lsof`, `curl`, `ping`, `nc`, `telnet`, `ip`, `iptables`, `firewall-cmd`, `nslookup`, or inspect `/proc`, nginx, Kubernetes, container, proxy, certificate, host, listener, interface, or local route state. Those describe the AgentHub runner, not the user's Alibaba Cloud network.

Once blocked, do not rerun `parse-input` with fabricated, guessed, example, or default endpoints. A normal second call cannot clear the guard. Only after a new user response supplies endpoint information, parse that response with `--resume-after-user-response`. Using this flag before a real user follow-up is a critical violation.

This gate applies even when the prompt only says that a protocol or port, such as TCP 443, is unreachable. The only permitted next action without a cloud endpoint is to ask for the missing endpoint information.

**Blocked-workflow completion rule**: The first turn is complete as soon as `required_action` is returned. Do not keep a command running while waiting for the user and do not poll, sleep, or retry. Resume only in a later user turn.

Applicable Scenarios

| Scenario | Typical Issues | |----------|---------------| | **Same-VPC instance interconnection** | ECS ping/telnet failure, security group blocks, missing route entries | | **Cross-VPC access** (VPC Peering / CEN) | Missing cross-VPC routes, CEN route not learned, VPC Peering status abnormal | | **Cloud-to-IDC** (VPN Gateway) | VPN tunnel status abnormal, routes not propagated, IKE/IPsec configuration issues | | **Cloud-to-IDC** (Express Connect / VBR) | VBR status abnormal, BGP neighbor down, routes not learned | | **NAT Gateway DNAT/SNAT** | DNAT asymmetric return path, missing DNAT/SNAT rules, NAT Gateway status abnormal |

**Not applicable**: Classic network, public internet access, DNS resolution (use `dns-resolve-diagnose`), CDN/SLB/WAF configuration.

Prerequisites

• **Python 3.7+** (required) — scripts use standard library only, no third-party dependencies
• **aliyun CLI** (required): macOS `brew install aliyun-cli`; Linux download from [aliyuncli.alicdn.com](https://aliyuncli.alicdn.com). See [cli-installation-guide.md](references/cli-installation-guide.md).
• **Alibaba Cloud credentials**: Use the aliyun CLI default credential chain. Prefer a configured CLI profile; if no profile is configured, an environment-backed default provider can be used. Diagnosis cannot run without credentials.
• **User input**: Supports any combination — instance IDs, VPC IDs, IP addresses, security group IDs, protocol/port, problem description. The skill intelligently determines the diagnosis path.

> See [ram-policies.md](references/ram-policies.md) for permission details. All operations are read-only.

Core Principles

> **Must use scripts for diagnosis**: Do not use ping/telnet/nc/traceroute, curl, ss, netstat, lsof, or direct `aliyun` commands. Never inspect or report the AgentHub runner/container's IP addresses, listening ports, processes, certificates, hosts file, proxy, firewall, or Kubernetes configuration as if they were the user's environment. All steps are executed through `net_common.py`, `net_ecs.py`, `net_vpc.py`, `net_cross_vpc.py`, `net_hybrid.py`, and `net_analyze.py`. The wrappers already retry and fall back between official CLI invocation modes. Run each script command once. If it returns a JSON `error`, preserve that file, mark the step failed, and continue only independent script-based checks. Do not retry it with a longer shell timeout, inspect script source to bypass it, invoke `aliyun` directly, or fabricate/modify step JSON. > > **Empty endpoint guardrail**: After `parse-input`, if `workflow_blocked` is `true`, output `required_action` and wait for the user. Do not make any cloud API call or execute Step 1 and later. There are no exceptions. > > **Multi-fault investigation**: After finding an issue, including a P0 root cause, continue all applicable remaining steps through Step 7. Do not run the final analysis early. The final report must list all problems found. > > **Bidirectional route check**: Route checks must cover both forward and return paths. Both VPC route tables and TR route tables require bidirectional verification. When the forward path passes through an intermediary device (e.g., NAT), the return path must also traverse the same device.

Diagnosis Workflow

Execute steps strictly in order. Output results and conclusions immediately after each step. Save data to `./output/net_diag_<timestamp>/`, analyze each step with `net_analyze.py` and output concise conclusions.

Before the final response, verify the execution log contains Step 0 and exactly one final `scripts/net_analyze.py all --dir "$DIAG_DIR"` call. If either is absent, the workflow is incomplete. Direct `aliyun` command