Advanced Rules

Info

This feature is available in selected plans. For up-to-date information on plan availability, see the billing documentation.

Similarly to WAAP custom rules, you can create, edit, and manage advanced custom rules. These rules also contain “If/Then” statements, but they support more complex conditions created with the Common Expression Language (CEL) syntax.

Create advanced rules

You can create and edit advanced rules in the Gcore Customer Portal or via our API. Advanced rules use the same If/Then structure as custom rules, but support more complex conditions written in Common Expression Language (CEL) syntax.

In the Customer Portal

1. In the Gcore Customer Portal, navigate to WAAP > Custom Rules.
2. Click Add custom rule to create a new rule, or open an existing rule to edit it.
3. Enter a Rule name and set the Status toggle as needed.
4. Under Rule type, select Advanced Rule.
5. In the Define rule section, configure the rule logic:
   • If: Select the domain or zone the rule applies to.
   • And: Add one or more conditions by choosing Object, Attribute, Operator, and Value. Click + to add additional conditions. To build more complex logic, select Group as the object type to add a nested group of conditions. Groups support And, Or, and If operators and can be nested inside each other to create layered rule logic.
   • Then: Select the action: Block, Allow, Captcha, JS Challenge (Handshake), or Tag. For Block, set the status code and optional block duration; for Tag, enter one or more tags.
   • Phase: Choose when the rule is evaluated (for example, Access (request phase)).
6. Review the generated Expression. To write or modify the CEL expression directly, click Edit manually.
7. Optionally, use a Quick Template to prefill common advanced rule configurations, such as brute force protection, blocking sanctioned countries, or rate limiting.
8. Click Save.

Tip

Use the visual rule builder to define conditions step by step. The portal generates the underlying CEL expression automatically. Switch to Edit manually when you need full control over the expression syntax.

The following Quick Templates are available for advanced rules:

• Block Fake Account Creation
• Brute Force Protection
• Challenge Suspicious User-Agent
• Block Malicious Automation
• Block Sanctioned Countries
• Form Spam Prevention
• Block Inventory Hoarding
• Block Dangerous Uploads
• Captcha Rate Limit 100 req/5s
• Block Rate Limit 200 req/5s
• Block Penalized Requests

Via API

You can also create and manage advanced rules programmatically using our API. This approach is useful for automation, bulk operations, or integration with your own tooling.

Check out the following guides for details on how to construct advanced rules and their key components:

• API docs: Learn how to construct and manage advanced rules.
• Advanced rule objects and attributes: Get the list of all available objects you can use in rule expressions along with their respective attributes and types.
• Source field objects: Check the available source field objects you can use in your expressions along with their respective attributes and types.

Advanced rule properties

The advanced rule object contains the following properties:

{
  "name": "string",
  "description": "",
  "enabled": true,
  "action": {
    "allow": {},
    "block": {
      "status_code": 403,
      "action_duration": "string"
    },
    "captcha": {},
    "handshake": {},
    "tag": {
      "tags": [
        "string"
      ]
    }
  },
  "source": "string",
  "phase": "access"
}

Info

Each rule can contain only one action—block, allow, captcha, handshake, or tag. If you use multiple actions in a single rule, the API will return an error.

Description of the properties

Field	Description	Values	Details
name	Rule name	Can contain only ASCII letters, numbers, spaces, periods, and colons.	Required.
action	The action to execute when a condition is true.	block: WAAP blocks the request. allow: WAAP allows the request. captcha: WAAP presents the user with a CAPTCHA. handshake: WAAP presents a JS Challenge. tag: WAAP generates a tag with no action.	Required. For the tag action, provide the tags list (1–5 tags). For the block action, optional fields: status_code (403 default; also accepts 405, 418, 429) and action_duration (a value above zero with optional unit s/m/h/d). If action_duration is omitted, no block duration is applied.
source	The condition part of the rule.	Can reference namespace objects: request, whois, session, response, tags, user_agent, client_data, as well as use data and functions. Supported Python operand syntax: and, or, in, not, ==, !=, >, <, etc. Supported CEL operand syntax: ||, &&	Required. Every string value should be enclosed in single quotation marks ' and not in double quotation marks ".
enabled	Whether or not the rule is enabled.	Boolean: true or false	Required.
description	A string to describe the purpose of the rule.	Any string. The character limit for the description field is 100 characters.
phase	The request processing phase.	access: The advanced rule applies to the request phase (request headers and body available). header_filter: The advanced rule applies to the response headers phase. body_filter: The advanced rule applies to the response body phase.	Default value: access

Best practices

The following sections provide examples of advanced rules you can create in the Gcore Customer Portal or via our API. Use the visual rule builder and Quick Templates for common scenarios, or adapt the API examples below when you need programmatic control.

Note

