alibabacloud-waf-quick-showcase

使用 WAF 保护 ECS 上的 Web 应用

借助此技能，你可以快速部署完整的 Web 应用防护解决方案，包括网络环境设置、ECS 实例创建、示例应用部署和 WAF 集成。

前提条件

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 获取安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

[MUST] AI-Mode 配置 — 执行 CLI 命令前必须配置 AI-Mode：

1. 启用 AI-Mode（在执行任何 CLI 命令前）：

   aliyun configure ai-mode enable
   

2. 为 AI-Mode 设置 User-Agent：

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

3. 禁用 AI-Mode（工作流完成后）：

   aliyun configure ai-mode disable
   

[MUST] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-quick-showcase

支持的场景

此技能支持两种使用场景：

1. 快速体验 WAF 防护：从头创建 VPC、ECS 和 WAF，体验完整的防护流程
2. 体验现有 WAF 防护：用户已有 WAF，创建新的 VPC 和 ECS 并接入现有 WAF

禁止的场景：

• 接入现有 ECS：不支持将用户现有的 ECS 接入 WAF

如果用户表示已有 ECS 并希望将其接入 WAF，请回复： “此技能旨在体验完整的 WAF 防护工作流，因此需要创建新的 ECS 实例。如果你希望将现有 ECS 接入 WAF，请参阅 WAF 控制台中的云产品接入功能。”

重要：场景 1 的资源创建规则

如果用户请求“快速体验”（场景 1）：

• VPC：配额充足时新建；配额已满时使用现有 VPC
• 必须新建：VSwitch、安全组、ECS
• WAF 可复用：如果 WAF 已存在，则跳过创建步骤，直接使用现有 WAF 接入 ECS
• 如果创建失败，必须停止并告知用户

必须：场景 1 必须检查是否存在 WAF 实例

确认身份验证后、确认参数前，必须执行：

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

• 如果返回有效的 InstanceId：跳过 WAF 创建步骤，直接使用此 WAF 接入 ECS
• 提示：“检测到你的账号已有 WAF 实例（InstanceId: [xxx]），将使用此实例体验防护。”
• 如果没有 WAF 实例：执行步骤 4 创建新的 WAF

场景 2：体验现有 WAF 防护（详细说明）

重要：用户已有 WAF 时的处理流程

当用户表示已有 WAF 实例时：

1. 询问 WAF 实例 ID：必须先询问用户现有 WAF 实例 ID
2. 跳过 WAF 创建：禁止执行 create-postpaid-instance，直接使用用户提供的 WAF 实例 ID
3. 创建新的网络环境和 ECS：仍需创建 VPC、VSwitch、安全组和 ECS
4. 接入现有 WAF：使用用户的 WAF 实例 ID 执行 sync-product-instance 和 create-cloud-resource

询问提示： “你已有 WAF 实例。请提供 WAF 实例 ID（格式：waf-cn-xxx），我将为你创建新的 ECS，并将其接入现有 WAF 供你体验。”

运行前检查（每次运行前必须提醒用户）

重要：运行前必须主动询问并帮助用户完成以下检查

1. CLI 版本：运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低，请运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新。 然后[必须]运行 aliyun plugin update，确保本地机器上的所有现有插件始终为最新版本。
2. 身份验证配置：运行 aliyun configure list，确认身份验证状态为 Valid
3. 自动安装插件：运行 aliyun configure set --auto-plugin-install true
4. 账户余额：确认阿里云账户余额 >= 100 CNY

身份验证配置检查（必须执行）

aliyun configure list

身份验证有效时的提醒： “检测到您当前的 CLI 身份验证配置有效：

• 身份验证模式：[OAuth/AK/StsToken] | 账户：[配置文件名称] | 区域：[区域]

请确认是否使用当前账户执行操作？操作将产生费用。”

必须：继续操作前等待用户确认

• 禁止：未经用户确认执行任何资源创建操作
• 禁止：任何身份验证模式（包括 StsToken）都必须等待用户确认

身份验证无效时：运行 aliyun configure --mode OAuth 完成配置

安全提醒：严格禁止显式处理 AK/SK 凭据。本技能仅支持 OAuth 身份验证模式。

解决方案架构

架构组件：VPC + VSwitch + 安全组 + ECS + WAF 3.0（按量付费）

流量路径：用户请求 → WAF 3.0（流量过滤与清洗）→ ECS（Web 应用）

安装和配置

详细安装步骤请参阅 references/cli-installation-guide.md

快速开始：

# macOS (Homebrew)
brew install aliyun-cli

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

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

安全提醒：严格禁止显式处理 AK/SK 凭据。本技能仅支持 OAuth 身份验证模式。

参数确认

必须：执行前确认参数

禁止：直接使用默认值执行命令；必须先与用户确认参数。

必须：输入验证规则（必须验证以下格式）

• RegionId：必须匹配 ^[a-z]{2}-[a-z]+-[a-z]\d*$ 格式（例如，cn-hangzhou-j）
• CidrBlock：必须是有效的 CIDR 格式，且位于 RFC1918 私有网络段内（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）
• ZoneId：必须以 RegionId 为前缀（例如，cn-hangzhou-j 对应 cn-hangzhou）
• InstanceType：必须符合阿里云 ECS 规格命名规范（ecs.[series]-[spec]）
• InstancePassword：8-30 个字符，必须包含大写字母、小写字母和数字
• 安全要求：所有参数中禁止包含特殊字符（例如 ; | & $ ` \ 等）

参数确认提示（必须执行）

完成身份验证确认后、执行任何命令之前，必须与用户确认以下参数：

确认提示： “开始部署前，请确认以下参数：

1. 地域：cn-hangzhou（或您偏好的其他地域，例如 cn-shanghai、cn-beijing）
2. VPC CIDR 网段：192.168.0.0/16
3. 可用区：cn-hangzhou-j
4. ECS 规格：ecs.e-c1m2.large
5. ECS 密码：请提供您的 ECS 登录密码（8-30 个字符，包含大写字母、小写字母和数字）

您要使用以上参数吗？或者请告知您想修改哪些参数。”

必须：在用户确认或修改前等待，不得继续操作

• 预期用户回复：“确认”、“是”、“好的”，或提供修改内容
• 禁止：用户确认参数前执行任何资源创建操作
• 禁止：自动生成 ECS 密码；密码必须由用户提供
• 如果用户未提供密码，必须再次询问，不得继续操作
• 如果用户想修改参数，记录修改内容并再次确认

必须：参数验证失败时必须拒绝执行

• 如果用户提供的参数不符合格式要求，必须明确告知用户并提供正确示例
• 禁止：使用无效参数执行命令
• 禁止：转义危险字符后继续执行（应直接拒绝，并要求用户提供合法参数）

必须：返回值和输出脱敏

• 在任何情况下，向用户显示的命令、日志和错误消息中的 --password 参数值都必须显示为 *** 或 [REDACTED]
• CLI 执行回显：如果 CLI 输出包含明文密码，显示给用户前必须替换并脱敏
• 错误消息处理：如果错误消息可能包含密码，显示前必须进行脱敏
• 禁止的行为：
  • 在终端打印包含明文密码的完整命令
  • 在历史记录中保存明文密码
  • 在错误日志中泄露明文密码
• 正确示例：

  # 实际执行的命令（内部）
  aliyun ecs run-instances --password MyPass@2024 ...
  
  # 显示给用户的命令（已脱敏）
  aliyun ecs run-instances --password *** ...
  

必须：执行命令时必须使用用户确认的参数

• 以下命令示例中的 cn-hangzhou、192.168.0.0/16 等仅为参考值
• 禁止：直接复制示例命令执行；必须替换为用户确认的实际值
• 如果用户将地域改为 cn-shanghai，则后续所有命令中的 --biz-region-id、--region、--zone-id 都必须相应修改

参数说明和验证规则

参数	说明	参考值	验证规则
RegionId	地域 ID	cn-hangzhou	格式：^[a-z]{2}-[a-z]+-[a-z]\d*$，仅允许小写字母、连字符和数字
CidrBlock	VPC CIDR 网段	192.168.0.0/16	必须是 RFC1918 私有网段（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16），掩码范围为 /8-/24
ZoneId	可用区 ID	cn-hangzhou-j	必须以 RegionId 为前缀，格式：${RegionId}-${letter}
InstanceType	ECS 规格	ecs.e-c1m2.large	格式：ecs.[series]-[spec]，series 可以是 e、c、g、r、t 等
ImageId	镜像 ID	aliyun_3_x64_20G_alibase_20240819.vhd	必须以 .vhd 结尾，并符合 Alibaba Cloud 镜像命名规范
InstancePassword	ECS 登录密码	用户提供	8-30 个字符，必须同时包含大写字母、小写字母和数字

SHOULD：特殊字符过滤

• 所有参数均禁止包含：; | & $ \ " ' < > ( ) { } [ ] ! # ~`
• 如果检测到上述字符，必须拒绝执行并提示用户重新输入

核心工作流

步骤 0：检查 VPC 配额

CRITICAL：创建 VPC 前必须检查配额（每个账号每个地域默认最多可创建 10 个 VPC）

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

幂等性保护：使用 --client-token 参数，确保多次执行不会创建重复资源。

配额检查结果处理：

• TotalCount < 10：配额充足，创建新的 VPC
• TotalCount >= 10：配额已满，使用现有 VPC

配额已满时的处理流程：

1. 从响应结果中选择一个现有 VPC（优先选择名称包含“waf”或“test”的 VPC）
2. 提示用户：“您的 VPC 配额已满，将使用现有 VPC（VpcId：[xxx]）继续部署。”
3. 在该 VPC 下创建新的 VSwitch、安全组和 ECS

步骤 1：创建 VPC 和 VSwitch

CRITICAL：失败处理和回滚机制

如果任何资源创建失败：

1. 立即停止：不得继续执行后续步骤
2. 告知用户：清楚说明失败原因（例如资源不足、权限不足、配额不足等）
3. 禁止替代：不得使用现有资源替代

失败提示： “抱歉，[VPC/ECS/WAF] 创建失败，原因：[error message]。请检查后重试。”

# 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

步骤 2：创建安全组并配置规则

# 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

步骤 3：创建 ECS 实例

关键：绝对禁止使用现有 ECS 实例

• 必须新建：始终使用 RunInstances 创建新的 ECS 实例
• 禁止：发现并重复使用现有 ECS 实例（例如，“Found multiple existing ECS instances... Selected i-bp1xxx”）
• 禁止：说“我找到了一个名为 ‘web-server-waf-demo’ 的现有 ECS 实例，将使用它”
• 安全策略：即使用户已有 ECS 实例，本技能也必须为 WAF 防护体验创建一个新实例
• 正确做法：
  • ✅ 始终执行 aliyun ecs run-instances 来创建新实例
  • ✅ 为新实例使用用户提供的密码
  • ✅ 如果用户要求使用现有 ECS，请说明：“本技能会创建新资源，以提供完整的 WAF 防护体验”

推荐镜像 ID（避免盲目查询）：

• Alibaba Cloud Linux 3：aliyun_3_x64_20G_alibase_20240819.vhd
• 替代选项：aliyun_3_x64_20G_alibase_20221102.vhd

直接使用上述 ImageId，无需调用 DescribeImages 查询。

必须：对密码进行脱敏处理

• 禁止：在终端输出、日志打印或向用户展示的命令中显示明文密码
• 必须：在显示前，将 --password 参数值替换为 *** 或 [REDACTED]
• 示例：使用 --password ***，而不是 --password MyPass@2024
• 安全要求：仅在传递给 CLI 命令时使用原始密码；任何回显都必须进行脱敏

# 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

步骤 4：启用 WAF 并接入 ECS

⚠️ 接入提醒：接入 WAF 时，Web 服务可能会出现数秒的短暂连接中断。建议在业务低峰时段执行操作。

4.1 创建按量付费的 WAF 实例

# 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

幂等性保护：使用 --client-token 参数，确保多次执行不会创建重复资源。

并发场景处理：如果创建失败，且错误提示“WAF instance already exists”，请执行 describe-instance 查询现有实例，并直接使用该实例。

授权失败处理：

• 如果返回 HTTP 500 或需要授权 → 提示用户前往控制台完成授权
• 提示：“首次使用 WAF 需要在控制台完成服务关联角色授权。请访问 https://yundun.console.aliyun.com/?p=waf 并点击 ‘Create Service Linked Role’ 完成授权。”
• 必须：等待用户回复“Authorization completed”后再重试创建
• 禁止：未经用户确认就反复尝试创建

注意：首次创建 WAF 实例时，需要在控制台完成服务关联角色授权。 如果 CLI 报错提示需要授权，请访问 WAF 控制台，点击 “Create Service Linked Role” 完成授权后再重试。

4.2 查询 WAF 实例信息

# 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 将 ECS 资产同步至 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 将 ECS 接入 WAF 防护

# 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 验证 ECS 是否已接入 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

完成提示

重要：完成 WAF 接入后，必须提示用户进行后续操作

提示： “WAF 已成功接入 ECS！你可以继续进行以下操作：

1. 部署 Web 应用：登录 ECS 部署 Web 应用，或使用示例应用进行测试
2. 验证防护效果：访问 ECS 公网 IP，测试正常访问和攻击拦截

有关详细的验证方法，请参阅 references/verification-method.md”

关键：完成工作流后，必须禁用 AI-Mode：

aliyun configure ai-mode disable

RAM 权限要求

详细权限列表请参阅 references/ram-policies.md

CLI 支持状态

此技能涉及的所有云服务操作（VPC、ECS、WAF）均支持通过 CLI 实现。

需要通过控制台操作：首次使用 WAF 时，需要在控制台中点击“创建服务关联角色”以完成授权。

详细的 API 和 CLI 命令列表请参阅 references/related-apis.md

参考资料

• CLI 安装指南 | RAM 权限策略 | 相关 API
• 验证方法 | 验收标准 | 官方解决方案文档