CreateDefenseRule - Web Application Firewall - Alibaba Cloud Documentation Center

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The ID of the WAF instance. Note You can call the DescribeInstance operation to query the ID of your WAF instance.	waf_v2_public_cn-****
TemplateId	integer	No	The ID of the protection rule template. Note This parameter is required only when DefenseType is set to template.	1122
DefenseScene	string	Yes	The scenario of the protection rule. If DefenseType is set to template, valid values are: waf_group: basic protection. waf_base: new web core protection. antiscan: scan protection. ip_blacklist: IP blacklist. custom_acl: custom rule. whitelist: whitelist. region_block: Location Blacklist. custom_response: custom response. cc: CC protection. tamperproof: web tamper proofing. dlp: data leak prevention. spike_throttle: peak traffic throttling. If DefenseType is set to resource, valid values are: account_identifier: account identifier. If DefenseType is set to global, valid values are: regular_custom: custom regular expression.	waf_group
Rules	string	Yes	The configuration of the rule. Specify a string that is a JSON-formatted array of parameters. Note The parameters vary based on the value of DefenseScene. For more information, see Protection rule parameters.	waf_group
ResourceManagerResourceGroupId	string	No	The ID of the resource group.	rg-acfm***q
DefenseType	string	No	The type of the protection rule. Valid values: template (default): template protection rule. resource: protection rule for a specific protected object. global: global protection rule.	template
RegionId	string	No	The region where the WAF instance is deployed. Valid values: cn-hangzhou: the Chinese mainland. ap-southeast-1: outside the Chinese mainland.	cn-hangzhou
Resource	string	No	The protected object. Note This parameter is required only when DefenseType is set to resource.	sec****-waf

Protection rule parameters

Template protection rules (template)

If DefenseType is set to template, the rule configuration is as follows.

Basic protection rules (waf_group)

Parameters

Name	Type	Required	Example	Description
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode.
policyId	Long	No	1012	The ID of the protection rule group. The default value is 1012, which indicates the medium-level rule group.
protectionType	String	No	sema	The type of the protection rule. Valid values: - regular (default): regular expression protection. - sema: semantic protection.
config	String	No	{"nonInjectionSql":1}	The custom configuration. This is a JSON string. For more information, see Detailed config parameters.

Detailed config parameters

If protectionType is set to sema (semantic protection)

Name	Type	Required	Example	Description
nonInjectionSql	Integer	Yes	1	The status of non-injection attack detection. Valid values: - 0: disabled. - 1 (default): enabled.

Example

{
    "DefenseScene": "waf_group",
    "TemplateId": 322,
    "InstanceId": "waf_cn****",
    "Rules": "[{\"status\":1,\"policyId\":1012,\"action\":\"block\"},{\"status\":1,\"action\":\"block\",\"protectionType\":\"sema\",\"config\":\"{\\\"nonInjectionSql\\\":1}\"}]"
}

New web core protection rules (waf_base)

Parameters

Name	Type	Required	Example	Description
autoUpdate	Boolean	Yes	true	Specifies whether to enable automatic updates. Valid values: - true: enables automatic updates. - false: disables automatic updates.
config	Array	Yes	[{"ruleType":"system","ruleDetail":[{"ruleId":13000412,"ruleStatus":1,"ruleAction":"block"}]}]	The rule configuration to be modified. For more information, see Detailed config parameters. Important You can call the DescribeBaseSystemRules operation to query the system protection rule configuration of the template. You can call the DescribeDefenseRules operation to query the custom regular expression rule configuration of the template.

Detailed config parameters

Name	Type	Required	Example	Description
ruleType	String	Yes	system	The type of the rule. Valid values: - system: system rule in basic protection. - custom: custom regular expression rule in basic protection.
ruleBatchOperationConfig	String	No	default	The batch operation to modify rules. If this parameter is not empty, the RuleDetail parameter must be empty. Valid values: - default: restores the default settings. - all_on: enables all rules. - all_off: disables all rules. - all_block: sets the action of all rules to block. - all_monitor: sets the action of all rules to monitor.
ruleDetail	Array	No	[{"ruleId":13000412,"ruleStatus":1,"ruleAction":"block"}]]	The rule configuration to be modified. It contains the following parameters: - ruleId: the rule ID. - ruleStatus: the rule status. - ruleAction: the rule action.

Example

{
    "DefenseScene": "waf_base",
    "TemplateId": 322,
    "InstanceId": "waf_cn****",
    "Rules": "[{\"autoUpdate\":true,\"config\":[{\"ruleType\":\"system\",\"ruleDetail\":[{\"ruleId\":13000412,\"ruleStatus\":1,\"ruleAction\":\"block\"}]}]}]"
}

Scan protection rules (antiscan)

Parameters

Name	Type	Required	Example	Description
protectionType	String	Yes	highfreq	The subtype of the scan protection rule. Valid values: - highfreq: high-frequency scan blocking. - dirscan: directory traversal blocking. - scantools: scan tool blocking.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode.
config	String	No	{"target":"remote_addr","interval":60,"ttl":180,"count":20}	The custom configuration. This is a JSON string. For more information, see Detailed config parameters.

