DataDome Bot protection can be integrated directly inside Fastly.

Before the regular Fastly process starts, a preflight request is performed on the closest DataDome endpoint. Depending on the API response, the module either blocks the request or lets Fastly proceed with the regular process.

The module has been implemented to ensure the best user experience: if any errors were to occur during the preflight, or if the timeout is reached, the module will automatically disable its blocking mechanism and allow the regular Fastly process to proceed.

Prerequisites

🚧

You need to Contact Fastly support to enable some features to be able to use DataDome Bot Protection

Send an email :

• To: [email protected]
• Subject: Pragmas needed on Service XXXXXXXXXX for DataDome support

How to integrate DataDome Bot Protection inside Fastly ?

DataDome provides 3 integration options:

• A. [Recommanded] VCL snippets through the Fastly dashboard
• B. Dynamic snippets through the Fastly API
• C. Custom VCL through the Fastly dashboard

You can find the code here

A. VCL snippets through the Fastly dashboard

❗️

Before integrating DataDome, you need to ask Fastly Support to enable DataDome support for your Fastly service as described here.

1. Create a Fastly service or use an existing one, then create a new version of this service by cloning the actual one.

2. Go to VCL snippets and upload each VCL snippets provided in our module.
   1. Start with the init one. Update your own server api key (You can find it inside our dashboard) on line 5.
   2. Making sure to select the proper snippet type from the dropdown menu (recv, pass, deliver, etc..).

3. Once done, click activate to deploy Fastly configuration.

4. You are now protected by DataDome

B. Regular VCL snippets with Terraform

You need to provide Terraform with your Fastly API key.
Follow the Fastly documentation to create it.

When you have your key, you must export a FASTLY_API_KEY environment variable in the shell from where you will launch Terraform commands
export FASTLY_API_KEY=<your API key>.

Next, you can open the main.tf Terraform file and edit the following sections:

• Line 21: Input the DNS you want to use to access your service
• Line 26: Provide a DNS or an IP to your origin backend. Warning: the backend must be named origin

provider "fastly" {}

locals {
  # Define all the datadome snippet names needed here
  datadome_snippets = toset([
    "init",
    "recv",
    "pass",
    "fetch",
    "deliver",
    "miss",
    "error"
  ])
}

# Create fastly service
resource "fastly_service_v1" "main" {
  name = "datadome_protected_service"

  domain {
    name    = "fastlysnippet.datadome.co"
    comment = "Test"
  }

  backend {
    address = "datadome.co"
    name    = "origin"
    port    = 80
  }

  # This dynamic block create a `snippet` block
  # for each datadome snippet defined in the locals
  dynamic "snippet" {
    for_each = local.datadome_snippets

    content {
      type    = snippet.value
      name    = format("datadome_%s", snippet.value)
      content = file(format("%s/%s.vcl", path.module, snippet.value))
    }
  }
}

🚧

Deploying the service for the first time

If you deploy this code for the first time, Terraform will fail on the plan stage, since the service needs to be created before we can provision the snippets code.
To deploy it for the first time you should first deploy the service and then the remaining code:

• terraform apply -target fastly_service_v1.demo
• terraform apply

C. Custom VCL

1. Download the latest version of the module
2. Connect to your Fastly console, and go to the Configuration tab
3. Switch to Required Services
4. Click configuration -> clone active

6. Go to Origin -> Hosts
7. Confirm that another upstream has the name origin
8. Go to Custom VCL and click Upload your first VCL file

9. Input name, for example datadome, and upload datadome.vcl from the distribution

10. Click Create
11. Go into the file and update the code at the Edit VCL block. You must replace your Server API Key (You can find it inside our Dashboard)https://app.datadome.co/dashboard/config/protection/keys near line 48

12. Update Shield Backend Name with the actual name near line 460. If you don't use it, feel free to comment this line
13. Click the Activate button on the top-right side

Settings

The Fastly module doesn't have a dedicated block for settings and you should update them in a different location in the file.

Shielding

This only applies to custom VCL.
If you use shielding you should update the shield backend name and the region name inside the FASTLY recv. This is region specific, and the backend name depends on your use of SSL/TLS to connect to your upstream. All theses values are actual for 2020-03-04T12:12:44Z

FAQ

• Subject: Pragmas needed on Service XXXXXXXXXX for DataDome support

How to log the enriched headers?

Before any setup, please read carefully our requirements about the enriched headers.

1. Setup a real-time logging providers
2. Edit the log format. DataDome's headers are available in the req.http object. For example req.http.x-datadome-isbot.

Please, find below an example with Loggly:

{
    "timestamp":"%{begin:%Y-%m-%dT%H:%M:%S}t",
    "client_ip":"%{req.http.Fastly-Client-IP}V",
    "geo_country":"%{client.geo.country_name}V",
    "geo_city":"%{client.geo.city}V",
    "url":"%{json.escape(req.url)}V",
    "request_referer":"%{json.escape(req.http.referer)}V",
    "request_user_agent":"%{json.escape(req.http.User-Agent)}V",
    "fastly_is_edge":%{if(fastly.ff.visits_this_service == 0, "true", "false")}V,
    "response_state":"%{json.escape(fastly_info.state)}V",
    "response_status":%{resp.status}V,
    "response_reason":%{if(resp.response, "%22"+json.escape(resp.response)+"%22", "null")}V,
    "response_body_size":%{resp.body_bytes_written}V,
    "request_method":"%{json.escape(req.method)}V",
    "request_protocol":"%{json.escape(req.proto)}V",
    "fastly_server":"%{json.escape(server.identity)}V",
    "host":"%{if(req.http.Fastly-Orig-Host, req.http.Fastly-Orig-Host, req.http.Host)}V",
    "datadome-isbot":"%{json.escape(req.http.x-datadome-isbot)}V",
    "datadome-botname":"%{json.escape(req.http.x-datadome-botname)}V",
    "datadome-ruletype":"%{json.escape(req.http.x-datadome-ruletype)}V",
     "datadome-captchapassed":"%{json.escape(req.http.x-datadome-captchapassed)}V"
   }

POST requests with a body are broken

You should ask Fastly Support to enable DataDome support for your Fastly service as described here.

How to integrate DataDome Bot Protection with Signal Sciences WAF

Both integrations can work together with a configuration change on the custom VCL's miss and pass subroutine snippets.

The call to edge_security that triggers Signal Sciences should only be done when the request is not being handled by DataDome, meaning that any call edge_security line should be replaced with the following piece of code:

  if (req.backend != datadome) {
    call edge_security;
  }

Find below an example of how the generated final VCL should look like in the miss and pass subroutine snippets:

sub vcl_miss {
	#--FASTLY MISS BEGIN
	[...]
  if (req.backend != datadome) {
  	call edge_security;
  }
# Snippet datadome_miss : 100

# Start of `miss.vcl` for DataDome-2.19.0
call set_origin_header;
# End of `miss.vcl` for DataDome-2.19.0

#--FASTLY MISS END
  return(fetch);
}

sub vcl_pass {
#--FASTLY PASS BEGIN
  [...]
  if (req.backend != datadome) {
    call edge_security;
  }
# Snippet datadome_pass : 100

# Start of `pass.vcl` for DataDome-2.19.0
call set_origin_header;
# End of `pass.vcl` for DataDome-2.19.0

#--FASTLY PASS END
}