Help Center/ Web Application Firewall/ API Reference/ APIs/ Rule Management/ Creating a CC Attack Protection Rule
Updated on 2024-04-25 GMT+08:00

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. To obtain it, go to Cloud management console and hover the cursor over your username. On the displayed window, choose My Credentials.Then, in the Projects area, view Project ID of the corresponding project.

policy_id

Yes

String

ID of a protection policy. You can specify a protection policy ID to query the rules used in the protection policy. You can obtain the policy ID by calling the ListPolicy API.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

enterprise_project_id

No

String

You can obtain the ID by calling the ListEnterpriseProject API of EPS.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token. It can be obtained by calling the IAM API (value of X-Subject-Token in the response header).

Content-Type

Yes

String

Content type.

Default: application/json;charset=utf8

Table 4 Request body parameters

Parameter

Mandatory

Type

Description

name

No

String

Rule name.

mode

Yes

Integer

Work mode. The value can be 0 (standard) or 1 (advanced). The parameters of the advanced mode cannot be described in the same document of the same API. For details, see this parameter on the console page.

Enumeration values:

  • 0

  • 1

conditions

Yes

Array of CcCondition objects

Condition list. This parameter is returned when mode is set to 1.

action

Yes

action object

Action to take if the number of requests reaches the upper limit.

tag_type

Yes

String

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

  • policy: Policy-based rate limiting

  • domain: Domain name rate limit

  • url: URL rate limit

Enumeration values:

  • ip

  • cookie

  • header

  • other

  • policy

  • domain

  • url

tag_index

No

String

User identifier. 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 duration, 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.

domain_aggregation

No

Boolean

Whether to enable domain name aggregation statistics

region_aggregation

No

Boolean

Whether to enable global counting.

description

No

String

Rule description.

Table 5 CcCondition

Parameter

Mandatory

Type

Description

category

Yes

String

Field type.

Enumeration values:

  • url

  • ip

  • ipv6

  • params

  • cookie

  • header

  • response_code

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

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 Field Type is set to params, cookie, or header, set this parameter based on the site requirements and this parameter is mandatory.

Table 6 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 7 detail

Parameter

Mandatory

Type

Description

response

No

response object

Block Page.

Table 8 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

Block page information.

Table 9 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 10 Response body parameters

Parameter

Type

Description

name

String

Rule name.

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

Boolean

Whether a prefix is used for the path. If the protected URL ends with an asterisk (*), a path prefix is used. If the value of mode is 0, this parameter has a return value.

mode

Integer

Mode.

  • 0: Standard.

  • 1: Advanced.

Enumeration values:

  • 0

  • 1

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

Condition list. This parameter is returned when mode is set to 1.

action

action object

Action to take if the number of requests reaches the upper limit.

tag_type

String

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

  • policy: Policy-based rate limiting

  • domain: Domain name rate limit

  • url: URL rate limit

Enumeration values:

  • ip

  • cookie

  • header

  • other

  • policy

  • domain

  • url

tag_index

String

User identifier. 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 duration, 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.

domain_aggregation

Boolean

Whether to enable domain name aggregation statistics

region_aggregation

Boolean

Whether to enable global counting.

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 is created.

Table 11 CcCondition

Parameter

Type

Description

category

String

Field type.

Enumeration values:

  • url

  • ip

  • ipv6

  • params

  • cookie

  • header

  • response_code

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

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 Field Type is set to params, cookie, or header, set this parameter based on the site requirements and this parameter is mandatory.

Table 12 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 13 detail

Parameter

Type

Description

response

response object

Block Page.

Table 14 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 15 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 16 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 401

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Example Requests

The following example shows how to create a CC protection rule. The project ID is specified by project_id and protection policy ID is specified by policy_id. The rule name is test55, rate limit mode is IP-based rate limit, the rate limit frequency is 10, the rate limit duration is 60s, and the protective action is verification code. The protection mode of the CC rule is advanced. The field type of the rate limit condition is the URL that contains /url. There is no subfield. Requests are counted only for the current WAF instance.

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

{
  "description" : "",
  "name" : "test55",
  "tag_type" : "ip",
  "limit_num" : 10,
  "limit_period" : 60,
  "action" : {
    "category" : "captcha"
  },
  "mode" : 1,
  "domain_aggregation" : false,
  "conditions" : [ {
    "category" : "url",
    "logic_operation" : "contain",
    "contents" : [ "/url" ],
    "index" : null
  } ],
  "region_aggregation" : false
}

Example Responses

Status code: 200

Request succeeded.

{
  "id" : "f88c5eabff9b4ff9ba6e7dd8e38128ba",
  "policyid" : "d471eef691684f1c8d7784532fd8f4bd",
  "name" : "test55",
  "timestamp" : 1678873040603,
  "description" : "",
  "status" : 1,
  "mode" : 1,
  "conditions" : [ {
    "category" : "url",
    "contents" : [ "/url" ],
    "logic_operation" : "contain"
  } ],
  "action" : {
    "category" : "captcha"
  },
  "producer" : 1,
  "unaggregation" : false,
  "total_num" : 0,
  "limit_num" : 10,
  "limit_period" : 60,
  "lock_time" : 0,
  "tag_type" : "ip",
  "aging_time" : 0,
  "region_aggregation" : false,
  "domain_aggregation" : false
}

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.