Configuring DoS Protection Service for Java

Python |Java |PHP |Go

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 blacklist IP addresses or subnets, 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.

Before you begin

Create a dos.xml file in the WEB-INF directory of your application. You will specify your blacklisted IP addresses and networks in this file.

Defining blacklists of IP addresses for your App Engine app

To specify a single IP address should be blocked from you can add an IP address in either IPv4 or IPv6 format:

<?xml version="1.0" encoding="UTF-8"?>
<blacklistentries>
  <blacklist>
    <subnet>1.2.3.4</subnet>
    <description>a single IP address</description>
  </blacklist>
  <blacklist>
    <subnet>abcd::123:4567</subnet>
    <description>an IPv6 address</description>
  </blacklist>
</blacklistentries>

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

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

Defining blacklists of IP subnets for your App Engine app

The dos.xml is limited to 100 entries, so blocking entire subnets might be necessary if you are facing a DDoS 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.

The IP subnets are specified in CIDR format. The IP to CIDR tool can help you define your CIDR notation for ranges of IP addresses.

<?xml version="1.0" encoding="UTF-8"?>
<blacklistentries>
  <blacklist>
    <subnet>abcd::123:4567/48</subnet>
    <description>an IPv6 subnet</description>
  </blacklist
  <blacklist>
    <subnet>abcd::123:4567/48</subnet>
    <description>an IPv6 subnet</description>
  </blacklist
</blacklistentries>

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

Creating custom error messages for blacklisted 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 explanation for 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 appengine-web.xml file, specify an error handler for DoS responses by providing the path to your static file and adding the <static-error-handlers> type of dos_api_denial:

    <static-error-handlers>
      <handler error-code="dos_api_denial" file="dos-response.html" />
    </static-error-handlers>
    

Deleting all blacklist entries

To delete all blacklist entries, change the dos.xml file to just contain:

<?xml version="1.0" encoding="UTF-8"?>
<blacklistentries/>

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 Platform Console:

    Open the App Engine error details graph

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

Upload your DOS blacklist

You can use AppCfg to upload DoS configs. When you upload your application to App Engine using AppCfg update, the DoS Protection Service is updated with the contents of dos.xml.

To update just the DoS configuration without uploading the rest of the application use the following command:

AppCfg update_dos <directory>

What's next

Send feedback about...

App Engine standard environment for Java