Bot Defender APICustom Rules

Custom rule operators and conditions

When sending a custom rule in a request body, you must specify the conditionType, operator, value, and sometimes the fieldOption. Depending on the conditionType, there are certain allowed operator values, and the data type of value and fieldOption may change. You must adhere to the specifications of these below, or your rule won’t properly update.

Operator definitions

The following allowed operator values correspond to operators in the HUMAN platform.

Operator valueOperator nameDescription
$eqisChecks if the value is equal to the specified value.
$containscontainsChecks if the value contains the specified substring.
$startsWithstarts withChecks if the value starts with the specified substring.
$endsWithends withChecks if the value ends with the specified substring.
$rematchesChecks if the value matches the specified regular expression.
$notEndsWithnot ends withChecks if the value does not end with the specified substring.
$neis notChecks if the value is not equal to the specified value.
$ininChecks if the value is in the specified list of values.
$notInnot inChecks if the value is not in the specified list of values.
$existsexistsChecks if the field exists.
$notExistsnot existsChecks if the field does not exist.

Supported operators by condition type

The conditionType dictates the field upon which the operator should act. Each conditionType has a certain set of supported operator values with specific value data types. Be sure to reference the relevant conditionType for the available operator values.

User agent (userAgent)

Supported operatorvalue typevalue format
$eqString
$containsString
$startsWithString
$endsWithString
$reArray of stringsValid regex expression

Examples

1{   
2    "conditionType": "userAgent",
3    "operator": "$re",
4    "value": ["Mozilla.*", "Chrome.*"],
5}
6
7{
8    "conditionType": "userAgent",
9    "operator": "$startsWith",
10    "value": "Mozilla",
11}

Domain (domain)

Supported operatorvalue typevalue format
$endsWithString
$notEndsWithString
$eqString
$neString
$reArray of stringsValid regex expression

Examples

1{
2    "conditionType": "domain",
3    "operator": "$notEndsWith",
4    "value": ".com",
5}
6
7{
8    "conditionType": "domain",
9    "operator": "$eq",
10    "value": "test-site",
11}

IP address (socketIps)

Supported operatorvalue typevalue format
$eqStringValid IP address
$neStringValid IP address
$inArray of stringsValid IP address
$notInArray of stringsValid IP address

Examples

1{
2    "conditionType": "socketIps",
3    "operator": "$in",
4    "value": [
5    "2001:db8:3333:4444:5555:6666:7777:8888",
6    "2001:db8:3333:4444:CCCC:DDDD:EEEE:FFFF",
7    "2.2.2.2",
8    "1.1.1.1",
9    "128.5.5.5/8",
10    "3.3.3.3/4",
11    ],
12}
13
14{
15    "conditionType": "domain",
16    "operator": "$ne",
17    "value": "128.5.5.5/8",
18}

ASN (socketIpASN)

Supported operatorvalue typevalue format
$eqStringAS<number>
$neStringAS<number>
$inArray of stringsAS<number>
$notInArray of stringsAS<number>

Examples

1{   
2    "conditionType": "socketIpASN",
3    "operator": "$notIn",
4    "value": ["AS61", "AS21", "AS55"],
5}
6
7{   
8    "conditionType": "socketIpASN",
9    "operator": "$ne",
10    "value": "AS61",
11}

Path (path)

Supported operatorvalue typevalue format
$startsWithString
$endsWithString
$containsString
$eqString
$reArray of stringsValid regex expression

Examples

1{
2    "conditionType": "path",
3    "operator": "$startsWith",
4    "value": "/login",
5}
6
7{ 
8    "conditionType": "path",
9    "operator": "$re",
10    "value": ["\/login.*", "\/sign-.*"],
11}

Query parameter (queryParam)

The queryParam condition also requires the fieldOption parameter, as described below.

Supported operatorfieldOption typevalue typevalue format
$existsString
$notExistsString
$inStringString
$notInStringString
$reArray of stringsStringValid regex expression

Examples

1{   
2    "conditionType": "queryParam",
3    "fieldOption": "param1",
4    "operator": "$exists",
5}
6
7{   
8    "conditionType": "queryParam",
9    "fieldOption": "param2",
10    "operator": "$re",
11    "value": ["value", "value2"],
12}

Header (header)

The header condition also requires the fieldOption parameter, as described below.

Supported operatorfieldOption typevalue typevalue format
$existsString
$notExistsString
$inStringString
$notInStringString
$reArray of stringsStringValid regex expression

Examples

1{   
2    "conditionType": "header",
3    "operator": "$exists",
4    "fieldOption": "header-1",
5}
6
7{   
8    "conditionType": "header",
9    "fieldOption": "header-1.1",
10    "operator": "$notIn",
11    "value": ["value1", "value2"],
12}

HTTP method (httpMethod)

Supported operatorvalue typevalue options
$inString”GET”, “POST”, “DELETE”, “PATCH”, “PUT”, “HEAD”, “OPTIONS”, “CONNECT”, “TRACE”
$notInString”GET”, “POST”, “DELETE”, “PATCH”, “PUT”, “HEAD”, “OPTIONS”, “CONNECT”, “TRACE”

Examples

1{ 
2    "conditionType": "httpMethod",
3    "operator": "$in",
4    "value": ["GET", "POST"],
5}

Device type (deviceType)

Supported operatorvalue typevalue options
$eqString”desktop”, “mobile”, “mobile_api”, “other”
$inString”desktop”, “mobile”, “mobile_api”, “other”

Examples

1{   
2    "conditionType": "deviceType",
3    "operator": "$eq",
4    "value": "desktop",
5}
6
7{
8    "conditionType": "deviceType",
9    "operator": "$in",
10    "value": ["desktop", "mobile_api"],
11}

Country (country)

Supported operatorvalue typevalue options
$inStringValid country code
$notInStringValid country code

Examples

1{
2    "conditionType": "country",
3    "operator": "$notIn",
4    "value": ["IR"],
5}
6
7{   
8    "conditionType": "country",
9    "operator": "$in",
10    "value": ["US", "UK"],
11}

Custom parameter (customParam)

The customParam condition also requires the fieldOption parameter, as described below.

Supported operatorfieldOption optionsvalue typevalue format
$exists”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”
$notExists”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”
$eq”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”String
$ne”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”String
$in”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”Array of strings
$notIn”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”Array of strings
$re”custom_param1”, “custom_param2”, “custom_param3”, “custom_param4”, “custom_param5”, “custom_param6”, “custom_param7”, “custom_param8”, “custom_param9”, “custom_param10”Array of stringsValid regex expression

Examples

1{
2    "conditionType": "customParam",
3    "fieldOption": "custom_param1",
4    "operator": "$re",
5    "value": ["^(?!user).*$","^(?!email).*$"],
6}
7
8{
9    "conditionType": "customParam",
10    "fieldOption": "custom_param5",
11    "operator": "$notExists",
12}