AWS waf medium security documentation change

Service: waf · 2025-10-16 · Security-related medium

File: waf/latest/developerguide/customizing-the-incoming-request.md

Summary

Added security recommendation to block requests with x-amzn-waf- headers not inserted by AWS WAF, including example rule configuration

Security assessment

The change introduces a security practice to block requests where headers mimic AWS WAF's custom headers, preventing potential spoofing. The example rule explicitly blocks requests with x-amzn-waf- headers not inserted by AWS WAF, addressing a security concern.

Diff

diff --git a/waf/latest/developerguide/customizing-the-incoming-request.md b/waf/latest/developerguide/customizing-the-incoming-request.md
index 9ac6bb4f4..39f5bd4b8 100644
--- a//waf/latest/developerguide/customizing-the-incoming-request.md
+++ b//waf/latest/developerguide/customizing-the-incoming-request.md
@@ -4,0 +5,2 @@
+Considerations when using custom request header namesUsing custom headers with non-terminating rule actionsCustom request handling example
+
@@ -12,0 +15,2 @@ This section explains how to instruct AWS WAF to insert custom headers into the
+###### Important
+
@@ -15 +19,3 @@ This option applies to the rule actions Allow, Count, CAPTCHA, and Challenge and
-###### Custom request header names
+## Considerations when using custom request header names
+
+###### Prefixes added to request headers
@@ -18,0 +25,45 @@ AWS WAF prefixes all request headers that it inserts with `x-amzn-waf-`, to avoi
+###### Important
+
+As a security practice, you can add a string match rule that blocks requests where the header already starts with `x-amzn-waf-`. This blocks requests from non-AWS WAF sources that mimic the `x-amzn-waf-` prefix string that is inserted by AWS WAF when processing custom request headers.
+
+The following example shows a string match rule configured to block traffic where the `x-amzn-waf-` prefix was not inserted by AWS WAF:
+    
+    
+        "Rules": [
+            {
+              "Name": "CustomHeader",
+              "Priority": 0,
+              "Statement": {
+                "ByteMatchStatement": {
+                  "SearchString": " x-amzn-waf-",
+                  "FieldToMatch": {
+                    "Headers": {
+                      "MatchPattern": {
+                        "All": {}
+                      },
+                      "MatchScope": "KEY",
+                      "OversizeHandling": "MATCH"
+                    }
+                  },
+                  "TextTransformations": [
+                    {
+                      "Priority": 0,
+                      "Type": "NONE"
+                    }
+                  ],
+                  "PositionalConstraint": "STARTS_WITH"
+                }
+              },
+              "Action": {
+                "Block": {}
+              },
+              "VisibilityConfig": {
+                "SampledRequestsEnabled": true,
+                "CloudWatchMetricsEnabled": true,
+                "MetricName": "CustomHeader"
+              }
+            }
+          ]
+
+For information on using string match rules, see [String match rule statement](./waf-rule-statement-type-string-match.html).
+
@@ -23 +74 @@ If the request already has a header with the same name that AWS WAF is inserting
-###### Custom headers with non-terminating rule actions
+## Using custom headers with non-terminating rule actions
@@ -40 +91 @@ AWS WAF inserts custom headers into a web request when it finishes inspecting th
-###### Example custom request handling
+## Custom request handling example