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.
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 the Basic plan or higher.
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.
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.
Related documentation
Rule-related features vary in effective priority, reentrancy, and effective granularity. For details, see Properties of Rule-Related Features.