Wallarm Connector for Kong API Gateway¶

To secure APIs managed by a standalone Kong API Gateway, Wallarm provides a connector implemented as a Lua plugin.

This document describes how to install and configure the Wallarm connector using a Docker-based setup. If your Kong environment is deployed in another way (e.g., as a system package or standalone binary), you may adapt the same steps accordingly.

The Wallarm connector for standalone Kong API Gateway supports both synchronous (in-line) and asynchronous (out‑of‑band) traffic analysis.

Use cases¶

This solution is recommended for securing APIs managed by a standalone Kong API Gateway.

It is suitable for environments where Kong is not deployed through Kubernetes (i.e., no Kong Ingress Controller is used). For this case, you can use the connector for the Kong Ingress Controller.

Limitations¶

• This setup allows fine-tuning Wallarm only via the Wallarm Console UI.

• Custom blocking page and code setup is not supported in this implementation as it requires file-based configuration.

Requirements¶

Before deploying the connector, make sure the following requirements are met:

• A running Kong API Gateway environment with:

  • Admin API enabled and accessible (typically on port 8001)
  • Proxy interface exposed to accept client traffic (typically on port 8000)

• Docker and Docker Compose installed on the host

• Access to https://us1.api.wallarm.com (US Wallarm Cloud) or to https://api.wallarm.com (EU Wallarm Cloud)

• Access to the IP addresses and their corresponding hostnames (if any) listed below. This is needed for downloading updates to attack detection rules, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers

  US CloudEU Cloud

  node-data0.us1.wallarm.com - 34.96.64.17
  node-data1.us1.wallarm.com - 34.110.183.149
  us1.api.wallarm.com - 35.235.66.155
  34.102.90.100
  34.94.156.115
  35.235.115.105
  

  node-data1.eu1.wallarm.com - 34.160.38.183
  node-data0.eu1.wallarm.com - 34.144.227.90
  api.wallarm.com - 34.90.110.226
  

• Administrator access to Wallarm Console for US Cloud or EU Cloud

• A trusted SSL/TLS certificate is required for the Node instance domain. Self-signed certificates are not yet supported.

Deployment¶

1. Deploy a Wallarm Native Node¶

The Wallarm node is a core component of the Wallarm platform that you need to deploy. It inspects incoming traffic, detects malicious activities, and can be configured to mitigate threats.

You can deploy it either hosted by Wallarm or in your own infrastructure, depending on the level of control you require.

2. Prepare the Wallarm Lua plugin¶

1. Contact support@wallarm.com to obtain the Wallarm Lua plugin files.

2. Create a working directory and add the plugin code:

   mkdir kong-wallarm
   cd kong-wallarm
   mkdir wallarm-plugin
   

3. Place the handler.lua and schema.lua files provided by Wallarm into the wallarm-plugin/ directory.

3. Build a Kong image with the Wallarm plugin¶

1. Create a Dockerfile in the kong-wallarm/ directory with the following content:

   FROM kong:latest
   
   # Copy Wallarm Lua plugin into Kong plugin directory
   COPY . /usr/local/share/lua/5.1/kong/plugins/wallarm-plugin
   
   # Enable the plugin
   ENV KONG_PLUGINS="bundled,wallarm-plugin"
   

2. Your project structure should now look as follows:

   kong-wallarm/
   ├── Dockerfile
   ├── wallarm-plugin/
   │ ├── handler.lua
   │ └── schema.lua
   

3. Build and restart Kong Gateway with the new image (or update your deployment pipeline accordingly):

   docker build -t kong-with-wallarm .
   docker stop kong && docker rm kong
   docker run -d --name kong \
     -p 8000:8000 -p 8001:8001 -p 8443:8443 \
     -e KONG_DATABASE=postgres \
     -e KONG_PG_HOST=db \
     -e KONG_PG_USER=kong \
     -e KONG_PG_PASSWORD=kong \
     -e KONG_PLUGINS="bundled,wallarm-plugin" \
     kong-with-wallarm
   

You can also copy the plugin into an existing Kong container and restart it, but rebuilding an image ensures persistence across restarts and upgrades.

4. Enable the Wallarm plugin for an existing service¶

Once Kong is running with the Wallarm plugin included, enable it for one or more of your existing services using the Kong Admin API:

1. Create a configuration file enable-plugin.json in the kong-wallarm/ directory with the following content:

   {
     "name": "wallarm-plugin",
     "instance_name": "wallarm-protection",
     "protocols": ["http", "https"],
     "enabled": true,
     "config": {
       "blocking": true,
       "wallarm_node_address": "<WALLARM_NODE_URL>",
       "timeout_ms": 500
     }
   }
   

   Available configuration parameters:

   Parameter	Description
   config.blocking	Set to true for synchronous (in-line) mode or to false for asynchronous (out‑of‑band) mode.
   config.wallarm_node_address	HTTPS URL of your Wallarm Node.
   config.timeout_ms	The maximum time (in milliseconds) the plugin waits for a response from the Wallarm Node. If the timeout is exceeded, the request is forwarded without Wallarm decision and the error is logged.

