Get Bot Rule Set

WAF Insights does not support automation via our REST API web service. If you are currently using WAF Insights, upgrade your WAF solution to take advantage of our REST API.

Retrieves a bot rule set. A bot rule set contains one or more bot rules. Each bot rule defines the set of requests that will require a client (e.g., a web browser) to solve a challenge before resolving the request.

Key information:

• There are two types of bot rules:

  • Reputation Database: A bot rule that relies on our reputation database is defined through the directive.include property.

    Example:

    {
    	"directive": [{
    			"include": "r3010_ec_bot_challenge_reputation.conf.json"
    		...

  • Custom Match Conditions: A bot rule that contains match conditions is defined through a directive.sec_rule object.

• A bot rule that contains custom match conditions may contain up to 6 sets of criteria to identify a request. The root of the sec_rule object defines the first set of criteria. Define additional criteria through chained_rule objects.

• Define criteria by specifying an operator object and one or more variable object(s). A set of criteria is satisfied when at least one variable object results in a successful match.

  You may also transform the source string via the action object to simplify matching. For example, you may transform the source string to all lowercase characters.

• The variable.type property determines the type of variable (e.g., REQUEST_HEADERS) through which traffic will be identified. Define a value property within the match object to further restrict the comparison (e.g., User-Agent).

  View example.

  A request will satisfy the following configuration when the value corresponding to any of its request headers contains the word Windows:

  	...
  	"operator": {
  		"type": "CONTAINS",
  		"value": "Windows"
  	},
  	"variable": [{
  			"match": [{
  					"is_negated": false,
  					"is_regex": false,
  				}
  			],
  			"type": "REQUEST_HEADERS"
  		}
  	...

  The following code excerpt adds a value property to the match object that restricts the current variable (i.e., REQUEST_HEADERS) to User-Agent. This means that a request will only satisfy this configuration when the User-Agent request header contains the word Windows.

  	...
  	"operator": {
  		"type": "CONTAINS",
  		"value": "Windows"
  	},
  	"variable": [{
  			"match": [{
  					"value": "User-Agent"
  				}
  			],
  			"type": "REQUEST_HEADERS"
  		}
  	...

• An alternative to a string comparison is to count the number of times that a variable is found within a request. This requires the following configuration:

  • Set the is_count property to true.
  • From within the operator object, set the type property to EQ and then set the value property to the number of times that the variable must be found before being considered malicious traffic.
  View example.

  A request will satisfy the following configuration when it contains 2 User-Agent request headers:

  	...
  	"operator": {
  		"is_negated": false,
  		"type": "EQ",
  		"value": "2"
  	},
  	"variable": [{
  			"is_count": true,
  			"match": [{
  					"is_negated": false,
  					"is_regex": false,
  					"value": "User-Agent"
  				}
  			],
  			"type": "REQUEST_HEADERS"
  		}
  	...

• A request satisfies a bot rule when all of the following conditions are met:

  • The request satisfies at least one variable object in the root of the sec_rule object.
  • The request satisfies at least one variable object in each chained_rule object.

Request

A request to retrieve a bot rule set is described below.

HTTP Method	Request URI
GET	https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/v1.0/bots/Bot Rule Set ID

Define the following variables when submitting the above request:

VariableA variable represents a value that must be replaced. A variable consists of either a URL segment (e.g., "0001" in /0001/) or a query string value (e.g., "3" in mediaTypes=3).	Description
AccountNumber Required	Replace this variable with a customer account number. This account number may be found in the upper left-hand corner of the TCC.
Bot Rule Set ID Required	Replace this variable with the system-defined ID for the desired bot rule set. Use the Get All Bot Rule Sets endpoint to retrieve a list of bot rule sets and their system-defined IDs

Request Headers

This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.

Request Body

Request body parameters are not required by this endpoint.

Response

The response to the above request includes an HTTP status code, response headers, and a response body.

Status Code

A status code indicates whether the request was successfully performed.

Response Headers

The response for this endpoint only includes standard HTTP response headers.

View common response headers.

Response Body

The response body for a successful request contains the following response elements for each bot rule set:

Name	Data Type	Description
customer_id	String	Identifies your account by its customer account number.
directive	Array Objects	Contains the bot rules associated with this bot rule set.
id	String	Indicates the system-defined ID for this bot rule set.
last_modified_date	String	Indicates the timestamp at which this bot rule set was last modified. Syntax: YYYY-MM-DDThh:mm:ss:ffffffZ Learn more.
name	String	Indicates the name assigned to this bot rule set.

directive Array

The directive array describes each bot rule through the following properties:

Name	Data Type	Description
include	String	Identifies a bot rule that uses our reputation database. This type of rule is satisfied when the client's IP address matches an IP address defined within our reputation database. Our reputation database contains a list of IP addresses known to be used by bots. This property is only returned when your bot rule set contains a bot rule that uses our reputation database. Returns the following value: r3010_ec_bot_challenge_reputation.conf.json
sec_rule	Object	Identifies a bot rule that uses custom match conditions. This type of rule is satisfied when a match is found for each of its conditions. A condition determines request identification by defining what will be matched (i.e., variable), how it will be matched (i.e., operator), and a match value.

sec_rule Object

The sec_rule object describes a bot rule using the following properties:

Name	Data Type	Description
action	Object	Determines whether the string identified in a variable object will be transformed and metadata through which you may identify traffic to which this bot rule was applied.
chained_rule	Array Object	Contains additional criteria that must be satisfied to identify traffic to which this bot rule will be applied. You may add up to 5 chained_rule objects per bot rule.
id	String	Indicates the system-defined ID for this bot rule.
name	String	Indicates the name assigned to this bot rule.
operator	Object	Indicates the comparison that will be performed against the request element(s) identified within a variable object.
variable	Array Object	Contains criteria that identifies a request element.

variable Array

The variable array identifies each request element for which a comparison will be made using the following properties:

Name	Data Type	Description
type	String	Determines the request element that will be assessed. Valid values are: GEOIdentifies the country from which the request originated by its 2 character country code. | QUERY_STRING | REMOTE_ADDRIdentifies the client's IP address. | REMOTE_ASN | REQUEST_COOKIES | REQUEST_FILENAMERequest URL Path: Match against the request's URL path. Define a URL path that starts directly after the hostname. Exclude the protocol, hostname, and query string when defining this property. | REQUEST_HEADERS | REQUEST_METHOD | REQUEST_URI If a request element consists of one or more key-value pairs (e.g., REQUEST_HEADERS), then you may identify a key via a match object. If is_count has been disabled, then you may identify a specific value via the operator object.
match	Array Object	Contains comparison settings for the request element identified by the type property.
is_count	Boolean	Determines whether a comparison will be performed between the operator object and a string value or the number of matches found. Valid values are: true: A counter will increment whenever the request element defined by this variable object is found. Our service will compare this value against operator.value. If you enable the is_count property, then you must also set the operator.type property to EQ. false: Our service will compare the string value derived from the request element defined by this variable object against operator.value.

match Array

The match array determines the comparison conditions for the request element identified by the type property.

Name	Data Type	Description
is_negated	Boolean	Determines whether this condition is satisfied when the request element identified by the variable object is found or not found. True: Not found If this property has been enabled, then the match array should contain an initial object that sets both the is_negated and is_regex properties to False. ... [{ "is_negated": false, "is_regex": false }, { "is_negated": true, ... False: Found
is_regex	Boolean	Determines whether the value property will be interpreted as a regular expression. Valid values are: True: Regular expression False: Default value. Literal value.
value	String	Restricts the match condition defined by the type property to the specified value. Example: If the type property is set to REQUEST_HEADERS and this property is set to User-Agent, then this match condition is restricted to the User-Agent request header. If the value property is omitted, then this match condition applies to all request headers.

action Object

The action object determines whether the value derived from the request element identified in a variable object will be transformed and the metadata that will be used to identify traffic to which this bot rule was applied.

Name	Data Type	Description
id	String	Determines the custom ID that will be assigned to this bot rule. This custom ID is exposed via the Browser Challenges Dashboard. Valid values fall within this range: 77000000 - 77999999 This field is only applicable for the action object that resides in the root of the sec_rule object. Default Value: Random number
msg	String	Determines the rule message that will be assigned to this bot rule. This message is exposed through the Browser Challenges Dashboard. This field is only applicable for the action object that resides in the root of the sec_rule object. Default Value: Blank
t	Array String values	Determines the set of transformations that will be applied to the value derived from the request element identified in a variable object (i.e., source value). Transformations are always applied to the source value, regardless of the number of transformations that have been defined. Valid values are: NONE: Indicates that the source value should not be modified. LOWERCASE: Indicates that the source value should be converted to lowercase characters. URLDECODE: Indicates that the source value should be URL decoded. This transformation is useful when the source value has been URL encoded twice. REMOVENULLS: Indicates that null values should be removed from the source value. A criterion is satisfied if the source value or any of the modified string values meet the conditions defined by the operator object.

operator Object

The operator object describes the comparison that will be performed on the request element(s) defined within a variable object using the following properties:

Name	Data Type	Description
is_negated	Boolean	Indicates whether a condition will be satisfied when the value derived from the request element defined within a variable object matches or does not match the value property. Valid values are: True: Does not match False: Matches
type	String	Indicates how the system will interpret the comparison between the value property and the value derived from the request element defined within a variable object. Valid values are: RX: Indicates that the string value derived from the request element must satisfy the regular expression defined in the value property. STREQ: Indicates that the string value derived from the request element must be an exact match to the value property. CONTAINS: Indicates that the value property must contain the string value derived from the request element. BEGINSWITH: Indicates that the value property must start with the string value derived from the request element. ENDSWITH: Indicates that the value property must end with the string value derived from the request element. EQ: Indicates that the number derived from the variable object must be an exact match to the value property. You should only use EQ when the is_count property has been enabled. IPMATCH: Requires that the request's IP address either be contained by an IP block or be an exact match to an IP address defined in the values property. Only use IPMATCH with the REMOTE_ADDR variable.
value	String	Indicates a value that will be compared against the string or number value derived from the request element defined within a variable object.

chained_rule Array

Each object within the chained_rule array describes an additional set of criteria that must be satisfied in order to identify a malicious request.

Name	Data Type	Description
action	Object	Determines whether the string value derived from the request element identified in a variable object will be transformed and metadata through which you may identify traffic to which this bot rule was applied.
operator	Object	Indicates the comparison that will be performed on the string value(s) derived from the request element(s) defined within the variable array.
variable	Array Object	Identifies each request element for which a comparison will be made.

Errors

The response body for an unsuccessful request may contain an error element that provides additional information.

View common error messages.

Sample Request and Response (JSON)

A sample JSON request is shown below.

A sample JSON response is shown below.

{
	"customer_id": "0001",
	"directive": [{
			"include": "r3010_ec_bot_challenge_reputation.conf.json"
		}, {
			"sec_rule": {
				"action": {
					"id": "77000001",
					"t": [
						"NONE"
					]
				},
				"chained_rule": [],
				"id": "Ukg1khPJ",
				"name": "Popular Bots",
				"operator": {
					"type": "RX",
					"value": ".*(Googlebot|Bingbot|Slurp|DuckDuckBot|Baiduspider|YandexBot|Spider|Exabot).*"
				},
				"variable": [{
						"match": [{
								"value": "User-Agent"
							}
						],
						"type": "REQUEST_HEADERS"
					}
				]
			}
		}
	],
	"id": "pfJKToQF",
	"last_modified_by": "joe@example.com via MCC portal",
	"last_modified_date": "2022-05-04T17:18:33.017946Z",
	"name": "My Bot Rule Set"
}