WAF Policy Review¶
Reviewer runbook for pull requests that change a web application firewall (WAF) policy of the Application Gateway: a custom rule, a managed rule override, an exclusion or a disabled rule. The policy files and their effects are in Application Gateway. The deployment is the same as for the gateway (Application Gateway deployment).
What a WAF policy change is¶
A WAF in prevention mode blocks requests that match its managed rules. A WAF policy change normally has one of these reasons:
| Reason | Example |
|---|---|
| A false positive: a legitimate request is blocked | A request with many special characters in one argument. |
| A new protection | A custom rule that blocks a source or a pattern. |
| A new policy for a workload | A separate policy for one listener or path. |
Each policy is a file web_application_firewall_policy_<name>.json in <region>/web_application_firewall_policies/.
1. Open the pull request and check its state¶
Open the ticket, follow the link to the pull request, and do the checks of Pull request review: not a draft, the validation pipeline is green, no merge conflicts, all comments resolved, a ticket linked. If one fails, send the pull request back.
2. Check the evidence¶
A change that disables or excludes a rule needs evidence in the ticket:
| Evidence | Why |
|---|---|
| The blocked request: URI, the name of the argument or header, the rule ID from the WAF log | Shows which rule to look at. |
| Why it is a false positive | Without it the exception is a guess. |
| The approval of security | An exception lowers protection. |
| The end of the exception, or a review date | Exceptions should not live forever. |
3. Check the file¶
For each file in the pull request:
| Check | Why |
|---|---|
| The change is the narrowest that solves the problem: an exclusion for one argument rather than disabling a rule | Keeps the rest of the protection. |
| The rule IDs are the ones from the log | A wrong ID leaves the false positive in place. |
The file name follows web_application_firewall_policy_<name>.json and it is in the right region folder |
The file is found by this pattern. |
| The JSON matches the WAF policy schema | The config tests use it. |
The policy that is referenced from a gateway, listener or path exists, with a correct firewall_policy_id |
A wrong ID makes the gateway change fail. |
| Custom rules: unique priorities, a clear match condition, a correct action | A broad custom rule can block real users. |
The change is in canary and in prod, or the description says why only in prod |
Canary is the place to test. |
| The list of exclusions and disabled rules is updated, with the rationale | You need it to review them later. |
policy_settings are applied only when the policy is created
The module ignores later changes of policy_settings (for example the mode Detection or Prevention, and the body
size limits), because Azure Policy changes them as well. A pull request that only changes these settings has no
effect on an existing policy. Custom rules and managed rule overrides are updated. Ask the author how the setting will
be changed (in the portal, with a record of the change, or with a new policy). See
WAF policy for the workload.
Test the effect
Enabling an extra WAF setting, such as inspection of the request body, without a test can block legitimate requests
(users see 403). Ask for a test on canary, and check the WAF log after the deployment
(Known issues).
4. Final review¶
- Everything is in order: approve the pull request, and deploy (Application Gateway deployment).
The layer is
connectivity. - Something is wrong: comment, put the ticket back to New and assign it to the author.
After the deployment, ask the requester to repeat the request that was blocked, and check that it passes. Look at the WAF log for the rule ID to see whether it still matches.