Show search and navigation.

 

Add Profile

This article explains the legacy version of WAF that underwent end-of-life on June 30, 2021. Our new version of WAF expands upon all of the capabilities offered by WAF (Legacy) and Rate Limiting (Legacy) with a simplified and centralized setup. Please upgrade to the latest version of WAF at your earliest convenience.

WAF Essential cannot be configured via our APIs. However, you may leverage our APIs to retrieve WAF and Rate Limiting event log data.

Creates a WAF profile.

Request

A request to create a profile is described below.

HTTP Method Request URI

POST

https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/config/profiles

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

access_settings

Required

Object

This request parameter contains access control settings.

asn

Object

access_settings object

This request parameter contains access controls for ASNs.

accesslist

Array (String values)

access_settings object > asn object

Defines each autonomous system in the accesslist by its ASN.

Default Value:

Null

blacklist

Array (String values)

access_settings object > country object

Defines each blacklisted autonomous system by its ASN.

Default Value:

Null

whitelist

Array (String values)

access_settings object > country object

Defines each whitelisted autonomous system by its ASN.

Default Value:

Null

country

Required

Object

access_settings object

This request parameter contains access controls for countries.

accesslist

Array (String values)

access_settings object > country object

Defines each country in the accesslist by its country code.

Default Value:

Null

blacklist

Array (String values)

access_settings object > country object

Defines each blacklisted country by its country code.

Default Value:

Null

whitelist

Array (String values)

access_settings object > country object

Defines each whitelisted country by its country code.

Default Value:

Null

ignore_cookie

Array (String values)

access_settings object

Identifies each cookie that will be ignored for the purpose of determining whether a request is malicious traffic. Each desired cookie should be identified by its name.

Each element in this array defines a regular expression.

Default Value:

Null

ignore_header

Array (String values)

access_settings object

Identifies each request header that will be ignored for the purpose of determining whether a request is malicious traffic. Each desired request header should be identified by its name.

Each element in this array defines a regular expression.

Default Value:

Null

ignore_query_args

Array (String values)

access_settings object

Identifies each query string argument that will be ignored for the purpose of determining whether a request is malicious traffic. Each desired query string argument should be identified by its name.

Each element in this array defines a regular expression.

Default Value:

Null

ip

Required

Object

access_settings object

This request parameter contains access controls for IP addresses.

accesslist

Array (String values)

access_settings object > ip object

Defines each IP address in the accesslist.

Default Value:

Null

blacklist

Array (String values)

access_settings object > ip object

Defines each blacklisted IP address.

Default Value:

Null

whitelist

Array (String values)

access_settings object > ip object

Defines each whitelisted IP address.

Default Value:

Null

referer

Required

Object

access_settings object

This request parameter contains access controls for referrers.

accesslist

Array (String values)

access_settings object > referer object

Defines each referrer in the accesslist via a regular expression.

The Referer request header identifies the URL of the resource (e.g., web page) from which the request was initiated. The specified regular expression may match any portion of the entire URL including the protocol and hostname.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes and periods using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    https:\/\/cdn\.example\.com\/marketing

    JSON-compatible regular expression:

    https:\\\/\\\/cdn\\.example\\.com\\\/marketing

Default Value:

Null

blacklist

Array (String values)

access_settings object > referer object

Defines each blacklisted referrer via a regular expression.

The Referer request header identifies the URL of the resource (e.g., web page) from which the request was initiated. The specified regular expression may match any portion of the entire URL including the protocol and hostname.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes and periods using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    https:\/\/cdn\.example\.com\/marketing

    JSON-compatible regular expression:

    https:\\\/\\\/cdn\\.example\\.com\\\/marketing

Default Value:

Null

whitelist

Array (String values)

access_settings object > referer object

Defines each whitelisted referrer via a regular expression.

The Referer request header identifies the URL of the resource (e.g., web page) from which the request was initiated. The specified regular expression may match any portion of the entire URL including the protocol and hostname.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes and periods using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    https:\/\/cdn\.example\.com\/marketing

    JSON-compatible regular expression:

    https:\\\/\\\/cdn\\.example\\.com\\\/marketing

Default Value:

Null

url

Required

Object

access_settings object

This request parameter contains access controls for URLs.

accesslist

Array (String values)

access_settings object > url object

