Update Custom 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.

Updates a custom rule set that defines custom threat assessment criteria.

Key information:

Request

A request to update a custom rule set is described below.

HTTP Method Request URI

PUT

https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/v1.0/rules/Custom 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.

Custom Rule Set ID

Required

Replace this variable with the system-defined ID for your custom rule set.

Use the Get All Custom Rule Sets endpoint to retrieve a list of custom rule sets and their IDs.

Request Headers

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

Request Body

Pass the following request body parameters:

Name Data Type Description

customer_id

String

Identifies your account by its customer account number.

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.

id

String

Indicates the system-defined ID for the custom rule set.

last_modified_date

String

Indicates the date and time at which the custom rule was last modified.

Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

name

String

Indicates the name of the custom rule.

sec_rule Object

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

Name Data Type Description

action

Required

Object

Determines whether the string identified in a variable object will be transformed and the metadata that will be assigned to malicious traffic.

chained_rule

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.

id

String

Indicates the system-defined ID for this custom rule.

name

String

Indicates the name assigned to this custom rule.

operator

Required

Object

Indicates the comparison that will be performed against the request element(s) identified within a variable object.

variable

Required

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

Required

String

Determines the request element that will be assessed. Valid values are:

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.

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. The operator object will perform a comparison against this number.

    If you enable is_count, then you must also set the type property to EQ.

  • false: The operator object will perform a comparison against the string value derived from the request element defined by this variable object.

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

    Enabling this property requires an initial object that sets both the is_negated and is_regex properties to False.

    ...
    [{
    		"is_negated": false,
    		"is_regex": false
    	}, {
    		"is_negated": true,
    		...	

    Omitting this initial object results in an invalid configuration.

  • 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 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:

  • 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

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:

  • 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.

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.
Sample values:
/marketing
/800001/mycustomerorigin

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 the metadata that will be used to identify malicious traffic.

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.

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 parameters:

Name Data Type Description

id

String

Indicates the system-defined ID for the resource.

status

String

Returns success.

success

Boolean

Returns true.

Errors

The response body for an unsuccessful request contains the following parameters:

Name Data Type Description

success

Boolean

Returns false.

errors

Array

Objects

Contains one or more error(s).

errors Array

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.

Sample Request and Response (JSON)

A sample JSON request is shown below.

PUT https://api.transactcdn.com/v2/mcc/customers/0001/waf/v1.0/rules/N8NxAJOA 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
}