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:

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:

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.

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.

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
3

{
  "foo": "bar"
}

Then the name of the Post Parameter will need to be /foo in the rule.

The leading / on of Post Parameter name facilitates nested values. For example, /foo/bar for a payload such as:

1
2
3
4
5

{
  "foo": {
    "bar": ["value1", "value2"]
  }
}

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.