Advanced Policy Engine Usage

This section provides more information on the full range of support for the policy engine syntax.

Advanced rule syntax

The policy below illustrates the use of a number of features. Please note that this policy is just meant to illustrate the usage of different syntax features and isn't optimized.

• Required rule labels like blockUser, allowASN, or allowEndpoint.
• Inline lists of strings, integers, and IP addresses.
• For longer lists, define a set and use the set's identifier instead of the inline list.
• An external set (list).
• String regular expression matching.
• User-defined actions, e.g. mfa.
• Reference to bot boolean in decision object.
• Reference to Threat Category using set operation.
• Reference to Threat Category string to boolean map in decision object.
• Reference to Threat Profile string in decision object.
• Execute a random defined action by executing a samplePercent function.
• A default action (this clause is required in each policy).

It executes the following:

1. If the client user id is "userID1" or "userID2", then stop processing and return the action of block.
2. If the client's IP came from an ASN of 1, 2, 3, or 4, or from an ASN in the set CustomAllowASNSet, then stop processing and return the action of allow.
3. If the client is not accessing the customer's login endpoint, a protected resource, then stop processing and return the action of allow.
4. If the client's referrer is from outside of mydomain.com, then stop processing and return the action of allow.
5. If the client's IP is 1.2.3.4 or 5.6.7.8, then stop processing and return the action of allow.
6. If the decision is bot, then stop processing and return the action of block.
7. If the decision threatCategory has "NSD-BAD_REP" or "NSD-ANO_DEV", then stop processing return the custom action of mfa.
8. If the decision threatCategory has "NSD-LOC", then stop evaluating and return the custom action of mfa.
9. If the decision threatProfile is "NSD", then stop processing and return the custom action of delay.
10. If the sampleAction(10) returns a true value, then stop evaluating and return the custom action of randomBlock.
11. Otherwise, return the default action of allow.

version 1

blockUser:
if clientds.ui in ["userID1", "userID2"] then block

allowASN:
if or(
    decision.asn in [1, 2, 3, 4],
    decision.asn in CustomAllowASNSet
) then allow

allowEndpoint:
if nor(
    clientds.endpoint = "https://www.mydomain.com/api/v1/login",
    clientds.url = "https://www.mydomain.com/api/v1/login"
) then allow

allowReferrer:
if and(
    clientds.ref != "",
    clientds.ref !~ /^*\.mydomain\.com.*$/
) then allow

allowIP:
if clientds.ip in ["1.2.3.4", "5.6.7.8"] then allow

blockBot:
if decision.bot then block

mfaNSD:
if decision.threatCategory hasAny ["NSD-BAD_REP", "NSD-ANO_DEV"] then action("mfa")

mfaNSDLoc:
if decision.threatCategory.NSD-LOC then action("mfa")

delayNSD:
if decision.threatProfile = "NSD" then action("delay")

randomBlock:
if samplePercent(10) then action("randomBlock")

default allow

Additional use cases

Here are some good ways to use the policy engine:

1. Having separate policies for stage and production environments (postfix policy name to make it clear).
2. Including an allowlist for safe bots (e.g. test bots or QA bots).
3. Adjusting action by surface and threat profile, e.g. do action("mfa") when Threat Profile is NSD and URL is login.
4. A/B test mitigation strategy, e.g. have policy alpha and policy bravo and compare the results of their usage.
5. Phased roll out of mitigation strategy - start with allow all, then update policy to block (or custom action) on specific Threat Profiles or Threat Categories or pages.

DSL syntax

The following sections provide more detailed information about the syntax of the Policy Engine's domain-specific language (DSL).

Start (start)

Rule chains (chain)

Match expressions (matchExpr)

Logical operators

andExpr orExpr

Scalar expressions

eqExpr

regularExpr

Regexp is expressed as /{regularExpression}/ where the regularExpression is POSIX compatible.

inCIDRExpr

Set inclusion

inInlineListExpr

inlineStringList

inlineUnsignedIntList

inExternalListExpr

This represents a set inclusion expression against an externally defined set. See the Policy Engine API.

Available variables

A contextVar has two namespaces, clientds and decision.

contextVar

decision fields

The decision object is a key-value map of the decision returned by HUMAN for a given event. Each decision includes several keys with a variety of possible values:

bot: (Boolean) Whether or not HUMAN classified the event as a bot. If an event was classified as a bot, this value equals true.

threatProfile: (string) The threat profile associated with the event. Possible values are "BOT" (bot), "NSD" (nonstandard), and "VAL"(valid).

threatCategory: (array) A full list of threat categories associated with the event. Example values include "BOT-BOT", "NSD-ENT_BVR", and "NSD-ANO_USR".

Actions

A policy can return any string as an action. The following examples show how you can define those actions. anAction

userDefinedAction

defaultAction

The default action returned if an event doesn't meet the criteria for any of the policy's rules. In most use cases, you should set this value to allow.