eCDN Custom Rules

Use custom rules to control incoming traffic by setting up security policies based on request parameters. With custom rules, you have complete control over the rule expression, the allowed request field types, and the rule actions. This flexibility helps you create expressions that match your traffic needs. To create a custom rule in Business Manager, see Create a Custom Rule for an eCDN Zone in Salesforce Help.

Validation Overview

Rule Expression

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.

Note

Rule Actions

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.

Legacy captcha still exist through the API. However, Salesforce recommends selecting the managed challenge response for a better user experience.
Note
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_security_level - Skips Security Level.
skip_rate_limiting_rules - Skips rate limiting rules. See eCDN Rate Limiting Rules for related documentation.
skip_wafv2 - Skips WAFv2 managed rules. For additional information, see eCDN WAFv2.

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:

Important

1"actions": ["block"]
2
3"actions": ["skip_custom_rules", "skip_wafv2"]
4
5"actions": ["managed_challenge"]

Rule Order

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_security_level, skip_rate_limiting_rules, skip_wafv2, and log actions do not stop custom rule evaluation.

Position

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:

1# Places the rule before rule <RULE_ID>
2
3"position": {
4   "before": "<RULE_ID>"
5}
6
7or
8
9# Places the rule after rule <RULE_ID>
10
11"position": {
12   "after": "<RULE_ID>"
13}

Create a Custom Rule

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

Newly created rules are enabled by default and added to the end of the ruleset unless specified otherwise. A maximum of 500 custom rules is allowed.

Important

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
2--header "Authorization: Bearer $TOKEN" \
3--header 'Content-Type: application/json' \
4--data '{
5    "description": "Skip Merchant Approval",
6    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
7    "actions": ["skip_custom_rules", "skip_wafv2"],
8    "enabled": false,
9    "position": {
10        "before": "ffffe61cf25e4ec49c34b029ff3060f7"
11    }
12}'

Sample Success Response - 201 HttpStatus Code

Response body contains the custom rule that was created.

1{
2  "data": {
3    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
4    "description": "Skip Merchant Approval",
5    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
6    "actions": ["skip_custom_rules", "skip_wafv2"],
7    "lastUpdated": "2022-12-14T21:25:22.329194Z",
8    "enabled": false
9  }
10}

Get All Custom Rules

This endpoint returns all of the custom rules in the specified zone. If no custom rules exist, a 404 Not Found response is returned.

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
2--header "Authorization: Bearer $TOKEN" \
3--header 'Content-Type: application/json'

Sample Success Response - 200 HttpStatus Code

Response body contains all of the existing custom rules in the specified zone.

1{
2  "data": [
3    {
4      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
5      "description": "Skip Merchant Approval",
6      "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
7      "actions": ["skip_custom_rules", "skip_wafv2"],
8      "lastUpdated": "2022-12-14T21:25:22.329194Z",
9      "enabled": true
10    },
11    {
12      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
13      "description": "Block Cuba",
14      "expression": "(ip.src.country eq \"CU\")",
15      "actions": ["block"],
16      "lastUpdated": "2022-12-14T21:27:45.245836Z",
17      "enabled": true
18    }
19  ]
20}

Get a Custom Rule

This endpoint returns the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
2--header "Authorization: Bearer $TOKEN" \
3--header 'Content-Type: application/json'

Sample Success Response - 200 HttpStatus Code

Response body contains the requested custom rule.

1{
2  "data": {
3    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
4    "description": "Skip Merchant Approval",
5    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
6    "actions": ["skip_custom_rules", "skip_wafv2"],
7    "lastUpdated": "2022-12-14T21:25:22.329194Z",
8    "enabled": false
9  }
10}

Update a 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.

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
2--request 'PATCH' \
3--header "Authorization: Bearer $TOKEN" \
4--header 'Content-Type: application/json' \
5--data '{
6    "description": "Block Merchant Approval",
7    "actions": ["block"],
8    "enabled": false,
9    "position": {
10        "after": "ffffe61cf25e4ec49c34b029ff3060f7"
11    }
12}'

Sample Success Response - 200 HttpStatus Code

Response body contains the requested rule.

1{
2  "data": {
3    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
4    "description": "Block Merchant Approval",
5    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
6    "actions": ["block"],
7    "lastUpdated": "2022-12-14T21:27:22.329194Z",
8    "enabled": false
9  }
10}

Update the Order of All Custom Rules

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.

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
2--request 'PATCH' \
3--header "Authorization: Bearer $TOKEN" \
4--header 'Content-Type: application/json' \
5--data '{
6    "ruleIds": ["ffffe61cf25e4ec49c34b029ff3060f7", "2c0fc9fa937b11eaa1b71c4d701ab86e"]
7}'

Sample Success Response - 200 HttpStatus Code

Response body contains all of the existing custom rules in updated rule order.

1{
2  "data": [
3    {
4      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
5      "description": "Block Cuba",
6      "expression": "(ip.src.country eq \"CU\")",
7      "actions": ["block"],
8      "lastUpdated": "2022-12-14T21:27:45.245836Z",
9      "enabled": true
10    },
11    {
12      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
13      "description": "Skip Merchant Approval",
14      "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
15      "actions": ["skip_custom_rules", "skip_wafv2"],
16      "lastUpdated": "2022-12-14T21:25:22.329194Z",
17      "enabled": true
18    }
19  ]
20}

Delete a Custom Rule

This endpoint deletes the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
2--request 'DELETE' \
3--header "Authorization: Bearer $TOKEN" \
4--header 'Content-Type: application/json'

Sample Success Response - 204 HttpStatus Code (No Content)

Custom Rules FAQ

How do I construct the rule expression?
- See the Cloudflare documentation for more information regarding constructing rule expressions.