DescribeSecurityEventTopNMetric - Web Application Firewall

Queries the top N statistics for attack traffic. Attack traffic is aggregated by a specified dimension, sorted, and the top N results are returned.

Operation description

Attack traffic refers to requests that hit a rule and are identified as a threat. The following types of requests are not included in the statistics:

Requests that hit a whitelist rule.
Requests that hit a bot rule with the action set to Tag.
Requests that hit a rule with the action set to Dynamic Token, Slider, Strict Slider, or JS Challenge, and are allowed after the user passes verification.

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

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

yundun-waf:DescribeSecurityEventTopNMetric

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The ID of the WAF instance. Note Call the DescribeInstance operation to query the ID of the WAF instance.	waf_cdnsdf3****
Filter	object	Yes	The filter conditions for the query. A logical AND operator is used between multiple filter conditions.
DateRange	object	Yes	The time range to query.
StartDate	integer	Yes	The start of the time range to query. The value is a UNIX timestamp. Unit: seconds. You can query data within the last 30 days. Note The start time must be within the last 30 days.	1713888000
EndDate	integer	Yes	The end of the time range to query. The value is a UNIX timestamp. Unit: seconds.	1713888600
Conditions	array	No	A list of filter conditions. Each object in the array represents a filter condition.
	object	No	The configuration of a single query condition. A query condition consists of a field name, an operator, and a filter value. For more information about the supported field names and operators, see the Additional information about request parameters section.
Key	string	No	The field to filter by. This operation supports all fields.	matched_host
OpValue	string	No	The operator.	eq
Values	any	No	The filter value.	test.waf-top
Limit	integer	Yes	The maximum number of entries to return. The entries are sorted in descending order. Maximum value: 10.	10
Metric	string	Yes	Specifies the content of the returned data. Different metrics correspond to different data content. This operation supports the following metrics: Note For the definition of an attack request, see the Description section of this topic. The following descriptions use this definition. real_client_ip: Aggregates the source IP addresses of attack requests, sorts them in descending order, and returns the top N results. http_user_agent: Aggregates the User-Agent headers of attack requests, sorts them in descending order, and returns the top N results. matched_host: Aggregates the protected objects that are hit by attack requests, sorts them in descending order, and returns the top N results. remote_region_id: Aggregates the countries of origin for the source IP addresses of attack requests, sorts them in descending order, and returns the top N results. request_path: Aggregates the URLs of attack requests, excluding query strings, sorts them in descending order, and returns the top N results. block_defense_scene: Aggregates the final protection modules that handled blocked requests, sorts them in descending order, and returns the top N results. Blocked requests are requests whose action is not Monitor. defense_scene: Aggregates all protection modules that are hit by attack requests, sorts them in descending order, and returns the top N results. defense_scene_rule_id: Queries the top rule IDs of hit rules that are not in Monitor mode and their corresponding protection modules. This query returns statistics only for rules that are not in Monitor mode. The data is returned in the following format: `{ "Attribute": "waf_base", "Value": 140, "Name": "111034" }` defense_scene_with_rule_id: Returns the top N rule IDs based on the number of hits and their corresponding protection modules. The rule ID and module are connected by a hyphen (-). This query includes rules in both Monitor and Block modes. The data is returned in the following format: `{ "Attribute": "", "Value": 1, "Name": "120075-waf_base" }` defense_scene_top_rule_id: Queries the top rules that are hit in a specific protection module. Specify a filter condition in the Conditions field of the Filter parameter. For example, to query the top rules that are hit in the custom access control list (ACL) module, set the Conditions field as follows: `{ "Key": "defense_scene_map", "OpValue": "contain", "Values": "custom_acl" }` defense_scene_rule_type: Queries the top rule types that are hit in the core web protection module. Only the core web protection module supports this query because it is the only module that has rule subtypes. Specify a filter condition in the Conditions field of the Filter parameter as follows: `{ "Key": "defense_scene", "OpValue": "eq", "Values": "waf_base" }`	real_client_ip
RegionId	string	No	The region where the WAF instance resides. Valid values: cn-hangzhou: the Chinese mainland. ap-southeast-1: outside the Chinese mainland.	cn-hangzhou
ResourceManagerResourceGroupId	string	No	The ID of the resource group.	rg-acfm***q