Examples are illustrative. Field values (paths, cookies, IPs, countries) should be adapted to the customer’s environment.

Rate limiting

You can rate limit IPs based on the number of requests they make to your website. For example, this can be useful for mitigating scrapers or automated clients that generate a high volume of requests over a short period of time.

You can find more examples in our Rate limiting guide.

The following rule limits the rate of requests an IP can send for 10 minutes, when it exceeds 200 requests in 5 seconds, but excludes requests from mobile or web clients that have specific cookies.

Rate Limiting curl example

curl --request POST \
--url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
  "action": {
    "block": {
      "status_code": 403,
      "action_duration": "10m"
    }
  },
  "phase": "access",
  "name": "Block Scrappers",
  "description": "Block IPs that hit more than 200 requests per 5 seconds for any `events` paths",
  "enabled": false,
  "source": "((request.limit_rate(url='.*events', interval=5, requests=200, scope='ip')) and not ('mb-web-ui' in request.headers['Cookie'] or 'mb-mobile-ios' in request.headers['Cookie'] or 'mobile-android' in request.headers['Cookie'] or 'mb-mobile-android' in request.headers['Cookie'] or 'session-token' in request.headers['Cookie']) and not request.headers['session']) or tags.exists('penalty')"
}'

The penalty tag

The WAAP system appends the penalty tag to the local (domain-related) IP record when an IP address triggers a block rule configured with an action_duration parameter.

To continue blocking an IP address after the original rule’s conditions are no longer met, include a penalty tag check in the rule’s source conditions (for example, by appending or tags.exists('penalty') to the existing conditions), or define a separate rule that targets requests carrying the penalty tag. The following example illustrates this approach.

Block all penalty requests

The following rule blocks requests from IP addresses tagged with the penalty tag, allowing block actions applied by other rules to persist.

Block penalty-tagged IP requests

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Block Penalized Requests",
    "description": "Block requests from IP addresses tagged with the penalty tag",
    "enabled": false,
    "phase": "access",
    "action": {
      "block": {}
    },
    "source": "tags.exists('penalty')"
  }'

Other examples

Validate a set of countries

Demonstrates how to apply browser validation (JavaScript-based challenge) using the handshake action to requests originating from specific countries, based on the whois.country field, while excluding requests that contain certain cookies.

Validate a set of countries

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "action": {
      "handshake": {}
    },
    "phase": "access",
    "name": "Validate set of countries",
    "description": "Validate with JavaScript challenge IPs that are coming from the following countries",
    "enabled": false,
    "source": "whois.country in ['BR', 'VN', 'ID', 'TH', 'ME', 'XK', 'LK'] and not ('mb-web-ui' in request.headers['Cookie'] or 'mb-mobile-ios' in request.headers['Cookie'] or 'mobile-android' in request.headers['Cookie'] or 'mb-mobile-android' in request.headers['Cookie'])"
  }'

Add clients to allow list

Demonstrates how to allow requests from specific IP addresses or IP ranges by matching IP values in the rule condition.

Add clients to allow list

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Whitelist known IPs",
    "enabled": false,
    "action": {
      "allow": {}
    },
    "source": "request.ip == '117.20.32.5' or request.ip == '117.20.32.4' or request.ip_in_range('72.21.217.0', '72.21.217.255')"
  }'

Tag and allow registered clients

Demonstrates how to tag requests based on the presence of a specific cookie and allow requests associated with the assigned tag. When defining tag values in JSON, double quotation marks must be used, while string values inside rule expressions must be enclosed in single quotation marks.

Tag registered clients

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Tag registered clients",
    "description": "Detect and tag registered clients by cookie",
    "enabled": false,
    "phase": "access",
    "source": "'mb-mobile-android' in request.headers['Cookie']",
    "action": {
      "tag": {
        "tags": ["registered"]
      }
    }
  }'

Allow registered clients

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Allow registered clients",
    "description": "Allow registered clients",
    "enabled": false,
    "phase": "access",
    "source": "tags.exists('registered')",
    "action": {
      "allow": {}
    }
  }'

Define login pages

Demonstrates how to tag requests that match specific URL patterns using string matching on the request URI.

Define login pages

curl --request POST \
  --url https://api.gcore.com/waap/v1/domains/{domain_id}/advanced-rules \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Detect and Tag Login Pages",
    "enabled": false,
    "phase": "access",
    "source": "['url1/login','url2/signup'] in request.uri",
    "action": {
      "tag": {
        "tags": ["login page"]
      }
    }
  }'

Review existing rules

Advanced rules can be reviewed, created, edited, enabled, disabled, or deleted in the Gcore Customer Portal on the WAAP > Custom Rules page. Advanced rules appear alongside other custom rules and are identified by the Advanced Rule type.

You can also retrieve and manage advanced rules programmatically using the Advanced Rules retrieval endpoint.