Creating a CC Attack Protection Rule

Function

This API is used to create a CC attack protection rule.

URI

POST /v1/{project_id}/waf/policy/{policy_id}/cc

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID

policy_id

Yes

String

Policy ID. It can be obtained by calling the ListPolicy API.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

auth token

Content-Type

Yes

String

Content type.

Default: application/json;charset=utf8

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

mode

Yes

Integer

Protection mode of the CC attack protection rule, which corresponds to the Mode field in the Add CC Attack Protection Rule dialog box on the WAF console.

  • 0: standard. Only the protected paths of domain names can be specified.

  • 1: The path, IP address, cookie, header, and params fields can all be set.

Enumeration values:

  • 0

  • 1

url

Yes

String

Path to be protected in the CC attack protection rule. This parameter is mandatory when the CC attack protection rule is in standard mode (i.e. the value of mode is 0).

conditions

No

Array of CcCondition objects

Rate limit conditions of the CC attack protection rule. This parameter is mandatory when the CC attack protection rule is in advanced mode (i.e. the value of mode is 1).

action

Yes

action object

Protection action to take if the number of requests reaches the upper limit.

tag_type

Yes

String

Rate limit mode.

  • ip: IP-based rate limiting. Website visitors are identified by IP address.

  • cookie: User-based rate limiting. Website visitors are identified by the cookie key value.

  • header: User-based rate limiting. Website visitors are identified by the header field.

  • other: Website visitors are identified by the Referer field (user-defined request source).

Enumeration values:

  • ip

  • cookie

  • header

  • other

tag_index

No

String

User tag. This parameter is mandatory when the rate limit mode is set to user (cookie or header).

  • cookie: Set the cookie field name. You need to configure an attribute variable name in the cookie that can uniquely identify a web visitor based on your website requirements. This field does not support regular expressions. Only complete matches are supported. For example, if a website uses the name field in the cookie to uniquely identify a website visitor, select name.

  • header: Set the user-defined HTTP header you want to protect. You need to configure the HTTP header that can identify web visitors based on your website requirements.

tag_condition

No

tag_condition object

User tag. This parameter is mandatory when the rate limit mode is set to other. - other: A website visitor is identified by the Referer field (user-defined request source).

limit_num

Yes

Integer

Rate limit frequency based on the number of requests. The value ranges from 1 to 2,147,483,647.

limit_period

Yes

Integer

Rate limit period, in seconds. The value ranges from 1 to 3,600.

unlock_num

No

Integer

Allowable frequency based on the number of requests. The value ranges from 0 to 2,147,483,647. This parameter is required only when the protection action type is dynamic_block.

lock_time

No

Integer

Block during, in seconds. The value ranges from 0 to 65,535. Access requests are blocked during the configured block duration, and an error page is displayed.

description

No

String

Rule description.

Table 4 CcCondition

Parameter

Mandatory

Type

Description

category

Yes

String

Field type. The value can be url, ip, params, cookie, or header.

Enumeration values:

  • url

  • ip

  • params

  • cookie

  • header

logic_operation

Yes

String

Logic for matching the condition.

  • If the category is url, the optional operations are contain, not_contain, equal, not_equal, prefix, not_prefix, suffix, not_suffix, contain_any, not_contain_all, equal_any, not_equal_all, equal_any, not_equal_all, prefix_any, not_prefix_all, suffix_any, not_suffix_all, len_greater, len_less, len_equal and len_not_equal

  • If the category is ip, the optional operations are: equal, not_equal, , equal_any and not_equal_all

  • If the category is params, cookie and header, the optional operations are: contain, not_contain, equal, not_equal, prefix, not_prefix, suffix, not_suffix, contain_any, not_contain_all, equal_any, not_equal_all, equal_any, not_equal_all, prefix_any, not_prefix_all, suffix_any, not_suffix_all, len_greater, len_less, len_equal, len_not_equal, num_greater, num_less, num_equal, num_not_equal, exist and not_exist

Enumeration values:

  • contain

  • not_contain

  • equal

  • not_equal

  • prefix

  • not_prefix

  • suffix

  • not_suffix

  • contain_any

  • not_contain_all

  • equal_any

  • not_equal_all

  • prefix_any

  • not_prefix_all

  • suffix_any

  • not_suffix_all

  • num_greater

  • num_less

  • num_equal

  • num_not_equal

  • exist

  • not_exist

contents

No

Array of strings

Content of the conditions. This parameter is mandatory when the suffix of logic_operation is not any or all.

value_list_id

No

String

