Creating a custom WAF error page (2020)

  Last updated 2020-07-13

IMPORTANT

As announced, April 30, 2023 marks the formal retirement of the Fastly WAF (WAF Legacy and WAF 2020). Our Fastly Next-Gen WAF offers similar functionality. It monitors for suspicious and anomalous web traffic and protects, in real-time, against attacks directed at the applications and origin servers that you specify.

You can create a custom HTML error page that will be presented to users who are blocked by the Fastly WAF response object. The attributes of the response object include the HTTP status code, the HTTP response text, the content type, and the returned content.

For this example, we'll:

  • use a dynamic VCL snippet to create a custom req.http.x-request-id HTTP header,
  • use that header as a global variable to store the transaction ID of the request so that it can be used in both the request and WAF logs, and
  • create a synthetic response to present the user with an HTML response.

The error page will display the transaction ID, something that might be useful if, for example, the user decides to contact your support team.

Creating a dynamic VCL Snippet

To create a dynamic VCL Snippet for the transaction ID, make the following API call in a terminal application:

$ curl -X POST -s https://api.fastly.com/service/<Service ID>/version/<Editable Version Number>/snippet -H "Fastly-Key:FASTLY_API_TOKEN" -H 'Content-Type: application/x-www-form-urlencoded' --data $'name=my_dynamic_snippet_name&type=recv&dynamic=1&content=if (!req.http.x-request-id) {\n set req.http.x-request-id = digest.hash_sha256(now randomstr(64) req.http.host req.url req.http.Fastly-Client-IP server.identity);\n}'

Creating a synthetic response

To create a synthetic response for the custom HTML error page, follow the steps below:

  1. Log in to the Fastly web interface.
  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
  3. Click Edit configuration and then select the option to clone the active version.
  4. Click Content.

  5. Click Set up advanced response.

    the Create a synthetic response page

  6. Fill out the Create a synthetic response fields as follows:

    • In the Name field, enter WAF_Response.

    • From the Status menu, select 403 Forbidden.

    • In the MIME Type field, specify the Content-Type of the response (e.g., text/html).

    • In the Response field, enter the following HTML. This response will display the value of req.http.x-request-id.

      1<html>
      2  <head>
      3    <title>403 Forbidden</title>
      4  </head>
      5  <body>
      6    <p>The requested URL was rejected.</p>
      7    <p>For additional information, please contact support and provide this reference ID:</p>
      8    <p>"} req.http.x-request-id {"</p>
      9    <p><button onclick='history.back();'>Go Back</button></p>
      10  </body>
      11</html>

  7. Click Create. Your new response appears in the list of responses.

  8. Click Activate to deploy your configuration changes.

Additional notes

  • You can change the composition of the transaction ID, but care should be taken to minimize the probability that multiple requests within a specified window of time (e.g., per day) have the same transaction ID value.
  • A VCL Snippet was used to simplify the example presented and is not explicitly required for a custom WAF error page. As an alternative, you can use custom VCL to create the transaction ID.
  • It's useful to include the transaction ID in the request and WAF logging formats to allow multiple messages generated for the same request to be correlated.
Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Fastly
© Fastly 2023