
Build a False-Positive reporting experience with AWS WAF
Learn how to build a user-friendly false-positive reporting mechanism with AWS WAF. Using managed rule labels, custom responses, dynamic label interpolation, and AWS WAF CAPTCHA, you can provide users with useful request details and a secure way to report legitimate requests that were incorrectly blocked, making it easier for security teams to investigate and resolve false positives.
AWS WAF managed rules provide strong protection against common web attacks, but they can occasionally block legitimate requests. In this article, I’ll show you how to build a user-friendly false-positive reporting mechanism that allows users to report when AWS WAF incorrectly blocks their request.
For example, a geo-blocking rule might incorrectly classify the country associated with a user's IP address, or a legitimate input might happen to match a pattern identified as a potential SQL injection by a managed rule.
The challenge
Let's use the AWSManagedRulesSQLiRuleSet managed rule as an example. The SQL database rule group contains rules designed to block request patterns associated with attacks against SQL databases, including SQL injection. This helps protect applications against attempts to inject unauthorized SQL queries.
When AWS WAF blocks a request, the default behavior is to return a generic error response:

While this is functional, it isn't necessarily the best user experience. Instead, you may want to return a custom error page that:
- Matches your application's branding
- Explains why the request was blocked
- Provides useful information for troubleshooting
- Allows the user to report a potential false positive
This is where AWS WAF labels and dynamic label interpolation become particularly useful.
Step 1: Change the managed rule action to Count
The first step is to change the action of the relevant managed rule from
Block to Count . This allows the managed rule to inspect the request and emit its associated label without immediately terminating the request.When configuring the managed rule, take note of the label namespace generated by the rule group. For the SQL database managed rule group, the namespace is:
awswaf:managed:aws:sql-database: . We can use this label namespace in a subsequent custom rule.
Step 2: Create a custom rule based on the managed-rule label
Next, create a custom AWS WAF rule that matches requests carrying a label from the SQL database managed rule group. The rule can use the label namespace:
awswaf:managed:aws:sql-database: . When the rule matches, instead of returning the default AWS WAF response, configure it to return a custom 403 response with your own response body, giving you complete control over the user experience.
Step 3: Create the custom response body
The custom response body can contain a branded error page explaining that the request was blocked and providing a way for the user to report a potential false positive.
AWS WAF currently limits custom response bodies to 4 KB, so the HTML needs to be kept relatively small. For that reason, I used a compressed version of the HTML in the AWS WAF configuration. Here is the uncompressed version:
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="robots" content="noindex, nofollow"><title>Access blocked</title><style> :root { --paper: #FAFAF7; --ink: #1C1F26; --ink-soft: #5B6270; --line: #E3E1DA; --rust: #B5451B; --rust-soft: #F4E4DB; --ok: #2F6E4E; --ok-soft: #E3EEE7; --mono: "IBM Plex Mono", "SFMono-Regular", Consolas, monospace; --sans: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", sans-serif; }
* { box-sizing: border-box; }
body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: var(--paper); color: var(--ink); font-family: var(--sans); padding: 24px; }
.card { width: 100%; max-width: 460px; }
.mark { display: flex; align-items: center; gap: 10px; margin-bottom: 28px; }
.mark svg { flex-shrink: 0; }
.mark span { font-family: var(--mono); font-size: 12px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--ink-soft); }
h1 { font-size: 26px; font-weight: 600; letter-spacing: -0.01em; margin: 0 0 12px; }
p.lede { font-size: 15px; line-height: 1.55; color: var(--ink-soft); margin: 0 0 28px; }
/* signature element: a log-style tick divider, nodding to request logs */ .ticks { display: flex; gap: 3px; margin: 0 0 28px; } .ticks i { display: block; width: 3px; height: 14px; background: var(--line); } .ticks i:nth-child(4n) { background: var(--rust); height: 18px; }
dl.meta { margin: 0 0 28px; border-top: 1px solid var(--line); }
dl.meta > div { display: flex; justify-content: space-between; align-items: baseline; gap: 16px; padding: 12px 0; border-bottom: 1px solid var(--line); }
dl.meta dt { font-size: 13px; color: var(--ink-soft); }
dl.meta dd { margin: 0; font-family: var(--mono); font-size: 13px; text-align: right; word-break: break-all; }
.actions { display: flex; flex-direction: column; gap: 12px; }
button.report { appearance: none; border: 1px solid var(--ink); background: var(--ink); color: var(--paper); font-family: var(--sans); font-size: 14px; font-weight: 600; padding: 12px 18px; border-radius: 3px; cursor: pointer; transition: opacity 0.15s ease; }
button.report:hover { opacity: 0.85; } button.report:focus-visible { outline: 2px solid var(--rust); outline-offset: 2px; } button.report[disabled] { opacity: 0.45; cursor: default; }
#captcha-wrap { display: none; margin-top: 20px; }
#captcha-wrap.open { display: block; }
#captcha-container { min-height: 80px; }
.status { display: none; margin-top: 14px; padding: 12px 14px; border-radius: 3px; font-size: 13px; line-height: 1.5; }
.status.show { display: block; } .status.ok { background: var(--ok-soft); color: var(--ok); } .status.err { background: var(--rust-soft); color: var(--rust); }
footer { margin-top: 32px; font-size: 12px; color: var(--ink-soft); }
@media (prefers-reduced-motion: reduce) { button.report { transition: none; } }</style></head><body>
<div class="card"> <div class="mark"> <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="var(--rust)" stroke-width="1.6"> <path d="M12 2 3 6v6c0 5 3.8 8.7 9 10 5.2-1.3 9-5 9-10V6l-9-4Z"/> </svg> <span>Request blocked</span> </div>
<h1>This request was blocked</h1> <p class="lede"> A firewall rule flagged this request as potentially unsafe. If you believe this is a mistake, you can report it below — solving a quick challenge helps us verify you're human and speeds up the review. </p>
<div class="ticks" aria-hidden="true"> <i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i><i></i> </div>
<dl class="meta"> <div> <dt>Your IP address</dt> <dd id="meta-ip">${awswaf:ip:}</dd> </div> <div> <dt>Request ID</dt> <dd id="meta-request-id">${awswaf:request_id:}</dd> </div> <div> <dt>JA$ fingerprint</dt> <dd id="meta-ja4">${awswaf:ja4:}}</dd> </div> </dl>
<div class="actions"> <button type="button" class="report" id="report-btn">Report a false positive</button> </div>
<div id="captcha-wrap"> <div id="captcha-container"></div> </div>
<div class="status" id="status"></div>
<footer>Reference this Request ID if you contact support.</footer></div>
<script type="text/javascript" src="https://6622021d89a5.edge.captcha-sdk.awswaf.com/6622021d89a5/jsapi.js" defer></script>
<script>(function () { // ---- Configuration placeholders — replace before deploying ---- var CAPTCHA_API_KEY = "VSXE/X68MhA7sA/QmtnlPN8YzpiXZlVvy9087Y4x9wR2m4yxfvyPmS0OuMLTu35Ey1sUfEXVVQJMRlMhxJ2VM01r4kwRLAzn4WkbqRdRWnnr5szwrKotBTwFDOb0ieY5yJALrXyIUNZIIc363Dn3sd8VC0mH+gIZj30aSkzBaZonEE7NF2JvW+WlbRbAkvbEB3kvC+LndEenWkbRZMdDKgLKw7N++kmGOh42VAv0gKUDjdjZ+dA52s2RNKRZOavLlhR7Dw3oMXm0/sFfWGXc/rDOV0BJDd9RpCAAbQD0R8N4Ok5PipgDaHNnzqr8g9op6HBIYTi/w4/2sBCQDOXI5tBpSuIdoHfB/2W2PCHuR5unojDaZzp6gZTgs3ptXmO/pJRDmwSFbxz7fD8wjrkH5iTB/a1kbzQRofySmK1ml5l/RkYPX0LDG6dbp6IuVsUX5tsthzu2Vs3+c4SyUK0jHIjz0feItxQiGKTZPZ6Zh26kot0CDs7It+BduCGYjJqXGpti0omxYDtrbcni2nOCFAvywdXVDzdIYOPlegzAyYX5pReZtf5JRK79UUy2YXEwHr2hrRw8B5HoeW0mscphkghQAocsx76skgdw1HHFa09ldvdj+J0FMYPhFy/SFlBKs60YkWpJdiLEMFZYkKiHUxD+YqymEFmMS6AOWC9mi1E=_1_1"; // encrypted API key from AWS WAF var REPORT_ENDPOINT = "https://www.achrafsouk.com/report"; // your backend URL that receives the report
function renderCaptcha() { if (typeof AwsWafCaptcha === "undefined") { showStatus("err", "The verification widget didn't load. Please refresh and try again."); return; }
AwsWafCaptcha.renderCaptcha(captchaContainer, { apiKey: CAPTCHA_API_KEY, onSuccess: function (wafToken) { showStatus("ok", "Verified. Submitting your report…"); submitReport(wafToken); }, onError: function (error) { showStatus("err", "Verification failed. Please try the challenge again."); } }); }
function submitReport(wafToken) { var payload = { requestId: document.getElementById("meta-request-id").textContent, ip: document.getElementById("meta-ip").textContent, ja4: document.getElementById("meta-ja4").textContent, wafToken: wafToken };
fetch(REPORT_ENDPOINT, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) }) .then(function (res) { if (!res.ok) throw new Error("Request failed: " + res.status); showStatus("ok", "Thanks — your report was submitted. Our team will review it shortly."); reportBtn.setAttribute("disabled", "disabled"); }) .catch(function () { showStatus("err", "We verified you, but the report didn't submit. Please try again shortly."); }); }
reportBtn.addEventListener("click", function () { reportBtn.setAttribute("disabled", "disabled"); captchaWrap.classList.add("open"); renderCaptcha(); });
var reportBtn = document.getElementById("report-btn"); var captchaWrap = document.getElementById("captcha-wrap"); var captchaContainer = document.getElementById("captcha-container"); var statusEl = document.getElementById("status");
function showStatus(kind, message) { statusEl.textContent = message; statusEl.className = "status show " + kind; }r})();</script>
</body></html>Let's break down the important parts.
I - Using dynamic AWS WAF values
The page can display useful information about the request, such as:
- Request ID
- Client IP address
- JA4 fingerprint
- Detected country
- Matched WAF labels
This is possible thanks to AWS WAF's dynamic label interpolation capability. For example:
${awswaf:request_id:} is dynamically replaced by AWS WAF with the actual request ID. This is particularly useful because the request ID gives you a direct way to correlate the user's report with the corresponding AWS WAF logs.You can learn more about this capability in AWS's documentation and blog post on dynamic label interpolation .
<dl class="meta"> <div> <dt>Your IP address</dt> <dd id="meta-ip">${awswaf:ip:}</dd> </div> <div> <dt>Request ID</dt> <dd id="meta-request-id">${awswaf:request_id:}</dd> </div> <div> <dt>JA$ fingerprint</dt> <dd id="meta-ja4">${awswaf:ja4:}/dd> </div> </dl>II - "Report false positive" button
The custom error page includes a Submit report button. The button calls a JavaScript function that sends a report to a predefined endpoint on your application. The report should contain, at a minimum, the AWS WAF request ID, with which you can correlate the report with your AWS WAF logs and investigate exactly why the request was blocked.
For example, the report could contain: Request ID, Client IP, JA4 fingerprint, Timestamp, the URL that was requested, and optionally, the user's contact information with any additional information the user wants to provide.
III - Protecting the reporting endpoint
There is an important security consideration here. You don't want someone to automate thousands or millions of requests to your false-positive reporting endpoint. For that reason, the report submission endpoint should itself be protected.
In this example, I use AWS WAF CAPTCHA. The button doesn't directly submit the report. Instead, it calls a
renderCaptcha() function, which uses the AWS WAF CAPTCHA SDK to present a CAPTCHA challenge to the user before submitting the report. To enable the CAPTCHA SDK:- The page needs to load the AWS WAF CAPTCHA SDK:
<script type="text/javascript" src="https://6622021d89a5.edge.captcha-sdk.awswaf.com/6622021d89a5/jsapi.js" defer></script> - Configure the CAPTCHA API key in the HTML. You have to create key in advance in the AWS WAF Console:
var CAPTCHA_API_KEY = "VSXE/X68MhA7sA/QmtnlPN8YzpiXZlVvy908..." Step 4: Protect the reporting endpoint with AWS WAF
Finally, create an AWS WAF rule that matches the reporting endpoint on your domain and configure the rule to return a CAPTCHA action.
This gives you two layers of protection:
- The client-side CAPTCHA challenge prevents normal users from submitting reports without completing the challenge.
- The server-side AWS WAF rule ensures that requests reaching the reporting endpoint are subject to AWS WAF enforcement.
This is important because anything implemented in JavaScript on the client can potentially be bypassed.
Example
Here's what happens when I include an SQL injection pattern in the query parameters:
?d=' OR '1'='1 
Instead of receiving the standard AWS WAF block page, the user receives the custom error page with the relevant request information and an option to report the block as a potential false positive. This approach turns what would otherwise be a frustrating "403 Forbidden" experience into a useful feedback mechanism between your application and its users.
More importantly, it gives your security team the information needed to investigate false positives without requiring the user to describe exactly what happened or provide screenshots.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article