Detailed config parameters

If protectionType is set to highfreq (high-frequency scan blocking)

Name	Type	Required	Example	Description
target	String	Yes	remote_addr	The type of the statistic object. Valid values: - remote_addr (default): IP address. - cookie.acw_tc: session. - header: custom header. If you select this value, you must specify the header to be used for statistics in the subkey parameter. - queryarg: custom parameter. If you select this value, you must specify the name of the custom parameter to be used for statistics in the subkey parameter. - cookie: custom cookie. If you select this value, you must specify the cookie to be used for statistics in the subkey parameter.
subKey	String	No	abc	The sub-feature of the statistic object. This parameter is required when target is set to cookie, header, or queryarg.
interval	Integer	No	60	The detection period in seconds. The default value is 60. Valid range: 5 to 1800.
ttl	Integer	No	1800	The blocking period in seconds. The default value is 1800. Valid range: 60 to 86400.
count	Integer	No	20	The maximum number of times a basic protection rule can be triggered. The default value is 20. Valid range: 3 to 50000.
ruleIdCount	Integer	No	2	The maximum number of triggered rules. The default value is 2. Valid range: 1 to 50.

If protectionType is set to dirscan (directory traversal blocking)

Name	Type	Required	Example	Description
target	String	Yes	remote_addr	The object for statistics and blocking. Valid values: - remote_addr (default): IP address. - cookie.acw_tc: session. - header: custom header. - queryarg: custom parameter. - cookie: custom cookie.
subKey	String	No	1	The sub-feature of the object for statistics and blocking. This parameter is required only when target is set to header, queryarg, or cookie.
interval	Integer	No	60	The detection period in seconds. The default value is 60. Valid range: 5 to 1800.
ttl	Integer	No	1800	The blocking period in seconds. The default value is 1800. Valid range: 60 to 86400.
count	Integer	No	20	The maximum number of times a basic protection rule can be triggered. The default value is 20. Valid range: 3 to 50000.
weight	Float	No	2	The percentage of 404 response codes. The default value is 0.7. Valid range: 0.01 to 1.0, accurate to two decimal places.
uriNum	Integer	No	2	The maximum number of non-existent directories. The default value is 50. Valid range: 2 to 50000.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2222,
    "DefenseScene": "antiscan",
    "Rules": "[{\"protectionType\":\"scantools\",\"action\":\"block\",\"status\":1},{\"protectionType\":\"dirscan\",\"status\":1,\"action\":\"block\",\"config\":\"{\\\"target\\\":\\\"remote_addr\\\",\\\"interval\\\":10,\\\"ttl\\\":1800,\\\"weight\\\":0.7,\\\"uriNum\\\":50,\\\"count\\\":50}\"},{\"protectionType\":\"highfreq\",\"status\":1,\"action\":\"block\",\"config\":\"{\\\"target\\\":\\\"remote_addr\\\",\\\"interval\\\":60,\\\"ttl\\\":1800,\\\"count\\\":20,\\\"ruleIdCount\\\":2}\"}]"
}

IP blacklist rules (ip_blacklist)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	iptest	The name of the IP blacklist rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode.
remoteAddr	Array	Yes	["1.1.XX.XX", "3.1.XX.XX/24"]	The list of IP addresses to add to the blacklist. Specify the list in the ["ip1","ip2",...] format.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2222,
    "DefenseScene": "ip_blacklist",
    "Rules": "[{\"name\":\"iptest1\",\"remoteAddr\":[\"1.1.1.2\",\"3.3.3.3/24\"],\"action\":\"monitor\",\"status\":1},{\"name\":\"iptest2\",\"remoteAddr\":[\"4.4.4.4\",\"5.5.5.5/32\"],\"action\":\"block\",\"status\":1}]"
}

Custom rules (custom_acl)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	iptest	The name of the custom ACL rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode. - js: performs a JavaScript challenge. - captcha: uses a slider. - captcha_strict: uses a strict slider. Note For the supported actions of custom ACL rules, see the custom rule actions displayed in the WAF console.
conditions	Array	Yes	[{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}]	The traffic characteristics for the ACL. This is a JSON string. You can specify up to five match conditions. For more information, see Detailed conditions parameters.
ccStatus	Integer	Yes	1	Specifies whether to enable rate limiting. Valid values: - 0: disables rate limiting. - 1: enables rate limiting.
ratelimit	JSON	No	{"target":"remote_addr","interval":5,"threshold":2,"ttl":1800,"status":{"code":404,"count":2}}	The detailed rate limiting configuration. This is a JSON string. This parameter is required only when ccStatus is set to 1. For more information, see Detailed ratelimit parameters.
effect	String	No	rule	The scope of the rate limiting rule. This parameter is required only when ccStatus is set to 1. Valid values: - service: The rule applies to the protected object. - rule: The rule applies to a single rule.
grayStatus	Integer	No	1	Specifies whether to enable canary release for the rule. Valid values: - 0 (default): disables canary release. - 1: enables canary release.
grayConfig	JSON	No	{"grayTarget":"header","grayRate":80,"graySubKey":"test"}	The canary release configuration for the rule. This is a JSON string. This parameter is required only when grayStatus is set to 1. For more information, see Detailed grayConfig parameters.
timeConfig	JSON	No	{"timeScope":"period","timeZone":8,"timePeriods":[{"start":1758771729787,"end":1758816000000}]}	The scheduled time for the rule to take effect. This is a JSON string. For more information, see Detailed timeConfig parameters.

