Web Application Firewall:Bot management (legacy)

• Legacy bot management:

• Bot management (New):

Features

Bot Management provides the following features:

• Bot traffic analysis (Available without enabling Bot Management)

  View API risk data without enabling Bot Management: bot traffic trends, top 20 riskiest clients and IP addresses, and per-object analysis. View bot traffic analysis data.

  To protect at-risk APIs, apply for a free trial or purchase Bot Management. Enable Bot Management.

• Scenario-specific Protection (Available after enabling Bot Management)

  Integrate an SDK and configure scenario-based protection for web and app traffic. Create scenario-specific protection rules for a website and Create scenario-specific protection rules for an application.

  Best for users with high sensitivity to bot traffic.

• Basic Protection (Available after enabling Bot Management)

  Identifies bot traffic through Layer 4 or Layer 7 fingerprinting. No SDK integration required — enable protection with a single click. Create basic protection rules.

  Best for blocking low- to medium-sophistication crawlers with minimal configuration.

Prerequisites

• You have completed Web service provisioning on the Onboarding page.

• To create a scenario-based app protection template, integrate your app with the SDK: Integrate the SDK for Android and Integrate the SDK for iOS.

Machine traffic analysis

1. Log on to the Web Application Firewall 3.0 console. From the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) for the WAF instance.

2. In the navigation pane on the left, choose Protection Config > Bot Management.

3. On the Bot Traffic Analysis tab, view the following data for a specific protected object and time range: Bot Traffic Trend, Top 20 Clients, Top 20 IPs, and Bot Traffic Analysis for Protected Objects.

Enable bot management

1. Log on to the Web Application Firewall 3.0 console. From the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) for the WAF instance.

2. In the navigation pane on the left, choose Protection Config > Bot Management.

3. Enable bot management.

   • Apply for a free trial

     Note

     • You can try bot management for free once if you use the Advanced, Enterprise, or Ultimate edition.

     • The trial lasts 7 days from approval. All trial data is immediately deleted if you do not purchase a paid plan before expiry.

     On the Bot Traffic Analysis tab, click Apply for Trial. On the WAF Bot Management PoC Questionnaire page, enter the required information and click Submit.

     An Alibaba Cloud engineer contacts you within one week. After approval, bot management is automatically enabled.

   • Purchase a paid plan for bot management

     1. On the Bot Traffic Analysis, Scenario-specific Protection, or Basic Protection tab, click Purchase Now.

     2. In the Purchase Now panel, enable Bot Management - Web Protection or Bot Management - App Protection, and complete the payment.

        Note

        • After you enable Bot Management - Web Protection, you can configure basic protection rules and scenario-based rules for web scraping protection.

        • After you enable Bot Management - App Protection, you can configure basic protection rules and scenario-based rules for app scraping protection.

        • To configure basic protection rules and scenario-based rules for both web and app scraping protection, enable both Bot Management - Web Protection and Bot Management - App Protection.

After you enable bot management, you can go to the Bot Traffic Analysis tab. In the Bot Traffic Analysis for Protected Objects area, locate at-risk APIs with high bot traffic and click Configure Protection in the Actions column to create a scenario-based protection policy. Create a scenario-based protection rule for website protection and Create a scenario-based protection rule for app protection.

To block low- to medium-sophistication crawlers, configure basic protection rules on the Basic Protection tab. Create a basic protection rule.

Create a scenario-based protection template

Create a scenario-specific protection template for web or H5 pages accessed through browsers (including H5 pages in apps).

1. Log on to the Web Application Firewall 3.0 console. From the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) for the WAF instance.

2. In the navigation pane on the left, choose Protection Config > Bot Management.

3. On the Scenario-specific Protection tab, click Create Template.

4. In the Configure Scenarios wizard, complete the following settings and click Next.

   Parameter	Description
   Template Name	Enter a name for the template. The name must be 1 to 255 characters in length and can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
   Template Description	Enter a description for the template.
   Service Type	Select Websites. This protects web pages or H5 pages (including H5 pages within apps) that are accessed through a browser.
   Web SDK Integration	Automatic Integration (Recommended) Enhances browser protection and prevents some compatibility issues using a JavaScript-based Web SDK. When enabled, WAF injects the SDK into HTML pages of protected objects. The SDK collects browser information, attack detection data, and user behavior (no sensitive personal data) to detect and block malicious requests. If a request originates from another domain, select the source domain from the Use Intermediate Domain Name drop-down list. For example, if domain B calls a logon API on domain A, select domain B from the Use Intermediate Domain Name drop-down list. Important Automatic integration of the Web SDK is not supported for protected objects integrated with WAF through ALB, MSE, or FC. These objects require manual SDK integration. Manual Integration If automatic integration is unsuitable, use manual integration. Click Obtain SDK to get the script node and place it before all other script nodes on your page to ensure it loads first. Deployment method. Integrate an SDK into a web application.
   Traffic Characteristics	Define target traffic by adding rules based on HTTP request fields. Up to five conditions can be added, joined by AND. Supported fields are listed in Match conditions.

