Creates Web core protection rules.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
yundun-waf:CreateDefenseRule |
create |
*All Resource
|
|
None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| InstanceId |
string |
Yes |
WAF instance ID. Note
You can view your current WAF instance ID by calling the DescribeInstance API. |
waf_v2_public_cn-**** |
| TemplateId |
integer |
No |
The protection template ID for the rule to create. Note
Provide this parameter only when DefenseType is template. |
1122 |
| DefenseScene |
string |
Yes |
The WAF protection scenario to create. When DefenseType is template, valid values are:
When DefenseType is resource, valid values are:
When DefenseType is global, valid values are:
Note
For globally configured custom responses, users can reference them under protected objects or rules. When referenced at different levels, the effective logic follows this order: rule level > protected object level > default page. |
waf_group |
| Rules |
string |
Yes |
Rule configuration content, formatted as a JSON string. Note
The specific parameters vary based on the specified DefenseType (DefenseScene). For details, see Protection Rule Parameter Descriptions. |
waf_group |
| ResourceManagerResourceGroupId |
string |
No |
Alibaba Cloud resource group ID. |
rg-acfm***q |
| DefenseType |
string |
No |
Protection rule type. Valid values:
|
template |
| RegionId |
string |
No |
The region where the WAF instance resides. Valid values:
|
cn-hangzhou |
| Resource |
string |
No |
The protected object associated with the rule. Note
Provide this parameter only when DefenseType is resource. |
sec****-waf |
Protection Rule Parameter Descriptions
Template-Based Protection Rules (template)
When DefenseType is set to template, the rule configuration details are as follows.
Basic Protection Rules (waf_group)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. |
| policyId | Long | No | 1012 | Protection rule group ID. Default is the medium rule group 1012. |
| protectionType | String | No | sema | Protection type. Valid values: - regular (default): regex-based protection. - sema: semantic protection. |
| config | String | No | {"nonInjectionSql":1} | Custom configuration in JSON string format. For details, see config detailed configuration. |
Config Parameter Details
When protectionType is set to sema (semantic protection for basic rules)
| Name | Type | Required | Example | Description |
| nonInjectionSql | Integer | Yes | 1 | Non-injection attack detection status. 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| autoUpdate | Boolean | Yes | true | Auto-update setting. Valid values: - true: enable auto-update. - false: disable auto-update. |
| config | Array | Yes | [{"ruleType":"system","ruleDetail":[{"ruleId":13000412,"ruleStatus":1,"ruleAction":"block"}]}] | Rule configurations to modify. For details, see config detailed configuration. Important You can query system rule configurations for this template using the DescribeBaseSystemRules API and custom regex rule configurations using the DescribeDefenseRules API. |
Config Parameter Details
| Name | Type | Required | Example | Description |
| ruleType | String | Yes | system | Rule type. Valid values: - system: system rules in basic protection. - custom: custom regex rules in basic protection. |
| ruleBatchOperationConfig | String | No | default | Batch operation for rules. If this field is not empty, RuleDetail must be empty. Valid values: - default: restore defaults. - all_on: enable all rules. - all_off: disable all rules. - all_block: set all rule actions to block. - all_monitor: set all rule actions to monitor. |
| ruleDetail | Array | No | [{"ruleId":13000412,"ruleStatus":1,"ruleAction":"block"}]] | Rule configurations to modify. Fields include the following: - ruleId: rule ID. - ruleStatus: rule status. - ruleAction: 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| protectionType | String | Yes | highfreq | Scan protection sub-type. Valid values: - highfreq: high-frequency scan blocking. - dirscan: directory traversal blocking. - scantools: scanner tool blocking. |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. |
| actionExternal | JSON | No | {"responseRuleId":123444} | Extended configuration for rule action. Supported only for the new custom response feature. When action is block, you can specify a custom block page. |
| config | String | No | {"target":"remote_addr","interval":60,"ttl":180,"count":20} | Custom configuration in JSON string format. For details, see config detailed configuration. |
Config Parameter Details
When protectionType is set to highfreq (high-frequency scan blocking)
| Name | Type | Required | Example | Description |
| target | String | Yes | remote_addr | Statistic object type. Valid values: - remote_addr (default): IP. - cookie.acw_tc: session. - header: custom header. When selected, specify the header name in the subkey parameter. - queryarg: custom parameter. When selected, specify the parameter name in the subkey parameter. - cookie: custom cookie. When selected, specify the cookie name in the subkey parameter. |
| subKey | String | No | abc | Sub-feature of the statistic object. Required when target is cookie, header, or queryarg. |
| interval | Integer | No | 60 | Detection duration in seconds. Default is 60 seconds. Valid range: 5–1800 seconds. |
| ttl | Integer | No | 1800 | Block duration in seconds. Default is 1800 seconds. Valid range: 60–86400 seconds. |
| count | Integer | No | 20 | Maximum trigger count for basic protection rules. Default is 20. Valid range: 3–50000. |
| ruleIdCount | Integer | No | 2 | Maximum number of triggered rules. Default is 2. Valid range: 1–50. |
When protectionType is set to dirscan (directory traversal blocking)
| Name | Type | Required | Example | Description |
| target | String | Yes | remote_addr | Statistic and block object. Valid values: - remote_addr (default): IP. - cookie.acw_tc: session. - header: custom header. - queryarg: custom parameter. - cookie: custom cookie. |
| subKey | String | No | 1 | Sub-feature of the statistic and block object. Required only when target is header, queryarg, or cookie. |
| interval | Integer | No | 60 | Detection duration in seconds. Default is 60 seconds. Valid range: 5–1800 seconds. |
| ttl | Integer | No | 1800 | Block duration in seconds. Default is 1800 seconds. Valid range: 60–86400 seconds. |
| count | Integer | No | 20 | Maximum trigger count for basic protection rules. Default is 20. Valid range: 3–50000. |
| weight | Float | No | 2 | 404 response code percentage. Default is 0.7. Valid range: 0.01–1.0, precise to two decimal places. |
| uriNum | Integer | No | 2 | Maximum number of non-existent directories. Default is 50. Valid range: 2–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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | iptest | IP blacklist rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. |
| actionExternal | JSON | No | {"responseRuleId":123444} | Extended configuration for rule action. Supported only for the new custom response feature. When action is block, you can specify a custom block page. |
| remoteAddr | Array | Yes | ["1.1.XX.XX", "3.1.XX.XX/24"] | IP addresses to add to the blacklist. Format: ["ip1","ip2",...]. |
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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | iptest | Custom ACL rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. - js: JS verification. - captcha: slider. - captcha_strict: strict slider. Note The available actions for custom ACL rules depend on what is shown in the WAF console. |
| actionExternal | JSON | No | {"responseRuleId":123444} | Extended configuration for rule action. Supported only for the new custom response feature. When action is block, you can specify a custom block page. When action is captcha or captcha_strict, you can specify a custom slider page. |
| conditions | Array | Yes | [{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}] | Traffic characteristics for the ACL rule, described in JSON string format. Supports up to five match conditions. For details, see conditions detailed configuration. |
| ccStatus | Integer | Yes | 1 | Rate limiting status. Valid values: - 0: disabled. - 1: enabled. |
| ratelimit | JSON | No | {"target":"remote_addr","interval":5,"threshold":2,"ttl":1800,"status":{"code":404,"count":2}} | Detailed rate limiting configuration in JSON string format. Required only when ccStatus is 1. For details, see ratelimit detailed configuration. |
| effect | String | No | rule | Scope of rate limiting effect. Required only when ccStatus is 1. Valid values: - service: applies to the protected object. - rule: applies to a single rule. |
| grayStatus | Integer | No | 1 | Grayscale deployment status. Valid values: - 0 (default): disabled. - 1: enabled. |
| grayConfig | JSON | No | {"grayTarget":"header","grayRate":80,"graySubKey":"test"} | Grayscale deployment configuration in JSON string format. Required only when grayStatus is 1. For details, see grayConfig detailed configuration. |
| timeConfig | JSON | No | {"timeScope":"period","timeZone":8,"timePeriods":[{"start":1758771729787,"end":1758816000000}]} | Scheduled rule activation configuration in JSON string format. For details, see timeConfig detailed configuration. |
Conditions Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | IP | 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 Supported match fields may vary by WAF version. Refer to the WAF console for the exact list. |
| subKey | String | No | abc | Custom sub-match field. Note Not all match fields support sub-match fields. Refer to the relationship between match fields and sub-match fields in the WAF console. |
| opValue | String | Yes | contain | Logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: not equal. - eq: equal. - lt: less than. - gt: greater than. - len-lt: length less than. - len-eq: length equal. - len-gt: length greater than. - not-match: does not match. - match-one: equals one of multiple values. - all-not-match: not equal to any value. - all-not-contain: does not contain any value. - contain-one: contains one of multiple values. - not-regex: regex does not match. - regex: regex matches. - all-not-regex: none of the regex patterns match. - regex-one: matches one of the regex patterns. - prefix-match: prefix matches. - suffix-match: suffix matches. - empty: content is empty. - exists: field exists. - inl: in list. Note Not all logical operators are supported for every match field. Refer to the association between match fields and logical operators in the WAF console. |
| values | String | Yes | abc | Match content. Fill in as needed. Note The valid values for opValue and values depend on the specified key. |
Ratelimit Parameter Details
| Name | Type | Required | Example | Description |
| target | String | Yes | remote_addr | Statistic object type. Valid values: - remote_addr (default): IP. - cookie.acw_tc: session. - header: custom header. When selected, specify the header name in the subkey parameter. - queryarg: custom parameter. When selected, specify the parameter name in the subkey parameter. - cookie: custom cookie. When selected, specify the cookie name in the subkey parameter. |
| subKey | String | No | abc | Sub-feature of the statistic object. Required when target is cookie, header, or queryarg. |
| interval | Integer | Yes | 60 | Statistic duration in seconds. This defines the period over which access counts are measured, working with the threshold parameter. Valid range: 1–1800 seconds. |
| threshold | Integer | Yes | 200 | Maximum allowed access count per statistic object within the detection period. |
| ttl | Integer | Yes | 1800 | Duration of enforcement action in seconds. Valid range: 60–86400 seconds. |
| status | JSON | No | {"code":404,"count":200} | Response code frequency settings in JSON string format. Fields include the following: code: Integer, required. Specifies the response code. ratio must be set, but not both. ratio must be set, but not both. |
GrayConfig Parameter Details
| Name | Type | Required | Example | Description |
| grayTarget | String | Yes | 80 | Grayscale object type. Valid values: - remote_addr (default): IP. - cookie.acw_tc: session. - header: custom header. When selected, specify the header name in the graySubKey parameter. - queryarg: custom parameter. When selected, specify the parameter name in the graySubKey parameter. - cookie: custom cookie. When selected, specify the cookie name in the graySubKey parameter. |
| graySubKey | String | No | abc | Sub-feature of the statistic object. Required when grayTarget is cookie, header, or queryarg. |
| grayRate | Integer | Yes | 20 | Grayscale deployment percentage. Valid range: 1–100. |
TimeConfig Parameter Details
| Name | Type | Required | Example | Description |
| timeScope | String | Yes | period | Rule activation time scope. Valid values: - permanent (default): permanently active. - period: active during specified time periods. - cycle: active periodically. |
| timeZone | Integer | Yes | 8 | Time zone for rule activation. Default is 8. Valid range: -12 to 12. 0 represents UTC, 8 represents UTC+8, and -8 represents UTC-8. |
| timePeriods | Array | No | [{"start":1758771729787,"end":1758816000000}] | Active time periods. Required when timeScope is period. Supports multiple time periods. - start: Long, required. Start time as a UNIX timestamp in milliseconds. - end: Long, required. End time 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}]}] | Periodic active time periods. Required when timeScope is cycle. Supports multiple time periods. - day: String, required. Activation cycle. Valid values: 1–7 (Monday to Sunday). Multiple days separated by commas (,). Example: "1" means active every Monday. - dayPeriods: Array, required. Daily active time periods, including start and end. Supports multiple time periods. • start: Long, required. Start time as milliseconds since 00:00 of the day. Valid range: [0–86400000). • end: Long, required. End time as milliseconds since 00:00 of the 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | whitelistTest | Whitelist rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. 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"}] | Traffic characteristics for the whitelist, described in JSON string format. Supports up to five match conditions. For details, see conditions detailed configuration. |
| tags | Array | Yes | ["waf", "regular"] | Modules affected by the whitelist, formatted as ["XX1", "XX2", ...]. 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 regex rule in basic protection. - regular_type: specific regex rule type in basic protection. - regular_field: specific field in basic protection. - major_protection: critical event protection. - cc: CC protection. - region_block: location blacklist. - antibot_scene: bot scenario protection. - antibot_scene_rule: specific bot scenario rule ID. - antibot_scene_label: specific bot scenario rule type. - dlp: data leak prevention. - tamperproof: web tamper-proofing. - spike_throttle: peak traffic throttling. |
| regularRules | Array | No | [ "111111", "222222" ] | Regex rule IDs to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes regular_rule. |
| regularTypes | Array | No | [ "xss", "css" ] | Regex rule types to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes 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"}] | Fields excluded from basic protection detection, described in JSON string format. Supports up to five match conditions. For details, see regularFields detailed configuration. Required only when tags includes regular_field. |
| customRules | Array | No | [ "111111", "222222" ] | Custom rule IDs to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes customrule_rule. |
| blacklistRules | Array | No | [ "111111", "222222" ] | IP blacklist rule IDs to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes blacklist_rule. |
| botRules | Array | No | [ "111111", "222222" ] | Bot scenario protection rule IDs to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes antibot_scene_rule. |
| botLables | Array | No | [ "abc", "cdcc" ] | Bot scenario protection rule types to exclude from detection, formatted as ["XX1", "XX2", ...]. Required only when tags includes antibot_scene_label. You can view bot rule types by calling the DescribeBotRuleLabels API. |
Conditions Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | IP | 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 Supported match fields may vary by WAF version. Refer to the WAF console for the exact list. |
| subKey | String | No | abc | Custom sub-match field. Note Not all match fields support sub-match fields. Refer to the relationship between match fields and sub-match fields in the WAF console. |
| opValue | String | Yes | contain | Logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: not equal. - eq: equal. - lt: less than. - gt: greater than. - len-lt: length less than. - len-eq: length equal. - len-gt: length greater than. - not-match: does not match. - match-one: equals one of multiple values. - all-not-match: not equal to any value. - all-not-contain: does not contain any value. - contain-one: contains one of multiple values. - not-regex: regex does not match. - regex: regex matches. - all-not-regex: none of the regex patterns match. - regex-one: matches one of the regex patterns. - prefix-match: prefix matches. - suffix-match: suffix matches. - empty: content is empty. - exists: field exists. - inl: in list. Note Not all logical operators are supported for every match field. Refer to the association between match fields and logical operators in the WAF console. |
| values | String | Yes | abc | Match content. Fill in as needed. Note The valid values for opValue and values depend on the specified key. |
RegularFields Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | URL | Field excluded from detection. Valid values: - URL-All: all URI-related fields. - URL: specific URI field. - URLPath: URI path. - Query-All: all query-related fields. - Query-Arg: specific query parameter. - Cookie-All: all cookie-related fields. - Cookie-Exact: specific cookie name. - Header-All: all header-related fields. - Header: specific header field. - Body-All: all body parameters. |
| subKey | String | No | abc | Specific field. Required when key is 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| responseType | String | Yes | response_block | Custom response type. Valid value: response_block (block response). |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| config | String | Yes | {"responseCode":400,"responseHeaders":[{"key":"custom","value":"123"},{"key":"aaa","value":"2223"}],"responseContent":"HelloWorld"} | Custom configuration in JSON string format. For details, see config detailed configuration. |
Config Parameter Details
| Name | Type | Required | Example | Description |
| responseCode | Integer | Yes | 400 | Specified response code. |
| responseHeaders | Array | No | [{"key":"custom","value":"123"},{"key":"aaaa","value":"2223"}] | Custom response headers in JSON string format. key is the header field, value is the header value. |
| responseContent | String | Yes | helloworld | Custom response content. |
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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| cnRegionList | String | No | 610000,230000 | Regions within China. Use ["CN"] to block all regions in the Chinese mainland (excluding Hong Kong, Macao, and Taiwan). Separate multiple regions with commas (,). For region code meanings, see Region Code Meanings for Areas Within China. |
| abroadRegionList | String | No | KE,KG | Regions outside China. Separate multiple regions with commas (,). You can view supported overseas countries and regions by calling the DescribeIpAbroadCountryInfos API. |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. |
| actionExternal | JSON | No | {"responseRuleId":123444} | Extended configuration for rule action. Supported only for the new custom response feature. When action is block, you can specify a custom block page. When action is captcha or captcha_strict, you can specify a custom slider page. |
Region Codes for Areas in Mainland China
{
"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": "Mainland China (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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| mode | Integer | Yes | 0 | CC protection mode. Valid values: - 0 (default): standard protection. - 1: emergency protection. |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | test | Rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| url | String | Yes | /abc | Cached page URL. |
| ua | String | No | app | User-agent for accessing this path. |
| protocol | String | Yes | https | Protocol for the cached page URL. Valid values: http, https. |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. 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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | test | Rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or 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"}] | Match conditions in JSON string format. Supports up to two conditions combined with AND logic. For details, see conditions detailed configuration. |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. Applies only when the condition includes an HTTP response code match. - monitor: monitor. - filter: sensitive information filtering. Applies only when the condition includes a sensitive information match. |
Conditions Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | URL | Match field. Valid values: URL, HttpCode, SensitiveInfo. |
| opValue | String | Yes | contain | Logical operator. Fixed value: contain. |
| values | String | Yes | abc | Match content. Separate multiple values with commas (,). HttpCode valid values: 400, 401, 402, 403, 404, 405 (represents 405–499), 500, 501, 502, 503, 504, 505 (represents 505–599). SensitiveInfo valid values: - phone: phone number. - card: credit card. - id: ID card. - word: default sensitive words. |
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)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | iptest | Peak traffic throttling rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| status | Integer | Yes | 1 | Rule status. Use this parameter only when creating a rule. To modify rule status, use the RuleStatus parameter in the ModifyDefenseRuleStatus API. Valid values: - 0: disabled. - 1 (default): enabled. |
| action | String | Yes | block | Rule action. Valid values: - block: block. - monitor: monitor. |
| actionExternal | JSON | No | {"responseRuleId":123444} | Extended configuration for rule action. Supported only for the new custom response feature. When action is block, you can specify a custom block page. |
| conditions | Array | Yes | [{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}] | Traffic characteristics for the ACL rule, described in JSON string format. Supports up to five match conditions. For details, see conditions detailed configuration. |
| cnRegionList | String | No | 610000,230000 | Regions within China. Use ["CN"] to block all regions in the Chinese mainland (excluding Hong Kong, Macao, and Taiwan). Separate multiple regions with commas (,). For region code meanings, see Region Code Meanings for Areas Within China. |
| abroadRegionList | String | No | KE,KG | Regions outside China. Separate multiple regions with commas (,). You can view supported overseas countries and regions by calling the DescribeIpAbroadCountryInfos API. |
| type | String | Yes | qps | Throttling method. Valid values: - qps: QPS-based throttling. - ratio (default): percentage-based throttling. |
| threshold | Integer | Yes | 500 | Throttling threshold. Valid ranges: - QPS: [1–5000000]. When set to 500 QPS, traffic exceeding 500 QPS that meets the throttling conditions will be blocked. - Percentage: [1–99]. When set to 80%, only 80% of traffic meeting the throttling conditions will be allowed. |
Conditions Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | IP | 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 | Custom sub-match field. Note Not all match fields support sub-match fields. Refer to the relationship between match fields and sub-match fields in the WAF console. |
| opValue | String | Yes | contain | Logical operator. Valid values: - not-contain: does not contain. - contain: contains. - none: does not exist. - ne: not equal. - eq: equal. - lt: less than. - gt: greater than. - len-lt: length less than. - len-eq: length equal. - len-gt: length greater than. - not-match: does not match. - match-one: equals one of multiple values. - all-not-match: not equal to any value. - all-not-contain: does not contain any value. - contain-one: contains one of multiple values. - not-regex: regex does not match. - regex: regex matches. - all-not-regex: none of the regex patterns match. - regex-one: matches one of the regex patterns. - prefix-match: prefix matches. - suffix-match: suffix matches. - empty: content is empty. - exists: field exists. - inl: in list. Note Not all logical operators are supported for every match field. Refer to the association between match fields and logical operators in the WAF console. |
| values | String | Yes | abc | Match content. Fill in as needed. Note The valid values for opValue and values depend on the specified key. |
Region Codes for Areas in Mainland China
{
"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": "Mainland China (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\"}]"}
}
Protected Object-Level Rules (resource)
When DefenseType is set to resource, the rule configuration details are as follows.
Account Extraction Rules (account_identifier)
Each protected object supports only one account extraction configuration.
Parameter Descriptions
| Name | Type | Required | Example | Description |
| accountIdentifiers | Array | Yes | [ { "key": "Header","subKey": "header-test", "decodeType": "jwt", "position": "username", "priority": 1 }, { "key": "Post-Arg", "subKey": "body_test", "decodeType": "plain", "priority": 2 } ] | Account extraction configurations. Supports up to 5 entries, each in JSON string format. For details, see accountIdentifiers detailed configuration. |
AccountIdentifiers Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | Query-Arg | Field location for extraction. Valid values: Query-Arg, Cookie-Exact, Post-Arg, Header. |
| subKey | String | Yes | query-test | Custom sub-match field. |
| decodeType | String | Yes | jwt | Authentication method. Valid values: - plain: plaintext. - basic: Basic authentication. - jwt: JWT authentication. For JWT, specify the account field after decoding (position). |
| priority | Integer | Yes | 1 | Match priority for this extraction configuration. Only one extraction strategy matches per request. Valid range: [0,20]. Lower numbers indicate higher priority. Values must be unique. |
| position | String | No | account | Account field after JWT decoding. |
Example
{
"DefenseScene": "account_identifier",
"Resource": "example.**.com-waf",
"DefenseType": "resource",
"InstanceId": "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}]}]"
}
Protected Object Custom Response Rules (custom_response)
Each protected object supports only one custom response configuration. The precedence of response pages is as follows: rule level > protected object level > default page.
Parameter Descriptions
| Name | Type | Required | Example | Description |
| blockRuleId | Long | No | 1123 | Rule ID for the custom block page. Returns this custom block page when the protected object triggers a block action. |
| captchaRuleId | Long | No | 1123 | Rule ID for the custom slider page. Returns this custom slider page when the protected object triggers a slider action. |
Example
{
"DefenseScene": "custom_response",
"Resource": "example.**.com-waf",
"DefenseType": "resource",
"InstanceId": "waf_cn****",
"Rules": "[{\"blockRuleId\":900000,\"captchaRuleId\":900001}]"
}
Protected Object Decoding Rules (waf_codec)
Each protected object supports only one decoding configuration.
Parameter Descriptions
| Name | Type | Required | Example | Description |
| codecList | Array | Yes | ["comment","space-zip","json","xml","form","multipart","graphql","js-unicode","url","hex","html","php","java","utf7","oct"] | Decoding types to enable. Valid values: - url: URL decoding (enabled by default, cannot be disabled). - js-unicode: Unicode decoding (enabled by default, cannot be disabled). - oct: OCT decoding (enabled by default, cannot be disabled). - hex: Hex decoding (enabled by default, cannot be disabled). - comment: comment decoding (enabled by default, cannot be disabled). - space-zip: space decoding (enabled by default, cannot be disabled). - multipart: Multipart parsing. - json: JSON parsing. - xml: XML parsing. - php: PHP deserialization decoding. - html: HTML entity decoding. - utf7: UTF-7 decoding. - base64: Base64 decoding. - form: Form parsing. - gzip: Gzip decompression. - java: Java deserialization decoding. - graphql: GraphQL parsing. |
Example
{
"DefenseScene": "waf_codec",
"Resource": "example.**.com-waf",
"DefenseType": "resource",
"InstanceId": "waf_cn****",
"Rules": "[{\"codecList\":[\"comment\",\"space-zip\",\"json\",\"xml\",\"form\",\"multipart\",\"graphql\",\"js-unicode\",\"url\",\"hex\",\"html\",\"php\",\"java\",\"utf7\",\"gzip\",\"oct\",\"base64\"]}]"
}
Global-Level Rules (global)
When DefenseType is set to global, the rule configuration details are as follows.
Custom Regex Rules (regular_custom)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | ruleTest | Custom regex rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| detectType | String | Yes | sqli | Detection type. Valid values: - sqli: SQL injection. - xss: XSS cross-site scripting attacks. - cmdi: OS command injection. - expression_injection: expression injection (including EL, SpEL, OGNL expressions). - java_deserialization: Java deserialization. - dot_net_deserialization: .NET deserialization. - php_deserialization: PHP deserialization. - code_exec: remote code execution (JNDI/XPATH). - ssrf: SSRF server-side request forgery. - 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 flaw. - 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 | Risk level. Valid values: - super_strict: super strict. - strict: strict. - medium: medium. - loose: loose. |
| description | String | No | Rule description. | Custom regex rule description. |
| condition | Array | Yes | [{"key":"IP","opValue":"eq","values":"11.XX.XX.1"},{"key":"Header","subKey":"abc","opValue":"contains","values":"test"}] | Traffic characteristics for the ACL rule, described in JSON string format. Supports up to five match conditions. For details, see condition detailed configuration. |
Condition Parameter Details
| Name | Type | Required | Example | Description |
| key | String | Yes | Query-Arg | 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 | Custom sub-match field. Important Sub-match fields are supported only when the match field is Header, Query-Arg, Post-Arg, or Multipart. |
| opValue | String | Yes | contain | Logical operator. Valid values: regex, prefix-match, suffix-match, eq, contain. |
| values | String | Yes | abc | Match content. Separate multiple values with commas (,). |
Example
{
"name": "ruleTest",
"detectType": "sqli",
"riskLevel": "strict",
"condition": [{"key": "FileName","opValue": "eq","values": "test"}]
}
Address Book (address_book)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | bookTest | Address book name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| valueType | String | Yes | ip | Address book type. Valid value: - ip: IP address book. |
| description | String | No | addressbookTest | Address book description. |
Example
{
"name": "bookTest",
"valueType": "ip",
"description": "addressbookTest"
}
Custom Response Rules (custom_response)
Parameter Descriptions
| Name | Type | Required | Example | Description |
| name | String | Yes | test | Custom response rule name. Length: 1–255 characters. Can contain letters, digits, underscores (_), periods (.), or hyphens (-). |
| action | String | Yes | block | Rule action. Valid values: - block: block. - captcha: slider. |
| responseCode | Integer | No | 400 | Specified response code. - Required for custom block page rules. - Not supported for custom slider page rules. Defaults to 200. |
| responseHeaders | Array | No | [{"key":"custom","value":"123"},{"key":"aaaa","value":"2223"}] | Custom response headers in JSON string format. key is the header field, value is the header value. |
| designType | String | No | custom | Response configuration type. Required only when action is captcha. Valid values: - custom: custom configuration. - preDefine: predefined configuration. |
| responseContent | String | No | helloworld | Custom response content. Required for custom slider or block pages. |
| preDefineContent | Array | No | [{"language":"cn","title":"test","description":"desc","captchaColor":"#FFFF","showTraceId":false},{"language":"en","title":"titel","description":"desc","captchaColor":"#FFFF","showTraceId":false}] | Predefined configuration content. Required only when designType is preDefine. For details, see Predefined Detailed Configuration. |
Predefined Parameter Details
| Name | Type | Required | Example | Description |
| language | String | Yes | en | Language setting. Valid values: - en: English. - cn: Chinese. |
| icon | String | Yes | https://img.alicdn.com/imgextra/i1/O1CN01L12MaQ1ZwfYKk7Yrc_!!6000000003259-2-tps-900-594.png | Icon. Must be a publicly accessible URL. |
| title | String | Yes | test_title | Custom slider page title. |
| description | String | Yes | For better experience, please slide to complete the verification process before accessing the web page. | Custom slider page description. |
| captchaColor | String | Yes | #ff6a00 | Slider color. |
| showTraceId | boolean | Yes | true | Show log ID. Valid values: - true: display log ID on the slider page. - false: hide log ID on the slider page. |
Custom Block Page Configuration Example
{
"name": "test",
"action": "block",
"responseContent": "helloworld",
"responseCode": 401,
"responseHeaders": [{"key":"t1","value":"v1"}],
}
Predefined Slider Page Configuration Example
{
"name": "test",
"designType": "preDefine",
"action": "captcha",
"responseHeaders": [
{
"key": "Content-Type",
"value": "text/html"
}
],
"preDefineContent": [
{
"language": "en",
"icon": "https://img.alicdn.com/imgextra/i1/O1CN01L12MaQ1ZwfYKk7Yrc_!!6000000003259-2-tps-900-594.png",
"title": "Access Verification-custom",
"description": "For better experience, please slide to complete the verification process before accessing the web page.",
"captchaColor": "#ff6a00",
"showTraceId": true
}
]
}
Response elements
|
Element |
Type |
Description |
Example |
|
object |
Response object structure. |
||
| RequestId |
string |
The ID of the current request. |
26E46541-7AAB-5565-801D-F14DBDC5**** |
| RuleIds |
string |
The IDs of the created protection rules, 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. |
| 400 | Defense.Control.DefenseBookTypeInvalid | The address book type is illegal. | The address book type is illegal. |
| 400 | Defense.Control.DefenseThreatIntelligenceConfigInvalid | Threat Intelligence Rule configuration error. | Threat Intelligence Rule configuration error. %s |
| 400 | Defense.Control.DefenseIpCountOversize | The number of IPs exceeds the limit. | The number of IPs exceeds the limit. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.