Detailed conditions parameters

Name	Type	Required	Example	Description
key	String	Yes	IP	The match field. Valid values: URL, URLPath, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header, Extension, Filename, Server-Port, Host, Cookie-Exact, Query-Arg, Post-Arg. Important The supported match fields vary by WAF version. Use the match fields for custom rules in the WAF console.
subKey	String	No	abc	The custom sub-match field. Note Not all match fields (key) have a custom sub-match field (subKey). For information about which match fields support a sub-match field, see the relationship between match fields and custom match fields for custom rules in the WAF console.
opValue	String	Yes	contain	The logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: is not equal to. - eq: is equal to. - lt: is less than. - gt: is greater than. - len-lt: length is less than. - len-eq: length is equal to. - len-gt: length is greater than. - not-match: does not match. - match-one: is equal to one of multiple values. - all-not-match: is not equal to any of the values. - all-not-contain: does not contain any of the values. - contain-one: contains one of multiple values. - not-regex: does not match the regular expression. - regex: matches the regular expression. - all-not-regex: does not match any of the regular expressions. - regex-one: matches one of the regular expressions. - prefix-match: matches the prefix. - suffix-match: matches the suffix. - empty: is empty. - exists: the field exists. - inl: is in the list. Note Not all match fields (key) support all logical operators (opValue). For information about which logical operators are supported for each match field, see the relationship between match fields and logical operators for custom rules in the WAF console.
values	String	Yes	abc	The match content. Specify the content as needed. Note The valid values for the logical operator (opValue) and match content (values) parameters depend on the specified match field (key).

Detailed ratelimit parameters

Name	Type	Required	Example	Description
target	String	Yes	remote_addr	The type of the statistic object. Valid values: - remote_addr (default): IP address. - cookie.acw_tc: session. - header: custom header. If you select this value, you must specify the header to be used for statistics in the subkey parameter. - queryarg: custom parameter. If you select this value, you must specify the name of the custom parameter to be used for statistics in the subkey parameter. - cookie: custom cookie. If you select this value, you must specify the cookie to be used for statistics in the subkey parameter.
subKey	String	No	abc	The sub-feature of the statistic object. This parameter is required when target is set to cookie, header, or queryarg.
interval	Integer	Yes	60	The statistical period in seconds. This is the period for counting access attempts and is used with the threshold (threshold) parameter. Valid range: 1 to 1800.
threshold	Integer	Yes	200	The maximum number of times a single statistic object can access the protected address within the detection period.
ttl	Integer	Yes	1800	The duration of the action in seconds. Valid range: 60 to 86400.
status	JSON	No	{"code":404,"count":200}	The response code frequency settings. This is a JSON string that contains the following parameters: code: Integer, required. The specified response code. count: Integer, optional. The trigger threshold. The protection rule is triggered if the specified response code appears more times than this threshold. Valid range: 2 to 50000. You can set either the count parameter or the ratio parameter. ratio: Integer, optional. The trigger threshold (percentage). The protection rule is triggered if the percentage of the specified response code exceeds this threshold. Valid range: 1 to 100. You can set either the count parameter or the ratio parameter.

Detailed grayConfig parameters

Name	Type	Required	Example	Description
grayTarget	String	Yes	80	The type of the canary release object. Valid values: - remote_addr (default): IP address. - cookie.acw_tc: session. - header: custom header. If you select this value, you must specify the header to be used for statistics in the graySubKey parameter. - queryarg: custom parameter. If you select this value, you must specify the name of the custom parameter to be used for statistics in the graySubKey parameter. - cookie: custom cookie. If you select this value, you must specify the cookie to be used for statistics in the graySubKey parameter.
graySubKey	String	No	abc	The sub-feature of the statistic object. This parameter is required when grayTarget is set to cookie, header, or queryarg.
grayRate	Integer	Yes	20	The percentage of traffic for the canary release. Valid range: 1 to 100.

Detailed timeConfig parameters

