Defining rule conditions
Last updated 2024-08-28
When creating rules, you define a set of conditions that outline the circumstances under which requests should be allowed, blocked, rate limited, or tagged.
About rule conditions
A rule condition is made up of a field, an operator, and a value.
Fields
A rule conditions is based on a specific field.
When creating a request rule or an advanced rate limiting rule, you can base a rule’s conditions on the following request fields:
Field | Type | Properties |
---|---|---|
Agent name | String | Text or wildcard |
Country | Enum | ISO countries |
Domain | String | Text or wildcard |
IP address | IP | Text or wildcard, supports CIDR notation |
JA3 Fingerprint | String | Text |
Method | Enum | GET, POST, PUT, PATCH, DELETE, HEAD, TRACE |
Path | String | Text or wildcard |
POST parameter | Multiple | Name (string), Value (string), Value (integer) |
Query parameter | Multiple | Name (string), Value (string), Value (integer) |
Request cookie | Multiple | Name (string), Value (string), Value (integer) |
Request header | Multiple | Name (string), Value (string), Value (IP), Value (integer) |
Response code | String | Text or wildcard |
Response header | Multiple | Name (string), Value (string) |
Scheme | Enum | http, https |
Signal | Multiple | Type (signal), Parameter name (string), Parameter value (string) |
User agent | String | Text or wildcard |
When creating a signal exclusion rule, you can base the rule conditions on the same request fields and fields specific to the particular signal that is being excluded:
Field | Type | Properties |
---|---|---|
Parameter name | String | Text or wildcard |
Parameter value | String | Text or wildcard |
Operators
When creating rules, operators are used to specify the logic of your rule when matching conditions. For example, the equals operator is used to check if a value in the request matches the value in the rule condition exactly, such as when attempting to match a specific IP address or path.
Operator | Description | Example Match |
---|---|---|
Equals | Checks if the request value matches the rule condition value exactly. | 203.0.113.169 Equals 203.0.113.169 |
Does not equal | Checks if the request value does not match the rule condition value exactly. | 203.0.113.169 Does not equal 192.0.2.191 |
Contains | Checks if the rule condition value being checked is contained within the request value; for example, to check if a substring is found within a larger string. | thisisanexamplestring Contains example |
Does not contain | Checks if the rule condition value being checked is not contained within the request value; for example, to check if a substring is not found within a larger string. | thisisanexamplestring Does not contain elephant |
Greater than or equal to | Checks if the request value is greater than or equal to the rule condition value | 12 Greater than or equal to 10 |
Less than or equal to | Checks if the request value is less than or equal to the rule condition value | 10 Less than or equal to 12 |
Like (wildcard) | Allows the use of wildcard characters in matching; checks if the request value matches the rule condition value. | bats Like (wildcard) [bcr]ats |
Not like (wildcard) | Allows the use of wildcard characters in matching; checks if the request value does not match the rule condition value. | bats Not like (wildcard) [hps]ats |
Matches (regexp) | Allows the use of regular expressions in matching; checks if the request value matches the rule condition value. Platform availability: Professional and Premier. | bats Matches (regexp) (b|c|r)ats |
Does not match (regexp) | Allows the use of regular expressions in matching; checks if the request value does not match the rule condition value. Platform availability: Professional and Premier. | bats Does not match (regexp) (h|p|s)ats |
Is in list | Checks if the request value matches any of the values in a specific list. Platform availability: Professional and Premier. | 203.0.113.169 Is in list Known IP Addresses |
Is not in list | Checks if the request value does not match any of the values in a specific list. Platform availability: Professional and Premier. | 192.0.2.191 Is not in list Known IP Addresses |
Exists where | Allows for name-value pair subconditions in matching; checks if the subconditions exist in the request value. | Request value: Content-Type: application/xml Condition: Request Header Exists whereSubconditions: Name Equals Content-Type And Value (string) Equals application/xml |
Does not exist where | Allows for name-value pair subconditions in matching; checks if the subconditions do not exist in the request value. | Request value: Content-Type: application/xml Condition: Request Header Does not exist whereSubconditions: Name Equals Content-Type And Value (string) Equals application/json |
Wildcards
The Like
(wildcard) operator uses glob syntax and supports 0-or-many wildcards (*
), single-character wildcards (?
), character-lists ([abc]
), character-ranges ([a-c]
, [0-9]
), alternatives ({cat,bat,[fr]at}
), and exclusions ([!abc]
, [!0-9]
).
If you need to match a literal *
, ?
, [
, or ]
character, escape them with the \
character. For example: \*
.
The Like
(wildcard) operator requires a full string match. If you're trying to match part of a string, you may need to include the *
wildcard at the beginning or end to include the rest of the string for correct matching.
Regular expressions are not supported with the Like
(wildcard) operator. If you want to use regular expressions, you must use the Matches
(regexp) operator.
Field value case sensitivity
All fields in rules are case sensitive with the exception of header names.
For example, if you create a rule that looks for a header named X-Custom-Header
, it will match on requests with headers named X-Custom-Header
and x-custom-header
because header names aren't case sensitive. However, if the rule looks for the value Example-Value
, it will only match on Example-Value
and not example-value
because all other rule fields—such as header values in this example—are case sensitive.
NOTE
When constructing a regular expression pattern (regexp) that matches on a header name, POST parameter name, or query parameter name, write the pattern in all lowercase or prefix the pattern with a case insensitive regex matching mode of (?i)
.
Path syntax best practices
When basing a rule condition on the Path field, keep these best practices in mind:
Always use leading slashes. For a URL like
https://example.com/some-path
, the correct path syntax to use would be/some-path
.Use relative paths instead of absolute URLs. For example, if the absolute URL to the login page on your site is
https://example.com/login
, then/login
is the correct path syntax to enter when configuring your login signals.Take care when using trailing characters in your paths. Since our path syntax uses exact matching, trailing characters can sometimes return zero matches. Consider an example where the path to your login page is
https://example.com/login/
:/login/
will return a match./login
with not return a match.
Post Parameter field
When creating rules that inspect the JSON body of POST requests, Post Parameter names require a leading /
. For example, if the JSON payload is:
1{2 "foo": "bar"3}
Then the name of the Post Parameter will need to be /foo
in the rule.
- Next-Gen WAF control panel
- Fastly control panel
The leading /
on of Post Parameter name facilitates nested values. For example, /foo/bar
for a payload such as:
1{2 "foo": {3 "bar": ["value1", "value2"]4 }5}
Country field
The Country field allows you to specify conditions that match against a particular country to block or allow traffic. Geolocation can be combined with other conditions like path or domain.
Where does the geodata come from?
We license MaxMind’s Geolite2 data and distribute it within our agent. This data is updated periodically and included with newer agent releases as well as dynamically updated similar to rule updates.
How often is geodata updated?
We update our geodata and release an agent monthly (typically the second week of the month). At the same time as the agent release, the new geodata is deployed to our cloud tagging so that the latest country information is present. This will be a minor agent increment. This data is also dynamically updated similar to rule updates and these agents will download and cache the updated geolocation data.
What happens if my agent is out-of-date?
If your agent is out-of-date, then an IP may be blocked or allowed based on outdated geo information. Or requests may display in the control panel that would have been blocked with newer geodata. The country displayed in the control panel will reflect the latest available geodata.
How do dynamic geolocation data updates work?
The geolocation data is packaged up for the agent to download whenever there is an update. This data is cached locally on the agent machine. The cache location is under the shared-cache-dir directory which defaults to {$TMPDIR|%TMP%|%TEMP%}/sigsci-agent.cache/
. The geolocation data is only downloaded if it does not exist locally or the data is not up-to-date.
Requirements for this functionality:
- The filesystem where this cache directory resides must be:
- Writeable by the person running the agent
- Have at least 5MB of free space
- While auto-detection of the cache directory normally works fine, you may need to configure shared-cache-dir on some systems where a TEMP space is not defined (e.g., where
$TMPDIR
or%TMP%
or%TEMP%
environment vars are not set properly)
- The network must be capable of:
- Downloading from the base download-url (this is the same base URL as normal rule updates)
- Downloading the data (currently about 2MB) within the timeout limit (currently 60 seconds)
If the dynamic geolocation data cannot be downloaded, then the agent will default to the geolocation data packaged with the agent.
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.