Defines each URL in the accesslist via a regular expression.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes, a period, and a question mark using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    \/marketing\/main\.html\?user=Joe

    JSON-compatible regular expression:

    \\\/marketing\\\/main\\.html\\?user=Joe

Default Value:

Null

blacklist

Array (String values)

access_settings object > url object

Defines each blacklisted URL via a regular expression.

Do not include a protocol or a hostname (e.g., http://cdn.example.com) when defining a regular expression for this access control.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes, a period, and a question mark using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    \/marketing\/main\.html\?user=Joe

    JSON-compatible regular expression:

    \\\/marketing\\\/main\\.html\\?user=Joe

Default Value:

Null

whitelist

Array (String values)

access_settings object > url object

Defines each whitelisted URL via a regular expression.

Do not include a protocol or a hostname (e.g., http://cdn.example.com) when defining a regular expression for this access control.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes forward slashes, a period, and a question mark using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    \/marketing\/main\.html\?user=Joe

    JSON-compatible regular expression:

    \\\/marketing\\\/main\\.html\\?user=Joe

Default Value:

Null

user-agent

Required

Object

access_settings object

This request parameter contains access controls for user agents.

accesslist

Array (String values)

access_settings object > user-agent object

Defines each user agent in the accesslist via a regular expression.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes a forward slash and a period using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    Mozilla\/5\.0

    JSON-compatible regular expression:

    Mozilla\\\/5\\.0

Default Value:

Null

blacklist

Array (String values)

access_settings object > user-agent object

Defines each blacklisted user agent via a regular expression.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes a forward slash and a period using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    Mozilla\/5\.0

    JSON-compatible regular expression:

    Mozilla\\\/5\\.0

Default Value:

Null

whitelist

Array (String values)

access_settings object > user-agent object

Defines each whitelisted user agent via a regular expression.

ClosedRegular Expressions and JSON

  • JSON requires a backslash to escape certain special characters (e.g., \ and /). This additional backslash will be consumed by JSON and will not be shown in the value displayed from within the TCC.

    JSON-escaped forward slash syntax:

    \/

    JSON-escaped backslash syntax:

    \\

  • Regular expression syntax allows special characters (e.g., \/?.+) to be treated as literal characters by using a backslash to escape them.

    Example:

    In the following example, notice the following:

    • The desired regular expression escapes a forward slash and a period using a backslash.
    • The JSON-compatible version of the regular expression escapes forward slashes and backslashes by prepending each one with a backslash.

    Regular expression:

    Mozilla\/5\.0

    JSON-compatible regular expression:

    Mozilla\\\/5\\.0

Default Value:

Null

disabled_policies

Deprecated

Array

This parameter is undergoing end-of-life and should not be used. Please update your scripts to specify policies within the policies array instead.

This request parameter contains all disabled policies.

Default Value:

Null

policy_id

Deprecated

]String

disabled_policies array

Defines a policy that will be disabled by its system-defined ID.

Default Value:

Null

policies

Array

Set this array to a comma-separated list of policies through which malicious traffic will be identified. Identify each policy by its system-defined ID.

Do not include the disabled_policies parameter when calling this endpoint.

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

This array should only contain policies that pertain to the rule set identified by the ruleset_id parameter.

The following policies cannot be deactivated regardless of whether they are specified within this array:

  • modsecurity_crs_30_http_policy.conf
  • modsecurity_crs_49_inbound_blocking.conf

The modsecurity_crs_23_request_limits.conf policy, which has been deprecated, cannot be deactivated.

disabled_rules

Array

This request parameter contains all disabled rules.

Default Value:

Null

policy_id

String

disabled_rules array

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

disabled_rules array

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

Required

Object

This request parameter contains global settings that define a valid HTTP request.

allowed_http_methods

Required

Array (String values)

general_settings object

Defines each allowed HTTP method (e.g., GET).

allowed_http_versions

Required

Array (String values)

general_settings object

Defines each allowed HTTP version (e.g., HTTP\/1.1).

allowed_request_content_types

Required

Array (String values)

general_settings object

Defines each allowed media type (e.g., application\/json).

anomaly_threshold

Required

Integer

general_settings object > anomaly_settings object

Defines the anomaly score threshold.

Valid values range from 1 to 10.

anomaly_settings

Deprecated

Object

general_settings object

This request parameter contains the configuration for the anomaly scoring detection mode.

inbound_threshold

Deprecated

Integer

general_settings object > anomaly_settings object

Defines the anomaly score threshold.

This parameter has been deprecated in favor of the anomaly_threshold parameter.

arg_length

Required

Integer

general_settings object

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

Default Value:

0

arg_name_length

Required

Integer

general_settings object

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

combined_file_sizes

Required

Integer

general_settings object

Defines the total file size for multipart message lengths.

disallowed_extensions

Array (String values)

general_settings object

Defines each file extension that should be disallowed.

Default Value:

Null

engine

Deprecated

String

general_settings object

This parameter has reached end-of-life.

json_parser

Boolean

Determines whether JSON payloads will be inspected.

max_file_size

Required

Integer

general_settings object

Defines the maximum file size for a POST request body.

max_num_args

Required

Integer

general_settings object

Defines the maximum number of query string parameters.

response_header_name

Required

String

general_settings object

Defines the name of the response header that will be included with requests blocked by WAF.

total_arg_length

Required

Integer

general_settings object

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

name

Required

String

Defines the name of the new profile.

rule_target_updates

Required

Array

This request parameter defines one or more targets. A target may be configured to allow the following behavior:

  • Ignore Target: It may identify criterion within a rule that should be ignored when identifying threats.

  • Replace Target: It may identify criterion that should be used to identify threats instead of the existing criterion.

    Take advantage of regular expressions to define criteria for identifying multiple types of threats.

Although changes defined through this parameter are not visible from within the MCC, they may be retrieved through either the Get Profile By ID endpoint.

A maximum of 25 target configurations may be created.

is_negated

Boolean

rule_target_updates array

This parameter is required when defining a target.

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

Boolean

rule_target_updates array

This parameter is required when defining a target.

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

rule_target_updates array

This parameter is required when defining a target.

A blank value should be assigned to this parameter 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

String

rule_target_updates array

This parameter is required when defining a target.

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

String

rule_target_updates array

This parameter is required when defining a target.

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

String

rule_target_updates array

This parameter is required when defining a target.

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.

ruleset_id

Required

String

Defines the rule set (e.g., Trustwave-OWASPIntegration-Application) through which threats will be detected.

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

ruleset_version

Required

String

Defines the version of the rule set, as defined in the ruleset_id parameter, that will be used to identify threats.

Use the Get Available Rule Sets endpoint to retrieve a list of rule set versions.

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

Name Data Type Description

id

String

Identifies the new WAF profile by its system-defined ID.

status

String

Returns success when a WAF profile is created.

success

Boolean

Indicates whether the WAF profile was created.

Valid values are:

  • true
  • false

Errors

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

View common error messages.

Sample Request and Response

A sample JSON request is shown below.

POST https://api.transactcdn.com/v2/mcc/customers/0001/waf/config/profiles HTTP/1.1

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

Accept: application/json

Content-Type: application/json

Host:api.transactcdn.com

Content-Length: 1034

{
			"access_settings": {
			"country": {},
			"ip": {},
			"referer": {},
			"url": {},
			"user-agent": {}
			},
			"policies": [
			"modsecurity_crs_45_trojans.conf",
			"modsecurity_crs_23_request_limits.conf",
			"modsecurity_crs_30_http_policy.conf",
			"modsecurity_crs_49_inbound_blocking.conf"
			],
			"general_settings": {
			"allowed_http_methods": ["GET", "POST", "OPTIONS", "HEAD", "PUT", "DELETE"],
			"allowed_http_versions": ["HTTP\/0.9", "HTTP\/1.0", "HTTP\/1.1"],
			"allowed_request_content_types": ["application\/x-www-form-urlencoded", "multipart\/form-data", "application\/json"],
			"anomaly_threshold": 10,
			"arg_length": 0,
			"arg_name_length": 0,
			"combined_file_sizes": 0,
			"engine": "anomaly",
			"max_file_size": 0,
			"max_num_args": 0,
			"response_header_name": "X-CDN-Security-Audit",
			"total_arg_length": 0
			},
			"name": "Site B Profile",
			"rule_target_updates": [],
			"ruleset_id": "Trustwave-OWASPIntegration-Application",
			"ruleset_version": "2017-09-18"
			}

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

{
			"id": "e032f437-6220-4bf7-a5ea-1a2bcd34e45f",
			"status": "success",
			"success": true
		}