Operator descriptions

Operator	Meaning	Description
all-not-match	Not equal to any value	The field value is not equal to any value in the dataset. For example, to filter for `real_client_ip` values that are not equal to any value in a collection: `{"Key":"real_client_ip","OpValue":"all-not-match","Values":["1.1.1.1","2.2.2.2","3.3.3.3"]}`
contain	Contains	The field value contains a specific string. For example, to filter for data where the URL contains "test": `{"Key":"request_path","OpValue":"contain","Values":"test"}`
eq	Equals	The field value is equal to a specific string. For example, to filter for data where the URL is "/testcase": `{"Key":"request_path","OpValue":"eq","Values":"/testcase"}`
match-one	Equals one of multiple values	The field value is equal to any value in the dataset. For example, to filter for `real_client_ip` values that are equal to any value in a collection: `{"Key":"real_client_ip","OpValue":"match-one","Values":["1.1.1.1","2.2.2.2","3.3.3.3"]}`
ne	Not equal to	The field value is not equal to a specific string. For example, to filter for statistics where the URL is not "/testcase": `{"Key":"request_path","OpValue":"ne","Values":"/testcase"}`
not-contain	Does not contain	The field value does not contain a specific string. For example, to filter for data where the URL does not contain "test": `{"Key":"request_path","OpValue":"not-contain","Values":"test"}`
prefix-match	Prefix match	The field value starts with a specific string. For example, to filter for data where the URL prefix is "/testcase": `{"Key":"request_path","OpValue":"prefix-match","Values":"/testcase"}`
suffix-match	Suffix match	The field value ends with a specific string. For example, to filter for data where the URL suffix is "/testcase": `{"Key":"request_path","OpValue":"suffix-match","Values":"/testcase"}`

Supported keys for filter conditions

Field name	Description	Supported operators
action	The protection action. This is the final action taken on the request.	ne, eq
cluster	The protection cluster.	ne, eq, match-one, all-not-match
defense_scene	The protection module. A request may hit multiple protection modules. Requests that are filtered by this field may also hit other modules.	ne, eq
host	The `host` header of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, suffix-match
http_cookie	The `cookie` header of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, suffix-match
http_user_agent	The `User-Agent` header of the HTTP request.	contain, not-contain, ne, eq, match-one, all-not-match, prefix-match, suffix-match
matched_host	The protected object.	ne, eq, match-one, all-not-match
real_client_ip	The source IP address of the request. The value can be an IP address string or a list of IP address strings. CIDR blocks are not supported.	ne, eq, match-one, all-not-match
remote_country_id	The country of origin for the source IP address of the HTTP request.	ne, eq, match-one, all-not-match
remote_region_id	The province or city of origin for the source IP address of the HTTP request.	ne, eq, match-one, all-not-match
request_method	The HTTP request method.	ne, eq, match-one, 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, suffix-match
request_traceid	The unique ID of the request.	ne, eq, match-one, all-not-match
rule_id	The rule ID. A request may hit multiple rules. Requests that are filtered by this field may also hit other rules.	ne, eq

Response elements

Element	Type	Description	Example
	object	The data returned. For a sample format, see the Examples section.
RequestId	string	The request ID.	D827FCFE-90A7-4330-9326-*****B4C7726
SecurityEventTopNValues	array<object>	An array of the top N statistics.
	object	Each object in the array represents one top statistic.
Name	string	The value of a field. The meaning of this parameter varies based on the specified `Metric`.	10000
Attribute	string	Additional information, such as the protection module to which a rule ID belongs.	waf_base
Value	integer	The statistical count used for top N sorting.	1111
TopNMetaData	object	The metadata of the returned data.
DateRange	object	The time range used for the query.
StartDate	integer	The start of the time range that was queried. The value is a UNIX timestamp. Unit: seconds. This value is the same as the `StartDate` request parameter.	1713888000
EndDate	integer	The end of the time range that was queried. The value is a UNIX timestamp. Unit: seconds. This value is the same as the `EndDate` request parameter.	1713888600
Units	string	The unit of the returned statistics.	requests

Examples

Success response

JSON format

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

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

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.