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.
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.
Reference the verified-bot fields (cf.client.bot, cf.verified_bot_category) and the Leaked Credentials Detection fields (cf.waf.auth_detected, cf.waf.credential_check.password_leaked, cf.waf.credential_check.username_and_password_leaked, cf.waf.credential_check.username_leaked, cf.waf.credential_check.username_password_similar) in custom rule expressions. See Rule Expression for field descriptions.
The maximum length of a custom rule expression is 4096 characters.
Note
Leaked Credentials Detection and the SLAS login API: Leaked Credentials Detection scans the Authorization header for HTTP Basic Authentication credentials. Use the cf.waf.credential_check.* fields on SLAS login endpoints (for example, /shopper/auth/v1/organizations/{organizationId}/oauth2/login) and on storefront login endpoints (for example, /Account-Login).
Note
Challenge actions on SLAS login endpoints: Don’t apply js_challenge, legacy_captcha, or managed_challenge to SLAS login endpoints in a custom rule. SLAS login is API-based, not a browser page, so the endpoint cannot present an interactive challenge. Unless the storefront interprets the challenge response and presents a challenge to the shopper, a Challenge action behaves like a permanent block: a shopper whose credentials appear in a leak has no way to prove they are human and log in. Start the rule with the log action. While the rule is in log mode, monitor the traffic that matches it and assess whether those requests are safe to block—or, if the storefront can present a challenge, safe to Challenge.
Important
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"]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.
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.skip_security_level, skip_rate_limiting_rules, skip_wafv2, 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:
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}The following examples show common custom rules. Combine and adjust them to your own business needs.
(http.request.uri.path contains "/Cart-AddProduct" and not cf.client.bot)managed_challenge(ip.src.country in {"CU" "IR"} and not cf.client.bot)block(http.request.uri.path contains "/Account-Login" and cf.waf.credential_check.password_leaked)managed_challengeThis endpoint creates a custom rule in the specified zone.
description, expression, and actions attributes are required.enabled and position attributes are optional.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}'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}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'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}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'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}This endpoint updates the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.
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}'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}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}'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}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'
j