Configuring DoS Protection Service

The App Engine Denial of Service (DoS) protection service enables you to protect your application from running out of quota when subjected to denial of service attacks or similar forms of abuse. You can add IP addresses or subnets to a denylist, and requests routed from those addresses or subnets will be dropped before your application code is called. No resource allocations, billed or otherwise, are consumed for these requests.

By default, App Engine serves a generic error page to addresses on the denylist. You can configure your app to serve a custom response instead.

Before you begin

Create a dos.yaml file in the root directory of your application. You will specify your denylisted IP addresses and networks in this file.

Blocking requests with DoS denylists

You can add IP addresses and IP subnets to a denylist to block them from accessing your app.

The dos.yaml is limited to 100 entries, so blocking entire subnets might be necessary if you are facing a DoS attack. This is also an efficient way to protect yourself if you find that multiple IP addresses from the same network are part of a DoS attack on your app.

Creating denylist entries for IP addresses

You can block one or more IP addresses from accessing your app by defining those IPv4 or IPv6 addresses in your dos.yaml file. For example:

blacklist:
- subnet: 192.0.2.1
  description: A single IPv4 address
- subnet: abcd::123:4567
  description: A single IPv6 address

In a distributed denial of service (DDoS) attack, you will likely need to block entire subnets rather than by individual IP address.

See the Example below to help you create your dos.yaml.

After creating your dos.yaml, you must upload it to your app.

Creating denylist entries for IP subnets

You can block an IP subnet from accessing your app by defining the IP subnet in CIDR format. You can use the IP to CIDR tool to help with creating rules that use CIDR notation.

blacklist:
- subnet: 1.2.3.4/24
  description: an IPv4 subnet
- subnet: abcd::123:4567/48
  description: an IPv6 subnet

See the Example below to help you create your dos.yaml.

After creating your dos.yaml, you must upload it to your app.

Example dos.yaml

The following is an example dos.yaml file:

blacklist:
- subnet: 1.2.3.4
  description: a single IP address
- subnet: 1.2.3.4/24
  description: an IPv4 subnet
- subnet: abcd::123:4567
  description: an IPv6 address
- subnet: abcd::123:4567/48
  description: an IPv6 subnet

Creating custom error messages for denylisted requests

By default, a generic error page is served to requests that are blocked by the DoS protection service. Distributed denial of service attacks could involve an infected machine from a legitimate user and this page could provide an explanation for those users about why their access was denied.

  1. Create a static file in your application directory for serving to requests that are blocked by the DoS protection service.

  2. In your app.yaml file, specify an error handler for DoS responses by providing the path to your static file and adding the error_handlers type of dos_api_denial: 

    error_handlers:
- error_code: dos_api_denial
  file: dos-response.html

Deleting all denylist entries

To delete all denylist entries:

  1. Edit the dos.yaml file to just contain:

    blacklist:

    Deleting the dos.yaml does not remove the denylists.

  2. Redeploy your dos.yaml for the changes to take effect.

Viewing DoS denial errors in the console

You can view a graph of the number of requests that are being denied:

  1. Go to the App Engine dashboard in the Google Cloud Console:

    Open the App Engine error details graph

  2. Adjust the graph time frame as necessary to see the results.

Upload your DoS denylist

You use the gcloud tool to deploy the updated DoS configuration file to your app in App Engine. For example, you run the following command to update the DoS Protection Service with the contents of dos.yaml:

 gcloud app deploy dos.yaml

What's next