Skip to main content
InfoThis 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"
}
InfoEach 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.
FieldDescriptionValuesDetails
nameRule nameCan contain only ASCII letters, numbers, spaces, periods, and colons.Required.
actionThe 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.
sourceThe 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 ".
enabledWhether or not the rule is enabled.Boolean: true or falseRequired.
descriptionA string to describe the purpose of the rule.Any string.
The character limit for the description field is 100 characters.
phaseThe 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. All examples were validated against the current WAAP API during review, returned 201 Created, and reflect the required fields and current syntax.
NoteExamples 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:
Advanced rules section with a sample penaly fingerprint rule