Reference table ID. It can be obtained by calling the API Querying the Reference Table List. This parameter is mandatory when the suffix of logic_operation is any or all. The reference table type must be the same as the category type.

index

No

String

Subfield. When category is set to params, cookie, or header, set this parameter based on site requirements. This parameter is mandatory.

Table 5 action

Parameter

Mandatory

Type

Description

category

Yes

String

Action type:

  • captcha: Verification code. WAF requires visitors to enter a correct verification code to continue their access to requested page on your website.

  • block: WAF blocks the requests. When tag_type is set to other, the value can only be block.

  • log: WAF logs the event only.

  • dynamic_block: In the previous rate limit period, if the request frequency exceeds the value of Rate Limit Frequency, the request is blocked. In the next rate limit period, if the request frequency exceeds the value of Permit Frequency, the request is still blocked. Note: The dynamic_block protection action can be set only when the advanced protection mode is enabled for the CC protection rule.

Enumeration values:

  • captcha

  • block

  • log

  • dynamic_block

detail

No

detail object

Block page information. When protection action category is set to block or dynamic_block, you need to set the returned block page.

  • If you want to use the default block page, this parameter can be excluded.

  • If you want to use a custom block page, set this parameter.

Table 6 detail

Parameter

Mandatory

Type

Description

response

No

response object

Returned page

Table 7 response

Parameter

Mandatory

Type

Description

content_type

No

String

Content type. The value can only be application/json, text/html, or text/xml.

Enumeration values:

  • application/json

  • text/html

  • text/xml

content

No

String

Protection page content.

Table 8 tag_condition

Parameter

Mandatory

Type

Description

category

No

String

User identifier. The value is fixed at referer.

contents

No

Array of strings

Content of the user identifier field.

Response Parameters

Status code: 200

Table 9 Response body parameters

Parameter

Type

Description

id

String

Rule ID.

policyid

String

Policy ID.

url

String

When the value of mode is 0, this parameter has a return value. URL to which the rule applies, excluding a domain name.

  • Prefix match: A path ending with * indicates that the path is used as a prefix. For example, to protect /admin/test.php or /adminabc, you can set Path to /admin*.

  • Exact match: The path you enter must exactly match the path you want to protect. If the path you want to protect is /admin, set url to /admin.

prefix

Boolean

Whether a prefix is used for the path. If the protected URL ends with an asterisk (*), a path prefix is used.

mode

Integer

Mode.

  • 0: Standard.

  • 1: Advanced.

status

Integer

Rule status. The value can be 0 or 1.

  • 0: The rule is disabled.

  • 1: The rule is enabled.

conditions

Array of CcCondition objects

Rate limit conditions of the CC attack protection rule. This parameter is mandatory when the CC attack protection rule is in advanced mode (i.e. the value of mode is 1).

action

action object

Protection action to take if the number of requests reaches the upper limit.

tag_type

String

Rate limit mode.

  • ip: IP-based rate limiting. Website visitors are identified by IP address.

  • cookie: User-based rate limiting. Website visitors are identified by the cookie key value.

  • other: Website visitors are identified by the Referer field (user-defined request source).

Enumeration values:

  • ip

  • other

  • cookie

  • header

tag_index

String

User tag. This parameter is mandatory when the rate limit mode is set to user (cookie or header).

  • cookie: Set the cookie field name. You need to configure an attribute variable name in the cookie that can uniquely identify a web visitor based on your website requirements. This field does not support regular expressions. Only complete matches are supported. For example, if a website uses the name field in the cookie to uniquely identify a website visitor, select name.

  • header: Set the user-defined HTTP header you want to protect. You need to configure the HTTP header that can identify web visitors based on your website requirements.

tag_condition

tag_condition object

User tag. This parameter is mandatory when the rate limit mode is set to other. - other: A website visitor is identified by the Referer field (user-defined request source).

limit_num

Integer

Rate limit frequency based on the number of requests. The value ranges from 1 to 2,147,483,647.

limit_period

Integer

Rate limit period, in seconds. The value ranges from 1 to 3,600.

unlock_num

Integer

Allowable frequency based on the number of requests. The value ranges from 0 to 2,147,483,647. This parameter is required only when the protection action type is dynamic_block.

lock_time

Integer

Block during, in seconds. The value ranges from 0 to 65,535. Access requests are blocked during the configured block duration, and an error page is displayed.

description

String

Rule description.

total_num

Integer

This parameter is reserved and can be ignored currently.

unaggregation

Boolean

This parameter is reserved and can be ignored currently.

aging_time

Integer

Rule aging time. This parameter is reserved and can be ignored currently.

producer

Integer

