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

Due to the highly technical aspect of the advanced rules functionality, the ability to create and edit these rules is currently only available through our API.

Check out the following guides for details on how to create 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 blocked the request. allow: WAAP allowed the request. captcha: WAAP presented the user with a CAPTCHA handshake: WAAP performed automatic browser validation. tag: WAAP will generate a tag with no action.	**Required. **On tag action, the tag field should be provided. For the block action, setting up the status_code (integer) and action_duration (time in seconds) is optional. By default, the status is set to "status_code": 403, and duration equals to 0s.
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

You can use our API documentation as a guide when constructing your own advanced rules. The following sections provide examples of advanced rules created via our API using cURL.

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, using a condition such as ... or tags.exists('penalty'), 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 by:

• Using the WAAP API via the Advanced Rules retrieval endpoint.
• Using the Gcore Customer Portal, where rules can be enabled, disabled, or deleted.