The API security module automatically sorts the APIs of services that are protected by Web Application Firewall (WAF) and detects API vulnerabilities, such as unauthorized access to APIs, exposure of sensitive data, and exposure of internal APIs, based on a built-in detection mechanism and custom detection policies. The module allows you to trace API exception events, check the compliance of outbound data transfer, trace sensitive data by using reports, and fix detected vulnerabilities. The module also provides data for API lifecycle management. This way, you can configure comprehensive security protection for your APIs. This topic describes how to configure the API security module.
Limits
You cannot enable this feature for protected objects that are added to WAF in hybrid cloud mode and Microservices Engine (MSE) instances or custom domain names bound to web applications in Function Compute that are added to WAF in cloud native mode.
Features
Feature | Description |
Analyzes access logs offline to automatically detect APIs and identify the business purposes of API calls based on API characteristics. | |
Detects various security risks, such as unauthorized access and sensitive data leaks, and provides risk analysis and suggestions on how to handle the security risks. | |
Monitors and analyzes API calls to detect abnormal requests and attacks at the earliest opportunity. | |
Helps identify risks that are associated with outbound data transfer operations based on the Measures for the Security Assessment of Outbound Data Transfer. The module checks the compliance requirements of the operations in the following scenarios:
| |
Performs source tracing by cross-referencing logs and sample sensitive data when sensitive data security events occur. | |
Allows you to configure custom detection policies based on your business requirements. This increases the detection accuracy and recall rate of the API security module. | |
Allows you to configure the API security module for a specific protected object. |
For information about the capabilities of the API security module, refer to the following section that provides answers to some frequently asked questions about the API security module:
Prerequisites
A WAF 3.0 instance is purchased. For more information, see Purchase a subscription WAF 3.0 instance and Purchase a pay-as-you-go WAF 3.0 instance.
Step 1: View basic detection data
Before you enable the API security module, you can view the overview information about security events and API assets and view security event data to obtain security information about APIs. By default, basic detection is enabled for subscription WAF instances. If you do not want to obtain basic detection data, skip this step.
You cannot enable basic detection for pay-as-you-go WAF instances.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and the region in which the WAF instance is deployed. You can select Chinese Mainland or Outside Chinese Mainland for the region.
In the left-side navigation pane, choose .
In the Basic Detection section, view basic detection data.
Security Event Overview: displays the total number of API security events, and the number of high-risk, medium-risk, and low-risk API security events.
API Asset Overview: displays the total number of APIs, the number of active APIs, and the number of deactivated APIs.
Security Events: displays the names, API paths, domain names, attack sources, and occurrence time of security events.
If you want to view the number of APIs that transfer sensitive data or view risk details and suggestions on how to handle security events, you can enable the API security module. For more information, see Step 2: Enable the API security module.
If you do not want to view basic detection data, turn off Basic Detection.
Step 2: Enable the API security module
Data computing and analysis are performed offline. The API security module does not actively detect APIs and does not affect your business.
The API security module detects responses that have specific characteristics and determines whether data leaks occurred. After you enable the API security module, WAF is authorized to analyze the responses. Enable the API security module based on your business requirements.
Log on to the WAF 3.0 console. In the top navigation bar, select the resource group and the region in which the WAF instance is deployed. You can select Chinese Mainland or Outside Chinese Mainland for the region.
In the left-side navigation pane, choose .
Enable the API Security module.
Apply for a free trial of the API security module
NoteEach Alibaba Cloud account can apply for the free trial only once.
The free trial is valid for seven days. The security analysis results that are generated during the trial period are available only during the trial period. If you want to retain the security analysis results, enable the API security module before the trial period ends.
On the API Security page, click Try Now. On the Try Now page, enter the application information and click Submit.
After you submit your trial application, Alibaba Cloud engineers will contact you based on the contact information that you submit to confirm information that is related to your application. After your trial application is approved, the API security module is automatically enabled for your WAF instance.
Enable the API security module
On the API Security page, click Enable Now.
On the Enable Now page, set the API Security parameter to Enable, click Buy Now, and then complete the payment.
Step 3: View API security data
View overview data
On the Overview tab of the API Security page, view the security analysis results.
Section | Description | Operation |
API Security Events (Figure 1) | Displays the total number of security events, including High-risk Events, Medium-risk Events, and Low-risk Events security events. The daily change in the total number of security events is also displayed to the right of the total number of security events. | N/A |
API Risk Items (Figure 2) | Displays the total number of API risk items, including High-risk Items, Medium-risk Items, and Low-risk Items items. The daily change in the total number of API risk items is also displayed to the right of the total number of API risk items. | N/A |
API Asset Overview (Figure 3) | Displays information about API assets based on statistics, including the following items:
| N/A |
API Asset List (Figure 4) | Displays the details of all APIs that are detected by WAF. The API assets list contains the following information: API name, domain name, request method, number of calls in the previous 30 days, sensitivity level of detected sensitive data, type of detected sensitive data, object for which the API is called to provide services, and purpose of the API call.
| In the upper-right corner of the API Assets section, click the To search for APIs, you can use the following methods:
To manage APIs, you can use the following methods:
Only Alibaba Cloud accounts support this feature.
Note
|
icon to specify the items that you want to view. 
icon and select API Operation or Domain Name from the API drop-down list. Then, enter the corresponding information in the search box. 
icon to the right of Request Method, Service Object, or Purpose to filter APIs. 
icon to the right of Calls Within Last 30 Days, Bot Requests, Cross-border Requests, or Risk Items/Events to sort APIs. 
icon in the Follow column. 
icon in the Remarks column. Then, click the 
icon. 
icon to create an export task. View risk detection data
On the Risk Detection tab of the API Security page, view API risk detection data.
Section | Description | Operation |
API Risk Overview (Figure 1) | Displays the Total Risk Items, including High-risk Items, Medium-risk Items, and Low-risk Items items. The daily change in the total number of risk items is also displayed to the right of the total number of risk items. | Click View to the right of the number of High-risk Items, Medium-risk Items, or Low-risk Items items to view the risk details. |
Trend of API Risks (Figure 2) | Displays the trend in the number of High, Medium, and Low items in the previous 30 days in a trend chart. | Click High, Medium, or Low below the trend chart to view specific data. |
API Risk Types (Figure 3) | Displays statistics about the types of API risks in a pie chart. For more information, see What types of API risks can be detected by the API security module? | Click a type of API risk to the right of a pie chart to view specific data. |
API Risk Details (Figure 4) | Displays the details of all API risks that are detected by WAF. The API risk list contains the following information: risk item ID, risk type, source type, API, domain name, purpose, status, and number of security events.
| Click the To search for API risks, you can use the following methods:
You can perform the following operations to manage API risks:
|
icon in the Status column. Then, select a state and click OK. View security event data
On the Security Events tab of the API Security page, view the security event analysis results.
Section | Description | Operation |
Overview of API Security Events (Figure 1) | Displays the total number of API security events, including High-risk Events, Medium-risk Events, and Low-risk Events security events. The daily change in the total number of API security events is also displayed to the right of the total number of API security events. | Click View to the right of the number of High-risk Events, Medium-risk Events, or Low-risk Events security events to view the event details. |
Trend of API Security Events (Figure 2) | Displays the trend in the number of high-risk, medium-risk, and low-risk security events in the previous 30 days in a trend chart. | Click High, Medium, or Low below the trend chart to view specific data. |
Types of API Security Events (Figure 3) | Displays statistics about the types of API security events in a pie chart. For more information, see What types of exception events can be detected by the API security module? | Click a type of API security event to the right of a pie chart to view specific data. |
Details of API Security Events (Figure 4) | Displays the details of all API security events that are detected by WAF. The API security event list contains the following information: event ID, event type, source type, API, domain name, purpose of the API call, attack source, attack status, and associated risk.
| Click the To search for API security events, you can use the following methods:
To manage API security events, you can use the following methods:
|
Step 4: Check the compliance of outbound data transfer and trace sensitive data
If your business requires providing information abroad, you must apply to the national cyberspace administration for the security assessment of the outbound data transfer through the local provincial cyberspace administration.Outside Chinese Mainland You can use the compliance check and tracing and auditing features of the API security module. The features are supported only in the Chinese mainland.
View compliance check data
On the Compliance Check tab of the API Security page, you can query compliance check data of specific protected objects in a specific period of time.
Specify the time range to query.
By default, compliance check data that is generated from January 1 of the previous year to the current day is displayed. You can also click Change Detection Configuration, configure the Evaluation Period parameter, and then click Save Configurations.
NoteAfter you view compliance check data that is generated in the specified period of time and refresh the page, the time range to query is automatically changed to the default time range to query.
Specify protected objects for which you want to enable compliance check
By default, compliance check is enabled for all protected objects. If you want to exclude specific protected objects from traffic analysis, you can disable compliance check for the protected objects. For more information, see Specify protected objects.
The following table describes the details of compliance check data.
Section | Description |
Detection Results | Displays the types of personal information and sensitive personal information that are detected by the compliance check feature and the detection results. Valid values of detection results:
|
Detection Items | Displays the number of personal information entries that are transferred abroad, number of natural persons associated with the personal information, and evaluation results. |
Outbound Transferred Data Trend | Displays the amount of sensitive personal information that is transferred abroad, total amount of personal information, and trend in the amount of personal information that is transferred abroad in a specific period of time in a chart. |
Flow Distribution of Outbound Transferred Data | Displays the cross-border flow of data on a map of the world. A darker color indicates a larger amount of data.
|
Statistics on Types of Outbound Transferred Personal Information | Displays different types of personal information and sensitive personal information that are transferred abroad since January 1 of the previous year and the evaluation results in a list. For information about the standards for the security assessment and filing of outbound data transfer, see What are the standards for the security assessment and filing of outbound data transfer? |
Statistics on Domain Names in Personal Information and API Names | Displays the domain names and APIs on which personal information and sensitive personal information are detected in a list. |
Trace sensitive data
On the Tracing and Auditing tab of the API Security page, view tracing and auditing data of sensitive data.
By default, the tracing and auditing feature is disabled. To enable the feature, click Applicable Object Configurations on the Policy Configurations tab and turn on Tracing and Auditing. For more information, see Specify protected objects.
Feature | Description |
Log Query | Displays the IP addresses and APIs that are used to obtain sensitive data, domain names whose sensitive data is leaked, and details of the leaked data.
|
Data Traceability | Enter sample sensitive data and obtain the tracing result.
|
Step 5: Configure API security policies
You can configure detection policies for APIs based on your business requirements. You can configure authentication credential policies, sensitive data type policies, attack detection model policies, business purpose policies, and API lifecycle for APIs based on your business requirements. This helps improve the detection accuracy and recall rate of the API security module.
Configure an authentication credential policy
After you create an authentication credential detection policy, the built-in model detects specific request parameters to check whether requests contain authentication credentials. This helps improve the detection accuracy for unauthorized requests.
On the API Security page, click the Policy Configurations tab. Then, click Authentication Credential.
In the Authentication Credential section, click Create Policy. Configure the parameters and click OK. The following table describes the parameters.
Parameter
Description
Field Name
The name of the parameter that you want the policy to detect. For example, if the request body is
xxx=123&yyy=456, the parameter names arexxxandyyy.Position
The type of parameter that you want the policy to detect. Valid values:
GET Parameter Name
POST Parameter Name
wafnew.apisec.policy.token.location.cookie
Header
Status
The status of the policy. By default, the policy is enabled.
Configure a sensitive data type policy
The API security module provides the following two sensitive data type policies:
Built-in policies
WAF provides built-in detection logic for common sensitive data types such as ID card numbers, bank card numbers, names, addresses, and mobile phone numbers. You can enable or disable a built-in policy based on your business requirements. You cannot modify or delete built-in policies.
Custom policies
If the built-in policies cannot meet your business requirements, you can configure custom sensitive data types.
On the API Security page, click the Policy Configurations tab. Then, click Sensitive Data Type.
In the Sensitive Data Type section, click Create Policy. Configure the parameters and click OK. The following table describes the parameters.
Parameter
Description
Package Name
The name of the policy.
The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Type
The detection mode of the custom policy.
Basic: You can perform simple configurations in this mode.
If you select Basic, you must configure the Characters and Length parameters.
Characters: the characters that you want the policy to detect. Valid values: Numeric, Uppercase Letters, and Lowercase Letters. You can select multiple values.
Length: the character length. Valid values: 6 to 64. The start and end values of this parameter must be integers.
Expert: supports the use of regular expressions.
If you select Expert, you must enter a regular expression. To prevent misdetection, make sure that the matched characters of the regular expression are at least 6 characters in length.
Sensitivity Level
The sensitivity level of the detected sensitive data. Valid values: High Sensitivity, Moderate Sensitivity, and Low Sensitivity.
Status
The status of the policy. By default, the policy is enabled.
Configure an attack detection model policy
To improve the detection recall rate of exception events, you can create a custom detection model policy.
On the API Security page, click the Policy Configurations tab. Then, click Attack Detection Model.
In the Attack Detection Model section, click Create Policy. Configure the parameters and click OK. The following table describes the parameters.
Parameter
Description
Rule Name
The name of the policy.
The name can contain letters, digits, periods (.), underscores (_), and hyphens (-).
Matching Condition
Specify the characteristics of requests that match the rule.
Each match condition consists of the Match Field, Logical Operator, and Match Content parameters. For information about match fields and logical operators, see the following table.
Click Add Condition to add a match condition. You can add up to five match conditions to a rule. If you add multiple match conditions, the rule is matched only when all match conditions are met.
Statistical Interval
The statistical interval for attack detection. Default value: 15. Unit: minutes.
Calls
The maximum number of API calls.
Statistical Object
The data deduplication mode. Valid values:
Disable Statistics: Deduplication is not performed on matched requests. In this case, alerts are triggered for all requests that meet the match conditions.
Specified Parameters: Deduplication is performed only on specified parameters in matched requests. In this case, alerts are triggered when the number of different values of the specified parameters in the matched requests exceeds the upper limit after deduplication.
If you select this value, you must configure the following parameters:
Parameter Position: the type of request parameter. Valid values: GET Parameter and POST Parameter.
Parameter Name: the name of the parameter.
Threshold: the maximum number of different values of the specified parameter.
All Parameters: Deduplication is performed on all parameters of matched requests. In this case, alerts are triggered when the number of different values of a parameter in matched requests exceeds the upper limit after deduplication.
If you select this value, you must configure the following parameters:
Excluded Parameter Name: the parameters on which you do not want to perform value deduplication. Separate multiple parameters with commas (,). Configure the parameters that are required by common requests, such as the timestamp and PageNumber parameters.
Threshold: the maximum number of different values of a specific parameter.
Event Level
The level of the security events that you want to detect. Valid values: High Risk, Medium, and Low.
Status
The status of the policy. By default, the policy is enabled.
Configure a business purpose policy
The API security module provides the following two types of business purpose policies:
Built-in policies
Multiple business purposes are configured in the built-in policies, such as data updates, data sharing, text message sending, and information sending. You can enable or disable a built-in policy based on your business requirements. You cannot modify or delete built-in policies.
Custom policies
If the built-in policies cannot meet your business requirements, you can configure custom business purpose policies.
On the API Security page, click the Policy Configurations tab. Then, click Business Purpose.
In the Business Purpose section, click Create Policy. 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 (-).
URL Characteristics
The keywords of the characteristics of the URLs that are used in the business scenarios for which you want to create a business purpose policy.
NoteIf you specify multiple keywords, the policy is matched when one of the keywords is matched and the note of the corresponding API is updated.
Parameter
The keywords of the parameters that are used in the business scenarios for which you want to create a business purpose policy.
Status
The status of the policy. By default, the policy is enabled.
Configure an API lifecycle management policy
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 API Security page, click the Policy Configurations tab. Then, click Lifecycle Management.
In the Lifecycle Management section, click Create Policy. Configure the parameters and click OK.
Click Built-in Model.
If you select Built-in Model, APIs that are not called in the previous 30 days or APIs for which the number of initiated calls decreased are determined to be deactivated APIs.
Click Custom and configure the number of daily calls and the number of consecutive days during which the API is not called.
If you select Custom, 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.
Specify protected objects
The following switches are provided for you to enable or disable the built-in detection mechanism, custom detection policies, compliance check, and tracing and auditing.
Switch: You can turn on or turn off Switch to enable or disable the built-in detection mechanism and custom detection policies.
Compliance Check: You can turn on or turn off Compliance Check to enable or disable the compliance check feature. You can turn on Compliance Check only after you turn on Switch.
Tracing and Auditing: You can turn on or turn off Tracing and Auditing to enable or disable the tracing and auditing feature. You can turn on Tracing and Auditing only after you turn on Switch.
The billing method of your WAF instance determines whether the switches are turned on or turned off by default.
Subscription billing method: By default, Switch is turned on and Compliance Check and Tracing and Auditing are turned off.
Pay-as-you-go billing method: By default, Switch is turned off.
To turn on the preceding switches, click Applicable Object Configurations on the Policy Configurations tab.
Step 6: View the updated API security data
After you complete Step 5: Configure API security policies, you can view API security data on the Overview, Risk Detection, and Security Events tabs of the API Security page. For more information, see Step 3: View API security data.
Related operations
You can configure monitoring and alerting for API security events in the CloudMonitor console. This way, you can receive alert notifications when high-risk events are detected and obtain security information about your API assets at the earliest opportunity. For more information, see Configure CloudMonitor notifications.