Alibabacloud Waf Quick Showcase

Using WAF to Protect Web Applications on ECS

With this skill, you can quickly deploy a complete web application protection solution, including network environment setup, ECS instance creation, sample application deployment, and WAF integration.

Prerequisites

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 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.

[MUST] AI-Mode Configuration — Must configure AI-Mode before executing CLI commands:

1. Enable AI-Mode (before any CLI commands):

   aliyun configure ai-mode enable

2. Set User-Agent for AI-Mode:

   aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase"

3. Disable AI-Mode (after workflow completion):

   aliyun configure ai-mode disable

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

Supported Scenarios

This skill supports two usage scenarios:

>

1. Quick WAF Protection Experience: Create VPC, ECS, and WAF from scratch for a complete protection experience

2. Existing WAF Protection Experience: User already has WAF, create new VPC and ECS to integrate with existing WAF

>

Prohibited Scenario:

- Existing ECS Integration: Does not support integrating user's existing ECS into WAF

>

If the user indicates they have existing ECS and want to integrate it into WAF, respond:

"This skill is designed for experiencing the complete WAF protection workflow and requires creating new ECS instances. If you want to integrate your existing ECS into WAF, please refer to the Cloud Product Integration feature in the WAF console."

CRITICAL: Scenario 1 Resource Creation Rules

>

If the user requests "Quick Experience" (Scenario 1):

- VPC: Create new if quota is sufficient; use existing VPC if quota is full

- Must Create New: VSwitch, Security Group, ECS

- WAF Reusable: If WAF already exists, skip creation and use existing WAF to integrate ECS

- If creation fails, must stop and inform the user

MUST: Scenario 1 Must Check for Existing WAF Instance

>

After authentication confirmation and before parameter confirmation, must execute:

```bash

aliyun waf-openapi describe-instance --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

```

>

- If valid InstanceId is returned: Skip WAF creation steps and use this WAF directly to integrate ECS

- Prompt: "Detected that your account already has a WAF instance (InstanceId: [xxx]), will use this instance for protection experience."

- If no WAF instance: Execute Step 4 to create new WAF

Scenario 2: Existing WAF Protection Experience (Detailed)

CRITICAL: Handling Process When User Already Has WAF

>

When the user indicates they have a WAF instance:

1. Ask for WAF Instance ID: Must first ask for the user's existing WAF instance ID

2. Skip WAF Creation: Prohibit executing create-postpaid-instance, directly use the WAF instance ID provided by the user

3. Create New Network and ECS: Still need to create VPC, VSwitch, Security Group, ECS

4. Integrate Existing WAF: Use the user's WAF instance ID to execute sync-product-instance and create-cloud-resource

>

Inquiry Prompt:

"You already have a WAF instance. Please provide your WAF instance ID (format: waf-cn-xxx), and I will create a new ECS for you and integrate it with your existing WAF for experience."

Pre-flight Checks (Must Remind Users Before Each Run)

IMPORTANT: Must proactively ask and help users complete the following checks before running

>

1. CLI Version: Run aliyun version to confirm version >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update.

Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

2. Authentication Configuration: Run aliyun configure list to confirm authentication status is Valid

3. Auto Plugin: Run aliyun configure set --auto-plugin-install true

4. Account Balance: Confirm Alibaba Cloud account balance >= 100 CNY

Authentication Configuration Check (Must Execute)

aliyun configure list

Reminder when authentication is valid:

"Detected that your current CLI authentication configuration is valid:

- Authentication Mode: [OAuth/AK/StsToken] | Account: [Profile Name] | Region: [Region]

>

Please confirm whether to use the current account for operations? Operations will incur charges."

>

MUST: Wait for user confirmation before continuing

- Prohibit: Executing any resource creation operations before user confirmation

- Prohibit: Any authentication mode (including StsToken) must wait for user confirmation

When authentication is invalid: Run aliyun configure --mode OAuth to complete configuration

Security Reminder: Explicitly handling AK/SK credentials is strictly prohibited. This skill only supports OAuth authentication mode.