Name	Type	Required	Example	Description
timeScope	String	Yes	perid	The effective time range of the rule. Valid values: - permanent (default): always effective. - period: effective during a specific time period. - cycle: effective periodically.
timeZone	Integer	Yes	8	The time zone for the rule to take effect. The default value is 8. Valid range: -12 to 12. 0 indicates UTC. 8 indicates UTC+8. -8 indicates UTC-8.
timePeriods	Array	No	[{"start":1758771729787,"end":1758816000000}]	The time period during which the rule is effective. This parameter is required when timeScope is set to period. You can set multiple time periods. - start: Long, required. The start time of the rule, specified as a UNIX timestamp in milliseconds. - end: Long, required. The end time of the rule, specified as a UNIX timestamp in milliseconds.
weekTimePeriods	Array	No	[{"day":"1","dayPeriods":[{"start":0,"end":51644084}]},{"day":"1,2,5","dayPeriods":[{"start":0,"end":42928908}]}]	The periodic time period during which the rule is effective. This parameter is required when timeScope is set to cycle. You can set multiple time periods. - day: String, required. The day of the week when the rule is effective. Valid range: 1 to 7. Separate multiple days with commas (,). For example, a value of 1 means the rule is effective every Monday. - dayPeriods: Array, required. The time period of each day when the rule is effective. It includes the start time start and end time end. You can set multiple time periods. • start: Long, required. The start time of the rule each day, specified as a millisecond timestamp relative to 00:00 of that day. Valid range: [0-86400000). • end: Long, required. The end time of the rule each day, specified as a millisecond timestamp relative to 00:00 of that day. Valid range: [0-86400000).

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 6242,
    "DefenseScene": "custom_acl",
    "Rules":"[{\"name\":\"acl_test\",\"action\":\"block\",\"conditions\":[{\"key\":\"URL\",\"opValue\":\"contain\",\"values\":\"abc\"}],\"ratelimit\":{\"target\":\"remote_addr\",\"interval\":5,\"threshold\":2,\"ttl\":1800,\"status\":{\"code\":404,\"count\":2}},\"ccStatus\":1,\"effect\":\"rule\",\"status\":1,\"origin\":\"custom\",\"timeConfig\":{\"timeScope\":\"cycle\",\"timeZone\":8,\"weekTimePeriods\":[{\"day\":\"1\",\"dayPeriods\":[{\"start\":0,\"end\":51644084}]},{\"day\":\"1,2,5\",\"dayPeriods\":[{\"start\":0,\"end\":42928908}]}]},\"grayStatus\":1,\"grayConfig\":{\"grayRate\":80,\"graySubKey\":\"test\",\"grayTarget\":\"header\"}}]"
}

Whitelist rules (whitelist)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	whitelistTest	The name of the whitelist rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
conditions	Array	Yes	[{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}]	The traffic characteristics for the whitelist. This is a JSON string. You can specify up to five match conditions. For more information, see Detailed conditions parameters.
tags	Array	Yes	["waf", "regular"]	The list of modules that the whitelist rule applies to. Specify the list in the ["XX1", "XX2",...] format. Valid values: - waf: all modules. - customrule_rule: specific custom rule. - customrule: custom rules. - blacklist: IP blacklist. - blacklist_rule: specific IP blacklist rule. - antiscan: scan protection. - regular: basic protection rules. - regular_rule: specific basic protection regular expression rule. - regular_type: specific basic protection regular expression rule type. - regular_field: specific basic protection field. - major_protection: major event support. - cc: CC protection. - region_block: Location Blacklist. - antibot_scene: BOT scenario protection. - antibot_scene_rule: specific BOT scenario protection rule ID. - antibot_scene_label: specific BOT scenario protection rule type. - dlp: data leak prevention. - tamperproof: web tamper proofing. - spike_throttle: peak traffic throttling.
regularRules	Array	No	[ "111111", "222222" ]	The list of regular expression rule IDs to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to specific basic protection regular expression rules (tags is set to regular_rule).
regularTypes	Array	No	[ "xss", "css" ]	The list of regular expression rule types to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to Web application regular expression types (tags is set to regular_type). Valid values: - sqli: SQL injection. - xss: cross-site scripting. - code_exec: code execution. - crlf: CRLF. - lfilei: local file inclusion. - rfilei: remote file inclusion. - webshell: WebShell. - csrf: CSRF. - other: other.
regularFields	Array	No	[{"key":"URL"},{"key":"Header","subKey":"abc"}]	The list of basic protection fields to be excluded from detection. This is a JSON string. You can specify up to five match conditions. For more information, see Detailed regularFields parameters. This parameter is required only when the whitelist rule applies to specific basic protection fields (tags is set to regular_field).
customRules	Array	No	[ "111111", "222222" ]	The list of custom rule IDs to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to specific custom rules (tags is set to customrule_rule).
blacklistRules	Array	No	[ "111111", "222222" ]	The list of IP blacklist rule IDs to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to specific IP blacklist rules (tags is set to blacklist_rule).
botRules	Array	No	[ "111111", "222222" ]	The list of BOT scenario protection rule IDs to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to specific BOT scenario protection rule IDs (tags is set to antibot_scene_rule).
botLables	Array	No	[ "abc", "cdcc" ]	The list of BOT scenario protection rule types to be excluded from detection. Specify the list in the ["XX1", "XX2",...] format. This parameter is required only when the whitelist rule applies to specific BOT scenario protection rule types (tags is set to antibot_scene_label). You can call the DescribeBotRuleLabels operation to query the BOT rule types.

