alibabacloud-waf-bot-management

WAF Bot 管理自动化配置助手

前置条件

Alibaba Cloud CLI

必须安装并配置 Alibaba Cloud CLI（aliyun）。必须通过默认凭证链获取凭证；禁止在脚本中硬编码 AK/SK。

# Verify CLI is available
aliyun version
# Verify credentials are valid
aliyun waf-openapi describe-instance --region cn-hangzhou \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

如果未安装 CLI 或凭证无效，请引导用户访问：https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3

WAF 实例

用户必须已购买 WAF 3.0 实例（企业版或更高版本），并启用 Bot 管理模块（Bot 管理是 WAF 的附加模块，必须单独购买）。

AI-Mode 配置

此技能使用 aliyun CLI 执行所有操作。AI-Mode 生命周期管理命令：

# Enable AI-Mode
aliyun configure ai-mode enable

# Set User-Agent
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Disable AI-Mode
aliyun configure ai-mode disable

# Update plugin
aliyun plugin update

当前状态：必须先启用 AI-Mode，才能执行任何 aliyun waf-openapi 命令。以下所有业务 CLI 命令均包含 --user-agent 标记，以便追踪。系统命令（例如 --help、configure）不设置 user-agent。

---

信息收集

使用 AskUserQuestion 收集以下信息。对于任何缺失的信息，都必须进行追问：

必填项

1. 行业场景：大模型/API 服务 | 零售电商/促销 | 通用反爬虫 | 学术研究平台
2. 受保护域名：至少提供一个需要保护的域名
3. 接入方式：CNAME | ALB 云产品接入 | 混合云 | 不确定（可通过 API 查询）

按场景追问的问题

• 大模型场景：API 端点路径前缀（例如 /api/v1/）、是否有移动应用、每日平均 API 调用量
• 零售场景：是否有促销时段（日期 + 时间段）、是否有应用/小程序、是否有闪购/秒杀场景
• 学术研究场景：用户是否从云服务商 VM 访问、是否允许基于 Python/脚本的 API 调用
• 通用场景：当前攻击症状（带宽饱和 / 数据抓取 / 短信轰炸 / 其他）

可选项

• WAF 实例地域（默认：cn-hangzhou）
• 是否有合规限制（例如，不能显示 CAPTCHA、不能按地域拦截）
• 是否需要保护特定的合法爬虫（例如，搜索引擎蜘蛛）

---

执行工作流

步骤 1：当前状态评估（CLI 自动化）

通过 API 查询当前 WAF 实例和 Bot Management 配置状态，并输出评估报告。

# 1.1 Query WAF instance information
aliyun waf-openapi describe-instance --region {region} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.2 Query existing protection template list
aliyun waf-openapi describe-defense-templates --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.3 Query Bot Management rule label information
aliyun waf-openapi describe-bot-rule-labels --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.4 Query log service status
aliyun waf-openapi describe-user-waf-log-status --region {region} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.5 Query protected object list
aliyun waf-openapi describe-defense-resources --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.6 Query CNAME access domain list (confirm protected domains are onboarded)
aliyun waf-openapi describe-domains --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

评估清单输出（逐项核验）：

• WAF 实例状态正常，Bot Management 模块已启用
• 受保护域名已接入 WAF（通过 CNAME 或云产品接入）
• 已创建并关联受保护对象
• 日志服务已启用（后续核验所必需）
• 已将 Bot 采集字段添加到日志，并启用索引

如果未启用 Bot 模块或域名尚未接入，请输出操作指引并暂停。等待用户确认完成后再继续。

运行时错误处理（适用于所有 CLI 调用）：

执行步骤 1/3/4 中的 CLI 命令时，按以下方式处理错误：

错误代码	含义	解决方法
command not found	未安装 CLI	暂停工作流。指引用户访问 https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3 安装 CLI，或运行 brew install aliyun-cli（macOS）
InvalidAccessKeyId / Forbidden.RAM	权限不足	暂停工作流。请用户确认 RAM 策略包含 AliyunWAFReadWriteAccess
InvalidSecurityToken.Expired	STS Token 已过期	请用户运行 aliyun configure 刷新凭证后重试
Throttling / Throttling.User	API 请求频率受限	等待 5 秒后重试，最多重试 3 次，间隔依次递增（5s/10s/15s）
InternalError	服务端错误	等待 10 秒后重试一次。如果仍然失败，请暂停并报告已完成的步骤
InvalidParameter	参数错误	确认 InstanceId 和区域是否正确。不要自动重试

回滚策略：如果步骤 3 中有部分规则创建失败，已成功创建的规则不会自动回滚。请输出已创建的规则 ID 列表，并建议用户手动运行 delete-defense-rule 清理，或等待确认所有规则均已创建后再启用模板（步骤 3.4 最后执行）。

SDK 集成清单（主动提醒以下三个关键注意事项）：

1. Web 客户端必须集成 Web SDK，否则四种软拦截操作（JS challenge、动态令牌、滑块、严格滑块）都会失效
2. 静态文件（js/css/images）无法注入 Web SDK；只能使用内置 Bot 检测规则和滑块
3. 当 APP 和 Web 共用同一域名时，APP 必须集成 SDK；否则，由于缺少 JS 环境，JS challenge 会失败并影响业务

有关详细的 SDK 集成步骤，请参阅 references/sdk-integration-guide.md。

---

步骤 2：基于场景的规则建议

根据用户选择的场景，加载相应的配置方案：

场景	参考文档	核心防护目标
LLM/API 服务	references/scene-llm-api.md	LLM API 端点
零售电商/促销	references/scene-retail-promotion.md	登录页 / 订单页 / 商品页 / 定价 API
通用反爬虫	references/scene-anti-crawl.md	所有网页
学术研究平台	references/scene-academic.md	API 端点 + 网页

每份场景文档均包含：建议启用的规则标签、不建议启用的规则及原因、操作选择、限速阈值参考和特别注意事项。

通用规则：所有场景都必须参考 references/rules-blacklist.md（不建议启用的规则列表）和 references/attack-level-matrix.md（攻击等级匹配矩阵）。

---

步骤 3：CLI 自动配置

根据步骤 2 的场景建议，通过 CLI 自动创建防护模板和规则。

3.0 配置白名单（优先执行）

创建防护规则前，请将可信 IP 添加到白名单，以避免对内部监控和合法服务产生误报：

# Query existing address books
aliyun waf-openapi describe-addresses --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Add trusted IPs to whitelist (can be executed multiple times)
aliyun waf-openapi add-address \
  --region {region} \
  --InstanceId {instance_id} \
  --AddressList '["{trusted_ip_1}","{trusted_ip_2}"]' \
  --AddressType "ipv4" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

白名单 IP 来源：用户提供的内部监控 IP、CI/CD 出口 IP、合作伙伴固定 IP、客户自有云资源 IP 范围。

3.1 创建防护模板

aliyun waf-openapi create-defense-template \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateName "{scenario_name}_Bot_Protection" \
  --DefenseScene "antibot" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

3.2 创建防护规则

根据场景推荐的规则标签，逐一创建规则。每条规则都需要：

• DefenseScene：防护场景（antibot）
• RuleName：规则名称
• RuleContent：匹配条件（标签、限速阈值等）
• Action：处置动作（block/captcha/captcha_strict/js/sigchl/monitor/bypass）

