Web Application Firewall exclusion lists

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 and Create Web Application Firewall policies for Application Gateway.

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.

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.

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.

Identify request attributes to exclude

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:

  • Request headers
  • Request cookies
  • Request attribute name (args) can be added as an exclusion element, such as:
    • Form field name
    • JSON entity
    • URL query string args

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:

  • 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.
  • Starts with: This operator matches all fields that start with the specified selector value.
  • Ends with: This operator matches all request fields that end with the specified selector value.
  • Contains: This operator matches all request fields that contain the specified selector value.
  • Equals any: This operator matches all request fields. * will be the selector value.

In all cases matching is case insensitive. Regular expressions aren't allowed as selectors.

Note

For more information and troubleshooting help, see WAF troubleshooting.

Request attributes by keys and values

When you configure an exclusion, you need to determine whether you want to exclude the key or the value from WAF evaluation.

For example, suppose your requests include this header:

My-Header: 1=1

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.

Note

Request attributes by key and values are only available in CRS 3.2 and newer.

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.

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.

Exclusion scopes

Exclusions can be configured to apply to a specific set of WAF rules, to rulesets, or globally across all rules.

Tip

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.

Per-rule exclusions

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.

Per-rule exclusions are available when you use the OWASP (CRS) ruleset version 3.2 or later.

Example

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.

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.

You can use the following approaches to exclude the User-Agent header from evaluation by all of the SQL injection rules:

Note

As of early May 2022, we are rolling out updates to the Azure portal for these features. If you don't see configuration options in the portal, please use PowerShell, the Azure CLI, Bicep, or ARM templates to configure global or per-rule exclusions.

$ruleGroupEntry = New-AzApplicationGatewayFirewallPolicyExclusionManagedRuleGroup `
  -RuleGroupName 'REQUEST-942-APPLICATION-ATTACK-SQLI'

$exclusionManagedRuleSet = New-AzApplicationGatewayFirewallPolicyExclusionManagedRuleSet `
  -RuleSetType 'OWASP' `
  -RuleSetVersion '3.2' `
  -RuleGroup $ruleGroupEntry

$exclusionEntry = New-AzApplicationGatewayFirewallPolicyExclusion `
  -MatchVariable "RequestHeaderValues" `
  -SelectorMatchOperator 'Equals' `
  -Selector 'User-Agent' `
  -ExclusionManagedRuleSet $exclusionManagedRuleSet

$wafPolicy = Get-AzApplicationGatewayFirewallPolicy `
  -Name $wafPolicyName `
  -ResourceGroupName $resourceGroupName
$wafPolicy.ManagedRules[0].Exclusions.Add($exclusionEntry)
$wafPolicy | Set-AzApplicationGatewayFirewallPolicy

Global exclusions

You can configure an exclusion to apply across all WAF rules.

Example

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.

The following example shows how you can exclude the user query string argument from evaluation:

Note

As of early May 2022, we are rolling out updates to the Azure portal for these features. If you don't see configuration options in the portal, please use PowerShell, the Azure CLI, Bicep, or ARM templates to configure global or per-rule exclusions.

$exclusion = New-AzApplicationGatewayFirewallExclusionConfig `
   -MatchVariable 'RequestArgNames' `
   -SelectorMatchOperator 'StartsWith' `
   -Selector 'user'

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.

Next steps

After you configure your WAF settings, you can learn how to view your WAF logs. For more information, see Application Gateway diagnostics.