Detailed conditions parameters

Name	Type	Required	Example	Description
key	String	Yes	IP	The match field. Valid values: URL, URLPath, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header, Server-Port, Host, Query-Arg. Important The supported match fields vary by WAF version. Use the match fields for whitelist rules in the WAF console.
subKey	String	No	abc	The custom sub-match field. Note Not all match fields (key) for whitelist rules have a custom sub-match field (subKey). For information about which match fields support a sub-match field, see the relationship between match fields and custom match fields for whitelist rules in the WAF console.
opValue	String	Yes	contain	The logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: is not equal to. - eq: is equal to. - lt: is less than. - gt: is greater than. - len-lt: length is less than. - len-eq: length is equal to. - len-gt: length is greater than. - not-match: does not match. - match-one: is equal to one of multiple values. - all-not-match: is not equal to any of the values. - all-not-contain: does not contain any of the values. - contain-one: contains one of multiple values. - not-regex: does not match the regular expression. - regex: matches the regular expression. - all-not-regex: does not match any of the regular expressions. - regex-one: matches one of the regular expressions. - prefix-match: matches the prefix. - suffix-match: matches the suffix. - empty: is empty. - exists: the field exists. - inl: is in the list. Note Not all match fields (key) for whitelist rules support all logical operators (opValue). For information about which logical operators are supported for each match field, see the relationship between match fields and logical operators for whitelist rules in the WAF console.
values	String	Yes	abc	The match content. Specify the content as needed. Note The valid values for the logical operator (opValue) and match content (values) parameters depend on the specified match field (key).

Detailed regularFields parameters

Name	Type	Required	Example	Description
key	String	Yes	URL	The field to be excluded from detection. Valid values: - URL-All: all URI-related fields. - URL: a specific URI field. - URLPath: URI Path. - Query-All: all query-related fields. - Query-Arg: a specific query parameter. - Cookie-All: all cookie-related fields. - Cookie-Exact: a specific cookie name. - Header-All: all header-related fields. - Header: a specific header field. - Body-All: all body parameters.
subKey	String	No	abc	The specific field. This parameter is required when the field to be excluded from detection (key) is set to URLPath, Query-Arg, Cookie-Exact, or Header.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 9242,
    "DefenseScene": "whitelist",
    "Rules":"[{\"name\":\"whitelistTest\",\"tags\":[\"regular_rule\",\"customrule\"],\"status\":1,\"origin\":\"custom\",\"conditions\":[{\"key\":\"URL\",\"opValue\":\"contain\",\"values\":\"/test\"},{\"key\":\"Header\",\"opValue\":\"eq\",\"values\":\"ffff\",\"subKey\":\"abc\"}],\"regularRules\":[\"123444\",\"444444\"]}]"
}

Custom response rules (custom_response)

Parameters

Name	Type	Required	Example	Description
responseType	String	Yes	response_block	The type of the custom response. Set the value to response_block, which indicates a blocked response.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
config	String	Yes	{"responseCode":400,"responseHeaders":[{"key":"custom","value":"123"},{"key":"aaa","value":"2223"}],"responseContent":"HelloWorld"}	The custom configuration. This is a JSON string. For more information, see Detailed config parameters.

Detailed config parameters

Name	Type	Required	Example	Description
responseCode	Integer	Yes	400	The specified response code.
responseHeaders	Array	No	[{"key":"custom","value":"123"},{"key":"aaaa","value":"2223"}]	The list of custom response headers. This is a JSON string. key is the header field and value is the header value.
responseContent	String	Yes	helloworld	The content of the custom response.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2841,
    "DefenseScene": "custom_response",
    "Rules":"[{\"responseType\":\"response_block\",\"config\":\"{\\\"templateName\\\":\\\"aaa\\\",\\\"responseCode\\\":\\\"400\\\",\\\"responseContent\\\":\\\"helloWorld\\\",\\\"responseHeaders\\\":[{\\\"key\\\":\\\"test1\\\",\\\"value\\\":\\\"abc\\\"}]}\",\"status\":1}]"
}

Location Blacklist rules (region_block)

Parameters

Name	Type	Required	Example	Description
cnRegionList	String	No	610000,230000	The list of regions in the Chinese mainland. To block access from all regions in the Chinese mainland except Hong Kong (China), Macao (China), and Taiwan (China), specify ["CN"]. Separate multiple regions with commas (,). For more information about the region codes, see Region codes for the Chinese mainland.
abroadRegionList	String	No	KE,KG	The list of regions outside the Chinese mainland. Separate multiple regions with commas (,). You can call the DescribeIpAbroadCountryInfos operation to query the supported countries and regions outside the Chinese mainland.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode.

Region codes for the Chinese mainland

