Kong

This page documents an inbound integration with your Kong API Gateway.

We currently support both Kong OS and Kong Enterprise deployments by the use of a custom plugin. This plugin may be attached to either a Service or a Route within your system, we do not currently support protection of Consumers.

Install the Spherical Defense plugin

To install the custom Spherical Defense plugin, we need to be inside your Kong docker container. Our plugin is hosted on the official Luarocks package manager and can easily be installed. Afterwards Kong must be restarted with the plugin enabled.

## get into the kong docker container
docker exec -u root -it <DOCKER_CONTAINER_NAME> sh
## install spherical defense (note the luarocks package name!)
luarocks install sphericaldefence
export KONG_PLUGINS=sphericaldefence,$KONG_PLUGINS
## restart kong
kong prepare
kong reload

Adding to your Kong deployment

Our plugin can be added to either a Route or Service. This can be done either via the Kong Enterprise GUI or if using Kong through curl commands, all that is required is the knowledge of the exposed IP address for your Spherical Defence Instance SPHERICAL_DEFENCE_IP. Below we list an example of either curl command to add the plugin to your services:

Adding to a Service

Adding a plugin to service is easy. All you need is the exposed IP address KONG for the container and the name of the SERVICEyou send the following command. Note, that Kong defaults the port to 8001 to be open.

$curl --request POST \
--url http://{KONG IP}:8001/services/{SERVICE}/plugins \
--form name=sphericaldefence \
--form config.url=http://{SPHERICAL_DEFENCE_IP} \
--form config.blocking=false \
--form config.timeout=10000 \
--form config.keepalive=60000

Adding to a Route

To add a plugin to a route, we require both the exposed IP address KONG for the container and name of the ROUTE

$curl --request POST \
--url http://{KONG IP}:8001/routes/{ROUTE}/plugins \
--form name=sphericaldefence \
--form config.url=http://{SPHERICAL_DEFENCE_IP} \
--form config.blocking=false \
--form config.timeout=10000 \
--form config.keepalive=60000

Additional Documentation

Below we've listed the parameters associated with the plugin:

form parameter

default

description

name

spherical_defence

The name of the plugin in use

config.url

The address of a Spherical Defence instance to which the plugin will validate before proxying the original request (required)

config.blocking

False

Whether malicious requests should be blocked from moving through to the service/route

config.timeout

10000

Timeout (milliseconds) for the request to the URL specified above.

config.keepalive

60000

Keepalive time (milliseconds) for the request to the URL specified above.

The plugin will execute a JSON POST request to the Spherical instance with the following body:

Form Parameter

Description

body_data

The body of the original request

url_args

The url arguments of the original request

headers

The headers of the original request

uri

The uri of the original request

method

The method of the original request