Policy Engine DSL

The Policy Engine can override the action in the Mitigation API response by implementing a custom policy (a set of rules). You can edit policies using the API.

If a valid policy name is specified in the Mitigation API decision request, the policy engine will execute the named policy and override the action in the Mitigation API decision response.

When a policy name is not included, the default logic of the Mitigation Engine is as follows:

if decision.threatProfile = "BOT" then block
default allow

A Policy consists of a policy name, a version, zero or more rules, and a default clause. A policy can be up to 10KB in size. You can up have up to 10 policies.

A Rule consists of a rule label (identifier), a match expression, and an action. The match expression can reference HUMAN decisioning data or customer provided clientds (a.k.a. business signal) for logical operations, scalar expressions, regular expression, or set inclusion. A rule can reference an inline list or an external set.

An external Set is a list of same type items. Supported types are "ip", "string", and "uint". A single set can have up to 100KB in size.

Common Use Cases

Here are some good ways to use the policy engine:

  1. Having a policy for stage vs. production environments (prefix policy name to make it clear).
  2. Include an allowlist for good bots, e.g. test bots or QA bots.
  3. Adjusting action by surface and threat pofile, 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 backend can reference either or.
  5. Phased roll out of mitigation strategy, start with allow all, then update policy to block (or custom action) on specific Threat Profile or Threat Categories or pages.

Conventions

Policy Example

The policy below shows the use of a number of features:

  • 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, 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
  • 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 processing return the custom action of mfa
    1. Note:could have combined with above in hasAny set operation, however showing example of using map of booleans.
  9. If the decision threatProfile is "NSD", then stop processing return the custom action of delay.
  10. 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 !~ /^https\:\/\/.*\.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")

default allow

Grammar

Start (start)

start

Rule Chains (chain)

chain

Match Expressions (matchExpr)

matchExpr

Logical Operators

andExpr andExpr orExpr orExpr

Scalar Expressions

eqExpr eqExpr

regularExpr

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

inCIDRExpr inCIDRExpr

Set Inclusion

inInlineListExpr inInlineListExpr

inlineStringList inlineStringList

inlineUnsignedIntList inlineUnsignedIntList

inExternalListExpr

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

Available Variables

A contextVar has two namespaces, clientds and decision.

contextVar contextVar

decision Fields

  • decision: An key-value mapping of bot classification.
    • bot: (boolean) if threatProfile is equals to "BOT".
    • threatProfile: (string) Eg. "BOT", "NSD", or "VAL".
    • threatCategory: (map of string to true)
    • Example string's: "BOT-ENT_BVR", "NSD-ENT_BVR", or "VAL-NEU".

Actions

anAction anAction

userDefinedAction userDefinedAction

defaultAction

defaultAction is either allow or block. defaultAction