{
    "110000": "Beijing",
    "120000": "Tianjin",
    "130000": "Hebei Province",
    "140000": "Shanxi Province",
    "150000": "Inner Mongolia Autonomous Region",
    "210000": "Liaoning Province",
    "220000": "Jilin Province",
    "230000": "Heilongjiang Province",
    "310000": "Shanghai",
    "320000": "Jiangsu Province",
    "330000": "Zhejiang Province",
    "340000": "Anhui Province",
    "350000": "Fujian Province",
    "360000": "Jiangxi Province",
    "370000": "Shandong Province",
    "410000": "Henan Province",
    "420000": "Hubei Province",
    "430000": "Hunan Province",
    "440000": "Guangdong Province",
    "450000": "Guangxi Zhuang Autonomous Region",
    "460000": "Hainan Province",
    "500000": "Chongqing",
    "510000": "Sichuan Province",
    "520000": "Guizhou Province",
    "530000": "Yunnan Province",
    "540000": "Tibet Autonomous Region",
    "610000": "Shaanxi Province",
    "620000": "Gansu Province",
    "630000": "Qinghai Province",
    "640000": "Ningxia Hui Autonomous Region",
    "650000": "Xinjiang Uygur Autonomous Region",
    "MO_01": "Macao (China)",
    "HK_01": "Hong Kong (China)",
    "TW_01": "Taiwan (China)",
    "CN": "Regions in the Chinese mainland (excluding Hong Kong, Macao, and Taiwan)",
}

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2341,
    "DefenseScene": "region_block",
    "Rules": "[{\"cnRegionList\":\"CN,HK_01,TW_01,MO_01\",\"abroadRegionList\":\"AU,NZ\",\"action\":\"block\",\"status\":1}]"
}

CC protection rules (cc)

Parameters

Name	Type	Required	Example	Description
mode	Integer	Yes	0	The CC protection mode. Valid values: - 0 (default): normal protection. - 1: emergency protection.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2241,
    "DefenseScene": "cc",
    "Rules":"[{\"mode\":0,\"status\":1}]"
}

Web tamper proofing rules (tamperproof)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	test	The name of the protection rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
url	String	Yes	/abc	The address of the cached page.
ua	String	No	app	The specified user-agent to access the path.
protocol	String	Yes	https	The protocol type of the cached page address. Valid values: http, https.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 1241,
    "DefenseScene": "tamperproof",
    "Rules": "[{\"name\":\"test1\",\"url\":\"www.test1.com\",\"ua\":\"firefox\",\"protocol\":\"https\",\"status\":1}]"
}

Data leak prevention rules (dlp)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	test	The name of the protection rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
conditions	Array	Yes	[{"key":"HttpCode","opValue":"contain","values":"400,401,402,403,404,405,500,501,502,503,504,505"},{"key":"URL","opValue":"contain","values":"test"}]	The match conditions. This is a JSON string. You can set up to two match conditions, which have a logical AND relationship. For more information, see Detailed conditions parameters.
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. This action is applicable only to scenarios that include a response code match condition. - monitor: places requests in observation mode. - filter: filters sensitive information. This action is applicable only to scenarios that include a sensitive information match condition.

Detailed conditions parameters

Name	Type	Required	Example	Description
key	String	Yes	URL	The match field. Valid values: URL, HttpCode, SensitiveInfo.
opValue	String	Yes	contain	The logical operator. The value is fixed to contain.
values	String	Yes	abc	The match content. Separate multiple values with commas (,). Valid values for HttpCode: 400, 401, 402, 403, 404, 405 (represents 405-499), 500, 501, 502, 503, 504, 505 (represents 505-599). Valid values for SensitiveInfo: - phone: phone number. - card: credit card. - id: ID card. - word: default sensitive word.

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 5241,
    "DefenseScene": "dlp",
    "Rules":"[{\"name\":\"test\",\"action\":\"filter\",\"status\":1,\"conditions\":[{\"key\":\"SensitiveInfo\",\"opValue\":\"contain\",\"values\":\"id,card\"},{\"key\":\"URL\",\"opValue\":\"contain\",\"values\":\"/test.html\"}]}]"
}

Peak traffic throttling (spike_throttle)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	iptest	The name of the peak traffic throttling rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
status	Integer	Yes	1	The status of the protection rule. This parameter is used only to create a protection rule. To modify the status of a protection rule, call the ModifyDefenseRuleStatus operation and use the RuleStatus parameter. Valid values: - 0: disabled. - 1 (default): enabled.
action	String	Yes	block	The action of the protection rule. Valid values: - block: blocks requests. - monitor: places requests in observation mode.
conditions	Array	Yes	[{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}]	The traffic characteristics for the ACL. This is a JSON string. You can specify up to five match conditions. For more information, see Detailed conditions parameters.
cnRegionList	String	No	610000,230000	The list of regions in the Chinese mainland. To block access from all regions in the Chinese mainland except Hong Kong (China), Macao (China), and Taiwan (China), specify ["CN"]. Separate multiple regions with commas (,). For more information about the region codes, see Region codes for the Chinese mainland.
abroadRegionList	String	No	KE,KG	The list of regions outside the Chinese mainland. Separate multiple regions with commas (,). You can call the DescribeIpAbroadCountryInfos operation to query the supported countries and regions outside the Chinese mainland.
type	String	Yes	qps	The throttling method. Valid values: - qps: by QPS. - ratio (default): by percentage.
threshold	Integer	Yes	500	The throttling threshold. Valid values: - If you set throttling by QPS, the valid range is [1-5000000]. For example, if you set the threshold to 500 QPS, traffic that meets the conditions and exceeds 500 QPS is blocked. - If you set throttling by percentage, the valid range is [1-99]. For example, if you set the threshold to 80%, only 80% of the traffic that meets the conditions is allowed.

