This topic describes how to configure built-in and custom policies for API Security. In addition to its built-in detection mechanisms, API Security lets you define custom detection policies that are specific to your business requirements. You can configure policies for risk detection, security events, sensitive data, authentication credentials, business purposes, whitelists, lifecycle management, log subscriptions, and effective objects. These configurations tailor API data identification to your business needs. This improves the accuracy and recall rate of API security detection and helps you respond to threats and reduce losses from attacks on your API assets.
1. Risk detection configuration
A security risk is a vulnerability in an API caused by defects in development, management, or configuration. A security risk does not necessarily mean an attack has occurred, while a security event is an alert generated by an attack.
Built-in policy configuration
On the Risk Detection Configuration tab of the Policy Configuration page, you can view configured risk policies. For built-in policies, you can enable or disable them and adjust their risk levels. You can set the risk level of a built-in policy to Low, Medium, or High, as needed.
Custom policy configuration
In addition to built-in policies, you can create up to 20 custom risk detection policies. To create a custom policy, follow these steps.
On the API Security page, go to the Policy Configurations > Risk Detection Configurations tab.
In the Custom Policy section on the left, click New. In the panel that appears, configure the parameters that are described in the following table.
Parameter
Description
Risk Status
Set the policy status. The default value is On.
Risk Name
Set the name for the custom risk. The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
Set the recommended action for the custom risk policy based on your business needs.
Risk Level
Set the risk level. Valid values are Low, Medium, and High.
Check Configurations
Set the detection conditions for your custom risk policy. You can add up to 10 conditions.
The following table describes the detailed configurations for detection settings, including logical operators and examples of match content.
NoteYou can enter up to 50 values for Match Content. Press the Enter key after you enter each value.
The match content for Risk Detection Configurations is case-sensitive.
After you complete the custom configuration, click OK.
2. Security event configuration
A security event is an abnormal call or an attack on an API. Examples include brute-force attacks on logon APIs and message flooding attacks that abuse SMS APIs. Built-in event detection performs detection based on the IP address and account dimensions.
Built-in policy configuration
After a built-in security event policy triggers an alert, it does not generate a new alert if the same attack continues. Instead, the attack time of the original alert is updated. The alert level may also change based on factors such as the attack volume.
On the Security Event Configurations tab of the Policy Configurations page, you can view configured security event policies. You cannot edit or delete built-in policies.
Custom policy configuration
In addition to built-in policies, you can create up to 10 custom security event policies. To create a custom policy, follow these steps.
On the API Security page, go to the Policy Configurations > Security Event Configurations tab.
In the Custom Policy section on the left, click New. In the panel that appears, configure the parameters that are described in the following table.
Parameter
Description
Event Status
Set the policy status. The default value is On.
Event Name
Set the name for the custom event. The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
Set the recommended action for the custom security event based on your business needs.
Event Level
Set the risk level. Valid values are Low, Medium, and High.
Match Condition
Set the detection conditions for your custom security event policy. You can add up to 10 conditions.
NoteIf you define multiple conditions, a rule is hit only when all conditions are met.
Rate Limiting
Set Statistical Object to IP or Account. Set Statistical Period in minutes, with a maximum of 15 minutes. Set Requests to a positive integer.
Data Statistics
Set the statistical conditions for your custom security event policy. You can add up to 10 conditions.
For detailed information about match conditions, logical operators, and examples of match content, see the Detailed configuration table in the Risk detection configuration section.
NoteYou can enter up to 50 values for Match Content. Press the Enter key after you enter each value.
The match content for Security Event Configurations is case-sensitive.
The following table describes the detailed configurations for data statistics, including logical operators and examples of match content.
After you complete the custom configuration, click OK.
3. Sensitive data configuration
On the Sensitive Data-related Configurations tab of the Policy Configurations page, you can search, filter, and view configured sensitive data policies.
Data masking display
The Sensitive Data-related Configurations tab has a De-identification Display switch. This switch is disabled by default, which means data is not masked.
When data masking is enabled, the following information is masked:
In Risk Details and API Details, sensitive data in all fields of request and response samples is replaced with a placeholder, such as
{{Phone}}.In the Event Details of a security event, request and response data samples that contain sensitive data are masked as
{}.In sample information, Request Cookie is masked as
{{Cookie}}, a Request Header that contains a token is masked as{{XXXToken}}, and Response Set-Cookie is masked as{{SetCookie}}.
The data masking feature applies to the following items:
Risk Details and API Details: The feature applies only to new request and response data samples.
Event Details: The feature applies to both new and existing request and response data samples.
Built-in policy configuration
You cannot edit, modify, or delete built-in policies. You can only enable or disable them.
Custom policy configuration
If your business uses custom sensitive data, you can configure custom sensitive data detection rules. You can create up to 20 custom policies. To create a custom policy, follow these steps.
On the API Security page, go to the Policy Configuration > Sensitive Data-related Configurations tab.
Click Create Policy. In the panel that appears, configure the parameters. You can create a custom policy in Basic Mode or Expert Mode.
Parameter
Description
Name
Set a name for the rule.
The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Mode
Set the detection mode for the custom policy.
Basic: Provides a simple configuration interface for ease of use.
If you select Basic mode, you must set the Characters and Length for detection.
Characters: You can select one or more character types to detect, including digits, uppercase letters, and lowercase letters.
Length: The supported length range is 6 to 64. The start and end values must be integers.
Expert: Supports regular expressions.
If you select Expert mode, you must enter a regular expression for detection. To avoid false positives, make sure the regular expression matches at least 6 characters.
Sensitivity Level
Set the level of the sensitive data to be detected. Valid values: S1, S2, S3, and S4.
NoteFor more information about sensitive data types, see What sensitive data can API Security detect.
After you complete the custom configuration, click OK.
4. Authentication credential configuration
If your business uses non-standard fields or fields with weak features (such as all-numeric names) for authentication, you can configure custom authentication credentials. In addition to the built-in credential detection, you can specify parameter names. This helps the built-in model accurately determine whether a request contains authentication credentials. This improves API security and the accuracy of unauthenticated risk detection.
On the API Security page, go to the Policy Configuration > Authentication Credential Configurations tab.
Click Create Policy, configure the parameters, and then click OK.
Parameter
Description
Name
Set a name for the policy.
The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Match Condition
Each condition consists of a Match Field, a Logical Operator, and Match Content. You can add up to 10 conditions. When configuring, add at least one match condition for Request Header, Request Cookie, Request Query, or Request Body.
NoteIf you define multiple conditions, a rule is hit only when all conditions are met.
The following table describes the detailed configurations for match conditions, including logical operators and examples of match content.
NoteYou can enter up to 50 values for Match Content. Press the Enter key after you enter each value.
The match content for Authentication Credential Configurations is case-sensitive.
5. Business purpose configuration
API Security provides two types of business purpose policy configurations:
Built-in policy configuration
Business purpose policies are supported for multiple scenarios, such as data updates, data sharing, text message sending, and information sending. You cannot modify or delete built-in policies, but you can enable or disable them as needed.
Custom policy configuration
If the built-in policies do not meet your business needs, you can define custom URL and parameter name features. This improves the detection accuracy of API Security in specific business scenarios.
On the API Security page, go to the Policy Configuration > Business Purpose tab.
Click the Custom Policy tab to manage custom policies. Click Create Policy, configure the parameters, and then click OK.
You can enter up to 50 values for Match Content. Press the Enter key after you enter each value.
The match content for Business Purpose is case-sensitive.
6. Whitelist configuration
The whitelist feature of API Security lets you create custom whitelists for security events and risk detection. This helps you filter out alert noise based on your business needs, such as alerts from your office network's egress IP address. This improves operational efficiency.
On the API Security page, go to the Policy Configuration > Configure Whitelist tab.
Click Create Policy, enter a name for your new policy, and select the feature type for which you want to configure a whitelist. You can configure whitelists for Risk Detection and Security Events.
Set the match conditions based on the feature type that you selected.
NoteYou can add up to 10 match conditions.
The match conditions for Configure Whitelist are case-sensitive.
Risk detection whitelist policy match conditions
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
Enter up to 50 values. Press the Enter key after each value.
API
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
Enter up to 50 values. Press the Enter key after each value.
Security event whitelist policy match conditions
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
Enter up to 50 values. Press Enter after each value.
API
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
Enter up to 50 values. Press Enter after each value.
IP
Belongs To
Does Not Belong To
Enter an IP address or an IP address range in CIDR block format (for example, 1.1.X.X/24). Regular expressions are not supported. You can enter up to 50 values, separated by commas (,) or by pressing Enter.
Account
Contains One of Multiple Values
Does Not Contain Any Value
Equals One of Multiple Values
Does Not Equal Any Value
Enter up to 50 values. Press Enter after each value.
Select the risk detection or security event types to ignore, and then click OK.
NoteYou can select multiple built-in and custom types to ignore.
7. Lifecycle management
API Security lets you define criteria for inactive APIs by setting the daily access volume and duration. This makes inactive API detection more relevant to your business. API lifecycle management helps you identify inactive APIs based on your custom standards and take prompt action. This helps prevent attackers from exploiting inactive APIs and causing business losses.
On the API Security page, go to the Policy Configuration > Lifecycle Management tab.
Set the criteria for inactive APIs, and then click OK.
Click Built-in Model.
An API is considered inactive under the built-in criteria if it has not been accessed or its access volume has dropped significantly over the past 8 days.
Click Custom and set the daily access volume and duration (up to 31 days). An API is considered inactive if its daily access volume is less than the specified value within the custom duration.
An API is considered inactive if its daily access count remains below a specified number for a custom duration.
If an asset's Last Active Time exceeds 30 days, the system automatically deletes the asset and its associated risk data and security event records.
8. Log subscription
After you enable log subscription for asset, risk, or event information, the corresponding logs are delivered to a specified Logstore in the Simple Log Service console when the delivery conditions are met. This lets you centrally manage and analyze logs using the features of Alibaba Cloud Simple Log Service (SLS).
Currently, Web Application Firewall (WAF) instances in the Chinese mainland can deliver logs only to SLS Logstores in the Chinese mainland. WAF instances outside the Chinese mainland can deliver logs only to SLS Logstores outside the Chinese mainland. Cross-region log delivery between the Chinese mainland and other regions is not supported.
Enable the service-linked role
If you have not enabled the service-linked role for WAF, you must do so before you use the API Security log subscription service. Follow the prompts to enable the role, which grants WAF permission to access your other cloud resources. For more information about service-linked roles, see Service-linked Role. If you have already granted this authorization when you enabled features such as Simple Log Service for WAF, you can skip this step.
Log subscription configuration
Before you configure a log subscription task for API Security, go to the Simple Log Service console to create a Project and a Logstore to receive the logs. If you have already created a target Logstore and confirmed that it follows the naming conventions, you can proceed to the next step.
NoteThe log subscription feature does not support using Logstores that are automatically created by SLS or that you have named "waf-logstore", "wafng-logstore", or "wafnew-logstore" as subscription targets.
After you create the Logstore, return to the log subscription tab to configure subscriptions for your asset information, risk information, and attack event information. If you want to analyze and query the logs that are delivered to the specified Logstore from the SLS console, you must first enable indexing as prompted. For more information, see Create indexes.
Select the log type for the subscription task, and click the Configure button to go to the configuration page.
Select the Region, Project name, and Logstore name for your log subscription task, and click the OK button to save the configuration. After the configuration is complete and logs are generated, you can go to the corresponding Logstore in the Simple Log Service console to query and analyze the logs. If you want to perform data transformation, such as data masking, see Data transformation.
If you disable the log subscription task, no longer need the existing logs, and want to avoid further charges for the Logstore, you can disable the task on the Log Subscription tab and then delete the corresponding Logstore. For more information, see How do I disable Simple Log Service or stop billing?.
The following sections describe the trigger conditions and detailed fields for log subscription tasks.
You may incur additional fees for creating cloud resources and performing operations such as enabling indexing in Simple Log Service. These fees are billed by Simple Log Service. For more information about billing items and pricing, see Billing overview of Simple Log Service.
Charges may still be incurred after you create a Project or Logstore, even if no log subscription task is enabled. If you are sure that you no longer need the created Logstore, delete it promptly to avoid extra charges. For more information, see Why am I charged for creating only a Project and a Logstore?.
Asset information logs
Trigger conditions:
Asset information logs are delivered immediately after a new API asset is added.
If no new API assets are added, asset information logs are delivered by default every hour.
Risk information logs
Trigger condition: When new risk information is detected, the risk information logs are delivered to your specified Logstore.
Attack event information logs
Trigger conditions:
When a new attack event is detected, the new attack event information logs are delivered to your specified Logstore.
If the attack continues, the attack event information logs are delivered to your specified Logstore at 10-minute intervals.
Log subscription field value descriptions
To understand the meaning of field values in the logs or view their corresponding descriptions on the console during log analysis or querying, refer to the following tables. The Description column shows the name of the log field as it appears in the WAF console.
9. Effective object configuration
Subscription WAF
API Security provides three switches at the protected object or protected object group level:
The Basic Detection switch: This switch is enabled by default. It controls whether all built-in and custom detection policies are effective.
The Compliance Check switch: This switch is disabled by default. It can be enabled only after the Basic Detection switch is enabled. It controls whether the Compliance Check feature is effective.
The Tracing and Auditing switch: This switch is disabled by default. It can be enabled only after the Basic Detection switch is enabled. It controls whether the Tracing and Auditing feature is effective.
Pay-as-you-go WAF
API Security provides one switch at the protected object or protected object group level:
The Basic Detection switch: This switch controls whether all built-in and custom detection policies are effective. To disable the API Security feature, you can turn off the Basic Detection switch for all protected objects and protected object groups.