You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -4,86 +4,297 @@ description: This article provides information on Web Application Firewall exclu
4
4
services: web-application-firewall
5
5
author: vhorne
6
6
ms.service: web-application-firewall
7
-
ms.date: 03/08/2022
7
+
ms.date: 04/21/2022
8
8
ms.author: victorh
9
9
ms.topic: conceptual
10
10
ms.custom: devx-track-azurepowershell
11
11
---
12
12
13
13
# Web Application Firewall exclusion lists
14
14
15
-
The Azure Application Gateway Web Application Firewall (WAF) provides protection for web applications. This article describes the configuration for WAF exclusion lists. These settings are located in the WAF Policy associated to your Application Gateway. To learn more about WAF Policies, see [Azure Web Application Firewall on Azure Application Gateway](ag-overview.md) and [Create Web Application Firewall policies for Application Gateway](create-waf-policy-ag.md)
15
+
The Azure Application Gateway Web Application Firewall (WAF) provides protection for web applications. This article describes the configuration for WAF exclusion lists. These settings are located in the WAF policy associated to your Application Gateway. To learn more about WAF policies, see [Azure Web Application Firewall on Azure Application Gateway](ag-overview.md) and [Create Web Application Firewall policies for Application Gateway](create-waf-policy-ag.md).
16
16
17
-
Sometimes Web Application Firewall (WAF) might block a request that you want to allow for your application. WAF exclusion lists allow you to omit certain request attributes from a WAF evaluation. The rest of the request is evaluated as normal.
17
+
Sometimes WAF might block a request that you want to allow for your application. WAF exclusion lists allow you to omit certain request attributes from a WAF evaluation. The rest of the request is evaluated as normal.
18
18
19
-
For example, Active Directory inserts tokens that are used for authentication. When used in a request header, these tokens can contain special characters that may trigger a false positive from the WAF rules. By adding the header to an exclusion list, you can configure WAF to ignore the header, but WAF still evaluates the rest of the request.
19
+
For example, Active Directory inserts tokens that are used for authentication. When used in a request header, these tokens can contain special characters that might trigger a false positive detection from the WAF rules. By adding the header to an exclusion list, you can configure WAF to ignore the header, but WAF still evaluates the rest of the request.
20
20
21
-
Exclusion lists are global in scope.
21
+
You can configure exclusions to apply when specific WAF rules are evaluated, or to apply globally to the evaluation of all WAF rules. Exclusion rules apply to your whole web application.
22
22
23
-
To set exclusion lists in the Azure portal, configure **Exclusions** in the WAF policy resource's **Policy settings** page:
23
+
## Identify request attributes to exclude
24
24
25
-
:::image type="content" source="../media/application-gateway-waf-configuration/waf-policy-exclusions.png" alt-text="Screenshot of the Azure portal that shows the exclusions configuration for the W A F policy.":::
25
+
When you configure a WAF exclusion, you must specify the attributes of the request that should be excluded from the WAF evaluation. You can configure a WAF exclusion for the following request attributes:
26
26
27
-
## Attributes
28
-
29
-
The following attributes can be added to exclusion lists by name. The values of the chosen field aren't evaluated against WAF rules, but their names still are (see Example 1 below, the value of the User-Agent header is excluded from WAF evaluation). The exclusion lists remove inspection of the field's value.
30
-
31
-
* Request Headers
32
-
* Request Cookies
27
+
* Request headers
28
+
* Request cookies
33
29
* Request attribute name (args) can be added as an exclusion element, such as:
34
-
35
30
* Form field name
36
31
* JSON entity
37
32
* URL query string args
38
33
39
-
You can specify an exact request header, body, cookie, or query string attribute match. Or, you can optionally specify partial matches. Exclusion rules are global in scope, and apply to all pages and all rules.
40
-
41
-
The following are the supported match criteria operators:
34
+
You can specify an exact request header, body, cookie, or query string attribute match. Or, you can specify partial matches. Use the following operators to configure the exclusion:
42
35
43
36
-**Equals**: This operator is used for an exact match. As an example, for selecting a header named **bearerToken**, use the equals operator with the selector set as **bearerToken**.
44
37
-**Starts with**: This operator matches all fields that start with the specified selector value.
45
38
-**Ends with**: This operator matches all request fields that end with the specified selector value.
46
39
-**Contains**: This operator matches all request fields that contain the specified selector value.
47
40
-**Equals any**: This operator matches all request fields. * will be the selector value.
48
41
49
-
In all cases matching is case insensitive and regular expression aren't allowed as selectors.
42
+
In all cases matching is case insensitive. Regular expressions aren't allowed as selectors.
50
43
51
44
> [!NOTE]
52
45
> For more information and troubleshooting help, see [WAF troubleshooting](web-application-firewall-troubleshoot.md).
53
46
54
-
## Examples
47
+
### Request attributes by keys and values
48
+
49
+
When you configure an exclusion, you need to determine whether you want to exclude the key or the value from WAF evaluation.
50
+
51
+
For example, suppose your requests include this header:
52
+
53
+
```
54
+
My-Header: 1=1
55
+
```
56
+
57
+
The value of the header (`1=1`) might be detected as an attack by the WAF. But if you know this is a legitimate value for your scenario, you can configure an exclusion for the *value* of the header. To do so, you use the **RequestHeaderValues** request attribute, and select the header name (`My-Header`) with the value that should be ignored.
58
+
59
+
> [!NOTE]
60
+
> Request attributes by key and values are only available in CRS 3.2 and newer.
61
+
>
62
+
> Request attributes by names work the same way as request attributes by values, and are included for backward compatibility with CRS 3.1 and earlier versions. We recommend you use request attributes by values instead of attributes by names. For example, use **RequestHeaderValues** instead of **RequestHeaderNames**.
63
+
64
+
In contrast, if your WAF detects the header's name (`My-Header`) as an attack, you could configure an exclusion for the header *key* by using the **RequestHeaderKeys** request attribute. The **RequestHeaderKeys** attribute is only available in CRS 3.2 and newer.
The following examples demonstrate the use of exclusions.
68
+
Exclusions can be configured to apply to a specific set of WAF rules, to rulesets, or globally across all rules.
59
69
60
-
### Example 1
70
+
> [!TIP]
71
+
> It's a good practice to make exclusions as narrow and specific as possible, to avoid accidentally leaving room for attackers to exploit your system. When you need to add an exclusion rule, use per-rule exclusions wherever possible.
61
72
62
-
In this example, you want to exclude the user-agent header. The user-agent request header contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor, or software version of the requesting software user agent. For more information, see [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent).
73
+
### Per-rule exclusions
63
74
64
-
There can be any number of reasons to disable evaluating this header. There could be a string that the WAF sees and assumes it’s malicious. For example, the classic SQL attack “x=x” in a string. In some cases, this can be legitimate traffic. So you might need to exclude this header from WAF evaluation.
75
+
You can configure an exclusion for a specific rule, group of rules, or rule set. You must specify the rule or rules that the exclusion applies to. You also need to specify the request attribute that should be excluded from the WAF evaluation.
65
76
66
-
The following Azure PowerShell cmdlet excludes the user-agent header from evaluation:
77
+
Per-rule exclusions are available when you use the OWASP (CRS) ruleset version 3.2 or later.
78
+
79
+
#### Example
80
+
81
+
Suppose you want the WAF to ignore the value of the `User-Agent` request header. The `User-Agent` header contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor, or software version of the requesting software user agent. For more information, see [User-Agent](https://developer.mozilla.org/docs/Web/HTTP/Headers/User-Agent).
82
+
83
+
There can be any number of reasons to disable evaluating this header. There could be a string that the WAF detects and assumes it’s malicious. For example, the `User-Agent` header might include the classic SQL injection attack `x=x` in a string. In some cases, this can be legitimate traffic. So you might need to exclude this header from WAF evaluation.
84
+
85
+
You can use the following approaches to exclude the `User-Agent` header from evaluation by all of the SQL injection rules:
86
+
87
+
# [Azure portal](#tab/portal)
88
+
89
+
:::image type="content" source="../media/application-gateway-waf-configuration/waf-policy-exclusions-rule-edit.png" alt-text="Screenshot of the Azure portal that shows the per-rule exclusion configuration for the W A F policy.":::
This example excludes the value in the *user* parameter that is passed in the request via the URL. For example, say it’s common in your environment for the user field to contain a string that the WAF views as malicious content, so it blocks it. You can exclude the user parameter in this case so that the WAF doesn't evaluate anything in the field.
129
+
# [Bicep](#tab/bicep)
77
130
78
-
The following Azure PowerShell cmdlet excludes the user parameter from evaluation:
You can configure an exclusion to apply across all WAF rules.
210
+
211
+
#### Example
212
+
213
+
Suppose you want to exclude the value in the *user* parameter that is passed in the request via the URL. For example, say it’s common in your environment for the `user` query string argument to contain a string that the WAF views as malicious content, so it blocks it. You can exclude all query string arguments where the name begins with the word `user`, so that the WAF doesn't evaluate the field's value.
214
+
215
+
The following example shows how you can exclude the `user` query string argument from evaluation:
216
+
217
+
# [Azure portal](#tab/portal)
218
+
219
+
:::image type="content" source="../media/application-gateway-waf-configuration/waf-policy-exclusions-global-edit.png" alt-text="Screenshot of the Azure portal that shows the global exclusion configuration for the W A F policy.":::
So if the URL `http://www.contoso.com/?user%3c%3e=joe` is passed to the WAF, it won't evaluate the string **joe**, but it will still evaluate the parameter name **user%3c%3e**.
So if the URL `http://www.contoso.com/?user%3c%3e=joe` is scanned by the WAF, it won't evaluate the string **joe**, but it will still evaluate the parameter name **user%3c%3e**.
0 commit comments