Detailed conditions parameters

Name	Type	Required	Example	Description
key	String	Yes	IP	The match field. Valid values: URL, URLPath, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header.
subKey	String	No	abc	The custom sub-match field. Note Not all match fields (key) for peak traffic throttling rules have a custom sub-match field (subKey). For information about which match fields support a sub-match field, see the relationship between match fields and custom match fields for peak traffic throttling rules in the WAF console.
opValue	String	Yes	contain	The logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: is not equal to. - eq: is equal to. - lt: is less than. - gt: is greater than. - len-lt: length is less than. - len-eq: length is equal to. - len-gt: length is greater than. - not-match: does not match. - match-one: is equal to one of multiple values. - all-not-match: is not equal to any of the values. - all-not-contain: does not contain any of the values. - contain-one: contains one of multiple values. - not-regex: does not match the regular expression. - regex: matches the regular expression. - all-not-regex: does not match any of the regular expressions. - regex-one: matches one of the regular expressions. - prefix-match: matches the prefix. - suffix-match: matches the suffix. - empty: is empty. - exists: the field exists. - inl: is in the list. Note Not all match fields (key) for peak traffic rules support all logical operators (opValue). For information about which logical operators are supported for each match field, see the relationship between match fields and logical operators for peak traffic throttling rules in the WAF console.
values	String	Yes	abc	The match content. Specify the content as needed. Note The valid values for the logical operator (opValue) and match content (values) parameters depend on the specified match field (key).

Region codes for the Chinese mainland

{
    "110000": "Beijing",
    "120000": "Tianjin",
    "130000": "Hebei Province",
    "140000": "Shanxi Province",
    "150000": "Inner Mongolia Autonomous Region",
    "210000": "Liaoning Province",
    "220000": "Jilin Province",
    "230000": "Heilongjiang Province",
    "310000": "Shanghai",
    "320000": "Jiangsu Province",
    "330000": "Zhejiang Province",
    "340000": "Anhui Province",
    "350000": "Fujian Province",
    "360000": "Jiangxi Province",
    "370000": "Shandong Province",
    "410000": "Henan Province",
    "420000": "Hubei Province",
    "430000": "Hunan Province",
    "440000": "Guangdong Province",
    "450000": "Guangxi Zhuang Autonomous Region",
    "460000": "Hainan Province",
    "500000": "Chongqing",
    "510000": "Sichuan Province",
    "520000": "Guizhou Province",
    "530000": "Yunnan Province",
    "540000": "Tibet Autonomous Region",
    "610000": "Shaanxi Province",
    "620000": "Gansu Province",
    "630000": "Qinghai Province",
    "640000": "Ningxia Hui Autonomous Region",
    "650000": "Xinjiang Uygur Autonomous Region",
    "MO_01": "Macao (China)",
    "HK_01": "Hong Kong (China)",
    "TW_01": "Taiwan (China)",
    "CN": "Regions in the Chinese mainland (excluding Hong Kong, Macao, and Taiwan)",
}

Example

{
    "InstanceId": "waf_v2_public_****",
    "TemplateId": 2341,
    "DefenseScene": "spike_throttle",
    "Rules":"[{\"name\":\"test\",\"action\":\"monitor\",\"conditions\":[{\"key\":\"URL\",\"opValue\":\"contain\",\"values\":\"abctest\"}],\"status\":1,\"type\":\"qps\",\"threshold\":1000,\"cnRegionList\":\"110000,140000\",\"abroadRegionList\":\"AD,AL\"}]"}
}

Protection rules for a specific protected object (resource)

If DefenseType is set to resource, the rule configuration is as follows.

Account identifier rules (account_identifier)

You can configure only one account identifier rule for each protected object.

Parameters

Name	Type	Required	Example	Description
accountldentifiers	Array	Yes	[ { "key": "Header","subKey": "header-test", "decodeType": "jwt", "position": "username", "priority": 1 }, { "key": "Post-Arg", "subKey": "body_test", "decodeType": "plain", "priority": 2 } ]	The list of account identifier configurations. You can specify up to five configurations. Each configuration is a JSON string. For more information, see Detailed accountIdentifiers parameters.

