# Wallarm Connector for Kong API Gateway To secure APIs managed by a standalone [Kong API Gateway](https://docs.konghq.com/gateway/latest/), 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)](https://docs.wallarm.com/installation/inline/overview.md) and [asynchronous (out‑of‑band)](https://docs.wallarm.com/installation/oob/overview.md) 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](https://docs.wallarm.com/installation/connectors/kong-ingress-controller.md). ## Limitations * This setup allows fine-tuning Wallarm only via the Wallarm Console UI. * [Custom blocking page and code setup](https://docs.wallarm.com/admin-en/configuration-guides/configure-block-page-and-code.md) 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`) * Kong API Gateway version 3.4-3.9 * Docker and Docker Compose installed on the host * Access to `https://us1.api.wallarm.com` (US Wallarm Cloud), `https://api.wallarm.com` (EU Wallarm Cloud), or `https://me1.api.wallarm.com` (ME 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](https://docs.wallarm.com/user-guides/ip-lists/overview.md) countries, regions, or data centers **US 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 ``` **EU Cloud:** ``` 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 ``` **ME Cloud:** ``` node-data0.me1.wallarm.com - 34.166.82.208 node-data1.me1.wallarm.com - 34.166.82.208 me1.api.wallarm.com - 34.166.82.208 ``` * **Administrator** access to Wallarm Console for [US Cloud](https://us1.my.wallarm.com/) or [EU Cloud](https://my.wallarm.com/), or [ME Cloud](https://me1.my.wallarm.com/) * 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. **Edge node:** To deploy a Wallarm-hosted node for the connector, follow the [instructions](https://docs.wallarm.com/installation/security-edge/se-connector.md). **Self-hosted node:** Choose an artifact for a self-hosted node deployment and follow the attached instructions: * [All-in-one installer](https://docs.wallarm.com/installation/native-node/all-in-one.md) for Linux infrastructures on bare metal or VMs * [Docker image](https://docs.wallarm.com/installation/native-node/docker-image.md) for environments that use containerized deployments * [Helm chart](https://docs.wallarm.com/installation/native-node/helm-chart.md) for infrastructures utilizing Kubernetes ### 2. Prepare the Wallarm Lua plugin 1. Contact [support@wallarm.com](mailto:support@wallarm.com) to obtain the Wallarm Lua plugin files. 1. Create a working directory and add the plugin code: ```bash mkdir kong-wallarm cd kong-wallarm mkdir wallarm-plugin ``` 1. 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: ```dockerfile 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" ``` 1. Your project structure should now look as follows: ``` kong-wallarm/ ├── Dockerfile ├── wallarm-plugin/ │ ├── handler.lua │ └── schema.lua ``` 1. Build and restart Kong Gateway with the new image (or update your deployment pipeline accordingly): ```bash 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=kongpass \ -e KONG_PLUGINS="bundled,wallarm-plugin" \ -e KONG_ADMIN_LISTEN=0.0.0.0:8001 \ 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: ```json { "name": "wallarm-plugin", "instance_name": "wallarm-protection", "protocols": ["http", "https"], "enabled": true, "config": { "blocking": true, "wallarm_node_address": "", "timeout_ms": 500 } } ``` Available configuration parameters: | Parameter | Description | | --------- | ----------- | | `config.blocking` | Set to `true` for [synchronous (in-line)](https://docs.wallarm.com/installation/inline/overview.md) mode or to `false` for [asynchronous (out‑of‑band)](https://docs.wallarm.com/installation/oob/overview.md) mode. | | `config.wallarm_node_address` | HTTPS URL of your [Wallarm Node](#1-deploy-a-wallarm-native-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. | 1. Attach the plugin to an existing service by its ID or name using [Kong Admin API](https://developer.konghq.com/api/gateway/admin-ee/): ```bash curl -i -X POST http://localhost:8001/services//plugins \ -H "Content-Type: application/json" \ -d "@enable-plugin.json" ``` To get a desired ``, use `curl http://localhost:8001/services`. 1. Verify that the plugin is active by listing plugins for the service: ```bash curl -s http://localhost:8001/services//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: ```bash 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](https://docs.wallarm.com/attacks-vulns-list.md#path-traversal) attack to your API Gateway: ``` curl http://localhost:8000/etc/passwd ``` 1. Open Wallarm Console → **Attacks** section in the [US Cloud](https://us1.my.wallarm.com/attacks) or [EU Cloud](https://my.wallarm.com/attacks), or [ME Cloud](https://me1.my.wallarm.com/attacks) and make sure the attack is displayed in the list. ![Attacks in the interface](https://docs.wallarm.com/images/admin-guides/test-attacks-quickstart.png) If the Wallarm node [mode is set to blocking](https://docs.wallarm.com/admin-en/configure-wallarm-mode.md), 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. 1. Replace the old files in `/usr/local/share/lua/5.1/kong/plugins/wallarm-plugin`. 1. [Rebuild and restart Kong Gateway](#3-build-a-kong-image-with-the-wallarm-plugin). 1. 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](#1-deploy-a-wallarm-native-node). 1. Contact [support@wallarm.com](mailto:support@wallarm.com) to obtain the Wallarm Lua plugin files. 1. 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 ``` **`Dockerfile`:** ```dockerfile 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" ``` **`docker-compose.yml`:** ```yaml 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" ``` **`enable-plugin.json`:** ```json { "name": "wallarm-plugin", "instance_name": "wallarm-protection", "protocols": ["http", "https"], "enabled": true, "config": { "blocking": true, "wallarm_node_address": "", "timeout_ms": 500 } } ``` The `handler.lua` and `schema.lua` files should be obtained from the Wallarm Support Team. 1. Start the environment: ```bash docker compose up -d --build ``` 1. Verify that Kong is running: ```bash curl -s http://localhost:8001/ | jq .version ``` 1. Create a test service and route ```bash 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"]}' ``` 1. Enable the Wallarm plugin: ```bash curl -i -X POST http://localhost:8001/services/test-service/plugins \ -H "Content-Type: application/json" \ -d "@enable-plugin.json" ``` 1. Test the setup by sending a test [Path Traversal](https://docs.wallarm.com/attacks-vulns-list.md#path-traversal) attack through Kong: ```bash curl -H "Host: test.com" \ http://localhost:8000/test/etc/passwd ```