Whitelist rules let requests that match specific conditions bypass all or selected protection modules in Web Application Firewall (WAF), preventing false positives for trusted traffic such as vulnerability scanners, authenticated partner interfaces, or internal monitoring tools.
This topic explains how to create a whitelist protection template and add whitelist rules to it.
Before you begin
Identify your goal before configuring whitelist rules:
| Goal | Recommended approach |
|---|---|
| Allow trusted traffic from a specific IP or path (proactive allow) | Create a whitelist rule with the All bypass option, or select only the modules you want to skip. |
| Stop a specific WAF rule from blocking legitimate requests (false positive remediation) | Create a whitelist rule with Core Protection Rule > IDs of Specific Rules, and enter the rule ID that caused the false positive. |
Prerequisites
Before you begin, make sure that you have:
A WAF 3.0 instance. For details, see Activate a pay-as-you-go WAF 3.0 instance.
Web services added to WAF 3.0 as protected objects. For details, see Configure protected objects and protected object groups.
Choose your starting point
Whitelist rules live inside protection templates. Before adding a rule, decide which template to use:
| Scenario | Action |
|---|---|
| Use the default protection template (applied to all protected objects by default) | Skip Step 1 and go directly to Step 2 |
| Create a custom template for specific protected objects or object groups | Complete Step 1, then Step 2 |
A whitelist protection template with no rules does not allow any requests to bypass WAF. By default, WAF inspects all requests.
Template types
| Template type | Description | Applies to |
|---|---|---|
| Default protection template | The initial template provided by WAF. Contains no whitelist rules. | All new and existing protected objects and groups by default. You can change this manually. |
| Custom protection template | A template you create based on your needs. | Only the protected objects and object groups you specify in Apply To. |
For a single protected object or object group, you can associate multiple whitelist protection templates. For details about how rules take effect when multiple templates apply, see Application examples for multiple protection templates.
Step 1: Create a whitelist protection template
Skip this step if you are using the default protection template.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) of your WAF instance.Web Application Firewall 3.0 console
In the left-side navigation pane, choose Protection Configuration > Core Web Protection.
In the Whitelist section, click Create Template.
In the Create Template - Whitelist panel, configure the following settings and click OK.
Configuration item Description Template Name Enter a name for the template. The name must be 1–255 characters and can contain letters, digits, periods (.), underscores (_), and hyphens (-). Set as Default Template Only one default template is allowed per protection module. This can only be set at creation time. If selected, the template applies to all protected objects and groups by default. Rule Configuration (Optional) Click Create Rule to add a whitelist rule now, or add rules after the template is created. Apply To Select protected objects on the Protected Objects tab and protected object groups on the Protected Object Groups tab. If you do not set a default template, no objects or groups are selected by default.
After the template is created, it is enabled by default. In the template list, you can:
View the number of associated objects and groups in the Protected Object/Group column.
Enable or disable the template using the Status column switch.
Click Create Rule, Edit, Delete, or Copy in the Actions column to manage the template.
Click the
icon next to a template name to view its protection rules.
WAF automatically creates a protection template named AutoTemplate in the following scenarios:
When the intelligent whitelisting engine identifies a false positive risk after analyzing logs, it adds a whitelist rule for the affected path and rule ID. For details, see Intelligent whitelisting engine.
When you select Ignore False Positive for an attack detected by a web core protection rule in a security report, WAF adds a whitelist rule with source Custom. For details, see Security reports.
When you select Add To Whitelist for an attack detected by the bot management module in a security report, WAF adds a whitelist rule with source Custom. For details, see Security reports.
Step 2: Add a whitelist rule to a whitelist protection template
A protection template only takes effect after it contains at least one whitelist rule. Skip this step if you already added rules during template creation.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and region (Chinese Mainland or Outside Chinese Mainland) of your WAF instance.
In the left-side navigation pane, choose Protection Configuration > Core Web Protection.
In the Whitelist section, find the target template and click Create Rule in the Actions column.
In the Create Rule dialog box, configure the following settings and click OK. Match condition examples:
URI contains
/login.php: Set Match Field to URI, Logical Operator to Contains, Match Content to/login.php.Requests from a specific IP: Set Match Field to IP, Logical Operator to Belongs To, Match Content to the IP address (for example,
192.1X.XX.XX).
Configuration item Description Rule Name Enter a name for the rule. The name can contain letters, digits, periods (.), underscores (_), and hyphens (-). Match Conditions Specify the request characteristics to match. Click Add Condition to add a condition — up to five per rule. All conditions must be met for the rule to match (AND logic). Each condition has three parameters: Match Field, Logical Operator, and Match Content. For the full list of supported fields and operators, see Match conditions. Bypassed Modules Select which protection modules to bypass for matching requests. See the table below. Bypassed Modules options:
Option Description All Matching requests bypass all protection modules and are forwarded to the origin server. Use this only for traffic you fully trust, such as access from verified vulnerability scan tools or authenticated third-party system interfaces. For better security, select specific modules rather than All. Core Protection Rule Matching requests bypass the specified web core protection rules. After selecting this option, choose the rules to ignore: All Rules (default), IDs of Specific Rules (enter rule IDs in six-digit format, one per Enter key press, up to 50 IDs; you can also add rule IDs for major event support to the whitelist), or Types of Specific Rules (click the 
icon and select rule types).Custom Rule Matching requests bypass the custom rules module. IP Address Blacklist Matching requests bypass the IP blacklist module. Scan Protection Matching requests bypass the scan protection module. Bot Management Matching requests bypass the bot management module. Website Tamper-proofing Matching requests bypass the web tamper proofing module. Data Leakage Prevention Matching requests bypass the data leakage prevention module. HTTP Flood Protection Matching requests bypass the HTTP flood protection module. Region Blacklist Matching requests bypass the Location Blacklist module. AI Application Protection Matching requests bypass the AI application protection module.
After the rule is created, it is enabled by default. In the rule list, you can:
View the rule ID and action in the Rule ID and Action columns.
Enable or disable the rule using the Status column switch.
Click Edit or Delete in the Actions column to modify or delete the rule.
Verify the whitelist rule
After adding a rule, confirm that it matches the intended traffic before relying on it in production.
On the Security Reports page, query the block records for the affected protection rules. If requests that should be whitelisted no longer appear as blocked, the rule is working correctly. If requests are still blocked, check the following:
Match conditions: Confirm the field, operator, and value match the actual request exactly.
Template association: Confirm the template is applied to the correct protected objects or object groups.
Rule and template status: Confirm both the template and the rule are enabled in the Status column.
For details on querying block records, see Security reports.
Tip: To find the rule ID that triggered a block (useful when configuring IDs of Specific Rules under Core Protection Rule), go to the Security Reports page and look up block records. For details, see Security reports.
References
Match conditions — Supported match fields and logical operators for whitelist rules.
Overview of mitigation settings — Protected objects, protection modules, and the protection process in WAF 3.0.
Create a protection template — API reference for creating a protection template.
Create a Web core protection rule — API reference for creating a web core protection rule.