DescribeSecurityEventTopNMetric - Web Application Firewall

Queries top N data entries of attack traffic. The system performs statistical aggregation on attack traffic from specific dimensions and returns top N data entries.

Operation description

Attack traffic refers to the traffic of requests that match protection rules and are identified as risky. The following types of requests are excluded:

Requests that match the protection rules of the whitelist module.
Requests that match the protection rules of the bot management module. The actions of the protection rules are set to Add Tag.
Requests that match protection rules with actions set to Dynamic Token-based Authentication, Slider CAPTCHA, Strict Slider CAPTCHA Verification, and JavaScript Validation, pass the verifications specified by the actions, and are allowed.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- For mandatory resource types, indicate with a prefix of * .
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
yundun-waf:DescribeSecurityEventTopNMetric	get	All Resources ``	none	none

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The ID of the Web Application Firewall (WAF) instance. Note You can call the DescribeInstanceInfo operation to query the ID of the WAF instance.	waf_cdnsdf3****
Filter	object	Yes	The filter conditions for the query. Multiple conditions are evaluated by using a logical AND.
DateRange	object	Yes	The time range for the query.
StartDate	long	Yes	The beginning of the time range to query. The value is a Unix timestamp. Unit: seconds.	1713888000
EndDate	long	Yes	The end of the time range to query. The value is a Unix timestamp. Unit: seconds.	1713888600
Conditions	array<object>	No	The filter conditions. Each object describes a filter condition.
	object	No	The filter condition. A condition consists of a field name, an operator, and field content.
Key	string	No	The field name. This operation supports all fields. For more information, see the Supported field names section below.	matched_host
OpValue	string	No	The operator. For more information, see the Supported operators section below.	eq
Values	any	No	The field content.	test.waf-top
Limit	long	Yes	The number of data entries that can be returned. Data entries are sorted in descending order before they are returned. Maximum value: 10.	10
Metric	string	Yes	The metric whose top N data entries you want to return. The following metrics are supported: Note For more information about attack requests, see the "Operation description" section of this topic. real_client_ip: The system aggregates the source IP addresses of attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. http_user_agent: The system aggregates the User-Agent header field of attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. matched_host: The system aggregates the protected objects that are matched by attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. remote_region_id: The system aggregates the countries to which the source IP addresses of attack requests belong to collect statistics, sorts the statistical results in descending order, and returns top N data entries. request_path: The system aggregates the URLs of attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. The URLs exclude query strings. block_defense_scene: The system aggregates the protection modules that block attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. The requests match protection rules whose actions are not set to Monitor. defense_scene: The system aggregates the protection modules that are matched by attack requests to collect statistics, sorts the statistical results in descending order, and returns top N data entries. defense_scene_rule_id: The system returns the IDs of top N protection rules that are matched by attack requests and also the related protection modules. Only protection rules whose actions are not set to Monitor are counted. The system returns the value in the following format: `{ "Attribute": "waf_base", "Value": 140, "Name": "111034" }` defense_scene_with_rule_id: The system returns the IDs of top N protection rules that are matched by attack requests and also the related protection modules. The IDs and protection modules are connected by using hyphens (-). Protection rules whose actions are set to Monitor and Block are counted. The system returns the value in the following format: `{ "Attribute": "", "Value": 1, "Name": "120075-waf_base" }` defense_scene_top_rule_id: The system returns top N matched protection rules of a specific protection module. You can specify Conditions in Filter to configure filter conditions. For example, you can use the following condition to query top N matched protection rules of the custom rule module: `{ "Key": "defense_scene_map", "OpValue": "contain", "Values": "custom_acl" }` defense_scene_rule_type: The system returns top N matched protection rules of the core web protection module. This metric is supported only by the core web protection module because only this module supports subtypes of protection rules. You must specify Conditions in Filter to configure filter conditions. Example: `{ "Key": "defense_scene", "OpValue": "eq", "Values": "waf_base" }`	real_client_ip
RegionId	string	No	The region ID of the WAF instance. Valid values: cn-hangzhou: The Chinese mainland. ap-southeast-1: Outside the Chinese mainland.	ap-southeast-1
ResourceManagerResourceGroupId	string	No	The ID of the Alibaba Cloud resource group.	rg-acfm***q

Supported operators

