what are whitelist rules,how to set whitelist rules - PolarDB

You can add, enable, or disable whitelist rules in the PolarDB console. You can also modify or delete existing rules. This topic describes whitelist rules and provides the steps to manage them.

Whitelist rules

After you set a whitelist rule, any SQL statement not on the whitelist is blocked or triggers an alert. This mode protects the accounts used by your primary business. It allows these accounts to execute only the SQL statements used in your business and blocks all other SQL statements. Your business may use many SQL statements, and entering them individually can be time-consuming. To improve efficiency, the proxy provides the following three whitelist modes:

Training Mode: The proxy collects SQL statements but does not block them or trigger alerts.
Detection Mode: When an SQL statement not on the whitelist is detected, the proxy records it but does not block it.
Protection Mode: When an SQL statement not on the whitelist is detected, the proxy blocks and records it.

You can also set multiple whitelists in the console. Each whitelist can be trained using a different account. After you enable Detection Mode and Protection Mode, you can also specify which accounts each whitelist applies to.

Add a whitelist rule

Log on to the PolarDB console. In the upper-left corner, select the region where your cluster is located. Find the destination cluster and click its ID.
In the upper-left corner, select the region where the cluster is deployed.
Find the target cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Security.
On the SQL Firewall tab, click Add on the left.

In the Create a Rule dialog box, set the parameters based on the required whitelist mode.

Table 1. SQL firewall rule parameters

Parameter Name		Required	Description
Basic Information	Rule Name	Yes	The name of the SQL firewall rule. The name must meet the following requirements: It must consist of digits and letters. It must be no more than 30 characters in length.
	Description	No	A description of the rule for easy management. Note The length must be 64 characters or less.
	Endpoint	Yes	The Endpoint to which the rule applies.
Configurations	Rule Type	Yes	The type of rule to add. Select Whitelist Rule.
	Current Mode	No	The mode of the SQL firewall rule. Valid values: Training Mode: Collects SQL statements but does not record or block them. Detection Mode: When an SQL statement not on the whitelist is detected, it is recorded but not blocked. Protection Mode: When an SQL statement not on the whitelist is detected, it is recorded and blocked.
	Database Account Name	No	The database accounts to which the rule applies. The following options are supported: All Accounts: The rule applies to all database accounts in the cluster. You do not need to enter anything in the text box on the right. Include: The rule applies only to the specified database accounts. You must enter one or more database account names in the text box on the right. Separate multiple accounts with commas (,). Exclude: The rule applies to all database accounts in the cluster except for the specified ones. You must enter one or more database account names in the text box on the right. Separate multiple accounts with commas (,). Note The database account names entered in the text box must be in one of the following formats: `account_name`. Example: `user`. `account_name@full_IP_address`. Example: `user@10.0.0.0`.

After you configure the rule, click OK.
Follow the steps for the mode you selected.
- If Current Mode is set to Training Mode, perform the following steps.
  1. Use the Database Account Name specified in the previous steps to connect to the database Endpoint.
  2. Use the account to execute the business SQL statements that you want to add to the whitelist. The proxy parameterizes the SQL statements and saves them to the whitelist in the database. For example,
```
update t set k = 2 where id = 2;
```
    The parameterized SQL statement is as follows:
```
update t set k = ? where id = ?
```
    The ? character represents any value. The parameterized SQL statement update t set k = ? where id = ? is collected and added to the whitelist.
  Note
  You can also add the HINT command hint(/* store_to_whitelist */) before a business SQL statement in any whitelist mode. This command parameterizes the SQL statement and adds it to the whitelist.
- If Current Mode is set to Detection Mode, perform the following steps.
  1. Use the Database Account Name specified in the previous steps to connect to the database Endpoint.
  2. Use the account to execute your business SQL statements to check whether any statements have not yet been added to the whitelist. For example:
```
update t set k = 2 where k = 2
```
    If this SQL statement is not on the whitelist, the proxy allows it to be executed and records it. The execution result is as follows:
```
Query OK, 0 rows affected (0.03 sec)
Rows matched:1 Changed: 0 Warnings:0
```
- If Current Mode is set to Protection Mode, perform the following steps.
  1. Use the Database Account Name specified in the previous steps to connect to the database Endpoint.
  2. Use the account to execute a business SQL statement. For example,
```
select id from t where id = 1;
```
    If this SQL statement is not on the whitelist, the proxy records and blocks it. The execution result is as follows:
```
ERROR 1141 (HY000): This SQL is rejected by SQL Firewall. Access denied for user 'xzh'@'x.x.x.x' to database 'xzh': This SQL is not in whitelist wl_test.
```

Note

You must train the SQL statements each time you update your business. Otherwise, the new business SQL statements cannot be executed.
You can add multiple whitelists in the console. Each whitelist can be trained using a different account. After you enable Detection Mode and Protection Mode, you can also specify which accounts each whitelist applies to.

Enable or disable a whitelist rule

Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
Find the target cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Security.
On the SQL Firewall tab, find the rule that you want to enable or disable and click the Enable/Disable switch.

Note
You can also select multiple rules in the list and click Enable or Disable at the bottom of the list to enable or disable them in bulk.
In the Enable or Disable dialog box that appears, click OK.

Modify a whitelist rule

Log on to the PolarDB console. In the upper-left corner, select the region where your cluster is located. Find the destination cluster and click its ID.
In the upper-left corner, select the region where the cluster is deployed.
Find the target cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Security.
On the SQL Firewall tab, find the rule that you want to modify, and click Modify in the Actions column. In the Modify A Rule dialog box that appears, modify the rule parameters as required. For more information about the parameters, see Add a whitelist rule.

Note
You cannot modify the Rule Name when you modify a rule.
After you modify the rule, click OK.

Note

You cannot modify parameterized SQL statements in the console. You can only delete the parameterized SQL statements from the proxy_auditing.sql_list database table and then add them again.

Delete a whitelist rule

Log on to the PolarDB console. In the upper-left corner, select the region where your cluster is located. Find the destination cluster and click its ID.
In the upper-left corner, select the region where the cluster is deployed.
Find the target cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Security.
On the SQL Firewall tab, find the rule that you want to delete, and click Delete in the Actions column.

Note
You can also select multiple destination rules in the rule list and click Delete below the list to delete the rules in a batch.
In the Delete dialog box that appears, click OK.