Use Alibaba Cloud CLI to call WAF 3.0 - Web Application Firewall

Alibaba Cloud CLI is a general-purpose command-line tool that is developed based on APIs. You can use Alibaba Cloud CLI to automatically manage and maintain Web Application Firewall (WAF) 3.0. For more information about Alibaba Cloud CLI, see What is Alibaba Cloud CLI? This topic uses the DescribeVisitTopIp operation as an example to describe how to use Alibaba Cloud CLI to call WAF 3.0. The DescribeVisitTopIp operation queries the top 10 IP addresses from which requests are sent.

Install Alibaba Cloud CLI

Before you can use Alibaba Cloud CLI, you must install Alibaba Cloud CLI. You can install Alibaba Cloud CLI on the Windows, Linux, and macOS operating systems. You must select an installation package for Alibaba Cloud CLI based on the operating system of your device. For more information, see the following topics:

Windows operating system: Windows
Linux operating system: Linux
macOS operating system: macOS

You can also use Cloud Shell provided by Alibaba Cloud to debug the commands that you want to run in Alibaba Cloud CLI. For more information about Cloud Shell, see What is Cloud Shell?

Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has permissions to manage and access the APIs of all Alibaba Cloud services. If you use an Alibaba Cloud account to call API operations, security risks may arise. We recommend that you create a Resource Access Management (RAM) identity, grant the required permissions to the RAM identity based on the principle of least privilege, and then use the RAM identity to call API operations.

Before you use Alibaba Cloud CLI, you must configure information, such as identity credentials and region IDs, in Alibaba Cloud CLI. Alibaba Cloud CLI supports various types of identity credentials. For more information, see Credential types. In this example, AccessKey pairs are used as identity credentials.

Create a RAM user and create an AccessKey pair for the RAM user. For more information, see Create a RAM user and Create an AccessKey pair.
Grant the RAM user the permissions to manage Alibaba Cloud services based on your business requirements. For this example, attach the AliyunYundunWAFv3ReadOnlyAccess policy that grants the read-only permissions on WAF 3.0 to the RAM user. For more information about system policies, see System policies for WAFV3.
Obtain and record the ID of the region that you want to use. Alibaba Cloud CLI uses the region ID that you specify to initiate API calls. For more information about the supported regions, see Endpoints.
Note
When you use Alibaba Cloud CLI, you can use the --region option to specify the region from which you want to initiate a call. If you use the option to specify a region, Alibaba Cloud CLI ignores the region information in the default credential settings and environment variables. For more information, see Command line options for API calls.
Use the AccessKey pair of the RAM user to configure identity credentials in the AkProfile configuration file. For more information, see Configuration examples.

Generate a sample CLI command

Click DescribeVisitTopIp to visit OpenAPI Explorer.
On the Parameters tab, configure the parameters. Then, click the CLI Example tab to view the generated sample CLI command.
Copy the CLI command or debug the CLI command in Cloud Shell.
- Click the icon to start Cloud Shell and debug the CLI command in Cloud Shell.
- Click the icon to copy the CLI command to the clipboard. You can also paste the CLI command into your on-premises shell to run the command.
  Note
  - When you paste the CLI command into your on-premises shell for debugging, take note of the parameter formats. For more information about the parameter formats required by Alibaba Cloud CLI, see Parameter formats.
  - By default, OpenAPI Explorer adds the --region option to the generated CLI command. When you copy the command to your on-premises shell, Alibaba Cloud CLI ignores the region information in the default identity credential settings and environment variables, and runs the command in the region specified by the option. You can delete or retain the option based on your business requirements.

Call the API operations of a cloud service

Note

Alibaba Cloud CLI integrates the API operations of WAF 2.0. If you want to call the API operations of WAF 3.0, you must append the --force --version 2021-10-01 setting to your CLI command to initiate a forceful call. For more information, see Forcibly call an API operation.
When a CLI command is generated in OpenAPI Explorer for an API operation of WAF 3.0, the forceful call-related setting is automatically appended to the CLI command. You do not need to manually perform this operation.
For more information about API operations, see List of operations by function.

Example: Query the top 10 IP addresses from which requests are sent

The following code provides an example on how to use Alibaba Cloud CLI to call the DescribeVisitTopIp operation of WAF 3.0. The operation queries the top 10 IP addresses from which requests are sent.

Run the following command:

aliyun waf-openapi DescribeVisitTopIp \
  --region cn-hangzhou \
  --RegionId 'cn-hangzhou' \
  --StartTimestamp 1665331200 \
  --EndTimestamp 1665386280 \
  --InstanceId 'waf_cdnsdf3****' \
  --version 2021-10-01 \
  --method POST \
  --force

View the output.
```
{
  "RequestId": "5D2B8DAE-A761-58CB-A68D-74989E4831DA",
  "TopIp": [
    {
      "Area": "310000",
      "Ip": "1.1.XX.XX",
      "Isp": "AAA",
      "Count": 2622
    }
  ]
}
```
Note
If an error is returned after you call an API operation of WAF 3.0, check whether the input parameters and values are valid based on the error code.
You can also use Alibaba Cloud OpenAPI Diagnostics to perform self-service diagnostics based on the returned request ID or SDK error information.