Operator	Meaning	Description
all-not-match	Does Not Equal Any Value	The field value does not equal any value in the data set. For example, you can use the following condition to query the real_client_ip fields whose value does not equal any value in the data set: `{"Key":"real_client_ip","OpValue":"all-not-match","Values":["1.XX.XX.1","2.XX.XX2","3.XX.XX.3"]}`.
contain	Contains	The field value contains a specific string. For example, you can use the following condition to query the URLs that contain the test string: `{"Key":"request_path","OpValue":"contain","Values":"test"}`.
eq	Equals	The field value equals a specific string. For example, you can use the following condition to query the URLs that equal the /testcase string: `{"Key":"request_path","OpValue":"eq","Values":"/testcase"}`.
match-one	Equals One of Multiple Values	The field value equals one of multiple values in the data set. For example, you can use the following condition to query the real_client_ip fields whose value equals one of multiple values in the data set: `{"Key":"real_client_ip","OpValue":"match-one","Values":["1.XX.XX.1","2.XX.XX.2","3.XX.XX.3"]}`.
ne	Does Not Equal	The field value does not equal a specific string. For example, you can use the following condition to query the URLs that do not equal the /testcase string: `{"Key":"request_path","OpValue":"ne","Values":"/testcase"}`.
not-contain	Does Not Contain	The field value does not contain a specific string. For example, you can use the following condition to query the URLs that do not contain the test string: `{"Key":"request_path","OpValue":"not-contain","Values":"test"}`.
prefix-match	Prefix Match	The field value is prefixed with a specific string. For example, you can use the following condition to query the URLs that are prefixed with the /testcase string: `{"Key":"request_path","OpValue":"prefix-match","Values":"/testcase"}`.
suffix-match	Suffix Match	The field value is suffixed with a specific string. For example, you can use the following condition to query the URLs that are suffixed with the /testcase string: `{"Key":"request_path","OpValue":"suffix-match","Values":"/testcase"}`.

Supported field names

Field name	Description	Supported operator
action	The action that is performed on the request.	ne and eq
cluster	The protection cluster.	ne, eq, match-one, and all-not-match
defense_scene	The protection module. A request may match multiple protection modules. The requests that are obtained by matching the value of this field may still match other protection modules.	ne and eq
host	The Host header field of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, and suffix-match
http_cookie	The Cookie header field of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, and suffix-match
http_user_agent	The User-Agent header field of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, and suffix-match
matched_host	The protected object.	ne, eq, match-one, and all-not-match
real_client_ip	The source IP address of the request. Only IP addresses are supported. CIDR blocks are not supported.	ne, eq,match-one, and all-not-match
remote_country_id	The country to which the source IP address of the HTTP request belongs.	ne, eq, match-one, and all-not-match
remote_region_id	The province or city to which the source IP address of the HTTP request belongs.	ne, eq, match-one, and all-not-match
request_method	The request method of the HTTP request.	ne, eq, match-one, and all-not-match
request_path	The URL of the HTTP request, excluding the query string.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, and suffix-match
request_traceid	The request ID, which is unique.	ne, eq, match-one, and all-not-match
rule_id	The ID of the protection rule. A request may match multiple protection rules. The requests that are obtained by matching the value of this field may still match other protection rules.	ne and eq

Response parameters

Parameter	Type	Description	Example
	object	The response parameters. For more information, see the Examples section below.
RequestId	string	The request ID.	D827FCFE-90A7-4330-9326-*****B4C7726
SecurityEventTopNValues	array<object>	The top N data entries returned.
TopNValue	object	The data entry.
Name	string	The field value, which varies based on the metric.	10000
Attribute	string	The additional information, such as the protection module for a protection rule whose ID is returned.	waf_base
Value	long	The count for the data entry.	1111
TopNMetaData	object	The metadata of the data entries returned.
DateRange	object	The time range that is used for the query.
StartDate	long	The beginning of the time range to query. The value is a Unix timestamp. Unit: seconds. This value is the same as the value of StartDate in the request parameters.	1713888000
EndDate	long	The end of the time range to query. The value is a Unix timestamp. Unit: seconds. This value is the same as the value of EndDate in the request parameters.	1713888600
Units	string	The unit of the statistics returned. It is fixed as requests.	requests

Examples

Sample success responses

JSONformat

{
  "RequestId": "D827FCFE-90A7-4330-9326-*****B4C7726",
  "SecurityEventTopNValues": [
    {
      "Name": "10000",
      "Attribute": "waf_base\n",
      "Value": 1111
    }
  ],
  "TopNMetaData": {
    "DateRange": {
      "StartDate": 1713888000,
      "EndDate": 1713888600
    },
    "Units": "requests"
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	Waf.Report.%s	Invalid parameter:%s.	Invalid parameter:%s
400	Waf.Report.InternalError	Server error occurred in report service.	Report Service Internal Error

For a list of error codes, visit the Service error codes.