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