Web Application Firewall
# Overview
Quickly protect your site from common attacks with our Web Application Firewall (WAF), which uses a ruleset managed by Netlify to block malicious requests.
The WAF feature is one element of Netlify Advanced Web Security, along with Firewall Traffic Rules and Rate limiting. These features are designed to complement each other for a robust solution, with a clear order of precedence between these.
Unlike Firewall Traffic Rules or Rate Limiting, the WAF does not require you to manually create rules based on traffic patterns you observe, and extensive customizations are typically not required.
However, we always recommend that you ensure that your security configuration does not prevent legitimate visitors from using your site. You can confirm by observing traffic behavior in detail using Log Drains.
# How WAF works
Before proceeding to enable protection and fine-tune your configuration, here is what you should know about how the WAF works.
# The baseline ruleset
Netlify maintains and updates WAF rules as a managed service. The rules included in the baseline ruleset are based on the OWASP CRS (Core Rule Set), which covers the most common attack types included in the OWASP Top 10, such as cross-site scripting (XSS), SQL injection attacks, remote code execution (RCE), and more.
The baseline ruleset is a subset of the rules in the full CRS. The ruleset includes rules that are related to common attacks observed on our platform and those that are less likely to block legitimate web requests.
Netlify WAF follows the CRS concepts of configurable Anomaly Scoring and Severity Levels. This means that requests are not naively blocked on any rule match. Rather, for a request to be blocked, the anomaly score threshold must be met for that request. More on this below.
# Blocking modes
When enabled, WAF supports two modes:
- In Active mode, requests matching the anomaly score threshold are blocked.
- In Passive mode, no requests are actually blocked, but all information about rule matches is logged. We recommend using this mode the first time you enable WAF, until you have completed tuning your configuration.
# Rules and actions
Each rule has an ID number, a category, and a severity level that match the same attributes in the OWASP CRS. This means that you can review rule definitions in the CRS GitHub repository, if needed.
Each rule has an action associated with it:
- Rules set to Block are counted towards the anomaly score threshold. If the threshold is met and blocking mode is Active, the request will be blocked.
- Rules set to Disable are not evaluated at all and will not appear in the logs.
- Rules set to Log do not count towards any score thresholds, but are included in the WAF log output. This lets you continue tracking a rule’s matches until you decide whether it should be set to Block or Disable.
After you enable WAF for a site, you will be able to review the rules list and set actions on the WAF configuration page.
# Anomaly scoring and score thresholds
Each rule in the baseline ruleset has a severity level set to either Critical, Error, Warning, or Notice. These levels, in turn, have a fixed anomaly score:
| Severity Level | Anomaly Score |
|---|---|
| Critical | 5 |
| Error | 4 |
| Warning | 3 |
| Note | 2 |
For each incoming web request, Netlify WAF will complete the following in order:
Evaluate all rules with action Block or Log.
Collect all matching rules with action Block (which is the default action), and sum up the anomaly scores of these rules based on their severity. This sum is the anomaly score of this request.
For example, if a request matches one critical-level rule and two warning-level rules, the anomaly score of that request would be 5 + 3 + 3 = 11.
For a request to be blocked, its anomaly score should be equal or greater than the anomaly score threshold set in your WAF configuration.
By default, that threshold is 5. This means that a request with a single matching rule of level Critical will be blocked, while requests with a single rule match of lower severity will not.
If you find that the default threshold is too low or too high for your site, you can adjust the threshold up to 100.
Be mindful when setting high thresholds
Keep in mind that setting the threshold too high may let some malicious requests through.
# Advanced: category-specific thresholds
In some cases, by observing the logs, you will find that rules of a specific category tend to fire too often and trigger blocking. If you do not want to disable these rules, you can add category-specific thresholds to adjust the sensitivity for that category.
When category-specific thresholds are in place, a request is blocked if either the general request score threshold is met, or when matching rules in a specific category meet the category-specific threshold.
This enables you to set a high threshold for some categories (meaning, more rules and/or higher-severity rules must match), while having a lower threshold for others.
# Enable WAF
Enabling and configuring WAF for a site requires you to have a Team Owner role. Users with a Developer role on your team only have read-only access to the current WAF configuration.
# Prerequisite: configure log drains
To successfully configure WAF, you need the ability to observe which rules are matching requests. This requires setting up Log Drains.
WAF-related information is included in two log output types. Make sure you enable both:
- The site traffic log includes high-level data on WAF behavior in the
waffield. - The WAF log provides detailed information on any requests that match one or more rules.
The traffic log is useful for looking at general traffic trends — for example, what portion of requests is blocked or which country or specific IP addresses do these requests originate from. You can use this data to block offending geographic regions or IP addresses using Firewall Traffic Rules.
In contrast, the WAF log lets you pinpoint exactly which rules were matched for a request, the details of that match, the accumulated anomaly scores, and more. You can use the WAF log to fine-tune the WAF configuration.
# Enable the baseline ruleset
To enable the baseline ruleset for a site:
For your site, go to
.Under Baseline Ruleset, select Configure.
Select Enabled.
We strongly recommend you set Blocking Mode to Passive first. Then, after you fine-tune your configuration, switch to Active mode.
To confirm, select Save.
# Fine-tune your configuration
To avoid false positives (that is, requests that are legitimate but end up being blocked), there are a few settings available to you. You can:
- Set a rule’s action to only Log matches (or disable it completely)
- Exclude specific request patterns using text or regular expressions (regex)
- Modify anomaly score thresholds
All of these options are available under
after you enable the Baseline ruleset.# A typical workflow
Here is a recommended workflow to follow when you set up WAF:
When enabling the baseline ruleset, set Blocking Mode to passive. Make sure both log drain output types (traffic log and WAF log) are configured.
Then, start observing logs in the WAF log output.
- If a matching rule looks valid, keep it at its default action (Block).
- If a rule match is consistently a false positive, set it to Disable.
- If you’re not sure yet about a rule, you can defer your decision until after you’ve enabled Active blocking mode, by changing the action to Log.
You may find that you want to tweak the request score threshold, so that more rules must match before the threshold is hit. You may also want to exclude some specific paths from the WAF completely. We recommend that you observe traffic logs for a while before and after you make such changes.
When you’re ready to start blocking, switch the blocking mode to Active.
If you need to temporarily pause the WAF operation, we recommend that you switch blocking mode back to Passive instead of disabling the baseline ruleset altogether because the latter option also clears any configuration changes you’ve made.
Did you find this doc useful?
Your feedback helps us improve our docs.