alibabacloud-waf-bot-management

What this skill does

# WAF Bot Management Automated Configuration Assistant

## Prerequisites

### Alibaba Cloud CLI

Alibaba Cloud CLI (aliyun) must be installed and configured. Credentials must be obtained through the default credential chain; hardcoding AK/SK in scripts is prohibited.

```bash
# 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"
```

If the CLI is not installed or credentials are invalid, direct the user to: https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3

### WAF Instance

The user must have purchased a WAF 3.0 instance (Enterprise edition or above), and the Bot Management module must be enabled (Bot Management is a WAF add-on module and must be purchased separately).

### AI-Mode Configuration

This skill uses the aliyun CLI for all operations. AI-Mode lifecycle management commands:

```bash
# 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
```

Current state: AI-Mode must be enabled before executing any `aliyun waf-openapi` commands. All business CLI commands below include the `--user-agent` flag for traceability. System commands (e.g., `--help`, `configure`) do not set user-agent.

---

## Input Collection

Use AskUserQuestion to collect the following information. Any missing items must be followed up on:

### Required Items

1. **Industry Scenario**: LLM/API Service | Retail E-commerce/Promotion | General Anti-Crawling | Academic Research Platform
2. **Protected Domains**: At least one domain that needs protection
3. **Access Method**: CNAME | ALB Cloud Product Access | Hybrid Cloud | Not sure (can be queried via API)

### Scenario-Specific Follow-Up Questions

- **LLM Scenario**: API endpoint path prefix (e.g., /api/v1/), whether there is a mobile app, daily average API call volume
- **Retail Scenario**: Whether there are promotion time windows (date + time period), whether there is an app/mini-program, whether there are flash-sale/seckill scenarios
- **Academic Research Scenario**: Whether users access from cloud provider VMs, whether Python/script-based API calls are allowed
- **General Scenario**: Current attack symptoms (bandwidth saturation / data scraping / SMS bombing / other)

### Optional Items

- WAF instance region (default: cn-hangzhou)
- Whether there are compliance restrictions (e.g., cannot show CAPTCHA, cannot block by region)
- Whether specific legitimate crawlers need to be protected (e.g., search engine spiders)

---

## Execution Workflow

### Step 1: Current State Assessment (CLI Automation)

Query the current WAF instance and Bot Management configuration status via API, and output an assessment report.

```bash
# 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"
```

**Assessment Checklist Output** (verify each item):
- [ ] WAF instance status is normal, Bot Management module is enabled
- [ ] Protected domains are onboarded to WAF (CNAME or cloud product access)
- [ ] Protected objects are created and associated
- [ ] Log service is enabled (required for subsequent verification)
- [ ] Bot collection fields are added to logs and indexing is enabled

If the Bot module is not enabled or domains are not onboarded, output operational guidance and pause. Wait for the user to confirm completion before continuing.

**Runtime Error Handling** (applies to all CLI calls):

When executing CLI commands in Step 1/3/4, handle errors as follows:

| Error Code | Meaning | Resolution |
|------------|---------|------------|
| command not found | CLI not installed | Pause the workflow. Direct the user to https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3 to install the CLI, or run `brew install aliyun-cli` (macOS) |
| InvalidAccessKeyId / Forbidden.RAM | Insufficient permissions | Pause the workflow. Ask the user to verify the RAM policy includes `AliyunWAFReadWriteAccess` |
| InvalidSecurityToken.Expired | STS Token expired | Ask the user to run `aliyun configure` to refresh credentials and retry |
| Throttling / Throttling.User | API rate limited | Wait 5 seconds and retry, up to 3 retries with increasing intervals (5s/10s/15s) |
| InternalError | Server-side error | Wait 10 seconds and retry once. If still failing, pause and report completed steps |
| InvalidParameter | Parameter error | Verify InstanceId and region are correct. Do not auto-retry |

**Rollback Strategy**: If some rules fail to create during Step 3, successfully created rules will not be automatically rolled back. Output the list of created rule IDs and advise the user to manually run `delete-defense-rule` to clean up, or wait until all rules are confirmed before enabling the template (Step 3.4 executes last).

**SDK Integration Checklist** (three critical pitfalls to proactively remind about):
1. Web clients must integrate the Web SDK; otherwise, all four soft-block actions (JS challenge, dynamic token, slider, strict slider) will fail
2. Static files (js/css/images) cannot have the Web SDK injected; only built-in Bot detection rules + slider can be used
3. When APP and Web share the same domain, the APP must integrate the SDK; otherwise, JS challenges will fail due to the lack of a JS environment, impacting business

For detailed SDK integration steps, see `references/sdk-integration-guide.md`.

---

### Step 2: Scenario-Based Rule Recommendation

Based on the user's selected scenario, load the corresponding configuration plan:

| Scenario | Reference Document | Core Protection Targets |
|----------|-------------------|------------------------|
| LLM/API Service | `references/scene-llm-api.md` | LLM API endpoints |
| Retail E-commerce/Promotion | `references/scene-retail-promotion.md` | Login page / Order page / Product page / Pricing API |
| General Anti-Crawling | `references/scene-anti-crawl.md` | All web pages |
| Academic Research Platform | `references/scene-academic.md` | API endpoints + Web pages |

Each scenario document includes: recommended rule labels to enable, rules not recommended for enabling with reasons, action selection, rate-limit threshold references, and special considerations.

**Universal Rules**: All scenarios must reference `references/rules-blacklist.md` (list of rules not recommended for enabling) and `references/attack-level-matrix.md` (attack level matching matrix).

---

### Step 3: CLI Automated Configuration

Based on the scenario recommendations from Step 2, automatically create protection templates and rules via C