Solution Architecture

Architecture Components: VPC + VSwitch + Security Group + ECS + WAF 3.0 (Pay-as-you-go)

Traffic Path: User Request → WAF 3.0 (Traffic Filtering and Cleaning) → ECS (Web Application)

Installation and Configuration

For detailed installation steps, see references/cli-installation-guide.md

Quick Start:

# macOS (Homebrew)
brew install aliyun-cli

# Authentication Configuration (OAuth Mode)
aliyun configure --mode OAuth

# Verify Version (must be >= 3.3.3)
aliyun version

Security Reminder: Explicitly handling AK/SK credentials is strictly prohibited. This skill only supports OAuth authentication mode.

Parameter Confirmation

MUST: Must confirm parameters before execution

>

Prohibit: Directly using default values to execute commands; must confirm parameters with the user first.

>

MUST: Input Validation Rules (Must verify the following formats)

- RegionId: Must match ^[a-z]{2}-[a-z]+-[a-z]\d*$ format (e.g., cn-hangzhou-j)

- CidrBlock: Must be valid CIDR format and within RFC1918 private network segments (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)

- ZoneId: Must have RegionId as prefix (e.g., cn-hangzhou-j corresponds to cn-hangzhou)

- InstanceType: Must comply with Alibaba Cloud ECS specification naming convention (ecs.[series]-[spec])

- InstancePassword: 8-30 characters, must contain uppercase letters, lowercase letters, and numbers

