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:

Identifies the set of traffic to which it applies by hostname, a URL path, or both.
Defines how threats will be detected via access rules, custom rule sets, managed rules, and rate rules.

If one or more condition group(s) have been defined within a rate rule, then traffic will only be rate limited when it also satisfies at least one of those condition groups.
Defines the production and/or audit enforcement action that will be applied to malicious traffic.

Key information:

This endpoint allows you to quickly create, update, or delete one or more Security Application Manager configurations. These actions cannot be undone.
Create a Security Application Manager configuration by adding a scope object in the request.
Update a Security Application Manager configuration by modifying an existing scope object in the request. The id property identifies the Security Application Manager configuration that will be updated.
Delete a Security Application Manager configuration by excluding a scope object from the request.

All Security Application Manager configurations that are not explicitly defined within the request will be deleted.
The recommended method for updating your Security Application Manager configurations is to perform the following steps:
1. Retrieve your current set of Security Application Manager configurations via the Get All Security Application Manager Configurations (Scopes) endpoint.
2. Add, modify, or remove Security Application Manager configurations from the response as needed.
3. Post the updated response to this endpoint.

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.

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 value | values.
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).

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
}