SASE Private Access Network Diagnosis

Diagnose whether the enterprise network path through the SASE cluster to office applications is connected, providing link-level visibility and problem localization.

Architecture: SASE Client → POP Entry Point → Connector/CEN/VPN → VPC → Origin Server

Diagnosis Types

Limitations

The following features cannot be implemented via CLI or SDK and require the SASE Console:

Prerequisites

• SASE App version >= 4.4.1
• Network tunnel established (VPC/CEN/Connector/VPN)
• Office application added and zero-trust policy configured

Installation

Pre-check: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required

• [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
• [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

aliyun configure set --auto-plugin-install true
aliyun plugin update

CLI invocation rule: Use Aliyun CLI plugin mode only. Commands MUST use lowercase kebab-case actions and parameters, for example aliyun csas create-pa-diagnosis-task --diagnose-type FullLink .... Do NOT use PascalCase OpenAPI action names in CLI invocations, and do NOT use --force generic mode for these diagnosis APIs.

Environment Variables

No skill-specific environment variables are required. Use an existing Aliyun CLI credential profile and verify it with aliyun configure list.

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

RAM Permissions

The following RAM permissions are required:

See references/ram-policies.md for full policy details.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Core Workflow

[MUST] Enable AI-Mode at the start of Core Workflow (before any CLI invocation): AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation in this skill:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sase-pa-network-diagnosis"

[MUST] Disable AI-Mode at EVERY exit point: Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

CLI invocation rule: Use plugin mode commands only: create-pa-diagnosis-task, get-pa-diagnosis-task, and list-user-devices. Do not use PascalCase API names or --force generic mode.

Task 0: Query User Device DevTag (FullLink prerequisite)

FullLink diagnosis requires DevTag (device ID), but users typically only know the username or hostname. Use list-user-devices to query the device list and filter for eligible devices to obtain DeviceTag.

Device selection criteria (ALL must be satisfied):

Query eligible devices by username:

aliyun csas list-user-devices \
  --current-page 1 --page-size 50 \
  --username <username> \
  --app-statuses Online \
  --device-types Windows macOS \
  --cli-query 'Devices[].{DeviceTag: DeviceTag, Hostname: Hostname, DeviceType: DeviceType, AppVersion: AppVersion}'

Query eligible devices by hostname:

aliyun csas list-user-devices \
  --current-page 1 --page-size 50 \
  --hostname <hostname> \
  --app-statuses Online \
  --device-types Windows macOS \
  --cli-query 'Devices[].{DeviceTag: DeviceTag, Hostname: Hostname, DeviceType: DeviceType, AppVersion: AppVersion}'

Version check: The API does not support filtering by version. Check the AppVersion field in results to verify >= 4.4.1. If the version does not meet requirements, prompt the user to upgrade SASE App first.

Multiple devices handling: A user may have multiple devices; the result is a list.

• If only 1 device with a valid version, use its DeviceTag directly
• If multiple devices, display the list and ask the user to confirm which device to use
• If no eligible devices found, inform the user to check: device online status, device type support, and version compliance

Task 1: Create FullLink Diagnosis Task

aliyun csas create-pa-diagnosis-task \
  --diagnose-type FullLink \
  --host <target_address> \
  --port <port> \
  --protocol TCP \
  --username <username> \
  --dev-tag <DeviceTag_from_Task0> \
  --pop-mode AutoSelect

Task 2: Create Application Diagnosis Task

aliyun csas create-pa-diagnosis-task \
  --diagnose-type Application \
  --host <target_address> \
  --port <port> \
  --protocol TCP \
  --user-group-id <user_group_id> \
  --pop-mode ManualSelect \
  --pop-id <pop_id>

UDP protocol example (with probe config):

aliyun csas create-pa-diagnosis-task \
  --diagnose-type Application \
  --host <target_address> \
  --port <port> \
  --protocol UDP \
  --user-group-id <user_group_id> \
  --pop-mode ManualSelect \
  --pop-id <pop_id> \
  --udp-extra-configs RequestContent=<request_content> ExpectedResponse=<expected_response>

Concurrency Limit and Retry

[IMPORTANT] Diagnosis task concurrency limit is 5. When the number of running tasks reaches the limit, create-pa-diagnosis-task returns the following error:

ErrorCode: DiagnosisTask.NumberExceedsLimit
Message: The number of running diagnosis tasks exceeds the limit of 5.
         Please wait for the tasks to complete.

When this error occurs, use bounded incremental backoff and retry:

1. Retry task creation up to 5 times.
2. Wait longer before each retry: 30 seconds, 60 seconds, 90 seconds, 120 seconds, then 150 seconds.
3. If any retry succeeds, extract DiagnoseId and continue to polling. Do not skip the polling and result analysis steps after a successful create.
4. If all 5 retries fail, clearly tell the user that the SASE diagnosis concurrency limit is still full. Ask the user to open the SASE Console and manually end idle diagnosis tasks, or confirm whether to retry with another --diagnose-type (FullLink <-> Application) after providing the parameters required by that diagnosis type.
5. If the user cannot clear tasks or switch diagnosis type, run aliyun configure ai-mode disable and terminate the current workflow.

Note: Do NOT expose the raw error message to the user. Instead, explain: "Other diagnosis tasks are currently running and the concurrency limit (5) has been reached. Waiting and retrying..."

Extract DiagnoseId from the successful response:

# Extract DiagnoseId
aliyun csas create-pa-diagnosis-task \
  --diagnose-type FullLink --host <target_address> --port <port> --protocol TCP \
  --username <username> --dev-tag <DeviceTag_from_Task0> --pop-mode AutoSelect \
  --cli-query 'DiagnosisTask.DiagnoseId' --quiet

Task 3: Query Diagnosis Task Result

aliyun csas get-pa-diagnosis-task \
  --diagnose-id <diagnose_id>

Task 4: Poll Until Task Completes

Poll manually with a bounded loop until Status contains Finished or Failed. The CLI output may contain quotes, whitespace, or line breaks, so do not rely on exact string equality.

MAX_POLLS=20
POLL_INTERVAL=10
POLL_COUNT=0
STATUS=""

while [ "$POLL_COUNT" -lt "$MAX_POLLS" ]; do
  sleep "$POLL_INTERVAL"
  POLL_COUNT=$((POLL_COUNT + 1))
  STATUS=$(aliyun csas get-pa-diagnosis-task \
    --diagnose-id <diagnose_id> \
    --cli-query 'DiagnosisTask.Status' --quiet 2>/dev/null | tr -d '[:space:]"')
  echo "Current status: $STATUS"
  if echo "$STATUS" | grep -qE 'Finished|Failed'; then
    break
  fi
done

if ! echo "$STATUS" | grep -qE 'Finished|Failed'; then
  echo "Polling timed out after $((MAX_POLLS * POLL_INTERVAL)) seconds; retrieve the full task result once and explain that the task may still be running or status parsing failed."
fi

Polling safety: Never poll more than MAX_POLLS times in one workflow. If polling times out, retrieve the full task result once with get-pa-diagnosis-task, summarize the current status, then stop or ask the user whether to continue waiting.

Task 5: Retrieve Full Diagnosis Result and Analyze

[IMPORTANT] Must retrieve the complete result before performing comprehensive analysis. The Success field only indicates whether the diagnosis task itself completed normally — it does NOT indicate whether the network link is healthy. Actual network issue information is distributed across NetworkLinkInfo.Nodes, NetworkLinkInfo.Links, PolicyInfo, and other fields. Example: Success=true but a Node has Success=false with Error containing zero-trust policy block info means the diagnosis process ran fine but the network is actually blocked.

Step 1: Retrieve the full diagnosis result (single call to get all fields):

aliyun csas get-pa-diagnosis-task \
  --diagnose-id <diagnose_id>

Step 2: Comprehensively analyze the following fields from the full result:

Analysis principle: Even when Success=true, you MUST iterate through every Node's Success and Error fields in Nodes. When a node-level Success=false with non-empty Error, explain the specific issue for that link segment to the user (e.g., policy block, connection timeout, etc.).

Verification

See references/verification-method.md

Cleanup

Note: There is no public API to delete diagnosis tasks. To delete, go to SASE Console > Private Access > Network Diagnosis.

Related Commands

See references/related-commands.md

Best Practices

1. FullLink diagnosis requires a specific device (DevTag) and username; Application diagnosis requires a user group (UserGroupId)
2. Choose a POP entry point closest to the target origin server to minimize network latency
3. FullLink supports auto-routing (PopMode=AutoSelect); Application requires manual POP selection
4. For UDP protocol, configure probe request and expected response to verify packet delivery
5. After creating a task, poll get-pa-diagnosis-task until Status becomes Finished or Failed
6. On diagnosis failure, use ErrorMessage and each Node's Success/Error in NetworkLinkInfo to locate the problematic segment
7. After resolving the issue, re-create a diagnosis task with the same parameters to verify

References