eCDN Custom Rules
Custom rules allow you to control incoming traffic by setting up firewall policies based on various request parameters. These API endpoints expand on the existing functionality of firewall rules. With custom rules, you have complete control over the rule expression. We’ve also extended the list of allowed request field types and rule actions, which offer increased flexibility and allows you to create expressions that match your specific traffic needs.
We expect all customers to transition to using custom rules in place of firewall rules, and firewall rules will be deprecated by February 1, 2024.
The fields and operators supported in the rule expression are now consistent with what is offered with rate limiting rules. For more information, refer to Rule Expression in the eCDN Rate Limiting Rules guide.
The maximum length of a custom rule expression is 4096 characters.
The following rule actions are supported in the actions array:
block
- Denies access to the requested site.js_challenge
- The client that made the request must pass a JavaScript Challenge before proceeding.legacy_captcha
- The client that made the request must pass an interactive challenge.managed_challenge
- Depending on the characteristics of the request, the appropriate type of challenge is presented to the client.log
- Logs matching requests.
The following skip actions are also supported in the actions array:
skip_custom_rules
- Skips all remaining custom rules (meaning custom rules with a lower priority are not evaluated).skip_waf
- Skips WAF-managed rules.skip_security_level
- Skips Security Level.
If using the skip actions, the user can provide multiple skip actions in the array. Otherwise, the array includes only 1 rule action. See the following usage examples:
Custom rules are evaluated in the order they are listed in the response body. If a custom rule’s expression is matched, the action is executed.
- The
managed_challenge
,js_challenge
,legacy_captcha
,block
, andskip_custom_rules
actions stop further custom rule evaluation and no other rules in the ruleset are evaluated. - The
skip_waf
,skip_security_level
, andlog
actions do not stop custom rule evaluation.
When creating or updating a custom rule, users can provide a position
attribute in the request body to insert the rule at a certain relative position in the ruleset. If the position is not provided during rule creation, the rule is added to the end of the ruleset by default. See the following usage examples:
This endpoint creates a custom rule in the specified zone.
- The
description
,expression
, andactions
attributes are required. - The
enabled
andposition
attributes are optional. - Refer to the Validation Overview section for more information on input validation
Newly created rules are enabled by default and added to the end of the ruleset unless specified otherwise. A maximum of 50 custom rules is allowed.
Response body contains the custom rule that was created.
This endpoint returns all of the custom rules in the specified zone. If no custom rules exist, a 404 Not Found response is returned.
Response body contains all of the existing custom rules in the specified zone.
This endpoint returns the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.
Response body contains the requested custom rule.
This endpoint updates the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.
- The user must provide at least one of the following attributes in the request body:
description
,expression
,actions
,enabled
, orposition
.
Response body contains the requested rule.
This endpoint updates the order of all existing custom rules. The user provides an array of ruleIds
that represents the new rule order. The array must contain exactly all of the existing custom rule ruleIds.
Response body contains all of the existing custom rules in updated rule order.
This endpoint deletes the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.
-
How are custom rules different from firewall rules?
- With custom rules, you have more flexibility when creating the rule expression. While both custom rules and firewall rules offer the ability to set up firewall policies for your storefront, custom rules offer an expanded set of supported actions and expression fields. In particular, custom rules expressions allow fields like URI Path (
http.request.uri.path
) and User Agent (http.user_agent
).
- With custom rules, you have more flexibility when creating the rule expression. While both custom rules and firewall rules offer the ability to set up firewall policies for your storefront, custom rules offer an expanded set of supported actions and expression fields. In particular, custom rules expressions allow fields like URI Path (
-
Can I continue to create and use firewall rules?
- Yes, the firewall rule endpoints will still be functional until we deprecate them by February 1st 2024. When we deprecate the firewall rule endpoints, we will convert all existing firewall rules to custom rules. Following the deprecation date, customers should use only the custom rules endpoints moving forward. Please expect more information to come regarding the deprecation plan.
-
In what order will firewall rules and custom rules be evaluated?
- Firewall rules will be evaluated before custom rules.
-
How do I construct the rule expression?
- See the Cloudflare documentation for more information regarding constructing rule expressions.