# Example: Create crawler client detection rule (action = block)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "Crawler_Client_Block" \
  --RuleContent '{"bot_labels":["malicious_crawler_python","malicious_crawler_java"],"action":"block"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Example: Create IP rate-limit rule (requests > 30 in 60 seconds -> JS challenge)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "IP_High_Frequency_Rate_Limit" \
  --RuleContent '{"stat_object":"ip","interval":60,"threshold":30,"action":"js","rule_type":"frequency"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

3.3 绑定受保护对象

aliyun waf-openapi modify-template-resources \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --ResourceMode "bind" \
  --ResourceList '["{resource_id_1}","{resource_id_2}"]' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

获取 resource_id：从 Step 1.5 中 describe-defense-resources 响应的 ResourceId 字段提取。如果 Step 1 中没有找到受保护对象，请先通过 create-defense-resource 创建一个。

3.4 启用防护模板

aliyun waf-openapi modify-defense-template-status \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --Status "enabled" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

灰度部署建议：首次配置时，将所有处置动作设为 monitor（仅观察，不拦截）。运行一段时间并查看命中数据。确认没有误报后，再切换为正式处置动作。各场景建议的灰度周期：LLM/零售场景 24-48 小时，常规反爬场景 24-48 小时，学术研究场景 7-14 天（用户模式多样，需要更长的观察周期）。

灰度切换 SOP（monitor -> 正式动作）：

1. 通过 describe-rule-hits-top-rule-id 和 describe-rule-hits-top-client-ip 查看灰度期间的命中数据
2. 检查任何被标记的 Top IP/UA 是否为合法用户（与 SLS 日志交叉验证）
3. 确认没有误报后，逐一修改规则动作：

# Switch a single rule from monitor to formal action (e.g., captcha)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "captcha" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

4. 每切换一条规则后，观察 4 小时。确认没有异常后，再切换下一条规则
5. 如果目标动作是 block，建议先切换为 captcha 并观察 4 小时，再升级为 block：

# captcha -> block upgrade (execute only after confirming captcha has no false positives)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "block" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

6. 完成所有切换后，通过 describe-defense-rules 确认所有规则状态

3.5 配置验证

每条规则创建后，查询并验证：

aliyun waf-openapi describe-defense-rules \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

---

步骤 4：CLI 自动化验证

配置完成并运行一段时间后（建议至少 1 小时），通过 API 查询防护效果。

# 4.1 Query Top 10 rule hits
aliyun waf-openapi describe-rule-hits-top-rule-id \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.2 Query Top 10 attack source IPs
aliyun waf-openapi describe-rule-hits-top-client-ip \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.3 Query attack traffic time series
aliyun waf-openapi describe-security-event-time-series-metric \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.4 Query Top traffic URLs
aliyun waf-openapi describe-flow-top-url \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.5 Query Top UAs hitting rules
aliyun waf-openapi describe-rule-hits-top-ua \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

如需进行更细致的日志分析（例如检测单设备多账号切换），请使用 SLS 查询。模板见 references/sls-query-templates.md。

---

步骤 5：效果评估与调优

根据步骤 4 的数据，输出评估报告：

拦截率评估：

• 目标拦截率 > 85%（实际参考范围：85%-95%）
• 如果拦截率过低，请检查规则是否覆盖了主要攻击特征
• 如果拦截率过高（>98%），请检查是否存在误报

误报风险评估：

• 检查是否有被拦截的 Top IP/UA 属于合法用户
• 参阅 references/rules-blacklist.md，确认未启用不应启用的规则

调优操作（CLI 命令）：

# 5.1 Adjust rule disposition action (e.g., if a rule has a high false positive rate, switch to observe mode)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "monitor" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.2 Disable false-positive rule
aliyun waf-openapi modify-defense-rule-status \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Status "disabled" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.3 Add targeted rule (based on newly discovered attack signatures)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "{new_rule_name}" \
  --RuleContent '{...}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.4 Adjust rate-limit threshold (modify existing frequency control rule)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --RuleContent '{"stat_object":"ip","interval":60,"threshold":50,"action":"captcha","rule_type":"frequency"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

调优建议：

• 阈值调整：根据正常业务基线调整限速阈值
• 动作调整：将观察期间确认存在误报的规则切换为 monitor 或禁用
• 新增规则：根据新发现的攻击特征添加针对性策略
• SDK 部署：如果尚未部署 SDK，强烈建议部署以获得最佳防护效果

---

动作选择原则（通用）

规则类型	推荐动作	原因
IDC 情报 / 请求序列 / 威胁情报	验证码（滑块）	合法用户可以通过验证
AI 爬虫 / 伪造蜘蛛 / 已知恶意工具	拦截	明确具有恶意，无需提供验证
脚本客户端（Python/Java/Go 等）	拦截或验证码	取决于具体场景；学术平台可能存在合法脚本
IP/设备/账号高频限流	js（JS 挑战）或验证码	普通浏览器可以自动通过
设备伪装检测	验证码	防止误伤合法用户
浏览器探测	验证码	检测开发者工具/模拟器

滑块类型区别：

• 标准滑块（captcha）：通过验证后，30 分钟内无需再次验证（基于 Cookie）。适用于登录页面
• 严格滑块（captcha_strict）：每次都进行验证。适用于订单页面/支付页面等关键操作

---

输出格式

每次执行后，输出一份包含以下内容的 Markdown 报告：

1. 当前状态评估摘要：实例状态、已配置规则数量、SDK 部署状态
2. 配置变更日志：列出本次会话中创建/修改的规则（规则名称、处置动作、生效范围）
3. 防护效果数据：拦截率、命中次数最多的规则、攻击 IP 排名
4. 调优建议：后续优化建议
5. 重要说明：SDK 部署提醒、不建议启用的规则

---

参考文档索引

文件	内容	使用场景
references/bot2-rules-reference.md	BOT2.0 完整规则标签参考	配置规则时查询标签名称和默认状态
references/sdk-integration-guide.md	Web/App SDK 集成指南	第 1 步：检查 SDK 部署
references/scene-llm-api.md	大模型 API 场景配置手册	第 2 步：场景建议
references/scene-retail-promotion.md	零售促销场景配置手册	第 2 步：场景建议
references/scene-anti-crawl.md	通用反爬虫场景配置手册	第 2 步：场景建议
references/scene-academic.md	学术研究场景配置手册	第 2 步：场景建议
references/sls-query-templates.md	SLS 查询模板库	第 4 步：深入分析日志
references/attack-level-matrix.md	攻击级别 × 防护策略矩阵	第 2 步：评估攻击级别
references/rules-blacklist.md	不建议启用的规则	第 2/3 步：筛选规则
references/openapi-reference.md	WAF Bot 管理 OpenAPI 快速参考	第 3 步：CLI 配置