Custom rules
If your website requires custom access control policies, you can create custom rules. A custom rule allows you to define match conditions for incoming requests and specify an action, such as block or monitor, for matching requests. This gives you flexible control over the content users can access.
Accuracy of client IP geolocation
When using WAF custom rules with the rules engine to block requests, note that IP geolocation data (such as continent, country/region, province, and ISP) may not be 100% accurate. Misidentification can occur, so use this feature with caution.
If you encounter inaccuracies in client IP geolocation, you can create a whitelist rule to allow specific IP addresses. This prevents WAF from incorrectly blocking legitimate client IP addresses.
Configure a custom rule
In the ESA console, select Websites. In the Website column, click the target website.
In the left-side navigation pane, choose .
Click the Custom Rules tab, and on the Custom Rules tab, click Create Rule.
Enter a Rule Name.
In the If requests match... area, configure the match conditions. For more information, see Rule expression syntax.
In the Then execute... area, specify an action for matching requests. For more information, see Actions.
Click OK.
When you configure rules, note the following:
User-Agent matching and case sensitivity: When you configure a rule to match on the User-Agent, if you select the Case-insensitive match mode, the match value must be in all lowercase. Also, make sure to select the correct match precision—Equals for an exact match or Contains for a partial match—based on your needs. An incorrect mode can prevent the rule from taking effect, for example, by allowing requests that should be blocked (returning a 200 status code).
Rules engine limitations: The WAF rules engine currently supports boolean matching, such as checking if a request field contains a specific string. It does not support more complex logic like counting occurrences or array lengths. Therefore, you cannot create a rule to "block a request if the URL contains a keyword more than N times." WAF protection policies must be based on request attributes like client IP, User-Agent, Referer, or URI. You cannot block traffic based solely on business-layer identifiers, such as a visitor ID.
Actions
Block: Blocks matching requests and returns a block page to the client.
NoteCustomize block pages through Configure custom pages.
Monitor: Allows matching requests to pass but logs the event. Use monitor mode to test new rules and check WAF logs for false positives. After confirming no false positives, change the action to Block.
NoteYou must enable Log Service to use the log query feature.
JavaScript Challenge: ESA returns a JavaScript snippet to the client. If the browser executes the script successfully,ESA allows all subsequent requests from that client for a default period of 30 minutes without another challenge. Otherwise, the request is blocked.
Slider CAPTCHA: ESA returns a slider CAPTCHA page. If the client solves the CAPTCHA, ESA allows all subsequent requests from that client for a default period of 30 minutes. Otherwise, the request is blocked.
NoteRequests that pass the Slider CAPTCHA are billed; blocked requests are not.
JavaScript Challenge and Slider CAPTCHA for WAF custom rules and rate limiting rules apply only to static pages. For asynchronous APIs (
XMLHttpRequestandFetch), enable these challenges in Bots. When a matching request passes the challenge, ESA adds aCookie acw_sc__v2oracw_sc__v3to the HTTP header to mark the client as verified.
Strict Slider CAPTCHA: In strict CAPTCHA mode, each client request must pass verification (unlike the Slider CAPTCHA which allows a 30-minute pass-through for previously verified clients). Enable with caution. Strict Slider CAPTCHA is available only for Enterprise plans upon request.
Custom rules support two human verification actions:
JS Challenge: Passive verification. The system sends JavaScript code to the client for automatic verification without requiring any user interaction.
Slider Challenge: Interactive verification. The user must complete a sliding action to pass verification.
When you use JS Challenge and Slider Challenge, note the following restrictions:
JavaScript Challenge and Slider CAPTCHA are suitable only for static page requests. We do not recommend them for dynamic scenarios, such as POST form submissions or API calls, as they can cause data loss or repeated verification.
If you apply JavaScript Challenge or Slider CAPTCHA to resource files like images, browser mechanisms may prevent the verification from completing, causing the resource to fail to display. For domains or paths that serve only images, we recommend using the block action or configuring a whitelist rule instead of human verification.
After a JavaScript Challenge is passed, the pass duration is 30 minutes by default and cannot be modified.
For more CAPTCHA types, such as one-click verification, use the AI Captcha feature. It supports various challenge types, including one-click, slider, and rotation puzzles, and can be configured separately in the ESA console.
Configuration example
Scenario: In Security Analytics or Event Analysis, you find that the client IP 192.168.0.1 is sending suspicious requests to the hostname dns.example.com.
Configuration:
Parameter | Example value |
If requests match... | Both of the following conditions are met:
You can also use the following expression directly: |
Then execute... | Block the request and respond with the Default Error Page |
Result: The custom rule blocks all matching requests.
Common configuration examples
Use the following examples for common protection scenarios as a starting point, and adjust them to fit your needs.
Scenario 1: Block a specific crawler (for example, Bytespider)
In the If requests match... area, set the match field to User-Agent, the operator to Contains, and the value to Bytespider. For the action, select Block.
Scenario 2: Restrict request methods (allow only GET and POST)
Configure a rule: If the Request Method is not equal to GET AND not equal to POST, then execute the Block action. This scenario requires the Advanced plan or higher.
Scenario 3: Allow only a specific IP to access a subdomain
Combine two match conditions: Hostname equals the target subdomain AND Client IP is not equal to the specified IP. For the action, select Block.
Scenario 4: Block requests with an empty Referer while allowing direct access to specific paths
You need to configure two rules and set their priority:
Whitelist rule (high priority): If the request URI equals a path that can be accessed directly (such as the homepage
/or article pages), execute the Skip All Rules action.Block rule (low priority): If the Referer is empty, execute the Block action.
The whitelist rule must have a higher priority than the block rule to ensure that direct access paths are not affected.
Scenario 5: Block anomalous requests for a specific URL path
Configure combined conditions: URI contains a specific string AND Referer is empty. For the action, select Block or JS Challenge.
Scenario 6: Block requests from a specific Referer source domain
The Referer match field requires the Basic plan or higher.
To block access requests from a specific source domain, in the If requests match... area, set the match field to Referer, the operator to Contains, and the value to the target domain, for example servicewechat.com. For the action, select Block and set the response code to 403.
Scenario 7: Allow WeChat Mini Program requests
The Referer header of requests sent from a WeChat Mini Program is usually empty. If you configure a rule that blocks requests with an empty Referer (see Scenario 4), such requests can be incorrectly blocked. To avoid this, add a rule with higher priority than the block rule: in the If requests match... area, set the match field to User-Agent, the operator to Contains, and the value to WeChat. For the action, select Skip All Rules (or Block or Allow, depending on your protection strategy) so that requests from the WeChat client are not affected by the empty-Referer block rule.
Scenario 8: Allow only a specified domain to access the current site
To strictly control which domains can reference your site's resources, configure a combined rule: Hostname equals your target domain (for example, lswgo.zlsgw.com) AND Referer does not contain the allowed source domain (for example, a.zlsgw.com). For the action, select Block. This ensures that only requests carrying a Referer from the allowed source domain can access the target domain.
Guidance on blocking based on User-Agent
Blocking requests based on an anomalous User-Agent (for example, a value with version number 0.0.0) rarely affects real users, but a direct Block action still carries some risk of false positives. If you are concerned about blocking legitimate traffic, set the action to Slider CAPTCHA or JS Challenge instead of Block so that suspicious requests are challenged rather than blocked outright. You can also review User-Agent distribution and Referer patterns in Security Analytics to identify crawler traffic before deciding on a protection strategy.
Feature availability by plan
Feature | Free | Basic | Standard | Advanced | Enterprise |
Number of custom rules | 5 | 10 | 50 | 100 | 100 |
The Free plan does not support match conditions based on fields such as Ip.Geoip.Country. If you use this field in a custom rule, the system returns an Ip.Geoip.Country.NotSupport error. To use geolocation-based match conditions, you must upgrade to higher plan.
FAQ
Why do country/region-based block rules cause false positives or fail to identify 'Unknown' regions?
IP geolocation data (continent, country/region, province, ISP) cannot be 100% accurate. In addition, VPNs or proxy services can change a client's apparent IP geolocation, which can cause rules to trigger incorrectly.
Private IP ranges (such as 100.64.0.0/10) and proxy IPs may be identified as an Unknown region. ESA does not support directly blocking the Unknown region.
Recommendations:
Combine geolocation conditions with other attributes like User-Agent or Referer. For example: country/region is not in the target list AND User-Agent does not match a specific value. This reduces false positives caused by relying solely on geolocation.
If false positives occur, configure a whitelist rule to allow legitimate IP addresses.
I configured a rule to block a specific country/region, but requests from that region can still access my site. Why?
This usually happens when the rule combines a Country/Region condition with other match conditions (for example, a Hostname pattern) that do not actually match the incoming request, so the rule as a whole never triggers. Check that the other fields in your rule expression, such as Hostname or URI, correctly match the traffic you intend to block. You can use Security Analytics or Event Analysis to verify the actual traffic characteristics before adjusting your rule logic.
Also note that blocking access by Country/Region requires a match condition based on geolocation fields (such as Ip.Geoip.Country). This match condition is not available on the Free plan; you must upgrade to the Basic plan or higher to use it.
For expression syntax, see request match rules.
How do I handle third-party callbacks (like Alipay notifications) being blocked by WAF?
Analyze the common characteristics of the callback requests (for example, the URI path contains /pay/notify/, a specific User-Agent, and the request method is POST). Then, create a custom rule to act as a whitelist: if a request matches all these characteristics, apply the Skip All Rules action.
If you cannot determine all characteristics, start by configuring block rules for known attack patterns and then test incrementally to ensure legitimate callbacks are not blocked.
How do I prevent the X-Forwarded-For header from being spoofed when I configure WAF rules?
The X-Forwarded-For request header can be modified by the client, so a custom rule that matches on it can be bypassed by an attacker who forges the header value. When you configure a custom rule that needs to identify the real client, use the Client IP match field (ip.src) instead of matching on X-Forwarded-For. The Client IP field reflects the actual connecting IP address and cannot be spoofed by the client.
If your origin server needs to obtain the real client IP address, you can use one of the following methods:
In Managed Transform, enable the option that adds the real client IP to the request sent to your origin (the header is named
ali-real-client-ipby default; the header name can be customized). Configure your origin to read this header instead ofX-Forwarded-For.You can also use the
modify-request-headeraction in Transform Rules to overwrite or remove the client-submittedX-Forwarded-Forheader before the request reaches your origin, so that a forged value does not reach your origin.
My requests are returning a 403 Forbidden error. How do I troubleshoot this?
A 403 response is most often caused by one of the following access control policies:
A WAF custom rule with the Block action matched your request.
Your client IP is on an IP blacklist rule.
Referer-based hotlink protection blocked a request that did not carry an allowed Referer.
A geo-restriction rule blocked your request based on the country/region of the client IP.
To find out which rule caused the 403 response, capture the complete HTTP response headers of the blocked request and check them against your configured rules. Then, in the ESA console, go to the security protection module for your site and review your WAF custom rules and any cache-related resource configuration to identify and adjust the specific rule that is blocking the request.
Related documentation
Rule-related features vary in effective priority, reentrancy, and effective granularity. For details, see Properties of Rule-Related Features.