5. On the Configure Protection Rules page, configure the following settings and click Next.

   Parameter	Description
   Risk Identification	Select Business Security and enter the required information. Fraud Detection. After you enable this rule, WAF integrates with the Fraud Detection service to block access from abnormal phone numbers, such as those used by scalpers. This is a pay-as-you-go service billed based on rule hits.
   Legitimate Bot Management	Select Spider Whitelist and choose a whitelist of legitimate search engines. After this rule is enabled, traffic from legitimate crawler IP addresses of the selected search engines is allowed and bypasses all Bot Management checks.
   Bot Characteristic Detection	Simple Script Filtering (JavaScript Challenge) When enabled, WAF performs a JavaScript challenge on clients accessing the protected object, filtering non-browser tools and blocking simple script-based attacks. Advanced Bot Mitigation (Token-Based Challenge) When enabled, WAF verifies the signature of each request and blocks requests that fail verification. Options: Signature Verification Exception (Required): Blocks requests that do not have a signature or have an invalid signature. Signature Timestamp Exception: Blocks requests that have an abnormal signature timestamp. WebDriver Attack: Blocks requests that are identified as WebDriver attacks.
   Bot Behavior Detection	Intelligent Protection After you select Intelligent Protection, you must set the action for detected bot behavior to Monitor, CAPTCHA, or Origin Custom Header. If you select Origin Custom Header, you must also specify the Header Name and Header Content to be added to the request sent to the origin server. When this feature is enabled, the Intelligent Protection engine analyzes and learns from your traffic to automatically generate targeted protection rules or blacklists. Custom Throttling When enabled, you can customize rate limiting to filter high-frequency bot requests and mitigate HTTP flood attacks. IP Address Throttling (Default) If the number of requests from a single IP address exceeds the specified Threshold (Times) within the Statistical Interval (Seconds), WAF applies the specified Action (Monitor, CAPTCHA, or Block) to subsequent requests from that IP address for the duration of the Throttling Interval (Seconds). You can add up to three conditions, which are joined by a logical OR. Custom Session-Based Rate Limiting If the number of requests for a specified Session Type exceeds the Threshold (Times) within the Statistical Interval (Seconds), WAF applies the specified Action (Monitor, CAPTCHA, or Block) to subsequent requests in that session for the duration of the Throttling Interval (Seconds). You can add up to three conditions, which are joined by a logical OR. Supported Session Type values are Custom Header, Custom Parameter, Custom Cookie, and Session.
   Bot Threat Intelligence	Bot Threat Intelligence Library This library contains source IP addresses that have launched multiple malicious scraping attacks against various Alibaba Cloud users over a period of time. You can apply the Monitor, CAPTCHA, or Origin Custom Header action to these IP addresses. If you select Origin Custom Header, you must also specify the Header Name and Header Content. Data Center Blacklist When enabled, if a source IP address is from a selected IP address library, WAF applies the specified action: Monitor, CAPTCHA, Block, or Origin Custom Header. If you select Origin Custom Header, you must also specify the Header Name and Header Content. Note If you access your services from source IP addresses in a public cloud or data center, make sure to add known legitimate calls to an allowlist. Examples include payment callbacks from Alipay or WeChat, and monitoring programs. Fake Crawler When enabled, WAF Block or Origin Custom Header requests with User-Agent headers that impersonate any search engine in the Legitimate Bot Management list. Requests from legitimate client IP addresses of whitelisted search engines are still allowed.

