Before the regular Kong process, the module makes a call to the DataDome API using a keep-alive connection.

Depending on the API response, the module will either block the query or let Nginx continue the regular process.
The module has been developed to protect user experience. In the event an error occurs during the process or if the timeout is reached, the module would automatically disable its blocking mechanism and fail open.

This module is based on the Nginx C module version, and it requires compiling a custom Kong image.

Compatibility

This module is compatible with Nginx >= 1.5.4.
The following documentation has been tested with Kong 3.1.0 and LuaJIT 2.1.0

How to build your Kong image

Prerequisite

apt-get install build-essential zlib1g-dev git

yum install @development-tools zlib zlib-devel git

Prepare the image

Clone the Kong repository

git clone https://github.com/Kong/kong.git

In the same parent directory, clone the Kong build tools

git clone https://github.com/Kong/kong-build-tools.git
cd kong-build-tools

In the kong-build-tools directory, download and extract DataDome Nginx module

wget https://package.datadome.co/linux/DataDome-Nginx-latest.tgz
tar -zxvf DataDome-Nginx-latest.tgz

Modify the Docker file dockerfiles/Dockerfile.openresty
Add COPY DataDome-NginxDome-* /tmp/DataDome-NginxDome to include the source of DataDome NGINX module to OpenResty Docker image

COPY kong-licensing /enterprise/kong-licensing
 COPY lua-kong-nginx-module /enterprise/lua-kong-nginx-module
 COPY lua-resty-lmdb /enterprise/lua-resty-lmdb

 # Add following 1 line
 COPY DataDome-NginxDome-* /tmp/DataDome-NginxDome
 
 ARG DEBUG=0
 RUN DEBUG="${DEBUG}" /tmp/build-openresty.sh \
     && rm -rf /work
 ...

In the kong-build-tools directory, modify the shell file build-openresty.sh
Add --add-module /tmp/DataDome-NginxDome argument to the command kong-ngx-build

/tmp/openresty-build-tools/kong-ngx-build -p /tmp/build/usr/local \
--openresty $RESTY_VERSION \
--openssl $RESTY_OPENSSL_VERSION \
--luarocks $RESTY_LUAROCKS_VERSION \
--kong-nginx-module $KONG_NGINX_MODULE \
--pcre $RESTY_PCRE_VERSION \
# Add the following 1 line
--add-module /tmp/DataDome-NginxDome \
--work /work $KONG_NGX_BUILD_ARGS >> $BUILD_OUTPUT 2>&1

In the kong-build-tools directory, build the Kong package with the following command.

# defaults if not set, change it if needed
# export PACKAGE_TYPE=deb RESTY_IMAGE_BASE=ubuntu RESTY_IMAGE_TAG=20.04 

export CACHE=false
sudo make package-kong

Note: If you need to compile another package than a deb one, you should use export PACKAGE_TYPE=dev|rpm|apk before the previous lines

The final package will be saved to the directory kong-build-tools/output.

Run custom Kong package

We now have the custom Kong package with a built-in DataDome NGINX module. The next step is to configure Kong to run in your preferred environment.

Prepare your Kong configuration

Create the following folder and files:

213 — Demo example with configuration files

The declarative/kong.yml contains information about your services and routes. For example

_format_version: "2.1"
_transform: true

services:
  - name: my-service
    protocol: https
    port: 443
    host: datadome.co
    path: /anything
    routes:
      - name: my-route
        paths:
          - /

Next, add the following code into nginx/datadome-http.conf.

resolver 8.8.8.8;

upstream datadome {
    dd_server api.datadome.co:443;
    keepalive 10;
}


# Globally disable DataDome
# set $is_datadome_enabled off;

# Globally enable DataDome
# set $is_datadome_enabled @datadome

# (Optional) Selectively enable or disable DataDome on hostname(s)
# http://nginx.org/en/docs/http/ngx_http_map_module.html
map $http_host $is_datadome_enabled {
    default '@datadome';
    www.example.com 'off';
}

# (Optional) Increase the variables_hash_bucket_size from the default of 64
# http://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_bucket_size
# variables_hash_bucket_size 128;

And do the same with nginx/datadome-proxy.conf. Don't forget to add your server-side key.

data_dome_auth $is_datadome_enabled;
data_dome_auth_set $datadome_status $upstream_status;
# Checking path against exclusion first, then inclusion. Both are optional.
# data_dome_auth_uri_regex_exclusion "^\/1";
# data_dome_auth_uri_regex "\/2";

location = @datadome {
    data_dome_shield_key "YOUR_DATADOME_KEY";
    proxy_pass https://datadome/validate-request/;
    proxy_method POST;
    proxy_http_version 1.1;
    proxy_set_header Connection "keep-alive";
    proxy_set_header Content-Type "application/x-www-form-urlencoded";
    proxy_set_body $data_dome_request_body;
    proxy_ignore_client_abort on;
    proxy_connect_timeout 150ms;
    proxy_read_timeout 50ms;
}

Run on OS

Install custom Kong Package

First, install the custom Kong package into your system

sudo dpkg -i kong-build-tools/output/kong-*.deb

# Test Kong installation
kong version -a

sudo rpm -i kong-build-tools/output/kong-*.rpm

# Test Kong installation
kong version -a

(Optional) Route on Kong

If there is not any existing route on Kong, create one using Kong's DB-less / declarative configuration.

export KONG_DATABASE=off
export KONG_DECLARATIVE_CONFIG=$(pwd)/declarative/kong.yml

Inject Nginx configuration

# Injection to the NGINX Server block 
export KONG_NGINX_PROXY_INCLUDE=$(pwd)/nginx/datadome-proxy.conf

# Injection to the NGINX HTTP block 
export KONG_NGINX_HTTP_INCLUDE=$(pwd)/nginx/datadome-http.conf

Run Kong

# Cleanup the Kong prefix directory
rm -rf $(pwd)/kong
 
# Use kong start -c kong.conf ... if a config file is used.
kong start -p $(pwd)/kong --vv

Run on docker

Build a custom Kong image

Building a custom Kong docker image using the Kong package generated from the build steps earlier.

# Use a Dockerfile and docker-entrypoint.sh forked from the official image
git clone [email protected]:Kong/docker-kong.git
cd docker-kong

# Copy the kong package built in the previous steps
# Must rename the built kong pkg to kong.deb
cp ../kong-build-tools/output/kong-*.deb ubuntu/ && mv ubuntu/kong-*.deb ubuntu/kong.deb
docker build ubuntu/ -t test/kong:ubuntu --build-arg ASSET=local

Run the container

docker run --rm --name kong-datadome-demo \
    -v "$(pwd):/etc/datadome" \
    -e "KONG_DATABASE=off" \
    -e "KONG_DECLARATIVE_CONFIG=/etc/datadome/declarative/kong.yml" \
    -e "KONG_NGINX_PROXY_INCLUDE=/etc/datadome/nginx/datadome-proxy.conf" \
    -e "KONG_NGINX_HTTP_INCLUDE=/etc/datadome/nginx/datadome-http.conf" \
        -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
    -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
    -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
    -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
    -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
    -p 8000:8000 \
    -p 127.0.0.1:8001:8001 \
    test/kong:ubuntu

Tests

In order to ensure Datadome is running properly on your Kong image, you can run the desire following command

# Find a configured route
curl -s  http://localhost:8001/routes

# Test the route
curl -I http://localhost:8000

In the response header, you should be able to see:

HTTP/1.1 200 OK
...
X-DataDome: protected
...