This topic describes the built-in policies and custom policy configuration for API security. Based on the built-in detection mechanisms, API security supports custom detection policies that align with your business characteristics. You can configure risk detection, security events, sensitive data, authentication credentials, business purposes, whitelists, lifecycle management, log subscription, and target objects, so that the identified API data better reflects your actual business scenario. This further improves the accuracy and recall rate of API security detection, helping you take appropriate actions based on your business needs and reducing losses caused by attacks on API business assets.
I. Risk detection configuration
A risk refers to a security risk or vulnerability caused by development defects, or management and configuration deficiencies in an API. The difference between a security risk and a security event is that a security risk does not necessarily indicate that an attack has occurred, while a security event indicates an alert triggered by an attack.
Built-in policy configuration
On the Risk Detection Configurations tab of Policy Configuration, you can view the configured risk policies. Built-in policies are enabled by default. You can modify their enable status and adjust risk levels. You can set the risk level of built-in policies to Low, Medium, or High based on your business needs.
Custom policy configuration
In addition to built-in policies, the risk detection configuration allows you to create up to 20 custom policies. The configuration rules for custom policies are as follows.
-
On the API Security page, select the tab.
-
In the left pane, click New in the Custom Policies section to open the configuration drawer. The following table describes the configuration parameters.
Parameter
Description
Risk Status
Set the policy status. The default value is Enabled.
Risk Name
Set a name for the custom risk. The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
Set the handling suggestions for the custom risk policy based on your business needs.
Risk Level
You can set the risk level to Low, Medium, or High.
Check Configurations
Set the detection conditions for your custom risk policy. A maximum of 10 conditions are supported.
The following table describes the detailed configuration for detection settings, including the logical operators and match content examples.
Note-
You can enter up to 50 match content items and press Enter to confirm.
-
The match content for Risk Detection Configurations is case-sensitive.
-
-
After completing the custom configuration, click OK to save the configuration.
II. Security event configuration
A security event indicates that an API has experienced abnormal calls or attack behavior, such as a brute-force attack on a login API or abuse of an SMS sending API for SMS bombing. Built-in event detection uses IP addresses and accounts as the detection dimensions.
Built-in policy configuration
When a built-in security event policy triggers an alert, if the attack continues, no new alert will be generated. However, the attack time of the existing alert will be updated, and the alert severity level may change based on factors such as the attack volume.
On the Security Event Configurations tab of Policy Configuration, you can view the configured security event policies. Built-in policies are enabled by default. You can modify their enable status and adjust risk levels.
Custom policy configuration
In addition to built-in policies, the security event configuration allows you to create up to 10 custom policies. The configuration rules for custom policies are as follows.
-
On the API Security page, select the Policy Configurations > Security Event Configurations tab.
-
In the left pane, click New in the Custom Policies section to open the configuration drawer. The following table describes the configuration parameters.
Parameter
Description
Event Status
Set the policy status. The default value is Enabled.
Event Name
Set a name for the custom event. The name can contain Chinese characters, uppercase and lowercase letters, digits, periods (.), underscores (_), and hyphens (-).
Suggestions
Set the handling suggestions for the custom security event based on your business needs.
Event Level
You can set the risk level to Low, Medium, or High.
Match Condition
Set the detection conditions for your custom security event policy. A maximum of 10 conditions are supported.
NoteIf multiple conditions are defined, the rule is triggered only when all conditions are met.
Rate Limiting
Set Statistical Object to IP or Account; set Statistical Period with a granularity in minutes, up to 15 minutes; set Requests to a positive integer only.
Data Statistics
Set the statistical conditions for your custom security event policy. A maximum of 10 conditions are supported.
For detailed configuration of match conditions, including the corresponding logical operators and match content examples, see Detailed Configuration in the Risk Detection section.
Note-
You can enter up to 50 match content items and press Enter to confirm.
-
The match content for Security Event Configurations is case-sensitive.
The following table describes the detailed configuration for data statistics, including the logical operators and match content examples.
-
-
After completing the custom configuration, click OK to save the configuration.
III. Sensitive Data-related Configurations
On the Sensitive Data-related Configurations tab of Policy Configuration, you can view and configure the following items.
-
Sensitive Data Type: The system has built-in detection logic for common sensitive data types such as ID numbers and mobile phone numbers. You can also customize sensitive data types based on your business needs.
-
API Real-Time Data Masking: The intelligent protection feature based on the AI baseline engine can autonomously learn API structures and identify sensitive data in real time to achieve fine-grained automatic data masking. This feature requires no manual pre-defined fields and can flexibly adapt to complex business scenarios to meet compliance requirements such as cross-border data transfer, achieving fully automatic real-time protection.
Sensitive Data Type
On the Sensitive Data-related Configurations tab, click Sensitive Data Type in the left-side list to view and configure the following items:
Built-in Sensitive Data Types
Built-in system policies are enabled by default. They cannot be edited, modified, or deleted. You can only enable or disable them.
Custom Sensitive Data Types
If your business defines its own sensitive data, you can configure custom sensitive data detection rules. You can configure up to 20 custom policies for sensitive data.
Click Create Policy to configure settings in the drawer page that appears. Currently, you can configure custom policies in two modes: Basic and Expert.
|
Configuration Item |
Description |
|
Name |
Set a name for the rule. |
|
Mode |
Set the detection mode of the custom policy.
|
|
Sensitivity Level |
Set the sensitivity level of detected sensitive data. Options: S1, S2, S3, S4. Note
For more information about sensitive data types, see What sensitive data can API Security detect. |
De-identification Display
On the Sensitive Data Configuration tab, the De-identification Display switch is provided. It is disabled by default, meaning data is not displayed in a masked format.
After 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 the placeholder
{{Phone}}by default. -
In the Event Details of security events, request and response data samples containing sensitive data are masked and displayed as
{}. -
Request Cookie in sample information is masked as
{{Cookie}}, Request Header containing Token is masked as{{XXXToken}}, and Response SetCookie is masked as{{SetCookie}}.
The scope of effect of the data masking feature is as follows:
-
Risk Details and API Details: Applies only to new request and response data sample information.
-
Event Details: Applies to both new and existing request and response data sample information.
API Real-Time Data Masking
On the Sensitive Data-related Configurations tab, click API Real-Time Data Masking in the left-side list, and then click Create Template to configure a masking template.
-
Template Name: Set a recognizable template name.
-
Masking Rule Configuration: Click Create Rule to configure specific masking rules. Multiple rules can be configured.
-
Rule Name: Set a recognizable rule name.
-
Sensitive Data Type: Select the data types to be masked. Only built-in sensitive data types are supported.
-
Match Condition: Set HTTP conditions to trigger the rule. 0 to 5 conditions can be configured. If no conditions are configured, the rule is triggered for all HTTP requests.
NoteIf a rule contains multiple conditions, the request must meet all conditions (logical AND) to trigger the rule. For detailed descriptions of match fields and logical operators, see Match conditions.
-
Data Processing Method: The following two processing methods are supported.
-
Mask: Masks the data. You need to further set a specific masking Action. Options: Clear and Masking.
-
Monitor: Does not mask data, only logs are recorded.
-
-
-
Apply To: Specify the API assets to which the rule applies. Only assets with high, medium, or low sensitivity levels are supported. Each target object can have only one masking template configured.
After the template is created, wait 10 to 20 minutes for the masking rules to take effect for newly added target objects. To view API masking logs, go to the Security reports page.
For created templates, the following management operations are supported:
-
Enable or disable the template and rules.
-
Add rules to the template.
-
Edit the template and rule information.
-
Delete templates and rules.
IV. Authentication credentials configuration
If you use unconventional fields as your authentication fields in your business, or use authentication field names with weak characteristics such as pure digits, we recommend that you configure custom authentication credentials. Based on the built-in authentication credential detection, you can specify parameter names to help the built-in model accurately identify whether a request carries authentication credentials, thereby improving API security and the accuracy of unauthenticated risk detection.
-
On the API Security page, select the Policy Configurations > Authentication Credential Configurations tab.
-
Click Create Policy, complete the following configurations, and then click OK.
Configuration Item
Description
Name
Set a name for the policy.
Chinese characters, uppercase and lowercase letters are supported. Digits, periods (.), underscores (_), and hyphens (-) are also allowed.
Match Condition
Each condition consists of Match Field, Logical Operator, and Match Content. Up to 10 conditions are supported. When configuring, add at least one match condition for Request Header, Request Cookie, Request Query, or Request Body.
NoteIf multiple conditions are defined, the rule is triggered only when all conditions are met simultaneously.
For detailed configuration of match conditions, see the following table for corresponding logical operators and match content examples.
Note-
You can enter up to 50 match values and press Enter to confirm.
-
Match content for Authentication Credential Configurations is case-sensitive.
-
V. Business purpose configuration
API Security provides the following two types of business purpose policies:
Built-in policy configuration
Built-in business purpose policies are provided for multiple scenarios, including data update, data sharing, mobile SMS sending, and information sending. Built-in policies are enabled by default and cannot be modified or deleted. You can enable or disable each policy as needed.
Custom policy configuration
If the built-in policies do not meet your business needs, you can customize URL features and parameter name features to further improve the detection accuracy of API Security in specific business scenarios.
-
On the API Security page, select the Policy Configurations > Business Purpose tab.
-
Click Custom Policy to enter custom policy management. Click Create Policy, complete the following configurations, and then click OK to save your configuration.
-
You can enter up to 50 match values and press Enter to confirm.
-
Match content for Business Purpose is case-sensitive.
VI. Allowlist configuration
The allowlist configuration feature of API security enables you to customize allowlists for security events and risk detection. This helps you filter out unnecessary alert noise based on your actual business scenarios—for example, alerts generated by IP addresses from your office network—and improve operational efficiency.
-
On the API Security page, select the Policy Configurations > Configure Whitelist tab.
-
Click Create Policy, enter a name for the policy, and select the feature type for which you want to configure an allowlist. Currently, you can configure allowlists for Risk Detection and Security Events.
-
Configure the match conditions based on the feature type you selected.
Note-
A maximum of 10 match conditions are supported.
-
Match conditions for Configure Whitelist are case-sensitive.
Risk detection allowlist match conditions
Match Field
Logical Operator
Match Content
Domain
Contains Any of Multiple Values
Does Not Contain Any Value
Equals Any of Multiple Values
Does Not Equal Any Value
Multiple values can be entered, up to 50. Press Enter to confirm.
API
Contains Any of Multiple Values
Does Not Contain Any Value
Equals Any of Multiple Values
Does Not Equal Any Value
Multiple values can be entered, up to 50. Press Enter to confirm.
Security event allowlist match conditions
Match Field
Logical Operator
Match Content
Domain
Contains Any of Multiple Values
Does Not Contain Any Value
Equals Any of Multiple Values
Does Not Equal Any Value
Multiple values can be entered, up to 50. Press Enter to confirm.
API
Contains Any of Multiple Values
Does Not Contain Any Value
Equals Any of Multiple Values
Does Not Equal Any Value
Multiple values can be entered, up to 50. Press Enter to confirm.
IP
Belongs To
Does Not Belong To
Enter an IP address or IP/mask (for example, 1.1.X.X/24). Regular expressions are not supported. Enter up to 50 entries, separated with commas (,) or by pressing Enter.
-
-
Select the risk detection or security event types to exclude, and click OK to save the configuration.
NoteExcluded types support both built-in and custom options, and multiple selections are allowed.
VII. Lifecycle management
API security allows you to customize the criteria for identifying inactive APIs by setting daily visit counts and duration thresholds. This makes inactive API detection more aligned with your actual business situation. Lifecycle management helps you identify inactive APIs that meet your custom criteria, so you can take timely actions and prevent attackers from exploiting inactive APIs, avoiding unnecessary business losses.
-
On the API Security page, select the Policy Configurations > Lifecycle Management tab.
-
After setting the criteria for identifying inactive APIs, click OK.
-
Click Built-in Model.
This uses the built-in criteria: an API is considered inactive if it has no visits in the last 8 days or if its traffic has dropped significantly.
-
Click Custom, and set the daily visit count and duration (up to 31 days).
If an API's daily visit count is below the specified threshold for the custom duration, the API is identified as inactive.
-
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.
VIII. Log subscription
After you enable log subscription for asset information, risk information, or event information, logs are delivered to a specified LogStore that you created in the Log Service console when the delivery conditions are met. This allows you to centrally manage and operate logs using the features of Alibaba Cloud Log Service (SLS).
Currently, only WAF instances in the Chinese mainland can deliver logs to LogStores in the Chinese mainland, and non-Chinese mainland WAF instances can deliver logs to non-Chinese mainland LogStores. Cross-region log delivery between the Chinese mainland and non-Chinese mainland is not supported.
Activate the service-linked role
If you have not activated the Web Application Firewall service-linked role, you must do so before using the API security log subscription service. Follow the prompts to activate the role, which authorizes WAF to access your other cloud resources. For details about service-linked roles, see Service-linked roles. If you have already completed authorization when activating features such as WAF log service, skip this step.
Log subscription configuration
-
Before configuring API security log subscription tasks, open the Log Service console and create the Project and LogStore where you want to receive log subscriptions. If you have already created the target LogStore and verified that its name complies with the naming rules, proceed to the next step.
NoteThe log subscription feature currently does not support selecting Logstores that are automatically created by Log Service or custom-named "waf-logstore", "wafng-logstore", or "wafnew-logstore" as the log subscription destination.
-
After creation, return to the log subscription tab to configure subscriptions for asset information, risk information, and attack event information. If you want to query and analyze logs delivered to the specified LogStore in the Log Service console, enable indexing first. For details, see Create indexes.
-
Select the log type for the subscription task and click the Settings button to go to the configuration page.
-
Select the region where the LogStore is located, along with the Project name and LogStore name, and click the OK button to save the configuration. After the configuration is complete and logs are generated, you can return to the corresponding LogStore in the Log Service console to query and analyze the logs. If you want to process the logs—for example, to perform data masking—see Data Processing.
-
If you disable the log subscription task and no longer need the existing logs, delete the corresponding LogStore after disabling the task on the Log Subscription tab to avoid ongoing charges. For details, see How to Disable Log Service or Stop Billing.
The following describes the trigger conditions and detailed field descriptions for log subscription tasks.
-
Creating cloud resources in Log Service and enabling indexing incur additional charges billed by the Log Service product. For billing items and pricing, see Log Service Billing Overview.
-
Charges may still accrue after you create a Project or LogStore but have not enabled the log subscription task. When you are sure that you no longer need the created LogStore, delete it promptly to avoid additional charges. For details, see Why Charges Accrue When Only a Project and LogStore Are Created.
Asset information logs
Log subscription trigger conditions:
-
Asset information logs are delivered immediately after new API assets are added.
-
If no new API assets are added, asset information logs are delivered on a scheduled basis every hour by default.
Risk information logs
Log subscription trigger condition: When new risk information is detected, the risk information logs are delivered to the specified LogStore.
Attack event information logs
Log subscription trigger conditions:
-
When a new attack event is detected, the new attack event information logs are delivered to the specified LogStore.
-
If the attack continues, the attack event information logs are continuously delivered to the specified LogStore at 10-minute intervals.
Log subscription field value descriptions
If you need to understand the meaning of field values in logs or see how they map to names displayed in the console while analyzing or querying logs, refer to the following tables. The Description column shows the corresponding name for each field value as it appears in the Web Application Firewall console.
IX. Target object configuration
Subscription-based WAF
API Security provides three effective switches at the protection object or protection object group level:
-
Basic Detection switch: Enabled by default. Controls whether all built-in detection mechanisms and custom detection policies take effect.
-
Compliance Check switch: Disabled by default. Can be enabled only after the Basic Detection switch is enabled. Controls whether the Compliance Check feature takes effect.
-
Traceability switch: Disabled by default. Can be enabled only after the Basic Detection switch is enabled. Controls whether the Traceability feature takes effect.
Pay-as-you-go WAF
API Security provides one effective switch at the protection object or protection object group level:
-
Basic Detection switch: Controls whether all built-in detection mechanisms and custom detection policies take effect. To disable the API Security feature, disable the Basic Detection switch for all protection objects and protection object groups.