6. On the Configure Effective Scope page, complete the following settings and click Next.

   Parameter	Description
   Apply To	Select the protected objects or protected object groups to which you want to apply the rule. Click the icon to move them to the Selected area.
   Effective Time and Canary Rule	Configure grayscale release and effective period for the selected protection rules. If skipped, Canary Rule is disabled and the rule is Permanently Effective by default. Locate the target rule and click Edit in the Actions column. Configure the grayscale release and effective period. Canary Rule: Configure the percentage of traffic that the rule applies to based on a specific dimension. After you enable Grayscale Release, you must also configure the grayscale Dimension and Canary Release Proportion. The grayscale Dimension include: IP, Custom Header, Custom Parameter, Custom Cookie, and Session. Note Grayscale rules are applied based on the Dimension you set, not randomly to a percentage of all requests. For example, if you select the IP dimension, all requests from an IP address that triggers the grayscale rule will be matched. Effective Mode Permanently Effective (Default): The rule is always in effect when the protection template is enabled. Fixed Schedule: You can set the rule to be effective for a specific period in a specific time zone. Recurring Schedule: You can set the rule to be effective during a specific time period that recurs daily in a specific time zone. You can also select multiple rules to modify their grayscale release and effective mode settings in bulk.

7. In the Verify Protection Effect wizard, test the bot protection rule.

   Test protection actions before publishing to prevent false positives. If the rule is configured correctly, click Skip in the lower-left corner.

   The verification steps are as follows:

   1. Step 1: Enter a public IP address.

      Enter your test device's public IP address (PC or mobile phone). The test applies only to this IP and does not affect your services.

      Important

      Do not use the ipconfig address — it returns an internal IP. Use an online IP query tool to find your public IP address.

   2. Step 2: Select an action.

      This step generates a test rule that applies only to your test IP address to verify the protection actions that you configured on the Configure Protection Rules page. The available actions are JavaScript Validation, Dynamic Token Challenge, CAPTCHA Challenge, and Block Verification.

      In the test action module, click Test. WAF immediately applies the protection policy to the test device and displays a demonstration of the protection effect. Read the explanation carefully.

      After you complete the test, click I Have Completed the Test to proceed. If the test result is abnormal, click Go Back, refer to FAQ for testing bot protection policies, optimize the rule, and then test it again.

Create a scenario-specific protection rule for apps

Create a scenario-specific protection template for native iOS or Android apps (excluding H5 pages within apps).

1. Log on to the Web Application Firewall 3.0 console. From the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) for the WAF instance.

2. In the navigation pane on the left, choose Protection Config > Bot Management.

3. On the Scenario-specific Protection tab, click Create Template.

4. On the Configure Scenarios page, complete the following settings and click Next.

   Parameter	Description
   Template Name	Enter a name for the template. The name must be 1 to 255 characters in length and can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
   Template Description	Enter a description for the template.
   Service Type	Select App. This protects native iOS or Android apps (excluding H5 pages within apps).
   APP SDK Integration	WAF provides an SDK for native apps (Android/iOS). After integration, the SDK collects client risk signals and attaches a security signature to requests. WAF uses this signature to detect and block risky requests. To integrate the app SDK: Submit a ticket to obtain the SDK for your iOS app. Click Obtain and Copy AppKey to get the key that you use to initialize the SDK. Integrate the app SDK. Integrate an SDK into an iOS app.
   Traffic Characteristics	Define target traffic by adding rules based on HTTP request fields. Up to five conditions can be added, joined by AND. Supported fields are listed in Match conditions.

