Kong
DataDome Kong build detects and protects against bot activity
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:

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
...
Updated 6 months ago