Manage All Security Application Manager Configurations (Scopes)

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, updates, and deletes one or more Security Application Manager configurations. Each configuration:

Key information:

Request

A request to manage Security Application Manager configurations is described below.

HTTP Method Request URI

POST

https://api.edgecast.com/v2/mcc/customers/AccountNumber/waf/v1.0/scopes

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 right-hand corner of the MCC.

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. This value is case-sensitive.

id

String

Indicates the system-defined ID for the set of Security Application Manager configurations defined within the scopes array.

last_modified_by

String

Reserved for future use.

last_modified_date

String

Indicates the timestamp at which the Security Application Manager configuration returned by the scopes array was last modified.

Syntax:

YYYY-MM-DDThh:mm:ss:ffffffZ

Learn more.

name

String

Reserved for future use.

scopes

Array

Objects

Contains a list of Security Application Manager configurations and their properties.

version

String

Reserved for future use.

scopes Array

The scopes array describes each Security Application Manager configuration using the following properties:

Name Data Type Description

acl_audit_action

Object

Contains properties that describe the type of action that will take place when the access rule defined within the acl_audit_id property is violated.

acl_audit_id

String

Indicates the system-defined ID for the access rule that will audit production traffic for this Security Application Manager configuration.

Use the Get All Access Rules (ACLs) endpoint to retrieve a list of access rules and their IDs.

acl_prod_action

Object

Contains properties that describe the type of action that will take place when the access rule defined within the acl_prod_id property is violated.

acl_prod_id

String

Indicates the system-defined ID for the access rule that will be applied to production traffic for this Security Application Manager configuration.

Use the Get All Access Rules (ACLs) endpoint to retrieve a list of access rules and their IDs.

bots_prod_action

Object

Contains properties that describe the browser challenge that will be applied to requests that satisfy the bot rule set defined within the bot_prod_id property.

bots_prod_id

String

Indicates the system-defined ID for the bot rule set that will be applied to production traffic for this Security Application Manager configuration.

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

host

Object

Contains properties that describe a hostname match condition.

id

String

Identifies the current Security Application Manager configuration by its system-defined ID.

limits

Array

Objects

Identifies the set of rate rules that will be enforced for this Security Application Manager configuration and the enforcement action that will be applied to rate limited requests.

name

String

Indicates the name assigned to the Security Application Manager configuration.

Default Value:

name

path

Object

Contains properties that describe a URL path match condition.

profile_audit_action

Object

Contains properties that describe the type of action that will take place when the managed rule defined within the profile_audit_id property is violated.

profile_audit_id

String

Indicates the system-defined ID for the managed rule that will audit production traffic for this Security Application Manager configuration.

Use the Get All Managed Rules (Profiles) endpoint to retrieve a list of managed rules and their IDs.

profile_prod_action

Object

Contains properties that describe the type of action that will take place when the managed rule defined within the profile_prod_id property is violated.

profile_prod_id

String

Indicates the system-defined ID for the manaed rule that will be applied to production traffic for this Security Application Manager configuration.

Use the Get All Managed Rules (Profiles) endpoint to retrieve a list of managed rules and their IDs.

rules_audit_action

Object

Contains properties that describe the type of action that will take place when the custom rule set defined within the rules_audit_id property is violated.

rules_audit_id

String

Indicates the system-defined ID for the custom rule set that will audit production traffic for this Security Application Manager configuration.

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

rules_prod_action

Object

Contains properties that describe the type of action that will take place when the custom rule set defined within the rules_prod_id property is violated.

rules_prod_id

String

Indicates the system-defined ID for the custom rule set that will be applied to production traffic for this Security Application Manager configuration.

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

Configuration Type_prod_action Object

The acl_prod_action, profile_prod_action, and rules_prod_action objects describe the enforcement action that will be taken when a request violates the configuration defined by acl_prod_id, profile_prod_id, or rules_prod_id, respectively. These objects may contain the following properties:

Name Data Type Description

enf_type

String

Indicates the enforcement action that will be applied to malicious traffic. Valid values are:

  • BLOCK_REQUEST: Block Request
  • ALERT: Alert Only
  • REDIRECT_302: Redirect (HTTP 302)
  • CUSTOM_RESPONSE: Custom Response

id

String

Reserved for future use.

name

String

Indicates the name assigned to this enforcement action configuration.

response_body_base64

String

type: CUSTOM_RESPONSE Only