5. On the Configure Protection Rules page, complete the following settings and click Next.

   Parameter	Description
   Risk Identification	Select Business Security and enter the required information. Fraud Detection. After you enable this rule, WAF integrates with the Fraud Detection service to block access from abnormal phone numbers, such as those used by scalpers. This is a pay-as-you-go service billed based on rule hits.
   Bot Characteristic Detection	Detection rules Invalid App Signature (Default, cannot be disabled) WAF detects requests from SDK-integrated apps that have missing or invalid signatures. Custom Signing Field (Optional) When enabled, define a custom signature field by specifying its Field Name in the Cookie, Parameter, or Header. If a signature object's body is too long, empty, or specially encoded, WAF can process the signature content (for example, by hashing) and place it in the custom field for verification. Abnormal Device Behavior Detection When enabled, WAF detects and manages requests from devices with abnormal characteristics, including: Expired Signature, Using Simulator, Using Proxy, Rooted Device, Debugging Mode, Hooking, Multiboxing, Simulated Execution, and Script Tools. Mitigation Action For the configured Bot Characteristic Detection rules, set the mitigation action to Monitor, Block, or Strict CAPTCHA. Advanced Protection Click Advanced Protection to configure the following settings: Secondary Packaging Detection Rule settings When enabled, WAF treats requests from apps not on the legitimate package name and signature whitelist as repackaging attempts. You can configure the legitimate version information: Valid Package Name: Specify the legitimate app package name. Example: example.aliyundoc.com. Signature: Specify the app package signature for verification. If you need signature verification, submit a ticket to contact us. If you do not need to verify the app package signature, leave this field empty. WAF will only verify the specified package name. Important The Signature is not the app certificate signature. You can add up to five legitimate versions. Package names cannot be repeated. The conditions are evaluated with a logical OR. Mitigation action For the configured repackaging detection rule, set the mitigation action to Monitor, Block, CAPTCHA, or Strict CAPTCHA. Custom Rule If the default device characteristic rules are not sufficient, click Create Rule under Custom Rule to configure the following: Match Condition: You can add up to five match conditions. All conditions must be met for the rule to take effect. Click to view supported match fields eeid_is_root: Indicates whether the device has root permissions. eeid_is_proxy: Indicates whether a proxy is used. eeid_is_simulator: Indicates whether an emulator is used. eeid_is_debugged: Indicates whether the app is being debugged. eeid_is_hook: Indicates whether the app is hooked. eeid_is_virtual: Indicates whether app cloning is used. eeid_is_new: Indicates whether it is a new device. eeid_is_wiped: Indicates whether the device is suspected of being flashed. eeid_short_uptime: Indicates whether the device uptime is too short. eeid_abnormal_time: Indicates whether the local time is abnormal. eeid_running_frame_xposed: Indicates whether the Xposed Framework is used. eeid_running_frame_frida: Indicates whether Frida is used. eeid_running_frame_cydia: Indicates whether Cydia is used. eeid_running_frame_fishhook: Indicates whether fishhook is used. eeid_running_frame_va: Indicates whether the VirtualApp framework is used. eeid_running_frame_magisk: Indicates whether Magisk is used. eeid_running_frame_edxposed: Indicates whether the EdXposed framework is used. eeid_umid: The UMID value of the device. appname: The application name. packagename: The package name. appversion: The application version number. version: The WAF SDK version number. brand: The mobile phone brand. model: The mobile phone model. product: The product code. manufacture: The mobile phone manufacturer. hardware: The hardware name. Action: Set the action to Monitor, Block, CAPTCHA, Strict CAPTCHA, or Origin Custom Header. If you select Origin Custom Header, you must also specify the Header Name and Header Content. You can add up to 10 rules. The rules are evaluated with a logical OR.
   Bot Behavior Detection	After selecting Intelligent Protection, configure the mitigation action for detected bot behaviors. You can set the action to Monitor, CAPTCHA, Strict CAPTCHA, or Mark For Origin Fetch. If you select Origin Custom Header, you must also specify the Header Name and Header Content to be added to the request. When this feature is enabled, the Intelligent Protection engine analyzes and learns from your traffic to automatically generate targeted protection rules or blacklists.
   Throttling	When enabled, you can customize access frequency limits to filter high-frequency bot requests and mitigate HTTP flood attacks. IP Address Throttling (Default) (Default) If the number of requests from a single IP address exceeds the specified Threshold (Times) within the Statistical Interval (Seconds), WAF applies the specified Action (Block, Monitor, CAPTCHA, or Strict CAPTCHA) to subsequent requests from that IP address for the duration of the Throttling Interval (Seconds). You can add up to three conditions, which are joined by a logical OR. Device-Based Rate Limiting If the number of requests from a single device exceeds the specified Threshold (Times) within the Statistical Interval (Seconds), WAF applies the specified Action (Block, Monitor, CAPTCHA, or Strict CAPTCHA) to subsequent requests from that device for the duration of the Throttling Interval (Seconds). You can add up to three conditions, which are joined by a logical OR. Custom Session-Based Rate Limiting If the number of requests for a specified Session Type exceeds the Threshold (Times) within the Statistical Interval (Seconds), WAF applies the specified Action (Block, Monitor, CAPTCHA, or Strict CAPTCHA) to subsequent requests in that session for the duration of the Throttling Interval (Seconds). You can add up to three conditions, which are joined by a logical OR. Supported Session Type values are Custom Header, Custom Parameter, Custom Cookie, and Session.
   Bot Threat Intelligence	Bot Threat Intelligence Library This library contains source IP addresses that have launched multiple malicious scraping attacks against various Alibaba Cloud users over a period of time. You can apply the Monitor, CAPTCHA, Strict CAPTCHA, or Origin Custom Header action to these IP addresses. If you select Origin Custom Header, you must also specify the Header Name and Header Content. Data Center Blacklist When enabled, if a source IP address is from a selected IP address library, WAF applies the specified action: Monitor, CAPTCHA, Block, Strict CAPTCHA, or Origin Custom Header. If you select Origin Custom Header, you must also specify the Header Name and Header Content. Note If your services receive traffic from public clouds or data centers, add known legitimate sources to an allowlist. Examples include payment callbacks from Alipay or WeChat, and monitoring programs.

