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.

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 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.
• skip_rate_limiting_rules - Skips rate limiting rules. See eCDN Rate Limiting Rules for related documentation.

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, and skip_custom_rules actions stop further custom rule evaluation and no other rules in the ruleset are evaluated.
• The skip_waf, skip_security_level, and log 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, and actions attributes are required.
• The enabled and position attributes are optional.
• Refer to the Validation Overview section for more information on input validation

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, or position.

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.

As of February 6th, 2024, the createFirewallRule and updateFirewallRule endpoints are deprecated and are no longer available. Existing firewall rules have been migrated to custom rules, and are accessible using both custom rule and firewall rule endpoints. The getFirewallRules, getFirewallRule, and deleteFirewallRule endpoints are still available to assist in the transition to custom rules, but will be deprecated in the near future.

Use the getCustomRules endpoint to view your custom rules. Your existing firewall rules and any custom rules that you created are included in the response.

If you have an existing allowlist firewall rule, the getCustomRules endpoint returns an additional Block All rule. The Block All rule was created by CDN-API to block all remaining traffic after configured allowlist rules are run. Previously, this rule was not displayed in the firewall rules API response. To provide more flexibility and control over your traffic, this rule is now exposed in the custom rules API response.

Use the getCustomRules endpoint to return Block All rule information, as shown in the following example response. If you created multiple allowlist firewall rules, then multiple allowlist rules are included in the response, for example:

• The first rule includes an allowlist that is specified using expression (either country, IP, or ASN), for example: (ip.geoip.country in {\"US\"}). Allowlist rules use the skip_custom_rules action, which means requests matching the allowlist are not evaluated by any custom rules that follow.
  • You can update this rule to include other skip options, for example: skip_rate_limiting_rules or skip_waf, based on your access control needs.
• The second rule provides Block All rule information. This includes the block action with expression defined as (ip.src in {0.0.0.0/0}). This blocks all remaining traffic following configured allowlist rules.
  • You are responsible for managing the Block All rule. You can delete this rule if you do not need it. If you keep it, remember that this rule must be last in the rule order. Rules listed after the Block All rule are never executed.

You can use either of the following options:

• Create an allowlist rule followed by a Block All rule. This option requires you to manage at least 2 separate rules, as shown in the previous example. Refer to the previous section for more details.
  • If a Block All rule exists, you do not need to create another.
  • The Block All rule must be last in the rule order.
• Create a block rule and use the not operator in the rule expression. For example:
  • This rule blocks all requests from any IP address that is not included in the list of IPs defined in expression. This rule immediately blocks requests from which the IP is not included in the expression. Therefore, this method does not work if you plan to define the allowlist across multiple rules. In this case, you should use the previous option.

Refer to IP Access Control.

• 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).

• 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.