Rule creation object. This parameter is reserved and can be ignored currently.

timestamp

Long

Timestamp the rule was created.

Table 10 CcCondition

Parameter

Type

Description

category

String

Field type. The value can be url, ip, params, cookie, or header.

Enumeration values:

  • url

  • ip

  • params

  • cookie

  • header

logic_operation

String

Logic for matching the condition.

  • If the category is url, the optional operations are contain, not_contain, equal, not_equal, prefix, not_prefix, suffix, not_suffix, contain_any, not_contain_all, equal_any, not_equal_all, equal_any, not_equal_all, prefix_any, not_prefix_all, suffix_any, not_suffix_all, len_greater, len_less, len_equal and len_not_equal

  • If the category is ip, the optional operations are: equal, not_equal, , equal_any and not_equal_all

  • If the category is params, cookie and header, the optional operations are: contain, not_contain, equal, not_equal, prefix, not_prefix, suffix, not_suffix, contain_any, not_contain_all, equal_any, not_equal_all, equal_any, not_equal_all, prefix_any, not_prefix_all, suffix_any, not_suffix_all, len_greater, len_less, len_equal, len_not_equal, num_greater, num_less, num_equal, num_not_equal, exist and not_exist

Enumeration values:

  • contain

  • not_contain

  • equal

  • not_equal

  • prefix

  • not_prefix

  • suffix

  • not_suffix

  • contain_any

  • not_contain_all

  • equal_any

  • not_equal_all

  • prefix_any

  • not_prefix_all

  • suffix_any

  • not_suffix_all

  • num_greater

  • num_less

  • num_equal

  • num_not_equal

  • exist

  • not_exist

contents

Array of strings

Content of the conditions. This parameter is mandatory when the suffix of logic_operation is not any or all.

value_list_id

String

Reference table ID. It can be obtained by calling the API Querying the Reference Table List. This parameter is mandatory when the suffix of logic_operation is any or all. The reference table type must be the same as the category type.

index

String

Subfield. When category is set to params, cookie, or header, set this parameter based on site requirements. This parameter is mandatory.

Table 11 action

Parameter

Type

Description

category

String

Action type:

  • captcha: Verification code. WAF requires visitors to enter a correct verification code to continue their access to requested page on your website.

  • block: WAF blocks the requests. When tag_type is set to other, the value can only be block.

  • log: WAF logs the event only.

  • dynamic_block: In the previous rate limit period, if the request frequency exceeds the value of Rate Limit Frequency, the request is blocked. In the next rate limit period, if the request frequency exceeds the value of Permit Frequency, the request is still blocked. Note: The dynamic_block protection action can be set only when the advanced protection mode is enabled for the CC protection rule.

Enumeration values:

  • captcha

  • block

  • log

  • dynamic_block

detail

detail object

Block page information. When protection action category is set to block or dynamic_block, you need to set the returned block page.

  • If you want to use the default block page, this parameter can be excluded.

  • If you want to use a custom block page, set this parameter.

Table 12 detail

Parameter

Type

Description

response

response object

Block Page

Table 13 response

Parameter

Type

Description

content_type

String

Content type. The value can only be application/json, text/html, or text/xml.

Enumeration values:

  • application/json

  • text/html

  • text/xml

content

String

Block page information.

Table 14 tag_condition

Parameter

Type

Description

category

String

User identifier. The value is fixed at referer.

contents

Array of strings

Content of the user identifier field.

Status code: 400

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 401

Table 16 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Example Requests

POST https://{Endpoint}/v1/{project_id}/waf/policy/{policy_id}/cc?

{
  "action" : {
    "category" : "captcha"
  },
  "description" : "",
  "limit_num" : 10,
  "limit_period" : 60,
  "mode" : 0,
  "tag_type" : "ip",
  "url" : "/path"
}

Example Responses

Status code: 200

Request succeeded.

{
  "description" : "",
  "id" : "a5f3fd28db564696b199228f0ac346b2",
  "limit_num" : 10,
  "limit_period" : 60,
  "lock_time" : 0,
  "mode" : 0,
  "policyid" : "1f016cde588646aca3fb19f277c44d03",
  "prefix" : false,
  "status" : 1,
  "tag_type" : "ip",
  "timestamp" : 1656494435686,
  "total_num" : 0,
  "aging_time" : 0,
  "unaggregation" : false,
  "producer" : 1,
  "url" : "/path"
}

Status Codes

Status Code

Description

200

Request succeeded.

400

Request failed.

401

The token does not have required permissions.

500

Internal server error.

Error Codes

See Error Codes.

last updated: UTC - commit: