If your business is affected by automated tools, such as scripts and emulators, that cause issues such as data scraping, business fraud, dictionary attacks, spam registrations, malicious flash sales, promotion abuse, or text message API abuse, you can enable the bot management feature of Web Application Firewall (WAF). This feature lets you create targeted bot mitigation policies based on machine traffic analysis data. This helps mitigate the risks of core data asset leakage and promotion abuse. It also reduces server bandwidth costs and server load. This topic describes how to enable and configure bot management policies.
A new version of bot management is being gradually rolled out. This topic describes the legacy version. For more information about the new version, see Bot management (new version). You can identify your version by the style of the menu in the navigation pane on the left of the WAF console:
Legacy bot management:
New bot management:

Features
Bot management provides the following features to help you quickly detect machine traffic, defend against bot threats, and prevent your business data from being scraped.
Bot traffic analysis (Bot Management not required)
You can view risk data for your API operations using the machine traffic analysis feature without enabling bot management. This data includes the trend of machine traffic within a specified time range, the top 20 clients and top 20 IP addresses that pose risks, and machine traffic analysis data for protected objects. This helps you quickly identify and locate API operations that may be at risk. For more information, see View machine traffic analysis data.
For API operations that are at risk, you can request a free trial or purchase a bot management plan to configure scene-based mitigation policies. For more information about how to request a free trial or purchase a plan, see Enable bot management.
Scenario-specific Protection (Available after you enable bot management)
This feature provides fine-grained control for specific business scenarios. You can integrate a software development kit (SDK) and configure scene-based mitigation policies for web pages and apps to achieve optimal protection. For more information, see Create a scene-based mitigation rule for web crawlers and Create a scene-based mitigation rule for app crawlers.
Audience: Users who are sensitive to machine traffic.
Basic Protection (Available after you enable bot management)
This feature detects bot traffic based on Layer 4 or Layer 7 traffic fingerprints. You do not need to integrate an SDK. You can enable protection with a single click. For more information, see Create a basic mitigation rule.
Audience: Users who want to configure simple mitigation policies to block low-level and mid-level bots.
Prerequisites
Web services are added to WAF on the Website Configuration page. For more information, see Website configuration overview.
To create a scene-based mitigation template for app crawlers, you must integrate the SDK into the app that you want to protect. For more information, see Integrate an SDK into an Android app and Integrate an SDK into an iOS app.
View machine traffic analysis data
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region of the WAF instance. You can select Chinese Mainland or Outside Chinese Mainland.
In the left-side navigation pane, choose .
On the Machine Traffic Analysis tab, view the Machine Traffic Trend, Top 20 Clients, Top 20 IPs, and Machine Traffic Analysis For Protected Objects for a specified protected object within a specific time range.

Enable bot management
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region of the WAF instance. You can select Chinese Mainland or Outside Chinese Mainland.
In the left-side navigation pane, choose .
Enable bot management.
Request a free trial
NoteYou can request a free trial of bot management once for each WAF instance of the Pro, Business, or Ultimate edition.
The free trial is valid for 7 days after your request is approved. After the trial expires, the analysis data generated during the trial is immediately purged if you do not purchase a bot management plan. To retain the data and continue using the bot management feature, purchase a plan before the trial expires.
On the Machine Traffic Analysis tab, click Free Trial. On the WAF-Bot Management PoC Questionnaire page, enter the required information and click Submit.
An Alibaba Cloud engineer will contact you within one week after you submit the request to confirm the trial details. After your request is approved, the bot management feature is automatically enabled for your WAF instance.
Purchase a bot management plan
On the Machine Traffic Analysis tab, or on the Scenario-specific Protection or Basic Protection tab, click Purchase.
In the Purchase panel, enable Bot Management - Web Protection or Bot Management - App Protection, and complete the payment.
NoteAfter you enable Bot Management - Web Protection, you can configure basic protection rules and scene-based rules for web crawlers.
After you enable Bot Management - App Protection, you can configure basic protection rules and scene-based rules for app crawlers.
To configure basic protection rules, scene-based rules for web crawlers, and scene-based rules for app crawlers, you can enable both Bot Management - Web Protection and Bot Management - App Protection.
After you enable bot management, you can click the Machine Traffic Analysis tab. In the Machine Traffic Analysis For Protected Objects section, locate the API operation that is at risk due to high machine traffic and click Add Mitigation in the Actions column to add a scene-based mitigation policy. For more information, see Create a scene-based mitigation rule for web crawlers and Create a scene-based mitigation rule for app crawlers.
If you want to configure simple mitigation policies to block low-level and mid-level bots, you can configure basic bot management rules on the Basic Protection tab. For more information, see Create a basic mitigation rule.
Create a scene-based mitigation rule for web crawlers
If your business involves accessing web pages or H5 pages (including H5 pages in apps) through a browser, you can create a scene-based mitigation template for web crawlers and customize mitigation rules to defend against web bots.
If you enable the JavaScript Challenge or Slider CAPTCHA action, WAF initiates a JavaScript challenge or slider verification for the client when a request hits a rule. After the client passes the verification, WAF inserts the
acw_sc__v2oracw_sc__v3cookie into the header of the HTTP message to indicate that the client is verified.If you configure a scene-based bot template and enable automatic integration of the Web SDK, WAF inserts the
ssxmod_itna,ssxmod_itna2, andssxmod_itna3cookies into the header of the HTTP message to obtain the browser fingerprint. The collected fingerprint information includes the host field of the HTTP message, and the height and width of the browser.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region of the WAF instance. You can select Chinese Mainland or Outside Chinese Mainland.
In the left-side navigation pane, choose .
On the Scenario-specific Protection tab, click Create Template.
On the Configure Scenarios page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Template Name
Set a name for the template.
The name of the template must be 1 to 255 characters in length and can contain 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 in apps) that are accessed through browsers.
Web SDK Integration
For more information, see Integrate an SDK into a web application.
Traffic Characteristics
Add HTTP request fields and their rules for the destination traffic. This refers to the content of fields related to the business scenario that are generated in the HTTP request message when the protected object is accessed. You can add up to five conditions. The logical operator between the conditions is AND. For more information about the fields, see Match conditions.
On the Configure Protection Rules page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Fraud Detection
After you select Business Security Policy, enter the required information. For more information, see Fraud Detection.
After you enable the rule, WAF integrates with the Fraud Detection service. This lets you block access from abnormal phone numbers, such as those used by scalpers. This is a pay-as-you-go service that is billed based on the number of rule hits.
Legitimate Bot Management
After you select Spider Whitelist, select a whitelist of legitimate search engines.
After you enable the rule, legitimate bot IP addresses from the relevant search engines are allowed to pass without being checked by the bot management module.
Bot Characteristic Detection
Bot Behavior Detection
Bot Threat Intelligence
On the Configure Effective Scope page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Apply To
Select the protected objects or protected object groups to which you want to apply the rule. Click the
icon to move the selected objects or groups to the Selected area.Effective Period And Grayscale Release
Set the grayscale release and effective period for the selected mitigation rule. If you do not configure these settings, Grayscale Release is disabled for the rule and the rule is Permanently Effective by default.
Locate the destination rule and click Edit in the Actions column.
Configure the grayscale release and effective period.
Grayscale Release: Configure the percentage of objects to which the rule applies based on different dimensions.
After you enable grayscale release, you must set the Dimension and Grayscale Ratio. The available Dimensions are IP, Custom Header, Custom Parameter, Custom Cookie, and Session.
NoteThe grayscale rule is applied based on the Dimension you set, not randomly to a percentage of requests. For example, if you select the IP dimension for grayscale release, all requests from an IP address that triggers the rule will be matched.
Effective Mode
Permanently Effective (Default): The rule is always in effect when the mitigation template is enabled.
Effective Within A Time Period: You can set a specific time period in a specific time zone for the rule to be effective.
Effective On A Recurring Basis: You can set a specific time period of each day in a specific time zone for the rule to be effective.
You can also select multiple rules and modify their grayscale release and effective period mode in a batch.
On the Verify Protection Effect page of the wizard, test the bot mitigation rule.
We recommend that you verify the mitigation action before you publish the policy. This helps prevent incorrect blocking caused by rule configuration errors or compatibility issues. If you are sure that the rule is correctly configured, you can click Skip in the lower-left corner.
Follow these steps to perform the verification:
The new rule template is enabled by default. On the Scenario-specific Protection tab, you can perform the following operations in the rule template card area:
Click a rule template card to view the information in the rule.
Copy, Edit, or Delete a rule template.
Use the switch on the template to enable or disable it.
View the rule actions and the number of associated Protected Object/Group.
Create a scene-based mitigation rule for app crawlers
If your business is based on a native iOS or Android app (excluding H5 pages used in the app), you can create a scene-based mitigation template for app crawlers and customize mitigation rules to defend against app bots.
If you enable the JavaScript Challenge or Slider CAPTCHA action, WAF initiates a JavaScript challenge or slider verification for the client when a request hits a rule. After the client passes the verification, WAF inserts the acw_sc__v2 or acw_sc__v3 cookie into the header of the HTTP message to indicate that the client is verified.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region of the WAF instance. You can select Chinese Mainland or Outside Chinese Mainland.
In the left-side navigation pane, choose .
On the Scenario-specific Protection tab, click Create Template.
On the Configure Scenarios page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Template Name
Set a name for the template.
The name of the template must be 1 to 255 characters in length and can contain 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 in apps).
App SDK Integration
WAF provides an SDK for native apps (Android/iOS) to improve protection in this scenario. After the SDK is integrated, it collects client risk features and attaches a security signature to requests. WAF uses the signature features to detect and block risk requests.
You can integrate the App SDK in the following ways:
Submit a ticket to contact us and obtain the SDK for your iOS app.
Click Obtain and Copy AppKey to use for initiating SDK initialization requests.
Integrate the App SDK. For more information, see Integrate an SDK into an iOS app.
Traffic Characteristics
Add HTTP request fields and their rules for the destination traffic. This refers to the content of fields related to the business scenario that are generated in the HTTP request message when the protected object is accessed. You can add up to five conditions. The logical operator between the conditions is AND. For more information about the fields, see Match conditions.
On the Configure Protection Rules page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Fraud Detection
After you select Business Security Policy, enter the required information. For more information, see Fraud Detection.
After you enable the rule, WAF integrates with the Fraud Detection service. This lets you block access from abnormal phone numbers, such as those used by scalpers. This is a pay-as-you-go service that is billed based on the number of rule hits.
Bot Characteristic Detection
Detection rules
Mitigation action
You can set the action for the configured Bot Characteristic Detection rule to Monitor, Block, or Strict Slider CAPTCHA Verification.
Advanced mitigation
Click Advanced Protection and configure the following settings:
Bot Behavior Detection
After you select Intelligent Protection, you must set the rule action for detected bot behavior to Monitor, Slider CAPTCHA, Strict Slider CAPTCHA Verification, or Mark For Origin Fetch. If you select Mark For Origin Fetch, you must also set the Header Name and Header Content for the mark.
After you enable this feature, the bot mitigation rule uses intelligent protection engines to analyze and automatically learn from access traffic, generating targeted mitigation rules or blacklists.
Throttling
After you enable this feature, you can customize access frequency limits to filter bot requests with excessively high frequencies. This effectively mitigates HTTP flood attacks.
Bot Threat Intelligence
On the Configure Effective Scope page of the wizard, complete the following configurations and click Next.
Configuration item
Description
Apply To
Select the protected objects or protected object groups to which you want to apply the rule. Click the
icon to move the selected objects or groups to the Selected area.Effective Period And Grayscale Release
Set the grayscale release and effective period for the selected mitigation rule. If you do not configure these settings, Grayscale Release is disabled for the rule and the rule is Permanently Effective by default.
Locate the destination rule and click Edit in the Actions column.
Configure the grayscale release and effective period.
Grayscale Release: Configure the percentage of objects to which the rule applies based on different dimensions.
After you enable grayscale release, you must set the Dimension and Grayscale Ratio. The available Dimensions are IP, Custom Header, Custom Parameter, Custom Cookie, and Session.
NoteThe grayscale rule is applied based on the Dimension you set, not randomly to a percentage of requests. For example, if you select the IP dimension for grayscale release, all requests from an IP address that triggers the rule will be matched.
Effective Mode
Permanently Effective (Default): The rule is always in effect when the mitigation template is enabled.
Effective Within A Time Period: You can set a specific time period in a specific time zone for the rule to be effective.
Effective On A Recurring Basis: You can set a specific time period of each day in a specific time zone for the rule to be effective.
You can also select multiple rules and modify their grayscale release and effective period mode in a batch.
On the Verify Protection Effect page of the wizard, test the bot mitigation rule.
We recommend that you verify the mitigation action before you publish the policy. This helps prevent incorrect blocking caused by rule configuration errors or compatibility issues. If you are sure that the rule is correctly configured, you can click Skip in the lower-left corner.
Follow these steps to perform the verification:
The new rule template is enabled by default. On the Scenario-specific Protection tab, you can perform the following operations in the rule template card area:
Click a rule template card to view the information in the rule.
Copy, Edit, or Delete a rule template.
Use the switch on the template to enable or disable it.
View the rule actions and the number of associated Protected Object/Group.
Create a basic mitigation rule
If your business is targeted by low-level or mid-level bots, you can configure simpler basic mitigation rules. Basic protection does not provide a default rule template. To enable this feature, you must create a new rule template.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region of the WAF instance. You can select Chinese Mainland or Outside Chinese Mainland.
In the left-side navigation pane, choose .
On the Basic Protection tab, click Create Template.
In the Create Template - Bot Management panel, complete the following configurations and click OK.
Configuration item
Description
Template Name
Set a name for the template.
The name of the template must be 1 to 255 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Template Description
Enter a description for the template.
Action
Set the action for the mitigation rule to Block or Monitor.
Advanced Settings
Grayscale Release: Configure the percentage of objects to which the rule applies based on different dimensions.
After you enable grayscale release, you must set the Dimension and Grayscale Ratio. The available Dimensions are IP, Custom Header, Custom Parameter, Custom Cookie, and Session.
NoteThe grayscale rule is applied based on the Dimension you set, not randomly to a percentage of requests. For example, if you select the IP dimension for grayscale release, all requests from an IP address that triggers the rule will be matched.
Effective Mode
Permanently Effective (Default): The rule is always in effect when the mitigation template is enabled.
Effective Within A Time Period: You can set a specific time period in a specific time zone for the rule to be effective.
Effective On A Recurring Basis: You can set a specific time period of each day in a specific time zone for the rule to be effective.
Apply To
From the added protected objects and object groups, select the ones to which you want to apply the template.
The new rule template is enabled by default. On the Basic Protection tab, you can perform the following operations in the rule template card area:
View the rule IDs included in the template.
NoteA basic mitigation template contains three rule IDs: two for whitelist rules and one for a rule that consists of an access control list (ACL) and an HTTP flood protection rule. You can use these rule IDs to view the mitigation effect in security reports. For more information, see Security reports.
Copy, Edit, or Delete a rule template.
Use the switch on the template to enable or disable it.
View the rule actions and the number of associated Protected Object/Group.
FAQ for testing bot mitigation policies
If an exception occurs during the Verify Protection Effect step, refer to the following table to resolve the issue.
Error | Cause | Solution |
No valid test requests were found. You can view the documentation or contact us to analyze possible causes. | The test request was not sent successfully, or it was not sent to WAF. | Confirm that the test request was sent to the address that WAF uses. |
The field content of the test request is inconsistent with the Traffic Characteristics defined in the bot mitigation rule. | Modify the protected object feature in the bot mitigation policy. | |
The source IP address of the test request is inconsistent with the public test IP address entered in the policy configuration. | Make sure that you are using the correct public IP address. We recommend that you use the diagnostic tool to query your public IP address. | |
The request failed verification. You can view the documentation or contact us to analyze possible causes. | The access was not from a real user. For example, the access was from a debug mode or an automated tool. | Use a client to simulate access from a real user during the test. |
The mitigation scenario was selected incorrectly. For example, you selected Websites when you needed to configure a scene-based rule for app crawlers. | Modify the mitigation scenario type in the scene-based bot mitigation rule. | |
The access request involves cross-domain access, but it is not correctly configured in the scene-based bot mitigation rule. | Modify the scene-based bot mitigation rule. Select Use Intermediate Domain Name and select the source domain name of the cross-domain access from the drop-down list. | |
Frontend compatibility issue. | Submit a ticket to contact us. | |
The request did not trigger verification. You can view the documentation or contact us to analyze possible causes. | The test rule has not been fully applied. | We recommend that you run the test again and wait for the bot mitigation test rule to be applied. |
Not blocked and no valid test requests were found. You can view the documentation or contact us to analyze possible causes. | The test request was not sent successfully, or it was not sent to WAF. | Confirm that the test request was sent to the address that WAF uses. |
The field content of the test request is inconsistent with the Protected Object Feature defined in the bot mitigation rule. | Modify the protected object feature in the bot mitigation policy. | |
The source IP address of the test request is inconsistent with the public test IP address entered in the policy configuration. | Make sure that you are using the correct public IP address. We recommend that you use the diagnostic tool to query your public IP address. |
What to do next
You can view the execution records of mitigation rules on the Security Reports page. For more information, see Security reports.