Detailed accountIdentifiers parameters

Name	Type	Required	Example	Description
key	String	Yes	Query-Arg	The position of the field to be extracted. Valid values: Query-Arg, Cookie-Exact, Post-Arg, Header.
subKey	String	Yes	query-test	The custom sub-match field.
decodeType	String	jwt	query-test	The authentication method. Valid values: - plain: plaintext. - basic: Basic authentication. - jwt: JWT authentication. For JWT authentication, you must specify the decoded account field (position).
priority	Integer	Yes	1	The match priority of the current identifier configuration. A single traffic flow can match only one identifier policy. The valid range is [0, 20]. A smaller value indicates a higher priority. Priorities cannot be repeated.
position	String	No	account	For JWT authentication, this is the decoded account field.

Example

{
    "DefenseScene": "account_identifier",
    "Resource": "example.**.com-waf",
    "DefenseType": "resource",
    "InstaneId": "waf_cn****",
    "Rules": "[{\"accountIdentifiers\":[{\"key\":\"Header\",\"subKey\":\"header-test\",\"decodeType\":\"jwt\",\"position\":\"username\",\"priority\":1},{\"key\":\"Post-Arg\",\"subKey\":\"body_test\",\"decodeType\":\"plain\",\"priority\":2}]}]"
}

Global protection rules (global)

If DefenseType is set to global, the rule configuration is as follows.

Custom regular expression rules (regular_custom)

Parameters

Name	Type	Required	Example	Description
name	String	Yes	ruleTest	The name of the custom regular expression rule. The name can be 1 to 255 characters in length and can contain letters, digits, underscores (_), periods (.), and hyphens (-).
detectType	String	Yes	sqli	The detection type. Valid values: - sqli: SQL injection. - xss: cross-site scripting (XSS) attacks. - cmdi: OS command injection. - expression_injection: expression injection (including EL, SpEL, and OGNL expressions). - java_deserialization: Java deserialize. - dot_net_deserialization: .NET deserialize. - php_deserialization: PHP deserialize. - code_exec: arbitrary code execution (JNDI/XPATH). - ssrf: server-side request forgery (SSRF). - path_traversal: path traversal. - arbitrary_file_uploading: arbitrary file upload. - webshell: webshell. - rfilei: remote file inclusion (RFI). - lfilei: local file inclusion (LFI). - protocol_violation: protocol violation. - scanner_behavior: scanner behavior. - logic_flaw: business logic bug. - arbitrary_file_reading: Arbitrary File Read. - arbitrary_file_download: arbitrary file download. - xxe: external entity injection. - csrf: cross-site request forgery. - crlf: CRLF. - other: other.
riskLevel	String	Yes	strict	The threat level. Valid values: - super_strict: Very Strict. - strict: Strict. - medium: Medium. - loose: Loose
description	String	No	The description of the rule.	The description of the custom regular expression rule.
condition	Array	Yes	[{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}]	The traffic characteristics for the ACL. This is a JSON string. You can specify up to five match conditions. For more information, see Detailed condition parameters.

Detailed condition parameters

Name	Type	Required	Example	Description
key	String	Yes	Query-Arg	The custom match field. Valid values: File-Name, Url, Raw-Url, Request-Url, Http-Method, Directory, Query, Raw-Header, Body, Extension, Union-Args, All-Data, All-Keys, Multipart-Keys, Multipart-Values, Header-Keys, Header-Values, Post-Arg-Keys, Post-Arg-Values, Query-Arg-Keys, Query-Arg-Values, Cookie-Keys, Cookie-Values, Header, Query-Arg, Post-Arg, Multipart.
subKey	String	No	query-test	The custom sub-match field. Important A sub-match field is supported only when the match field is set to Header, Query-Arg, Post-Arg, or Multipart.
opValue	String	Yes	contain	The logical operator. Valid values:regex, prefix-match, suffix-match, eq, contain.
values	String	Yes	abc	The match content. Separate multiple values with commas (,).

Example

{
  "name": "ruleTest",
  "detectType": "sqli",
  "riskLevel": "strict",
  "condition": [{"key": "FileName","opValue": "eq","values": "test"}]
}

Response elements

Element	Type	Description	Example
	object	The response object.
RequestId	string	The ID of the request.	26E46541-7AAB-5565-801D-F14DBDC5****
RuleIds	string	The IDs of the created protection rules. Multiple rule IDs are separated by commas (,).	22215,23354,462165

Examples

Success response

JSON format

{
  "RequestId": "26E46541-7AAB-5565-801D-F14DBDC5****",
  "RuleIds": "22215,23354,462165"
}

Error codes

HTTP status code	Error code	Error message	Description
400	Defense.Control.DefenseWhitelistBypassRuleNotExist	The whitelist protection rule does not exist.	The whitelist protection rule does not exist. Rule ID:%s.
400	Defense.Control.DefenseWhitelistConfigInvalid	The whitelist rule is misconfigured.	Error configuring whitelist rule: %s.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.