ClawHub

Alibabacloud Waf Bot Management

Automation

Alibaba Cloud WAF Bot Management automated configuration assistant. Automatically completes bot protection policy evaluation, configuration, verification, and tuning via OpenAPI/CLI. Supports scenarios such as LLM API protection, retail promotion anti-scalper, general anti-crawling, and academic research platforms. Triggers when the user mentions Bot management, crawler protection, anti-crawling, WAF Bot, BOT2.0, LLM API abuse prevention, retail anti-scalper, promotion protection, SMS bombing, script attacks, or automated traffic protection.

Install

openclaw skills install alibabacloud-waf-bot-management

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.

# 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:

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

# 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 CodeMeaningResolution
command not foundCLI not installedPause 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.RAMInsufficient permissionsPause the workflow. Ask the user to verify the RAM policy includes AliyunWAFReadWriteAccess
InvalidSecurityToken.ExpiredSTS Token expiredAsk the user to run aliyun configure to refresh credentials and retry
Throttling / Throttling.UserAPI rate limitedWait 5 seconds and retry, up to 3 retries with increasing intervals (5s/10s/15s)
InternalErrorServer-side errorWait 10 seconds and retry once. If still failing, pause and report completed steps
InvalidParameterParameter errorVerify 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:

ScenarioReference DocumentCore Protection Targets
LLM/API Servicereferences/scene-llm-api.mdLLM API endpoints
Retail E-commerce/Promotionreferences/scene-retail-promotion.mdLogin page / Order page / Product page / Pricing API
General Anti-Crawlingreferences/scene-anti-crawl.mdAll web pages
Academic Research Platformreferences/scene-academic.mdAPI 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 CLI.

3.0 Configure Whitelist (Execute First)

Before creating protection rules, add trusted IPs to the whitelist to avoid false positives on internal monitoring and legitimate services:

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

Whitelist IP sources: internal monitoring IPs provided by the user, CI/CD egress IPs, partner fixed IPs, customer-owned cloud resource IP ranges.

3.1 Create Protection Template

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 Create Protection Rules

Based on the scenario-recommended rule labels, create rules one by one. Each rule requires:

  • DefenseScene: Protection scenario (antibot)
  • RuleName: Rule name
  • RuleContent: Match conditions (labels, rate-limit thresholds, etc.)
  • Action: Disposition 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 Bind Protected Objects

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"

To obtain resource_id: Extract the ResourceId field from the describe-defense-resources response in Step 1.5. If no protected objects were found in Step 1, create one first via create-defense-resource.

3.4 Enable Protection Template

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"

Canary Deployment Recommendation: For initial configuration, set all disposition actions to monitor (observe only, no blocking). Run for a period and review hit data. After confirming no false positives, switch to the formal disposition actions. Recommended canary periods by scenario: LLM/Retail scenarios 24-48 hours, general anti-crawling 24-48 hours, academic research scenarios 7-14 days (diverse user patterns require a longer observation period).

Canary Switch SOP (monitor -> formal action):

  1. Review canary period hit data via describe-rule-hits-top-rule-id and describe-rule-hits-top-client-ip
  2. Check whether any flagged Top IPs/UAs are legitimate users (cross-validate with SLS logs)
  3. After confirming no false positives, modify rule actions one by one:
# 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"
  1. After switching each rule, run for 4 hours of observation. Confirm no anomalies before switching the next rule
  2. If the target action is block, it is recommended to first switch to captcha and observe for 4 hours before upgrading to 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"
  1. After all switches are complete, confirm all rule statuses via describe-defense-rules

3.5 Configuration Verification

After each rule is created, query to verify:

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

Step 4: CLI Automated Verification

After configuration is complete and has run for a period (recommended at least 1 hour), query protection effectiveness via 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"

For more granular log analysis (e.g., single-device multi-account switching detection), use SLS queries. Templates are available in references/sls-query-templates.md.

Step 5: Effectiveness Assessment and Tuning

Based on the data from Step 4, output an assessment report:

Block Rate Assessment:

  • Target block rate > 85% (practical reference range: 85%-95%)
  • If the block rate is too low, check whether rules cover the main attack signatures
  • If the block rate is too high (>98%), check for false positives

False Positive Risk Assessment:

  • Check whether any blocked Top IPs/UAs are legitimate users
  • Refer to references/rules-blacklist.md to confirm no rules are enabled that should not be

Tuning Operations (CLI commands):

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

Tuning Recommendations:

  • Threshold adjustment: Adjust rate-limit thresholds based on normal business baselines
  • Action adjustment: Switch rules confirmed as false positives during observation to monitor or disable them
  • New rules: Add targeted policies based on newly discovered attack signatures
  • SDK deployment: If the SDK is not yet deployed, it is strongly recommended to deploy it for optimal protection

Action Selection Principles (Universal)

Rule TypeRecommended ActionReason
IDC Intelligence / Request Sequence / Threat Intelligencecaptcha (slider)Legitimate users can pass verification
AI Crawlers / Forged Spiders / Known Malicious ToolsblockClearly malicious; no need to offer verification
Script Clients (Python/Java/Go, etc.)block or captchaDepends on scenario; academic platforms may have legitimate scripts
IP/Device/Account High-Frequency Rate Limitingjs (JS challenge) or captchaNormal browsers can pass automatically
Device Spoofing DetectioncaptchaPrevents false positives on legitimate users
Browser ProbecaptchaDetects developer tools/emulators

Slider Type Distinction:

  • Standard slider (captcha): After passing verification, no further verification for 30 minutes (Cookie-based). Suitable for login pages
  • Strict slider (captcha_strict): Verifies every time. Suitable for critical operations such as order pages/payment pages

Output Format

After each execution, output a Markdown report containing:

  1. Current State Assessment Summary: Instance status, number of configured rules, SDK deployment status
  2. Configuration Change Log: List of rules created/modified in this session (rule name, disposition action, effective scope)
  3. Protection Effectiveness Data: Block rate, top hit rules, top attack IPs
  4. Tuning Recommendations: Next optimization suggestions
  5. Important Notes: SDK deployment reminders, rules not recommended for enabling

Reference Document Index

FileContentUsage Scenario
references/bot2-rules-reference.mdBOT2.0 full rule label referenceLook up label names and default states when configuring rules
references/sdk-integration-guide.mdWeb/App SDK integration guideStep 1 SDK deployment check
references/scene-llm-api.mdLLM API scenario configuration manualStep 2 scenario recommendation
references/scene-retail-promotion.mdRetail promotion scenario configuration manualStep 2 scenario recommendation
references/scene-anti-crawl.mdGeneral anti-crawling scenario configuration manualStep 2 scenario recommendation
references/scene-academic.mdAcademic research scenario configuration manualStep 2 scenario recommendation
references/sls-query-templates.mdSLS query template libraryStep 4 deep log analysis
references/attack-level-matrix.mdAttack level x protection strategy matrixStep 2 attack level assessment
references/rules-blacklist.mdRules not recommended for enablingStep 2/3 rule filtering
references/openapi-reference.mdWAF Bot Management OpenAPI quick referenceStep 3 CLI configuration
More in Automation