6. On the Configure Effective Scope page, complete the following settings and click Next.

   Parameter	Description
   Apply To	Select the protected objects or protected object groups to which you want to apply the rule. Click the icon to move them to the Selected area.
   Effective Time and Canary Rule	Configure grayscale release and effective period for the selected protection rules. If skipped, Canary Rule is disabled and the rule is Permanently Effective by default. Locate the target rule and click Edit in the Actions column. Configure the grayscale release and effective period. Canary Rule: Configure the percentage of traffic that the rule applies to based on a specific dimension. After you enable Grayscale Release, you must also configure the grayscale Dimension and Canary Release Proportion. The grayscale Dimension include: IP, Custom Header, Custom Parameter, Custom Cookie, and Session. Note Grayscale rules are applied based on the Dimension you set, not randomly to a percentage of all requests. For example, if you select the IP dimension, all requests from an IP address that triggers the grayscale rule will be matched. Effective Mode Permanently Effective (Default): The rule is always in effect when the protection template is enabled. Fixed Schedule: You can set the rule to be effective for a specific period in a specific time zone. Recurring Schedule: You can set the rule to be effective during a specific time period that recurs daily in a specific time zone. You can also select multiple rules to modify their grayscale release and effective mode settings in bulk.

7. On the Verify Protection Effect page, test the bot protection rule.

   Test protection actions before publishing to prevent false positives. If the rule is configured correctly, click Skip in the lower-left corner.

   The verification steps are as follows:

   1. Step 1: Enter a public IP address.

      Enter your test device's public IP address (PC or mobile phone). The test applies only to this IP and does not affect your services.

      Important

      Do not use the ipconfig address — it returns an internal IP. Use an online IP query tool to find your public IP address.

   2. Step 2: Select an action.

      Generate a test rule that applies only to your test IP address to verify the mitigation actions that you configured on the Configure Protection Rules page. The available actions are Block Verification and SDK Signature Verification.

      In the test action module, click Test. WAF immediately applies the test rule to your device and demonstrates the result. Read the explanation carefully.

      After you complete the test, click I Have Completed the Test to proceed. If the test result is abnormal, click Go Back, refer to FAQ for testing bot protection policies, optimize the rule, and then test it again.

Create a basic protection rule

Configure basic protection rules to block low- to medium-sophistication crawlers. No default template is provided — you must create one.

1. Log on to the Web Application Firewall 3.0 console. From the top menu bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) for the WAF instance.

2. In the navigation pane on the left, choose Protection Config > Bot Management.

3. On the Basic Protection tab, click Create Template.

4. In the Create Template panel, configure the following settings and click OK.

   Parameter	Description
   Template Name	Enter a name for the template. The name must be 1 to 255 characters in length and can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
   Template Description	Enter a description for the template.
   Action	Set the action for the protection rule to Block or Log.
   Advanced Settings	Canary Rule: Configure the percentage of traffic that the rule applies to based on a specific dimension. After you enable Grayscale Release, you must also configure the grayscale Dimension and Canary Release Proportion. The grayscale Dimension include: IP, Custom Header, Custom Parameter, Custom Cookie, and Session. Note Grayscale rules are applied based on the Dimension you set, not randomly to a percentage of all requests. For example, if you select the IP dimension, all requests from an IP address that triggers the grayscale rule will be matched. Effective Mode Permanently Effective (Default): The rule is always in effect when the protection template is enabled. Fixed Schedule: You can set the rule to be effective for a specific period in a specific time zone. Recurring Schedule: You can set the rule to be effective during a specific time period that recurs daily in a specific time zone.
   Apply To	Select the protected objects or groups to which the template applies.

The new rule template is enabled by default. On the Basic Protection tab, you can perform the following operations on the rule template card:

• View the rule IDs included in the template.

  Note

  A basic protection template contains three rule IDs: two for whitelist rules and one combining an ACL rule with HTTP flood protection. Use these rule IDs to track protection effectiveness in security reports.

• Copy, Edit, or Delete a rule template.

• Use the switch on the template to enable or disable it.

• View the template's action and the number of Protected Object/Group items it applies to.

FAQ for bot protection testing

If you encounter an issue during the Verify Protection Effect step, use this table to troubleshoot.

Next steps

View protection rule execution records on the Security Reports page.