Creates configuration rules in a specified Web Application Firewall (WAF) protection module. WAF protection modules include web intrusion protection, data security, advanced mitigation, bot management, and access control or throttling.

You can specify the protection module configuration by setting the DefenseType parameter. For more information about the valid values of this parameter, see the description of DefenseType.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateProtectionModuleRule

The operation that you want to perform. Set the value to CreateProtectionModuleRule.

DefenseType String Yes ac_custom

The protection module. Valid values:

  • waf-codec: RegEx protection engine
  • tamperproof: website tamper-proofing
  • dlp: data leak prevention
  • account: account security rules
  • antifraud: data risk control
  • antifraud_js: insertion of JavaScript plug-ins for data risk control
  • bot_algorithm: intelligent algorithm rules for bot management
  • bot_wxbb_pkg: version protection rules for app protection
  • bot_wxbb: path protection rules for app protection
  • ac_custom: custom protection policies
  • whitelist: whitelist rules
Domain String Yes www.example.com

The domain name that is added to WAF.

InstanceId String Yes waf_elasticity-cn-0xldbqt****

The ID of the WAF instance.

Note You can query the ID of the WAF instance by calling DescribeInstanceInfo.
Rule String Yes {"action":"monitor","name":"test","scene":"custom_acl","conditions":[{"opCode":1,"key":"URL","values":"/example"}]}

The content of the rule. It is a JSON string that contains multiple parameters.

