Show search and navigation.

 

Add Managed Rule (Profile)

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 managed rule that identifies a rule set configuration and describes a valid request.

Request

A request to create a managed rule is described below.

HTTP Method Request URI

POST

https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/v1.0/profile

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

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.

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

disabled_rules

Array

Objects

Contains all disabled rules.

Default Value:

Null

general_settings

Required

Object

Contains settings that define the profile for a valid request.

name

String

Indicates the name of the managed rule.

policies

Array

String values

Contains a list of policies that have been enabled on this managed rule.

Use the Get Available Policies endpoint to retrieve a list of policies and their IDs.

rule_target_updates

Array

Objects

Defines one or more targets that will be ignored and/or replaced.

Key information:

  • If is_negated is set to true, then this target identifies rule criterion that will be ignored when identifying threats.
  • The replace_target property defines criterion that will be used to identify threats instead of the existing criterion.
  • If is_regex is set to true, then you may use regular expressions to define criteria for identifying multiple types of threats.
  • A maximum of 25 target configurations may be created.

ruleset_id

Required

String

Indicates the ID for the rule set associated with this managed rule.

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

ruleset_version

Required

String

Indicates the version of the rule set associated with this managed rule.

disabled_rules Array

The disabled_rules array identifies each rule that has been disabled using the following properties:

Name Data Type Description

policy_id

String

Identifies a policy from which a rule will be disabled by its system-defined ID.

Use the Get Available Policies endpoint to retrieve a list of policies and their system-defined IDs.

Default Value:

Null

rule_id

String

Identifies a rule that will be disabled by its system-defined ID.

Use the Get Available Rules endpoint to retrieve a list of rules and their system-defined IDs.

Default Value:

Null

general_settings Object

The general_settings object describes a valid request using the following properties:

Name Data Type Description

anomaly_threshold

Required

Integer

Indicates the anomaly score threshold.

arg_length

Required

Integer

Indicates the maximum number of characters for any single query string parameter value.

arg_name_length

Required

Integer

Indicates the maximum number of characters for any single query string parameter name.

combined_file_sizes

Integer

Indicates the total file size for multipart message lengths.

ignore_cookie

Array

String values

Identifies each cookie that will be ignored for the purpose of determining whether a request is malicious traffic.

Each element in this array defines a regular expression.

ignore_header

Array

String values

Identifies each request header that will be ignored for the purpose of determining whether a request is malicious traffic.

Each element in this array defines a regular expression.

ignore_query_args

Array

String values

Identifies each query string argument that will be ignored for the purpose of determining whether a request is malicious traffic.

Each element in this array defines a regular expression.

json_parser

Boolean

Determines whether JSON payloads will be inspected. Valid values are:

true | false

max_file_size

Deprecated

Integer

Indicates the maximum file size, in bytes, for a POST request body.

This property, which has undergone end-of-life, does not affect your security configuration. Use the Add Access Rule (ACL) and the Update Access Rule (ACL) endpoints to manage this setting.

max_num_args

Required

Integer

Indicates the maximum number of query string parameters.

paranoia_level

Integer

Indicates the balance between the level of protection and false positives. Valid values are:

1 | 2 | 3 | 4

Learn more.

process_request_body

Boolean

Indicates whether WAF will inspect a POST request body. Valid values are:

true | false

response_header_name

String

Determines the name of the response header that will be included with blocked requests.

total_arg_length

Required

Integer

Indicates the maximum number of characters for the query string value.

validate_utf8_encoding

Boolean

Indicates whether WAF may check whether a request variable (e.g., ARGS, ARGS_NAMES, and REQUEST_FILENAME) is a valid UTF-8 string. This validation includes checking for missing bytes, invalid characters, and ASCII to UTF-8 character mapping. Valid values are:

true | false

You should only enable this validation if your web server or application uses UTF-8. Otherwise, this validation will result in many false positives.

xml_parser

Boolean

Determines whether XML payloads will be inspected. Valid values are:

true | false

rule_target_updates Array

The rule_target_updates array describes each target using the following properties:

Name Data Type Description

is_negated

Boolean

Determines whether the current target, as defined within this object, will be ignored when identifying threats. Valid values are:

  • True: Ignore this target.
  • False: Default value. Allow this target to identify threats.

is_regex

Required

Boolean

Determines whether the target_match parameter may leverage regular expressions. Valid values are:

  • True: Interprets the target_match parameter as a regular expression.
  • False: Default value. Interprets the target_match parameter as a literal value.

replace_target

String

This parameter should be a blank value unless you are configuring a rule to identify threats based on a different data source.

This parameter replaces an existing threat identification criterion. For example, this capability may be used to identify threats based on a cookie value instead of a query string argument.

Defines the data source (e.g., REQUEST_COOKIES, ARGS, GEO, etc.) that will be used instead of the one defined in the target parameter.

rule_id

Required

String

Identifies a rule by its system-defined ID.

The configuration defined within this object will alter the behavior of the rule identified by this parameter.

target

Required

String

Identifies the type of data source (e.g., REQUEST_COOKIES, ARGS, GEO, etc.) for which a target will be created.

The maximum size of this value is 256 characters.

target_match

Required

String

Identifies a name or category (e.g., cookie name, query string name, country code, etc.) for the data source defined in the target parameter. The category defined by this parameter will be analyzed when identifying threats.

The maximum size of this value is 256 characters.

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.

POST https://api.transactcdn.com/v2/mcc/customers/0001/waf/v1.0/profile HTTP/1.1

Authorization: TOK:12345678-1234-1234-1234-1234567890ab

Accept: application/json

Content-Type: application/json

Host: api.transactcdn.com 

{
	"created_date": "06/10/2020 05:54:31 PM",
	"customer_id": "0001",
	"general_settings": {
		"anomaly_threshold": 5,
		"arg_length": 400,
		"arg_name_length": 100,
		"combined_file_sizes": 1048576,
		"disallowed_headers": [],
		"max_file_size": 1048576,
		"max_num_args": 3,
		"process_request_body": true,
		"total_arg_length": 64000,
		"validate_utf8_encoding": true,
		"xml_parser": true
	},
	"id": "Oxeludse",
	"last_modified_date": "2020-06-10T17:54:31.252870Z",
	"name": "my_managed_rule",
	"policies": [
		"r4020_tw_cpanel.conf.json",
		"r4040_tw_drupal.conf.json",
		"r4030_tw_iis.conf.json",
		"r4070_tw_joomla.conf.json",
		"r4050_tw_microsoft_sharepoint.conf.json",
		"r4010_tw_struts.conf.json",
		"r4060_tw_wordpress.conf.json",
		"r5040_cross_site_scripting.conf.json",
		"r2000_ec_custom_rule.conf.json",
		"r5021_http_attack.conf.json",
		"r5020_http_protocol_violation.conf.json",
		"r5043_java_attack.conf.json",
		"r5030_local_file_inclusion.conf.json",
		"r5033_php_injection.conf.json",
		"r5032_remote_code_execution.conf.json",
		"r5031_remote_file_inclusion.conf.json",
		"r5010_scanner_detection.conf.json",
		"r5042_session_fixation.conf.json",
		"r5041_sql_injection.conf.json",
		"r4000_tw_ip_reputation.conf.json",
		"r6000_blocking_evaluation.conf.json"
	],
	"ruleset_id": "ECRS",
	"ruleset_version": "2019-11-01"
}

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": "Tq2WAbLu",
	"status": "success",
	"success": true
}