Indicates the response body that will be sent to malicious traffic. This value is Base64 encoded.

response_headers

Object

type: CUSTOM_RESPONSE Only

Indicates the set of response headers that will be sent to malicious traffic.

Each response header is specified as a name/value pair.

status

Integer

type: CUSTOM_RESPONSE Only

Indicates the HTTP status code (e.g., 404) for the custom response that will be sent to malicious traffic.

url

String

type: REDIRECT_302 Only

Indicates the URL to which malicious requests will be redirected.

bots_prod_action Object

The bots_prod_action object describes the browser challenge that will be applied to requests that satisfy the configuration defined by bots_prod_id. This object may contain the following properties:

Name Data Type Description

enf_type

String

Set this property to BROWSER_CHALLENGE.

id

String

Reserved for future use.

is_custom_challenge

Boolean

Indicates whether we will serve a standard or custom browser challenge. Valid values are:

true | false

name

String

Indicates the name assigned to this enforcement action configuration.

response_body_base64

String

is_custom_challenge: True

Defines a Base64 encoded HTML page that we will serve as a custom browser challenge. This HTML page must satisfy the following requirements:

  • It must contain the following mustache:

    {{BOT_JS}}

    Due to the speed at which our JavaScript function is executed, we recommend that you place the {{BOT_JS}} mustache after all rendered content (e.g., near the end of the document's body).

    We will replace the above {{BOT_JS}} mustache with JavaScript upon serving a browser challenge.

  • It must check whether the user agent allows JavaScript using a <noscript> tag. Your custom HTML must display an error message if it has been disabled.
  • It must check whether the user agent allows third-party cookies. Your custom HTML must display an error message if they have been disabled.

A custom browser challenge will not be served if your custom HTML does not satisfy the above requirements.

status

Integer

Indicates the HTTP status code (e.g., 404) for the response provided to clients that are being served the browser challenge.

valid_for_sec

Integer

Indicates the number of minutes for which our CDN will serve content to a client that solves a browser challenge without requiring an additional browser challenge to be solved. Specify a value between 1 and 1,440 minutes.

Configuration Type_audit_action Object

The acl_audit_action, profile_audit_action, and rules_audit_action objects describe the enforcement action that will be taken when a request violates the configuration defined by acl_audit_id, profile_audit_id, or rules_audit_id, respectively. These objects may contain the following properties:

Name Data Type Description

name

String

Indicates the name assigned to this enforcement action configuration.

enf_type

String

Set to ALERT. This indicates that malicious traffic will be audited.

host Object

The host object describes a hostname match condition using the following properties:

Name Data Type Description

is_case_insensitive

Boolean

type: EM Only

Indicates whether the comparison between the requested hostname and the values property is case-sensitive. Valid values are:

  • True: Case-insensitive
  • False: Case-sensitive

is_negated

Boolean

Indicates whether this match condition will be satisfied when the requested hostname matches or does not match the value defined by the value/values property. Valid values are:

  • True: Does not match
  • False: Matches

type

String

Indicates how the system will interpret the comparison between the request's hostname and the value defined within the value | values property. Valid values are:

  • EM: Indicates that request's hostname must be an exact match to one of the case-sensitive values specified in the values property.
  • GLOB: Indicates that the request's hostname must be an exact match to the wildcard pattern defined in the value property.

  • RX: Indicates that the request's hostname must be an exact match to the regular expression defined in the value property.

Apply this Security Application Manager configuration across all hostnames by setting this property to "GLOB" and setting the value property to "*." This type of configuration is also known as "Default."

value

String

type: GLOB or RX Only

Identifies a value that will be used to identify requests that are eligible for this Security Application Manager configuration.

values

Array

String values

type: EM Only

Identifies one or more values used to identify requests that are eligible for this Security Application Manager configuration.

limits Array

The limits array identifies the set of rate rules that will be enforced for this Security Application Manager configuration and the enforcement action that will be applied to rate limited requests.

Name Data Type Description

action

Object

Describes the action that will take place when the rate rule identified by the id property is enforced.

duration_sec

Integer

Indicates the length of time, in seconds, that the action defined within this object will be applied to a client that violates the rate rule identified by the id property. Valid values are:

10 | 60 | 300

enf_type

String

Indicates the type of action that will be applied to rate limited requests. Valid values are:

  • ALERT: Alert Only
  • REDIRECT_302: Redirect (HTTP 302)
  • CUSTOM_RESPONSE: Custom Response
  • DROP_REQUEST: Drop Request (503 Service Unavailable response with a retry-after of 10 seconds)

name

String

Indicates the name assigned to this enforcement action.

response_body_base64

String

type: CUSTOM_RESPONSE Only

Indicates the response body that will be sent to rate limited requests. This value is Base64 encoded.

response_headers

Object

type: CUSTOM_RESPONSE Only

Contains the set of headers that will be included in the response sent to rate limited requests.

Syntax:

"Response Header": "Value"

status

Integer

type: CUSTOM_RESPONSE Only

Indicates the HTTP status code (e.g., 404) for the custom response sent to rate limited requests.

url

String

type: REDIRECT_302 Only

Indicates the URL to which rate limited requests will be redirected.

id

String

Indicates the system-defined ID for the rate rule that will be applied to this Security Application Manager configuration.

path Object

The path object describes a URL path match condition using the following properties:

Name Data Type Description

is_case_insensitive

Boolean

type: EM Only

Indicates whether the comparison between the requested URL and the values property is case-sensitive. Valid values are:

  • True: Case-insensitive
  • False: Case-sensitive

is_negated

Boolean

Indicates whether this match condition will be satisfied when the requested URL matches or does not match the value defined by the value/values property. Valid values are:

  • True: Does not match
  • False: Matches

type

String

Indicates how the system will interpret the comparison between the request's URL and the value defined within the value | values property. Valid values are:

  • EM: Indicates that request's URL path must be an exact match to one of the case-sensitive values specified in the values property.
  • GLOB: Indicates that the request's URL path must be an exact match to the wildcard pattern defined in the value property.

  • RX: Indicates that the request's URL path must be an exact match to the regular expression defined in the value property.

Apply this Security Application Manager configuration across all URLs by setting this property to "GLOB" and setting the value property to "*." This type of configuration is also known as "Default."

value

String

type: GLOB or RX Only

Identifies a value that will be used to identify requests that are eligible for this Security Application Manager configuration.

values

Array

String values

type: EM Only

Identifies one or more values used to identify requests that are eligible for this Security Application Manager configuration.

Specify a URL path pattern that starts directly after the hostname. Exclude a protocol or a hostname when defining valuevalues.
Sample values:
/marketing
/800001/mycustomerorigin

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 your customer account number.

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.edgecast.com/v2/mcc/customers/0001/waf/v1.0/scopes HTTP/1.1

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

Accept: application/json

Content-Type: application/json

Host: api.edgecast.com

{
	"name": "scopes-web-security",
	"scopes": [{
			"acl_prod_action": {
				"name": "acl-action",
				"response_body_base64": "VGhpcyBpcyBhY2wgY3VzdG9tIHJlc3BvbnNlCg==",
				"response_headers": {
					"x-ec-rules": "acl-rejected"
				},
				"status": 403,
				"enf_type": "CUSTOM_RESPONSE"
			},
			"acl_prod_id": "CGefudum",
			"host": {
				"is_negated": false,
				"type": "RX",
				"value": ".*.toontot.com"
			},
			"id": "Je0eroPH",
			"limits": [{
					"action": {
						"duration_sec": 10,
						"name": "ddos-action",
						"response_body_base64": "VGhpcyBpcyBkZG9zIGN1c3RvbSByZXNwb25zZQo=",
						"response_headers": {
							"x-ec-rules": "ddos_rejected"
						},
						"status": 403,
						"enf_type": "CUSTOM_RESPONSE"
					},
					"id": "vTma2xvK"
				}
			],
			"name": "name",
			"path": {
				"is_negated": false,
				"type": "GLOB",
				"value": "*"
			},
			"profile_prod_action": {
				"id": "QCtpQ46-",
				"name": "waf-action",
				"response_headers": {
					"x-ec-rules": "profile-rejected"
				},
				"status": 403,
				"enf_type": "CUSTOM_RESPONSE"
			},
			"profile_prod_id": "jYrI-b9K",
			"rules_prod_action": {
				"name": "rules-action",
				"response_headers": {
					"x-ec-rules": "customrules-rejected"
				},
				"status": 403,
				"enf_type": "CUSTOM_RESPONSE"
			},
			"rules_prod_id": "nTCd8ghw"
		}
	]
}

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

{
	"id": "0001",
	"status": "success",
	"success": true
}