Note The parameters required for creating a rule vary depending on the specified protection module. The protection module is specified by using the DefenseType parameter. For more information, see the "Rule parameters" section.
Rule parameters
  • If the DefenseType parameter is set to waf-codec, the value of the Rule parameter contains the following parameters:
    • codecList: required. The decoding settings. Data type: array. You can view the valid values of this parameter in the WAF console.
    • Example
      
          {
              "codecList":["url","base64"]
          }
          
  • If the DefenseType parameter is set to tamperproof, the value of the Rule parameter contains the following parameters:
    • uri: required. The URL that needs protection.Data type: string.
    • name: required. The name of the rule. Data type: string.
    • Example
      
          {
              "name":"example",
              "uri":"http://www.example.com/example"
          }
          
  • If the DefenseType parameter is set to dIp, the value of the Rule parameter contains the following parameters:
    • name: required. The name of the rule. Data type: string.
    • conditions: required. The matching condition that is described in a JSON string. You can specify a maximum of two matching conditions. The AND operator must be used for the two conditions. The JSON string includes the following parameters:
      • key: the matching items. Valid values:
        • 0: URL
        • 10: sensitive information
        • 11: HTTP status code
          Note You cannot configure matching conditions for the HTTP status code (11) and sensitive information (10) in the conditions at the same time.
      • operation: the matching logic. The value is set to 1 by default, which specifies the INCLUDES logical operator.
      • value: the matching condition values, which are formulated in a JSON string. You can specify multiple values. The JSON string includes the following parameters:
        • v: This parameter is valid only when key is set to 0 or 11.
          • URL: If key is set to 0, the value of the v parameter is a URL.
          • HTTP status code: If key is set to 11, the valid values for the v parameter are 400, 401, 402, 403, 404, 405-499, 500, 501, 502, 503, 504, and 505-599.
        • k: This parameter is valid only when key is set to 10. Valid values:
          • 100: resident ID card numbers
          • 101: credit card numbers
          • 102: phone numbers
          • 103: default sensitive words
    • action: matching actions. Valid values:
      • 3: reports an alert.
      • 10: filters sensitive information. This action applies only to scenarios where key is set to 10.
      • 11: returns the built-in interception page of the system. This action applies only to scenarios where key is set to 11.
    • Example
      
        {
      	"name":"example",
      	"conditions":[{"key":11,"operation":1,"value":[{"v":401}]},{"key":"0","operation":1,"value":[{"v":"www.example.com"}]}],
      	"action":3
        }
        
  • If the DefenseType parameter is set to ng_account, the value of the Rule parameter contains the following parameters:
    • url_path: required. The URL to the operation that runs detection tasks. The URL must start with a forward slash (/). Data type: string.
    • method: required. The request method of the detection. Valid values: POST, GET, PUT, and DELETE. Data type: string. You can specify multiple request methods. Separate them with commas (,).
    • account_left: required. The parameter that specifies the account. Data type: string.
    • password_left: optional. The parameter that specifies the password. Data type: string.
    • action: required. The protection action. Data type: string. Valid values:
      • monitor: reports an alert for the request.
      • block: blocks the request.
    • Example
      
          {
              "url_path":"/example",
              "method":"POST,GET,PUT,DELETE",
              "account_left":"aaa",
              "password_left:"123",
              "action":"monitor"
          }
          
  • If the DefenseType parameter is set to antifraud, the value of the Rule parameter contains the following parameters:
    • uri: required. The specific request URL. Data type: string.
    • Example
      
          {
              "uri": "http://1.example.com/example"
          }
          
  • If the DefenseType parameter is set to antifraud_js, the value of the Rule parameter contains the following parameters:
    • uri: required. The URL of the web page into which you want to insert JavaScript plug-ins for data risk control. The system inserts the JavaScript plug-ins into all the pages under the specified URL directory. Data type: string.
    • Example
      
          {
              "uri": "/example/example"
          }
          
  • If the DefenseType parameter is set to bot_algorithm, the value of the Rule parameter contains the following parameters:
    • name: required. The name of the rule. Data type: string.
    • algorithmName: required. The name of the algorithm. Data type: string. Valid values:
      • RR: the identification algorithm for special resource crawlers
      • PR: the identification algorithm for specific path crawlers
      • DPR: the identification algorithm for parameter round-robin crawlers
      • SR: the identification algorithm for dynamic IP address crawlers
      • IND: the identification algorithm for proxy device crawlers
      • Periodicity: the identification algorithm for periodical crawlers
    • timeInterval: required. The time period during which the request is detected. Data type: integer. Valid values: 30, 60, 120, 300, and 600. Unit: seconds.
    • action: required. The action performed after the rule is matched. Data type: string. Valid values:
      • monitor: monitors requests
      • captcha: performs CAPTCHA verification
      • js: performs JavaScript verification
      • block: blocks requests If you choose to block requests, you must specify the blocktime parameter.
    • blocktime: optional. The time period during which requests are blocked. Data type: integer. Valid values: 1 to 600.
    • config: required. The configuration information of the algorithm. The information is formulated in a JSON string. Data type: string. The parameters in the configuration information must be set based on algorithmName.
      • If you set algorithmName to RR, the configuration information contains the following parameters:
        • resourceType: optional. The requested resources. Data type: integer. Valid values:
          • 1: dynamic resources
          • 2: static resources
          • -1: custom resources In this case, you must also use the extensions parameter to specify resource suffix names in a string. Separate multiple names with commas (,), such as css,jpg,xls.
        • minRequestCountPerIp: required. The minimum number of requests from an IP address. If the number of requests from an IP address is greater than or equal to the value of this parameter, the system detects this IP address. Data type: integer. Valid values: 5 to 10000.
        • minRatio: required. The threshold for the proportion of requests that access specified types of resources or specified paths to requests that are initiated from an IP address. This threshold is used to determine whether risks exist. If the proportion of such requests that access specified types of resources or specified paths is greater than the threshold, risks exist. The requests for access to specified types of resources are identified by using the identification algorithm for special resource crawlers. The requests for access to specified paths are identified by using the identification algorithm for specific path crawlers. Data type: float. Valid values: 0.01 to 1.
      • If you set algorithmName to PR, the configuration information contains the following parameters:
        • keyPathConfiguration: optional. The paths for requests. Data type: array. You can specify a maximum of 10 paths. This parameter is valid only when algorithmName is set to PR. Specify this request parameter in a JSON string that contains the following parameters:
          • method: required. The request method. Data type: string. Valid values: POST, GET, PUT, DELETE, HEAD, and OPTIONS.
          • url: required. The keyword for the request path. This path must start with a forward slash (/). Data type: string.
          • matchType: required. The matching method. This parameter specifies the request path in combination with the keyword for the request path (url). Data type: string. Valid values: all (exact match), prefix (prefix match), and regex (regular expression match).
        • minRequestCountPerIp: required. The minimum number of requests from an IP address. If the number of requests from an IP address is greater than or equal to the value of this parameter, the system detects this IP address. Data type: integer. Valid values: 5 to 10000.
        • minRatio: required. The threshold for the proportion of requests that access specified types of resources or specified paths to requests that are initiated from an IP address. This threshold is used to determine whether risks exist. If the proportion of such requests that access specified types of resources or specified paths is greater than the threshold, risks exist. The requests for access to specified types of resources are identified by using the identification algorithm for special resource crawlers. The requests for access to specified paths are identified by using the identification algorithm for specific path crawlers. Data type: float. Valid values: 0.01 to 1.
      • If you set algorithmName to DPR, the configuration information contains the following parameters:
        • method: required. The request method. Data type: string. Valid values: POST, GET, PUT, DELETE, HEAD, and OPTIONS.
        • urlPattern: required. The path of the key parameter, which must start with a forward slash (/). Data type: string. You can specify multiple key parameters. Specify each parameter with braces {}. Example: /company/{}/{}/{}/user.php? uid={}.
        • minRequestCountPerIp: required. The minimum number of requests from an IP address. If the number of requests from an IP address is greater than or equal to the value of this parameter, the system detects this IP address. Data type: integer. Valid values: 5 to 10000.
        • minRatio: required. The threshold for the proportion of requests that contain specified key parameters to requests that are initiated from an IP address. This threshold is used to determine whether risks exist. If the proportion of such requests that contain specified key parameters is greater than the threshold, risks exist. Data type: float. Valid values: 0.01 to 1.
      • If you set algorithmName to SR, the configuration information contains the following parameters:
        • maxRequestCountPerSrSession: required. The minimum number of requests in each session. If the number of requests in a single session is smaller than the value of this parameter, the session is considered abnormal. Data type: integer. Valid values: 1 to 8.
        • minSrSessionCountPerIp: required. The threshold of abnormal sessions in the requests that are initiated from an IP address. The threshold is used to determine whether risks exist. If the number of abnormal sessions in the requests that are initiated from an IP address is greater than the threshold, a risk exists. Data type: integer. Valid values: 5 to 300.
      • If you set algorithmName to IND, the configuration information contains the following parameters:
        • minIpCount: required. The threshold for the number of IP addresses that the device linked with Wi-Fi accesses. This parameter specifies the condition that is used to determine malicious devices. If the number of IP addresses exceed the parameter value, a risk exists. Data type: integer. Valid values: 5 to 500.
        • keyPathConfiguration: optional. The paths for the detection. You can specify a maximum of 10 paths. Data type: array. Specify this parameter in a JSON string that contains the following parameters:
          • method: required. The request method. Data type: string. Valid values: POST, GET, PUT, DELETE, HEAD, and OPTIONS.
          • url: required. The keyword for the detection path. The keyword must start with a forward slash (/). Data type: string.
          • matchType: required. The matching method. This parameter specifies the path for the detection in combination with the url parameter. Data type: string. Valid values: all (exact match), prefix (prefix match), and regex (regular expression match).
      • If you set algorithmName to Periodicity, the configuration information contains the following parameters:
        • minRequestCountPerIp: required. The minimum number of requests from an IP address. If the number of requests from an IP address is greater than or equal to the value of this parameter, the system detects this IP address. Data type: integer. Valid values: 5 to 10000.
        • level: required. The risk level, namely, the extent of obviousness of periodical access from IP addresses. Data type: integer. Valid values:
          • 0: obvious
          • 1: moderate
          • 2: weak
    • Example
      
          {
              "name": "Crawler identification for proxy devices",
              "algorithmName":"IND",
              "timeInterval":"60",
              "action":"warn",
              "config":{
                  "minIpCount":5,
                  "keyPathConfiguration":[{"url":"/index","method":"GET","matchType":"prefix"}]
              }
          }
          
  • If the DefenseType parameter is set to bot_wxbb_pkg, the value of the Rule parameter contains the following parameters:
    • name: required. The name of the rule. Data type: string.
    • action: required. The action performed after the rule is matched. Data type: string. Valid values:
      • test: monitors requests.
      • close: blocks requests.
    • nameList: required. The information of the valid version. You can specify a maximum of five rules. Data type: array. Specify this request parameter in a JSON string that contains the following parameters:
      • name: required. The valid package name. Data type: string.
      • signList: required. The signature for the package. You can specify a maximum of 15 signatures. Separate them with commas (,).
    • Example
      
          {
              "name":"test",
              "action":"close",
              "nameList":[{
                  "name":"apk-xxxx",
                  "signList":["xxxxxx","xxxxx","xxxx","xx"]
              }]
          }
          
  • If the DefenseType parameter is set to bot_wxbb, the value of the Rule parameter contains the following parameters:
    • name: required. The name of the rule. Data type: string.
    • url: required. The path for the protection. This parameter must start with a forward slash (/). Data type: string.
    • matchType: required. The matching method. Data type: string. Valid values: all (exact match), prefix (prefix match), and regex (regular expression match).
    • arg: required. The inclusion of the parameter. This parameter specifies the protection path in combination with the matchType parameter. Data type: string.
    • action: required. The action performed after the rule is matched. Data type: string. Valid values:
      • test: monitors requests.
      • close: blocks requests.
    • hasTag: required. This parameter specifies whether a signature field needs to be customized. Data type: Boolean.
      • true: A signature field needs to be customized. In this case, you need to set wxbbVmpFieldTyp and wxbbVmpFieldValue to specify the type and value of the field.
      • false: A signature field does not need to be customized.
    • wxbbVmpFieldType: optional. The type of the signature field. Data type: integer. You must specify this parameter if hasTag is set to true. Valid values:
      • 0: header
      • 1: parameter
      • 2: cookie
    • wxbbVmpFieldValue: optional. The value of the signature field. Data type: string. You must specify this parameter if hasTag is set to true.
    • blockInvalidSign: required. This parameter specifies whether the system takes actions on an invalid signature. Data type: integer. Set the value to1. This parameter specifies the default protection policy for path protection rules.
    • blockProxy: optional. This parameter specifies whether the system takes actions on a proxy. Data type: integer. Set the value to 1. This parameter is not required if you do not need to perform the action on the proxy.
    • blockSimulator: optional. This parameter specifies whether the system takes actions on a simulator. Data type: integer. Set the value to 1. This parameter is not required if you do not need to perform the action on the simulator.
    • Example
      
          {
              "name":"test",
              "uri":"/index",
              "matchType":"all",
              "arg":"test",
              "action":"close",
              "hasTag":true,
              "wxbbVmpFieldType":2,
              "wxbbVmpFieldValue":"test",
              "blockInvalidSign":1,
              "blockProxy":1
          }
          
  • If the DefenseType parameter is set to ac_custom, you also need to specify the scene parameter in the Rule parameter to configure an ACL rule and HTTP flood protection rule.
    • To modify an ACL rule, set scene to custom_acl and construct a JSON string that contains the following parameters:
      • name: required. The name of the rule. Data type: string.
      • scene: required. The type of the protection policy. Data type: string. If you need to modify an ACL rule, set the value to custom_acl.
      • action: required. The action performed after the rule is matched. Data type: string. Valid values:
        • monitor: monitors requests.
        • captcha: performs CAPTCHA verification.
        • captcha_strict: performs strict CAPTCHA verification.
        • js: performs JavaScript verification.
        • block: blocks requests.
      • conditions: required. The matching conditions. You can specify a maximum of five matching conditions. Data type: array. Specify this parameter in a JSON string that contains the following parameters:
        • key: the matching field. Valid values: URL, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header, and URLPath.
        • opCode: the logical operator. Valid values:
          • 0: exclusion
          • 1: inclusion
          • 2: non-existence
          • 10: not equal to
          • 11: equal to
          • 20: the length less than
          • 21: the length equal to
          • 22: the length greater than
          • 30: the value less than
          • 31: the value equal to
          • 32: the value greater than
          • 40: not belong to
          • 41: belong to
        • values: the matching content. Set this parameter as needed. Data type: string.
          Note The valid values of opCode and values in the matching conditions must be set based on the key parameter. For more information about matching conditions, see Matching conditions.
      • Example
        
                {
                    "action":"monitor",
                    "name":"test",
                    "scene":"custom_acl",
                    "conditions":[{"opCode":1,"key":"URL","values":"/example"}]
                }
                
    • If the DefenseType is set to a protection rule against HTTP flood attacks, you also need to set scene to custom_cc and construct a JSON string that contains the following parameters:
      • name: required. The name of the rule. Data type: string.
      • scene: required. The type of the protection policy. Data type: string. If you set a protection rule against HTTP flood attacks, set the value to custom_cc.
      • conditions: required. The matching conditions. You can specify a maximum of five matching conditions. Data type: array. Specify this parameter in a JSON string that contains the following parameters:
        • key: the matching field. Valid values: URL, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header, and URLPath.
        • opCode: the logical operator. Valid values:
          • 0: exclusion
          • 1: inclusion
          • 2: non-existence
          • 10: not equal to
          • 11: equal to
          • 20: the length less than
          • 21: the length equal to
          • 22: the length greater than
          • 30: the value less than
          • 31: the value equal to
          • 32: the value greater than
          • 40: not belong to
          • 41: belong to
        • values: the matching content. Set this parameter as needed. Data type: string.
          Note The valid values of opCode and values in the matching conditions must be set based on the key parameter.
      • action: required. The action performed after the rule is matched. Data type: string. Valid values:
        • monitor: monitors requests.
        • captcha: performs CAPTCHA verification.
        • captcha_strict: performs strict CAPTCHA verification.
        • js: performs JavaScript verification.
        • block: blocks requests.
      • ratelimit: required. The frequency of the request. Data type: JSON. Specify this parameter in a JSON string that contains the following parameters:
        • target: required. The type of the object whose request frequency is calculated. Data type: string. Valid values:
          • remote_addr: IP addresses
          • cookie.acw_tc: sessions
          • queryarg: custom parameters If you choose to use custom parameters, specify the name of the custom parameter that needs to be calculated in the subkey parameter.
          • cookie: custom cookies If you choose to use custom cookies, specify the cookie content that needs to be calculated in the subkey parameter.
          • header: custom headers If you choose to use custom headers, specify the header content that needs to be calculated in the subkey parameter.
        • subkey: optional. When target is set to cookie, header or queryarg, you must specify the required information in the subkey parameter. Data type: string.
        • interval: required. The time period during which the number of requests from the specified object is calculated. This parameter must be used together with the threshold parameter. Data type: integer. Unit: seconds.
        • threshold: required. During the specified time period, the maximum number of requests that are allowed from an individual object. Data type: integer.
        • status: optional. The frequency of the HTTP status code. Data type: string. Specify this parameter in a JSON string that contains the following parameters:
          • code: required. The specified HTTP status code. Data type: integer.
          • count: optional. The maximum number of the specified HTTP status code. If the number of the HTTP status code exceeds the upper limit, the corresponding protection rule is hit. Data type: integer. Valid values: [1,999999999]. You can set the count or ratio parameter.
          • ratio: optional. The maximum percentage of the specified HTTP status code. If the percentage of the HTTP status code exceeds the upper limit, the corresponding rule is hit. Data type: integer. Valid values: [1,100]. You can set the count or ratio parameter.
        • scope: required. This parameter specifies where the settings take effect. Data type: string. Valid values:
          • rule: objects that match the specified conditions.
          • domain: domains where the rule is applied.
        • ttl: required. The effective time period of the action. Data type: integer. Valid values: 60, 86400. Unit: seconds.
      • Example
        
                {
                    "name":"HTTP flood protection",
                    "conditions":[{"opCode":1,"key":"URL","values":"/example"}],
                    "action":"block", 
                    "scene":"custom_cc",  
                    "ratelimit":{
                        "target": "remote_addr", 
                        "interval": 300,
                        "threshold": 2000,
                        "status": {
                            "code": 404,
                            "count": 200
                        },
                        "scope": "rule",
                        "ttl": 1800
                    }
                }
                
  • If the DefenseType parameter is set to whitelist, the value of the Rule parameter contains the following parameters:
    • name: required. The name of the rule. Data type: string.
    • tags: required. The protection modules that can be skipped. You can specify multiple modules. Data type: array. Valid values:
      • waf: website whitelist
      • cc: HTTP flood protection of the system
      • customrule: custom rule
      • blacklist: IP blacklist
      • antiscan: scan protection
      • regular: web application attack protection
      • deeplearning: deep learning
      • antifraud: data risk control
      • dlp: data leak prevention
      • tamperproof: website tamper-proofing
      • bot_intelligence: bot threat intelligence
      • bot_algorithm: intelligent algorithm
      • bot_wxbb: app protection
    • conditions: required. The matching conditions. You can specify a maximum of five matching conditions. Data type: array. Specify this parameter in a JSON string that contains the following parameters:
      • key: the matching field. Valid values: URL, IP, Referer, User-Agent, Params, Cookie, Content-Type, Content-Length, X-Forwarded-For, Post-Body, Http-Method, Header, and URLPath.
      • opCode: the logical operator. Valid values:
        • 0: exclusion
        • 1: inclusion
        • 2: non-existence
        • 10: not equal to
        • 11: equal to
        • 20: the length less than
        • 21: the length equal to
        • 22: the length greater than
        • 30: the value less than
        • 31: the value equal to
        • 32: the value greater than
        • 40: not belong to
        • 41: belong to
      • values: the matching content. Set this parameter as needed. Data type: string.
        Note The valid values of opCode and values in the matching conditions must be set based on the key parameter.
    • Example
      
          {
              "name": "test",
              "tags": ["cc","customrule"],
              "conditions":[{"opCode":1,"key":"URL","values":"/example"}],
         }
         

Response parameters

Parameter Type Example Description
RequestId String D7861F61-5B61-46CE-A47C-6B19160D5EB0

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/? Action=CreateProtectionModuleRule
&Domain=www.example.com
&InstanceId=waf_elasticity-cn-0xldbqt****
&DefenseType=ac_custom
&Rule= {"action":"monitor","name":"test","scene":"custom_acl","conditions":[{"opCode":1,"key":"URL","values":"/example"}]}
&<Common request parameters>

Sample success responses

XML format

<CreateProtectionModuleRuleResponse>
	  <RequestId>D7861F61-5B61-46CE-A47C-6B19160D5EB0</RequestId>
</CreateProtectionModuleRuleResponse>

JSON format

{
    "RequestId": "D7861F61-5B61-46CE-A47C-6B19160D5EB0"
}

Error codes

For a list of error codes, visit the API Error Center.