Adding a Precise Protection Rule¶

Function¶

This API is used to add a precise protection rule.

URI¶

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

**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
time	Yes	Boolean	Time the precise protection rule takes effect. false: The rule takes effect immediately. true: The effective time is customized.
start	No	Long	Timestamp (ms) when the precise protection rule takes effect. This parameter is returned only when time is true.
terminal	No	Long	Timestamp (ms) when the precise protection rule expires. This parameter is returned only when time is true.
description	No	String	Rule description.
conditions	No	Array of CustomConditions objects	Match condition List
action	Yes	CustomAction object	Protective action of the precise protection rule.
priority	Yes	Integer	Priority of a rule. A small value indicates a high priority. If two rules are assigned with the same priority, the rule added earlier has higher priority. Value range: 0 to 1000.

**Table 4** CustomConditions¶
Parameter	Mandatory	Type	Description
category	No	String	Field type. The options are url, user-agent, ip, params, cookie, referer, header, request_line, method, and request. Enumeration values: url user-agent referer ip method request_line request params cookie header
index	No	String	Subfield: When the field type is url, user-agent, ip, refer, request_line, method, or request, index is not required. When the field type is params, header, or cookie, and the subfield is customized, the value of index is the customized subfield.
logic_operation	No	String	Logic for matching the condition. If the category is url, user-agent or referer , 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 method, the optional operations are: equal and not_equal If the category is request_line and request, the optional operations are: len_greater, len_less, len_equal and len_not_equal If the category is params, header, and cookie, 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.

**Table 5** CustomAction¶
Parameter	Mandatory	Type	Description
category	Yes	String	Operation type block: WAF blocks attacks. pass: WAF allows requests. log: WAF only logs detected attacks. Enumeration values: block pass log
followed_action_id	No	String	ID of a known attack source rule. This parameter can be configured only when category is set to block.

Response Parameters¶

Status code: 200

**Table 6** Response body parameters¶
Parameter	Type	Description
id	String	Rule ID.
policyid	String	Policy ID.
description	String	Rule description.
status	Integer	Rule status. The value can be 0 or 1. 0: The rule is disabled. 1: The rule is enabled.
conditions	Array of conditions objects	List of matching conditions. All conditions must be met.
action	CustomAction object	Protective action of the precise protection rule.
priority	Integer	Priority of a rule. A small value indicates a high priority. If two rules are assigned with the same priority, the rule added earlier has higher priority. Value range: 0 to 1000.
timestamp	Long	Timestamp when the precise protection rule is created.
start	Long	Timestamp (ms) when the precise protection rule takes effect. This parameter is returned only when time is true.
terminal	Long	Timestamp (ms) when the precise protection rule expires. This parameter is returned only when time is true.
action_mode	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.

**Table 7** conditions¶
Parameter	Type	Description
category	String	Field type. The options are url, user-agent, ip, params, cookie, referer, header, request_line, method, and request. Enumeration values: url user-agent ip params cookie referer header request_line method request
index	String	Subfield: When the field type is url, user-agent, ip, refer, request_line, method, or request, index is not required. When the field type is params, header, or cookie, and the subfield is customized, the value of index is the customized subfield.
logic_operation	String	Logic for matching the condition. 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 len_greater len_less len_equal len_not_equal num_greater num_less num_equal num_not_equal exist not_exist
contents	Array of strings	Content of the conditions.
value_list_id	String	Reference table ID. It can be obtained by calling the API Querying the Reference Table List. This parameter is available only when a reference table is used when a protection rule is created.

**Table 8** CustomAction¶
Parameter	Type	Description
category	String	Operation type block: WAF blocks attacks. pass: WAF allows requests. log: WAF only logs detected attacks. Enumeration values: block pass log
followed_action_id	String	ID of a known attack source rule. This parameter can be configured only when category is set to block.

Status code: 400

**Table 9** Response body parameters¶
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error message

Status code: 401

**Table 10** Response body parameters¶
Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error message

Status code: 500

**Table 11** 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}/custom?enterprise_project_id=0

{
  "action" : {
    "category" : "block"
  },
  "time" : false,
  "priority" : 50,
  "description" : "",
  "conditions" : [ {
    "category" : "url",
    "logic_operation" : "contain",
    "index" : null,
    "contents" : [ "test" ]
  } ]
}

Example Responses¶

Status code: 200

Request succeeded.

{
  "id" : "88e8bf4158324b2d9a233e7ffb95516d",
  "policyid" : "dde63c25e8394b21b16a2a49a99e659b",
  "timestamp" : 1678799936830,
  "description" : "",
  "status" : 1,
  "time" : false,
  "priority" : 50,
  "action_mode" : false,
  "conditions" : [ {
    "category" : "url",
    "contents" : [ "test" ],
    "logic_operation" : "contain"
  } ],
  "action" : {
    "category" : "block"
  },
  "producer" : 1,
  "aging_time" : 0
}

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: 2024-11-08 14:20 UTC - commit: 3d7e87e2762d0d183bd2e3d9c35302c29ab1233b