- Security Requirement: All parameters are prohibited from containing special characters (such as ; | & $ ` \ etc.)

Parameter Confirmation Prompt (Must Execute)

After authentication confirmation and before executing any commands, must confirm the following parameters with the user:

>

Confirmation Prompt:

"Before starting deployment, please confirm the following parameters:

>

1. Region: cn-hangzhou (or other regions you prefer, such as cn-shanghai, cn-beijing)

2. VPC CIDR Block: 192.168.0.0/16

3. Zone: cn-hangzhou-j

4. ECS Specification: ecs.e-c1m2.large

5. ECS Password: Please provide your ECS login password (8-30 characters, containing uppercase letters, lowercase letters, and numbers)

>

Do you want to use the above parameters? Or tell me which ones you want to modify."

>

MUST: Wait for user confirmation or modification before continuing

- Expected user responses: "Confirm", "Yes", "OK", or provide modifications

- Prohibit: Executing any resource creation operations before user confirms parameters

- Prohibit: Auto-generating ECS passwords; passwords must be provided by the user

- If the user does not provide a password, must ask again and cannot continue

- If the user wants to modify parameters, record the modifications and confirm again

>

MUST: Must reject execution if parameter validation fails

- If user-provided parameters do not meet the format requirements, must clearly inform the user and provide correct examples

- Prohibit: Using invalid parameters to execute commands

- Prohibit: Escaping dangerous characters and continuing execution (should directly reject and require user to provide legal parameters)

>

MUST: Return Value and Output Desensitization

- In any scenario, the --password parameter value in commands, logs, and error messages displayed to users must be shown as *** or [REDACTED]

- CLI Execution Echo: If CLI output contains plaintext passwords, must replace and desensitize before displaying to users

- Error Message Handling: If error messages may contain passwords, must desensitize before displaying

- Prohibited Behaviors:

- Printing complete commands containing plaintext passwords in terminal

- Saving plaintext passwords in history records

- Leaking plaintext passwords in error logs

- Correct Example:

```bash

# Actually executed command (internal)

aliyun ecs run-instances --password MyPass@2024 ...

>

# Command displayed to user (desensitized)

aliyun ecs run-instances --password *** ...

```

MUST: Must use user-confirmed parameters when executing commands

- The cn-hangzhou, 192.168.0.0/16, etc. in the command examples below are reference values only

- Prohibit: Directly copying example commands for execution; must replace with actual values confirmed by the user

- If the user changes the region to cn-shanghai, then all subsequent commands' --biz-region-id, --region, --zone-id must be modified accordingly

Parameter Description and Validation Rules

SHOULD: Special Character Filtering

- All parameters are prohibited from containing: ; | & $ \ " ' < > ( ) { } [ ] ! # ~`

- If the above characters are detected, must reject execution and prompt the user to re-enter

Core Workflow

Step 0: Check VPC Quota

CRITICAL: Must check quota before creating VPC (Each account has a maximum of 10 VPCs per region by default)

aliyun vpc describe-vpcs --biz-region-id cn-hangzhou --page-size 50 --connect-timeout 5 --read-timeout 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase
# Check TotalCount in the response

>

Idempotency Protection: Use --client-token parameter to ensure multiple executions won't create duplicate resources.

Quota Check Result Handling:

>

- TotalCount < 10: Quota is sufficient, create new VPC

- TotalCount >= 10: Quota is full, use existing VPC

>

Handling Process When Quota is Full:

1. Select an existing VPC from the response results (prioritize those with names containing "waf" or "test")

2. Prompt the user: "Your VPC quota is full, will use existing VPC (VpcId: [xxx]) to continue deployment."

3. Create new VSwitch, Security Group, and ECS under this VPC

Step 1: Create VPC and VSwitch

CRITICAL: Failure Handling and Rollback Mechanism

>

If any resource creation fails:

1. Stop Immediately: Must not continue executing subsequent steps

2. Inform User: Clearly explain the failure reason (such as insufficient resources, insufficient permissions, insufficient quota, etc.)

3. Prohibit Substitution: Must not use existing resources instead

>

Failure Prompt:

"Sorry, [VPC/ECS/WAF] creation failed, reason: [error message]. Please check and try again."

# 1.1 Create VPC (Idempotent Operation)
aliyun vpc create-vpc \
  --biz-region-id cn-hangzhou \
  --cidr-block 192.168.0.0/16 \
  --vpc-name VPC_HZ \
  --description "WAF Protection Solution VPC" \
  --connect-timeout 10 --read-timeout 60 \
  --client-token $(uuidgen) \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Save the returned VpcId, e.g., vpc-bp1234567890abcdef

# 1.2 Query VPC Status, Wait Until Status Becomes Available
aliyun vpc describe-vpcs \
  --biz-region-id cn-hangzhou \
  --vpc-id <VpcId> \
  --connect-timeout 5 --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 1.3 Create VSwitch (Idempotent Operation)
aliyun vpc create-vswitch \
  --zone-id cn-hangzhou-j \
  --cidr-block 192.168.1.0/24 \
  --vpc-id <VpcId> \
  --vswitch-name vsw_001 \
  --connect-timeout 10 --read-timeout 60 \
  --client-token $(uuidgen) \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Save the returned VSwitchId

Step 2: Create Security Group and Configure Rules

# 2.1 Create Security Group (Idempotent Operation)
aliyun ecs create-security-group \
  --biz-region-id cn-hangzhou \
  --vpc-id <VpcId> \
  --security-group-name SecurityGroup_1 \
  --security-group-type normal \
  --description "WAF Protection Solution Security Group" \
  --connect-timeout 10 --read-timeout 60 \
  --client-token $(uuidgen) \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Save the returned SecurityGroupId

# 2.2 Add Inbound Rule - Open Port 80
aliyun ecs authorize-security-group \
  --biz-region-id cn-hangzhou \
  --security-group-id <SecurityGroupId> \
  --permissions '[{"Policy":"Accept","Priority":"1","IpProtocol":"TCP","PortRange":"80/80","SourceCidrIp":"0.0.0.0/0"}]' \
  --connect-timeout 10 --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

Step 3: Create ECS Instance

CRITICAL: ABSOLUTELY PROHIBITED - Using Existing ECS Instances

- MUST CREATE NEW: Always create a new ECS instance using RunInstances

- PROHIBITED: Discovering and reusing existing ECS instances (e.g., 'Found multiple existing ECS instances... Selected i-bp1xxx')

- PROHIBITED: Saying "I found an existing ECS instance named 'web-server-waf-demo', will use it"

- Security Policy: Even if user has existing ECS instances, the skill MUST create a new one for the WAF protection experience

- Correct Behavior:

- ✅ Always execute aliyun ecs run-instances to create a new instance

- ✅ Use user-provided password for the new instance

- ✅ If user asks to use existing ECS, explain: "This skill creates new resources for a complete WAF protection experience"

>

Recommended Image IDs (Avoid Blind Queries):

- Alibaba Cloud Linux 3: aliyun_3_x64_20G_alibase_20240819.vhd

- Alternative: aliyun_3_x64_20G_alibase_20221102.vhd

>

Directly use the above ImageId, no need to call DescribeImages query.

>

MUST: Password Desensitization Processing

- Prohibit: Displaying plaintext passwords in terminal output, log printing, or commands shown to users

- Must: Replace --password parameter value with *** or [REDACTED] before displaying

- Example: --password *** instead of --password MyPass@2024

- Security Requirement: Password is only used in original form when passing to CLI commands; any echo must be desensitized

# 3.1 Create ECS Instance (Idempotent Operation)
aliyun ecs run-instances \
  --biz-region-id cn-hangzhou \
  --instance-type ecs.e-c1m2.large \
  --image-id aliyun_3_x64_20G_alibase_20240819.vhd \
  --security-group-id <SecurityGroupId> \
  --vswitch-id <VSwitchId> \
  --instance-name web-server \
  --host-name web-server \
  --internet-charge-type PayByTraffic \
  --internet-max-bandwidth-out 5 \
  --system-disk-size 40 \
  --system-disk-category cloud_essd_entry \
  --password <YourPassword> \
  --amount 1 \
  --connect-timeout 10 --read-timeout 120 \
  --client-token $(uuidgen) \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Save the returned InstanceId

# 3.2 Query ECS Status, Wait Until Status Becomes Running
aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["<InstanceId>"]' \
  --connect-timeout 5 --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

Step 4: Enable WAF and Integrate ECS

⚠️ Integration Reminder: When integrating WAF, web services may experience brief second-level connection interruptions. It is recommended to perform operations during off-peak business hours.

4.1 Create WAF Pay-as-you-go Instance

# Create WAF 3.0 Pay-as-you-go Instance (Idempotent Operation)
aliyun waf-openapi create-postpaid-instance \
  --region cn-hangzhou \
  --connect-timeout 10 --read-timeout 60 \
  --client-token $(uuidgen) \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# The response result contains InstanceId, please save it

Idempotency Protection: Use --client-token parameter to ensure multiple executions won't create duplicate resources.

Concurrent Scenario Handling: If creation fails and the error indicates "WAF instance already exists", execute describe-instance to query existing instance and use it directly.

Authorization Failure Handling:

- If HTTP 500 is returned or authorization is required → Prompt user to go to console for authorization

- Prompt: "First-time use of WAF requires completing service linked role authorization in the console. Please visit https://yundun.console.aliyun.com/?p=waf and click 'Create Service Linked Role' to complete authorization."

- MUST: Wait for user to reply "Authorization completed" before retrying creation

- Prohibit: Repeatedly attempting creation before user confirmation

Note: When creating a WAF instance for the first time, you need to complete the service linked role authorization in the console.

If CLI reports an error indicating authorization is required, please visit WAF Console and click "Create Service Linked Role" to complete authorization before trying again.

4.2 Query WAF Instance Information

# Query WAF Instance Details
aliyun waf-openapi describe-instance \
  --region cn-hangzhou \
  --connect-timeout 5 --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Save the returned InstanceId

4.3 Sync ECS Assets to WAF

# Sync ECS, CLB, NLB Assets to WAF
# Note: WAF instance may need to wait about 10 seconds after creation before it can be called normally
aliyun waf-openapi sync-product-instance \
  --instance-id <WAF-InstanceId> \
  --region cn-hangzhou \
  --connect-timeout 10 --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# If 503 error is returned, please wait 10 seconds and retry

4.4 Integrate ECS into WAF Protection

# Integrate ECS Instance into WAF, Configure HTTP 80 Port Protection
# Note: Must provide --redirect parameter with ReadTimeout and WriteTimeout
aliyun waf-openapi create-cloud-resource \
  --instance-id <WAF-InstanceId> \
  --biz-region-id cn-hangzhou \
  --listen '{"ResourceProduct":"ecs","ResourceInstanceId":"<ECS-InstanceId>","Port":80,"Protocol":"http"}' \
  --redirect '{"ReadTimeout":120,"WriteTimeout":120}' \
  --connect-timeout 10 --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

4.5 Verify ECS Has Been Integrated into WAF

# Query Cloud Products List That Have Been Integrated into WAF
aliyun waf-openapi describe-cloud-resources \
  --instance-id <WAF-InstanceId> \
  --resource-product ecs \
  --page-number 1 \
  --page-size 10 \
  --region cn-hangzhou \
  --connect-timeout 5 --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

Completion Prompt

IMPORTANT: Must prompt users for next steps after WAF integration is complete

>

Prompt:

"WAF has been successfully integrated with ECS! You can proceed with the following operations:

>

1. Deploy Web Application: Log in to ECS to deploy your web application, or use sample application for testing

2. Verify Protection Effectiveness: Access ECS public IP to test normal access and attack interception

>

For detailed verification methods, see references/verification-method.md"

>

CRITICAL: After completing the workflow, MUST disable AI-Mode:

```bash

aliyun configure ai-mode disable

```

RAM Permission Requirements

For detailed permission list, see references/ram-policies.md

CLI Support Status

All cloud service operations involved in this skill (VPC, ECS, WAF) support CLI implementation.

Console Operation Required: When using WAF for the first time, need to click "Create Service Linked Role" in the console to complete authorization.

For detailed API and CLI command list, see references/related-apis.md

References

• CLI Installation Guide | RAM Policies | Related APIs
• Verification Methods | Acceptance Criteria | Official Solution Document

Acceptance Criteria: alibabacloud-waf-quick-showcase

Scenario: 使用WAF防护ECS上的Web应用 Purpose: Skill测试验收标准

---

Correct CLI Command Patterns

1. Product — 验证产品名称存在

VPC 产品

# ✅ CORRECT
aliyun vpc --help
# 应显示vpc命令的帮助信息

# ❌ INCORRECT
aliyun VPC --help  # 产品名应为小写

ECS 产品

# ✅ CORRECT
aliyun ecs --help
# 应显示ecs命令的帮助信息

2. Command — 验证操作存在于产品下

VPC 命令

# ✅ CORRECT - 使用plugin模式（小写连字符）
aliyun vpc create-vpc --help
aliyun vpc create-vswitch --help
aliyun vpc describe-vpcs --help
aliyun vpc delete-vpc --help

# ❌ INCORRECT - 使用传统API格式
aliyun vpc CreateVpc --help  # 应使用 create-vpc

ECS 命令

# ✅ CORRECT
aliyun ecs create-security-group --help
aliyun ecs authorize-security-group --help
aliyun ecs run-instances --help
aliyun ecs describe-instances --help

# ❌ INCORRECT
aliyun ecs CreateSecurityGroup --help  # 应使用 create-security-group

3. Parameters — 验证每个参数存在

create-vpc 参数

# 验证参数
aliyun vpc create-vpc --help
# 确认以下参数存在:
# --cidr-block
# --vpc-name
# --biz-region-id
# --description

create-vswitch 参数

aliyun vpc create-vswitch --help
# 确认以下参数存在:
# --vpc-id
# --zone-id
# --cidr-block
# --vswitch-name

create-security-group 参数

aliyun ecs create-security-group --help
# 确认以下参数存在:
# --vpc-id
# --security-group-name
# --biz-region-id
# --description
# --security-group-type

authorize-security-group 参数

aliyun ecs authorize-security-group --help
# 确认以下参数存在:
# --security-group-id
# --permissions
# --biz-region-id

run-instances 参数

aliyun ecs run-instances --help
# 确认以下参数存在:
# --biz-region-id
# --instance-type
# --image-id
# --security-group-id
# --vswitch-id
# --instance-name
# --internet-charge-type
# --internet-max-bandwidth-out
# --system-disk-size
# --system-disk-category
# --password
# --amount

4. User-Agent Flag — 必须包含

# ✅ CORRECT - 每个命令必须包含 --user-agent
aliyun vpc create-vpc \
  --biz-region-id cn-hangzhou \
  --cidr-block 192.168.0.0/16 \
  --vpc-name my-vpc \
  --user-agent AlibabaCloud-Agent-Skills

# ❌ INCORRECT - 缺少 --user-agent
aliyun vpc create-vpc \
  --biz-region-id cn-hangzhou \
  --cidr-block 192.168.0.0/16 \
  --vpc-name my-vpc

---

Common SDK Code Patterns (if applicable)

1. Import Patterns

✅ CORRECT

from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_openapi_util.client import Client as OpenApiUtilClient  # Required for RPC

❌ INCORRECT

# 错误的导入路径
from alibabacloud_openapi.client import Client  # 不存在此模块
from aliyun.sdk import Client  # 旧版SDK，不推荐

2. Authentication — 必须使用CredentialClient

✅ CORRECT

# 使用CredentialClient自动获取凭证
credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'
client = OpenApiClient(config)

❌ INCORRECT

# 硬编码AK/SK
config = open_api_models.Config()
config.access_key_id = 'LTAI5tXXXXXXXX'  # 安全风险!
config.access_key_secret = '8dXXXXXXXXXXX'  # 安全风险!

3. API Style — RPC vs ROA

✅ CORRECT - RPC Style (ECS/VPC)

params = open_api_models.Params(
    action='CreateVpc',
    version='2016-04-28',
    protocol='HTTPS',
    method='POST',
    auth_type='AK',
    style='RPC',
    pathname='/',  # RPC style always uses '/'
    req_body_type='json',
    body_type='json'
)

# RPC使用query参数
queries = {
    'RegionId': 'cn-hangzhou',
    'CidrBlock': '192.168.0.0/16',
    'VpcName': 'my-vpc'
}
request = open_api_models.OpenApiRequest(
    query=OpenApiUtilClient.query(queries)
)

❌ INCORRECT

# RPC不应使用body参数
request = open_api_models.OpenApiRequest(
    body={'RegionId': 'cn-hangzhou'}  # 错误！RPC应使用query
)

---

Validation Checklist

• [ ] 所有CLI命令使用plugin模式格式（小写连字符）
• [ ] 所有CLI命令包含 --user-agent AlibabaCloud-Agent-Skills
• [ ] 所有参数名称正确（已通过 --help 验证）
• [ ] SDK代码使用 CredentialClient，未硬编码凭证
• [ ] SDK代码正确区分 RPC/ROA 风格
• [ ] 所有用户可定制参数在执行前需确认

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget --connect-timeout=10 --read-timeout=60 https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget --connect-timeout=10 --read-timeout=60 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget --connect-timeout=10 --read-timeout=60 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget --connect-timeout=10 --read-timeout=60 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

安全警告 / SECURITY WARNING

>

本技能严禁显式处理 AK/SK 凭证，应依赖默认凭证链。

仅支持 OAuth 认证模式，无需管理 AccessKey。

>

This skill prohibits explicit handling of AK/SK credentials.

Only OAuth authentication mode is supported - no AccessKey management required.

Quick Start (OAuth Mode - Required)

# OAuth 模式登录（唯一支持的模式）
aliyun configure --mode OAuth

ECS RAM Role Mode (For ECS Instances)

如果在 ECS 实例上运行，可以使用实例 RAM 角色，无需任何凭证：

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

要求：必须在绑定了 RAM 角色的 ECS 实例上运行。

Verification

Test Authentication

# 检查认证状态
aliyun configure list

# 基本测试 - 列出地域
aliyun ecs describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• Forbidden.RAM - Insufficient permissions
• OAuth token expired - Re-run aliyun configure --mode OAuth

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use OAuth Mode (Required for This Skill)

aliyun configure --mode OAuth

2. Use RAM Users (Not Root Account)

✔️ Do: Create RAM users with specific permissions ✔️ Do: Use OAuth login for RAM users

3. Principle of Least Privilege

Grant only the minimum permissions needed in RAM Console.

4. Use ECS RAM Roles When Running on ECS

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

5. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure list

# Re-authenticate with OAuth
aliyun configure --mode OAuth

# Test with debug
aliyun ecs describe-regions --log-level=debug --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions in RAM console
# Attach necessary policies
# Example: AliyunECSFullAccess for ECS operations

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Permissions Required

Summary Table

RAM Policy Document

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc:CreateVpc",
        "vpc:DescribeVpcs",
        "vpc:CreateVSwitch",
        "vpc:DescribeVSwitches"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSecurityGroup",
        "ecs:AuthorizeSecurityGroup",
        "ecs:DescribeSecurityGroups",
        "ecs:RunInstances",
        "ecs:DescribeInstances"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "waf:CreatePostpaidInstance",
        "waf:DescribeInstance",
        "waf:SyncProductInstance",
        "waf:DescribeProductInstances",
        "waf:CreateCloudResource",
        "waf:DescribeCloudResources"
      ],
      "Resource": "*"
    }
  ]
}

系统策略（不推荐 - 权限过大）

⚠️ 安全警告：FullAccess 系统策略包含所有产品 Action

>

以下系统策略虽然可以使用，但违背最小权限原则，存在安全风险：

- AliyunVPCFullAccess: 包含 VPC 所有操作（创建、删除、修改等全部权限）

- AliyunECSFullAccess: 包含 ECS 所有操作（包括释放实例、磁盘等危险操作）

- AliyunYundunWAFFullAccess: 包含 WAF 所有操作（包括释放实例、删除配置等）

>

强烈建议: 使用上方自定义 RAM Policy，仅授予必要的 15 个权限。

>

如果确实需要使用系统策略，请确保：

1. 仅在测试环境或临时场景下使用

2. 定期审计这些账号的操作日志

3. 不要将 AK/SK 用于生产环境

4. 了解 FullAccess 权限可能被滥用的风险

~~如果不想手动配置权限，可以绑定以下系统策略:~~

~~| 产品 | 系统策略名称 | 说明 |~~ ~~|------|------------|------|~~ ~~| VPC | AliyunVPCFullAccess | VPC 完整权限 |~~ ~~| ECS | AliyunECSFullAccess | ECS 完整权限 |~~ ~~| WAF | AliyunYundunWAFFullAccess | WAF 完整权限 |~~

Best Practices

1. 最小权限原则: 仅授予必要的权限，避免使用 FullAccess 系统策略 2. 资源范围限定: 在生产环境中，建议将 Resource 限定为具体的资源 ARN 3. 定期审计: 定期检查和清理不再使用的权限 4. 使用 STS 临时凭证: 对于临时任务，建议使用 STS Token 而非永久 AK 5. 权限分离: 开发和测试环境使用不同的 RAM 角色，避免权限混用

Related APIs

本技能涉及的所有CLI命令和API列表。

VPC 相关

ECS 相关

WAF 3.0 相关

官方文档链接

• VPC API参考
• ECS API参考
• WAF 3.0 API参考

Success Verification Method

场景目标验证

预期结果: 完成VPC网络环境搭建、ECS实例创建、Web应用部署，并通过WAF进行安全防护。

分步验证

Step 1: 验证VPC和网络环境

# 验证VPC创建成功且状态为Available
aliyun vpc describe-vpcs \
  --biz-region-id cn-hangzhou \
  --vpc-id <VpcId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 预期输出应包含:
# "Status": "Available"

成功标志: VPC状态为 Available

# 验证VSwitch创建成功且状态为Available
aliyun vpc describe-vswitches \
  --biz-region-id cn-hangzhou \
  --vswitch-id <VSwitchId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 预期输出应包含:
# "Status": "Available"

成功标志: VSwitch状态为 Available

Step 2: 验证安全组配置

# 验证安全组存在
aliyun ecs describe-security-groups \
  --biz-region-id cn-hangzhou \
  --security-group-id <SecurityGroupId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 验证安全组规则（80端口已开放）
aliyun ecs describe-security-group-attribute \
  --biz-region-id cn-hangzhou \
  --security-group-id <SecurityGroupId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

成功标志:

• 安全组存在
• 入方向规则包含 TCP 80端口

Step 3: 验证ECS实例

# 验证ECS实例状态为Running
aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["<InstanceId>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 预期输出应包含:
# "Status": "Running"
# "PublicIpAddress": {"IpAddress": ["x.x.x.x"]}

成功标志:

• 实例状态为 Running
• 已分配公网IP地址

Step 4: 验证Web应用部署

# 获取ECS公网IP
ECS_IP=$(aliyun ecs describe-instances \
  --biz-region-id cn-hangzhou \
  --instance-ids '["<InstanceId>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq -r '.Instances.Instance[0].PublicIpAddress.IpAddress[0]')

# 验证Web应用可访问
curl --connect-timeout 5 --max-time 10 -I "http://${ECS_IP}/"

成功标志:

• HTTP响应状态码为 200
• 能够正常访问Web页面

Step 5: 验证WAF接入

# 查询WAF实例信息
aliyun waf-openapi describe-instance \
  --region-id cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 查询已接入WAF的ECS实例
aliyun waf-openapi describe-cloud-resources \
  --instance-id <WAF-InstanceId> \
  --resource-product ecs \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

# 预期输出应包含接入的ECS实例信息

成功标志:

• WAF实例状态正常
• 已接入的云产品列表中包含目标ECS实例

也可以通过控制台验证:

1. 登录 WAF控制台 2. 进入 接入管理 > 云产品接入 > 云服务器ECS 3. 检查ECS实例的"防护状态"是否显示为"已接入"

完整验证脚本

#!/bin/bash

# 设置变量（请替换为实际值）
REGION="cn-hangzhou"
VPC_ID="<your-vpc-id>"
VSWITCH_ID="<your-vswitch-id>"
SG_ID="<your-security-group-id>"
INSTANCE_ID="<your-ecs-instance-id>"
WAF_INSTANCE_ID="<your-waf-instance-id>"

echo "=== 验证VPC状态 ==="
aliyun vpc describe-vpcs --biz-region-id $REGION --vpc-id $VPC_ID --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq '.Vpcs.Vpc[0].Status'

echo "=== 验证VSwitch状态 ==="
aliyun vpc describe-vswitches --biz-region-id $REGION --vswitch-id $VSWITCH_ID --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq '.VSwitches.VSwitch[0].Status'

echo "=== 验证ECS状态 ==="
aliyun ecs describe-instances --biz-region-id $REGION --instance-ids "[\"$INSTANCE_ID\"]" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq '.Instances.Instance[0].Status'

echo "=== 获取ECS公网IP ==="
ECS_IP=$(aliyun ecs describe-instances --biz-region-id $REGION --instance-ids "[\"$INSTANCE_ID\"]" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq -r '.Instances.Instance[0].PublicIpAddress.IpAddress[0]')
echo "ECS公网IP: $ECS_IP"

echo "=== 验证Web应用 ==="
curl --connect-timeout 5 --max-time 10 -I "http://${ECS_IP}/" 2>/dev/null | head -1

echo "=== 验证WAF实例 ==="
aliyun waf-openapi describe-instance --region-id $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq '.InstanceId'

echo "=== 验证ECS已接入WAF ==="
aliyun waf-openapi describe-cloud-resources --instance-id $WAF_INSTANCE_ID --resource-product ecs --page-number 1 --page-size 10 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase | jq '.CloudResources'

echo "=== 验证完成 ==="

常见问题排查