Defining rule conditions

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:

FieldTypeProperties
Agent nameStringText or wildcard
CountryEnumISO countries
DomainStringText or wildcard
IP addressIPText or wildcard, supports CIDR notation
JA3 FingerprintStringText
MethodEnumGET, POST, PUT, PATCH, DELETE, HEAD, TRACE
PathStringText or wildcard
POST parameterMultipleName (string), Value (string), Value (integer)
Query parameterMultipleName (string), Value (string), Value (integer)
Request cookieMultipleName (string), Value (string), Value (integer)
Request headerMultipleName (string), Value (string), Value (IP), Value (integer)
Response codeStringText or wildcard
Response headerMultipleName (string), Value (string)
SchemeEnumhttp, https
SignalMultipleType (signal), Parameter name (string), Parameter value (string)
User agentStringText 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:

FieldTypeProperties
Parameter nameStringText or wildcard
Parameter valueStringText 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.

OperatorDescriptionExample Match
EqualsChecks if the request value matches the rule condition value exactly.203.0.113.169 Equals 203.0.113.169
Does not equalChecks if the request value does not match the rule condition value exactly.203.0.113.169 Does not equal 192.0.2.191
ContainsChecks 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 containChecks 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 toChecks if the request value is greater than or equal to the rule condition value12 Greater than or equal to 10
Less than or equal toChecks if the request value is less than or equal to the rule condition value10 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 listChecks 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 listChecks 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 whereAllows 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 where
Subconditions:

Name Equals Content-Type
And
Value (string) Equals application/xml
Does not exist whereAllows 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 where
Subconditions:

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.

  1. Next-Gen WAF control panel
  2. Fastly control panel

An example rule using the condition of a Post Parameter with the name /foo and the value of bar.

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.

Was this guide helpful?

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.