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.
Creates a custom rule set that defines custom threat assessment criteria.
Key information:
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 type property determines the type of variable (e.g., REQUEST_HEADERS) through which malicious traffic will be identified. Define a value property within the match object to further restrict the comparison (e.g., User-Agent).
A request will satisfy the following configuration when the value corresponding to any of its request headers contains the word Windows:
... "operator": { "is_negated": false, "is_regex": false, "type": "CONTAINS", "value": "Windows" }, "variable": [{ "is_count": false, "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": { "is_negated": false, "is_regex": false, "type": "CONTAINS", "value": "Windows" }, "variable": [{ "is_count": false, "match": [{ "is_negated": false, "is_regex": false, "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:
A request will satisfy the following configuration when it contains 2 User-Agent request headers:
... "operator": { "is_negated": false, "is_regex": false, "type": "EQ", "value": "2" }, "variable": [{ "is_count": false, "match": [{ "is_negated": false, "is_regex": false, "value": "User-Agent" } ], "type": "REQUEST_HEADERS" } ...
A request will be flagged as malicious traffic when all of the following conditions are met:
A request to create a custom rule set is described below.
HTTP Method | Request URI |
---|---|
POST |
https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/v1.0/rules |
Define the following variable 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 |
---|---|
Required |
|
This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.
Pass the following request body parameters:
Name | Data Type | Description |
---|---|---|
directive Required |
Array Object |
Contains custom rules. Each directive object defines a custom rule via the sec_rule object. You may create up to 10 custom rules. |
name |
String |
Indicates the name of the custom rule. |
The sec_rule object describes a custom rule using the following properties:
Name | Data Type | Description |
---|---|---|
Required |
Object |
Determines whether the string identified in a variable object will be transformed and the metadata that will be assigned to malicious traffic. |
Array Object |
Contains additional criteria that must be satisfied to identify a malicious request. You may add up to 5 chained_rule objects per custom rule. |
|
name |
String |
Indicates the name assigned to this custom rule. |
Required |
Object |
Indicates the comparison that will be performed against the request element(s) identified within a variable object. |
Required |
Array Object |
Contains criteria that identifies a request element. |
The variable array identifies each request element for which a comparison will be made using the following properties:
Name | Data Type | Description |
---|---|---|
type Required |
String |
Determines the request element that will be assessed. Valid values are: ARGS_POSTIdentifies key-value pairs within a POST request. | 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_BODYIdentifies a URL-encoded request body. | 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_COOKIES | REQUEST_HEADERS | REQUEST_METHOD | REQUEST_URI
If a request element consists of one or more key-value pairs, 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. |
Array Object |
Contains comparison settings for the request element identified by the type property. |
|
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:
|
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.
|
is_regex |
Boolean |
Determines whether the value property will be interpreted as a regular expression. Valid values are:
|
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. |
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 malicious traffic.
Name | Data Type | Description |
---|---|---|
id |
String |
Determines the custom ID that will be assigned to this custom rule. This custom ID is exposed via the Threats Dashboard. Valid values fall within this range: 66000000 - 66999999
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 custom rule. This message is exposed via the Threats 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:
A criterion is satisfied if the source value or any of the modified string values meet the conditions defined by the 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:
|
Required |
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:
|
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. If you are identifying traffic via a URL path (REQUEST_URI), then you should specify a URL path pattern that starts directly after the hostname. Exclude a protocol or a hostname when defining this property. |
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 |
---|---|---|
Object |
Determines whether the string value derived from the request element identified in a variable object will be transformed and the metadata that will be used to identify malicious traffic. |
|
Object |
Indicates the comparison that will be performed on the string value(s) derived from the request element(s) defined within the variable array. |
|
Array Object |
Identifies each request element for which a comparison will be made. |
The response to the above request includes an HTTP status code, response headers, and a response body.
A status code indicates whether the request was successfully performed.
The response for this endpoint only includes standard HTTP response headers.
The response body for a successful request contains the following parameters:
Name | Data Type | Description |
---|---|---|
id |
String |
Indicates the system-defined ID for the resource. |
status |
String |
Returns success. |
success |
Boolean |
Returns true. |
The response body for an unsuccessful request contains the following parameters:
Name | Data Type | Description |
---|---|---|
success |
Boolean |
Returns false. |
Array Objects |
Contains one or more error(s). |
The errors array describes each error that occurred using the following properties:
Name | Data Type | Description |
---|---|---|
code |
Integer |
Indicates the HTTP status code for the error. |
message |
String |
Indicates the description for the error that occurred. |
A sample JSON request is shown below.
POST https://api.transactcdn.com/v2/mcc/customers/0001/waf/v1.0/rules HTTP/1.1
Authorization: TOK:12345678-1234-1234-1234-1234567890ab
Accept: application/json
Content-Type: application/json
Host: api.transactcdn.com
{ "directive": [{ "sec_rule": { "action": { "id": "123456", "msg": "Invalid user agent.", "t": [ "NONE" ] }, "operator": { "is_negated": false, "is_regex": false, "type": "CONTAINS", "value": "bot" }, "variable": [{ "is_count": false, "match": [{ "is_negated": false, "is_regex": false, "value": "User-Agent" } ], "type": "REQUEST_HEADERS" } ] } } ], "name": "My-Rule" }
A sample JSON response is shown below.
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Date: Thu, 15 Apr 2021 12:00:00 GMT
Content-Length: 65
{ "id": "N8NxAJOA", "status": "success", "success": true }