This topic describes the built-in and custom policies of the API security module. The module has a built-in detection mechanism. You can configure detection policies for your API assets based on your business requirements. You can configure the policies on the following tabs in the Web Application Firewall (WAF) console: Risk Detection Configurations, Security Event Configurations, Sensitive Data-related Configurations, Authentication Credential Configurations, Business Purpose, Configure Whitelist, Lifecycle Management, Log Subscription Configurations, and Applicable Object Configurations. After you configure the policies, the module can detect risks in a more accurate manner with a higher recall rate. You can handle the detected risks to prevent your API assets from being attacked.
1. Risk Detection Configurations
Risks refer to API security risks or security threats that are caused by development, management, or configuration defects. Security risks differ from security events. Security risks can be detected regardless of whether attacks are initiated. Security events can be detected only when attacks are initiated and alerts are generated.
Built-in policies
On the Risk Detection Configurations tab of the Policy Configurations tab, you can view the built-in policies. You can also change the status and risk level of a built-in policy. The risk level can be Low Risk, Medium Risk, or High Risk.
Custom policies
On the Risk Detection Configurations tab, you can configure up to 20 custom policies. To create a custom policy, perform the following steps:
On the API Security page, choose Policy Configurations > Risk Detection Configurations.
In the left-side section of the tab that appears, click New to the right of Custom Policy. In the panel that appears, configure the parameters. The following table describes the parameters.
Parameter
Description
Risk Status
The status of the policy. By default, the switch is turned on.
Risk Name
The risk name. You can specify a custom value. The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
The suggestion on how to handle the detected risks. You can specify a value based on your business requirements.
Risk Level
The risk level. Valid values: Low Risk, Medium Risk, and High Risk.
Check Configurations
The detection conditions. You can specify up to 10 conditions based on your business requirements.
The following table describes the Match Field, Logical Operator, and Match Content parameters that you must configure to specify a detection condition.
NoteYou can specify up to 50 items for the Match Content parameter. Press the Enter key to confirm each item.
After you configure the parameters, click OK to save the configurations.
2. Security Event Configurations
Security events are generated when errors occur during API calls or when attacks are initiated. For example, a security event is generated when a brute-force attack is initiated against the logon API or an SMS flood attack is initiated by abusing the SMS sending API. The built-in detection mechanism detects events based on IP addresses. If events have the same CIDR block, API, and type and are generated on the same day, the events are aggregated, and one alert is generated for the events.
Built-in policies
After an alert is triggered by a built-in policy of security events, no new alert is triggered if attacks are continuously initiated from the same IP address. However, the attack time of the triggered alert is updated, and the severity is changed based on the volume of the attack traffic.
On the Security Event Configurations tab of the Policy Configurations tab, you can view the built-in policies. You cannot modify or delete the policies.
Custom policies
On the Security Event Configurations tab, you can configure up to 10 custom policies. To create a custom policy, perform the following steps:
On the API Security page, choose Policy Configurations > Security Event Configurations.
In the left-side section of the tab that appears, click New to the right of Custom Policy. In the panel that appears, configure the parameters. The following table describes the parameters.
Parameter
Description
Event Status
The status of the policy. By default, the switch is turned on.
Event Name
The event name. You can specify a custom value. The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
The suggestion on how to handle the detected events. You can specify a value based on your business requirements.
Event Level
The risk level. Valid values: Low Risk, Medium Risk, and High Risk.
Match Condition
The detection conditions. You can specify up to 10 conditions based on your business requirements.
NoteIf you specify multiple conditions, the policy is considered hit only when all conditions are matched.
Statistical Period
The statistical period. Maximum value: 15. Unit: minutes.
Requests
The number of requests. Valid values: positive integers.
Data Statistics
The counting conditions. You can specify up to 10 conditions based on your business requirements.
For more information about how to configure the Match Field, Logical Operator, and Match Content parameters to specify a detection condition, see Condition settings in the "1. Risk Detection Configurations" section of this topic.
NoteYou can specify up to 50 items for the Match Content parameter. Press the Enter key to confirm each item.
The following table describes the Match Field, Logical Operator, and Match Content parameters that you must configure to specify a counting condition.
After you configure the parameters, click OK to save the configurations.
3. Sensitive Data-related Configurations
On the Sensitive Data-related Configurations tab of the Policy Configurations tab, you can search, filter, and view the built-in policies.
De-identification Display
The Sensitive Data-related Configuration tab provides the De-identification Display switch. By default, the switch is turned off.
If you turn on the switch, the system masks the related information before the information is displayed.
In the Risk Details and API Details panels, the system replaces sensitive data in the Sample Request and Sample Response sections with
{{Phone}}
. You can go to the panels on the Risk Detection tab.In the Event Details panel, the system replaces sensitive data in the Sample Request Data and Sample Response Data sections with
{}
. You can go to the panel on the Security Events tab.In the sample data, Request Cookie is masked as
{{Cookie}}
, Request Header that contains Token is masked as{{XXXToken}}
, and Response SetCookie is masked as{{SetCookie}}
.
The switch takes effect on the following data:
Risk Details and API Details: The switch takes effect only on new sample request data and sample response data.
Event Details: The switch takes effect on both new and existing sample request data and sample response data.
Built-in policies
You cannot modify or delete a built-in policy. You can only change the status of a built-in policy.
Custom policies
If you define custom sensitive data in your business, you can configure custom policies to detect the sensitive data. On the Sensitive Data-related Configurations tab, you can configure up to 20 custom policies. To create a custom policy, perform the following steps:
On the API Security page, choose Policy Configurations > Sensitive Data-related Configurations.
Click Create Policy. In the panel that appears, configure the parameters. The following table describes the parameters. You can create a custom policy in Basic or Expert mode.
Parameter
Description
Name
The name of the policy.
The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Mode
The detection mode of the policy. Valid values:
Basic: In this mode, you need to only perform simple configurations.
If you select Basic, you must configure the Characters and Length parameters.
Characters: You can select Numeric, Uppercase Letters, and Lowercase Letters. You can select multiple options.
Length: You can specify a length range. You must specify integers as the start and end values. The start value must be in the range of 6 to 63, and the end value must be in the range of 7 to 64.
Expert: In this mode, you can specify a regular expression.
If you select Expert, you must enter a regular expression to detect sensitive data. To prevent misdetection, make sure that the regular expression can match at least six characters.
Sensitivity Level
The sensitivity level of data that can be detected. Valid values: S1, S2, S3, and S4.
NoteFor more information about the types of sensitive data, see What types of sensitive data can be detected by the API security module?
After you configure the parameters, click OK to save the configurations.
4. Authentication Credential Configurations
If you use unconventional fields as authentication fields in your business or specify weak names for authentication fields, such as by using only digits, we recommend that you configure custom authentication credentials. The API security module has a built-in mechanism that identifies authentication credentials. You can configure the required parameters to help the mechanism check whether authentication credentials are included in requests. This helps improve API security and the identification accuracy of authentication risks.
On the API Security page, choose Policy Configurations > Authentication Credential Configurations.
Click Create Policy. In the panel that appears, configure the parameters and click OK. The following table describes the parameters.
Parameter
Description
Name
The name of the policy.
The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Match Condition
The match conditions. You must configure the Match Field, Logical Operator, and Match Content parameters to specify a condition. You can specify up to 10 conditions. You must specify a condition in which the Match Field parameter is set to Request Header, Request Cookie, Request Query, or Request Body.
NoteIf you specify multiple conditions, the policy is considered hit only when all conditions are matched.
The following table describes the Match Field, Logical Operator, and Match Content parameters that you must configure to specify a match condition.
NoteYou can specify up to 50 items for the Match Content parameter. Press the Enter key to confirm each item.
5. Business Purpose
The API security module provides the following types of business purpose policies:
Built-in policies
The module provides built-in policies for various scenarios, including data update, data sharing, text message sending, and information sending. You cannot modify or delete a built-in policy. You can only change the status of a built-in policy. You can enable or disable a built-in policy based on your business requirements.
Custom policies
If the built-in policies do not meet your business requirements, you can configure custom policies based on URL and parameter name patterns to improve the detection accuracy of API risks.
On the API Security page, choose Policy Configurations > Business Purpose.
Click the Custom Policy card. Then, click Create Policy. In the panel that appears, configure the parameters and click OK. The following table describes the parameters.
You can specify up to 50 items for the Match Content parameter. Press the Enter key to confirm each item.
6. Configure Whitelist
On the Configure Whitelist tab of the Policy Configurations tab, you can configure separate whitelists for risks and security events to reduce alerts. For example, you can configure a whitelist to mute alerts for egress IP addresses of your office network, which helps improve the operational efficiency of your business.
On the API Security page, choose Policy Configurations > Configure Whitelist.
Click Create Policy. In the panel that appears, enter the name of the whitelist policy that you want to create and select the type of the whitelist policy that you want to configure. You can select Risk Detection or Security Events.
Specify match conditions based on the whitelist policy type that you select.
NoteYou can specify up to 10 match conditions.
Match conditions for a whitelist policy of the Risk Detection type
Match Field
Logical Operator
Match Content
Domain Name
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
You can enter up to 50 items. Press the Enter key to confirm each item that you enter.
API
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
You can enter up to 50 items. Press the Enter key to confirm each item that you enter.
Match conditions for a whitelist policy of the Security Events type
Match Field
Logical Operator
Match Content
Domain Name
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
You can enter up to 50 items. Press the Enter key to confirm each item that you enter.
API
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
You can enter up to 50 items. Press the Enter key to confirm each item that you enter.
IP
Belongs To
Does Not Belong To
You can enter an IP address or a CIDR block. Example: 1.1.X.X/24. You can enter up to 50 items. Separate the items with commas (,) and press the Enter key to confirm each item. Regular expressions are not supported.
Select the types of risks or security events whose alerts you want to mute. Then, click OK.
NoteThe system supports built-in and custom types. You can select multiple types.
7. Lifecycle Management
You can specify the number of daily API calls and the number of consecutive days during which the API is not called to determine whether an API is a deactivated API. On the Lifecycle Management tab of the Policy Configurations tab, you can specify a standard to identify deactivated APIs. This way, you can handle the APIs at the earliest opportunity. This prevents attackers from exploiting deactivated APIs.
On the API Security page, choose Policy Configurations > Lifecycle Management.
Specify a standard to identify deactivated APIs and click OK.
Click Built-in Model.
If you select Built-in Model, the API security module considers APIs that are not called within the previous 30 days or APIs whose calls significantly decrease as deactivated APIs.
Click Custom. Then, specify the number of daily API calls and the number of consecutive days during which the API is not called. The maximum number of consecutive days allowed is 31.
If you select Custom, the API security module considers APIs whose number of daily API calls is less than the specified number within the specified consecutive days as deactivated APIs.
8. Log Subscription Configurations
After you configure log subscription settings for a specific log type, a log subscription task is generated. When trigger conditions of log delivery are met, the task delivers related logs to the Simple Log Service Logstore that you specify. You can create the required Logstore in the Simple Log Service console. The API security module supports the following log types: AssetInformation, riskInformation, and Attack EventInformation. You can use Simple Log Service to manage the logs in a centralized manner.
WAF instances in the Chinese mainland can deliver logs only to Simple Log Service Logstores in the Chinese mainland. WAF instances outside the Chinese mainland can deliver logs only to Simple Log Service Logstores outside the Chinese mainland.
Create a service-linked role
If no service-linked roles are created for WAF, you must create a service-linked role before you can use the log subscription feature of the API security module. Then, WAF can assume the role to access other cloud resources. For more information, see Service-linked roles. If the role already exists, skip this step.
Configure log subscription settings
Log on to the Simple Log Service console and create a project and a Logstore to which you want to deliver logs. Perform this step before you configure log subscription settings. If the project and Logstore already exist and meet the naming requirements, skip this step.
NoteWhen you select a Logstore to which you want to deliver logs, you cannot select the Logstores that are automatically created by Simple Log Service or the Logstores named waf-logstore, wafng-logstore, and wafnew-logstore.
Log on to the WAF console and go to the Log Subscription tab. On this tab, you can configure log subscription settings for AssetInformation, riskInformation, and Attack EventInformation. If you want to query and analyze logs that are delivered to the Logstore in the Simple Log Service console, enable indexing for the Logstore. For more information, see Create indexes.
Select the log type for which you want to configure log subscription settings and click Configure in the related section.
In the dialog box that appears, select the region of the Logstore to which logs are delivered, the project to which the Logstore belongs, and the Logstore. Then, click OK. When trigger conditions are met and logs are generated, the log subscription task delivers the logs to Simple Log Service. Then, you can go to the Simple Log Service console and access the selected Logstore to query and analyze the logs. You can also use the data transformation feature of Simple Log Service to mask log data. For more information, see Overview of data transformation (new version).
If you want to disable the log subscription task, turn off Status on the Log Subscription tab. If you no longer require delivered logs after you disable the task and you want to prevent fees generated by log storage, delete the selected Logstore in the Simple Log Service console. For more information, see How do I deactivate Simple Log Service or stop being billed for Simple Log Service?
The following sections describe the trigger conditions of a log subscription task and the details of log fields.
You are charged additional fees for the project, Logstore, and indexes that you create in the Simple Log Service console. The fees are included in the bills of Simple Log Service. For more information about the billable items and pricing of Simple Log Service, see Billing overview of Simple Log Service.
After you create the project and Logstore, you are charged even if your log subscription task is disabled. Therefore, if you confirm that the Logstore is no longer required, delete the Logstore at the earliest opportunity. For more information, see Why am I charged even if I only create projects and Logstores?
Logs of the AssetInformation type
Trigger conditions of the log subscription task:
If new API assets are detected, logs of the AssetInformation type are immediately delivered.
If no new API assets are detected, logs of the AssetInformation type are delivered at 1-hour intervals.
Logs of the riskInformation type
Trigger conditions of the log subscription task: If new API risks are detected, logs of the riskInformation type are delivered to the Logstore that you specify.
Logs of the Attack EventInformation type
Trigger conditions of the log subscription task:
If new attack events are detected, logs of the Attack EventInformation type are delivered to the Logstore that you specify.
If an attack continues, logs of the Attack EventInformation type are continuously delivered to the Logstore that you specify at 10-minute intervals.
Values of log subscription fields
If you want to learn more about the values of fields in the delivered logs when you query and analyze the logs, you can refer to the following tables. The Description column in the following tables provides the display names of the field values in the WAF console.
9. Applicable Object Configurations
The API security module provides the following switches for protected objects and protected object groups:
Switch: specifies whether to enable all built-in and custom policies.
Compliance Check: specifies whether to enable the compliance check feature. You can turn on this switch only when Switch is turned on.
Tracing and Auditing: specifies whether to enable the tracing and auditing feature. You can turn on this switch only when Switch is turned on.
After you add a domain name or an instance to WAF, you can configure the switches. The default settings of the switches vary based on the billing method.
By default, if you use the subscription billing method, Switch is turned on, and Compliance Check and Tracing and Auditing are turned off.
By default, if you use the pay-as-you-go billing method, Switch is turned off.
You can go to the
page to turn on or turn off Switch, Compliance Check, and Tracing and Auditing.