2. Attach the plugin to an existing service by its ID or name using Kong Admin API:

   curl -i -X POST http://localhost:8001/services/<SERVICE_NAME_OR_ID>/plugins \
     -H "Content-Type: application/json" \
     -d "@enable-plugin.json"
   

   To get a desired <SERVICE_NAME_OR_ID>, use curl http://localhost:8001/services.

3. Verify that the plugin is active by listing plugins for the service:

   curl -s http://localhost:8001/services/<SERVICE_NAME_OR_ID>/plugins | jq .
   

5. (Optional) Enable the plugin globally¶

To protect all services automatically, you can apply the plugin globally by omitting the service and route parameters:

curl -i -X POST http://localhost:8001/plugins \
  -H "Content-Type: application/json" \
  -d "@enable-plugin.json"

Testing¶

To test the functionality of the deployed connector, follow these steps:

1. Send the request with the test Path Traversal attack to your API Gateway:

   curl http://localhost:8000/etc/passwd
   

2. Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.

   

   If the Wallarm node mode is set to blocking, the request will also be blocked.

Upgrading the Wallarm Lua plugin¶

To upgrade the Wallarm Lua plugin:

1. Obtain the updated handler.lua and schema.lua from support@wallarm.com.

2. Replace the old files in /usr/local/share/lua/5.1/kong/plugins/wallarm-plugin.

3. Rebuild and restart Kong Gateway.

4. Verify the plugin version via the Kong Admin API:

   curl -s http://localhost:8001/plugins | grep wallarm-plugin
   

Example: Running Kong Gateway with the Wallarm plugin from scratch¶

The following example shows how to quickly start Kong API Gateway with the Wallarm Lua plugin on a clean host using Docker Compose.

1. Deploy a Wallarm Native Node.

2. Contact support@wallarm.com to obtain the Wallarm Lua plugin files.

3. Create the kong-wallarm working directory and add the following files:

   kong-wallarm/
   ├── Dockerfile
   ├── docker-compose.yml
   ├── wallarm-plugin/
   │ ├── handler.lua
   │ └── schema.lua
   └── enable-plugin.json
   

   Dockerfiledocker-compose.ymlenable-plugin.json

   FROM kong:latest
   
   # Copy Wallarm Lua plugin
   COPY wallarm-plugin /usr/local/share/lua/5.1/kong/plugins/wallarm-plugin
   
   # Enable the plugin
   ENV KONG_PLUGINS="bundled,wallarm-plugin"
   

   version: "3.8"
   services:
     db:
       image: postgres:15
       environment:
       POSTGRES_USER: kong
       POSTGRES_DB: kong
       POSTGRES_PASSWORD: kong
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U kong -d kong"]
       interval: 5s
       timeout: 3s
       retries: 20
   
     kong:
       build: .
       depends_on:
         db:
           condition: service_healthy
       environment:
         KONG_DATABASE: "postgres"
         KONG_PG_HOST: "db"
         KONG_PG_USER: "kong"
         KONG_PG_PASSWORD: "kong"
         KONG_PG_DATABASE: "kong"
         KONG_ADMIN_LISTEN: "0.0.0.0:8001"
         KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
         KONG_LOG_LEVEL: "info"
         KONG_PLUGINS: "bundled,wallarm-plugin"
       ports:
         - "8000:8000"
         - "8001:8001"
         - "8443:8443"
       command: >
         /bin/sh -c "
         kong migrations bootstrap &&
         kong start --vv &&
         tail -f /usr/local/kong/logs/*.log"
   

   {
       "name": "wallarm-plugin",
       "instance_name": "wallarm-protection",
       "protocols": ["http", "https"],
       "enabled": true,
       "config": {
           "blocking": true,
           "wallarm_node_address": "<WALLARM_NODE_URL>",
           "timeout_ms": 500
       }
   }
   

   The handler.lua and schema.lua files should be obtained from the Wallarm Support Team.

4. Start the environment:

   docker compose up -d --build
   

5. Verify that Kong is running:

   curl -s http://localhost:8001/ | jq .version
   

6. Create a test service and route

   curl -i -X POST http://localhost:8001/services \
       --data name=test-service \
       --data url='http://httpbin.org'
   
   curl -i -X POST http://localhost:8001/services/test-service/routes \
       -H "Content-Type: application/json" \
       -d '{"paths": ["/test"]}'
   

7. Enable the Wallarm plugin:

   curl -i -X POST http://localhost:8001/services/test-service/plugins \
       -H "Content-Type: application/json" \
       -d "@enable-plugin.json"
   

8. Test the setup by sending a test Path Traversal attack through Kong:

   curl -H "Host: test.com" \
       http://localhost:8000/test/etc/passwd
   

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send