This is a preview release. Do not use it in production environments.

Download the release bundle from Download Edge-Native Defender (Preview). New to Edge-Native Defender? Start with Edge-Native Defender overview.

Watch the install (3 minutes): downloading the release, building Kong Gateway with Defender, enabling the plugin in kong.yml, allowed and blocked requests, the plugin in Kong Manager, and Kong's own counters.

At a glance

Deployment architecture

Defender runs inside the Kong Gateway you already operate, as the plugin cequence-defender with a native engine it loads. Each request is decided inside the Kong worker that already holds it, from a policy set kept in memory, so there is no extra service to size and no extra hop.

  BEFORE

    client ---> Kong Gateway ----------------------------> your services
                +--------------------------+
                | your plugins and routes  |
                +--------------------------+


  AFTER

    client ---> Kong Gateway ----------------------------> your services
                +----------+  +--------------------------+
                | Defender |  | your plugins and routes  |
                | decides  |  | unchanged                |
                +----------+  +--------------------------+
                     |
                     +---> your Cequence tenant: policies in, analytics out,
                           in the background

What stays the same. Your routes, services, upstreams and other plugins. Kong fetches your policies in the background and sends analytics in batches after your clients have their responses: no request waits on Cequence.

What Defender does with a request. A blocked request is answered by Kong and never reaches your service. An allowed request is forwarded byte for byte, and your client receives the response byte for byte: Defender inspects a copy of each body, up to your tenant's capture settings, and never changes what it forwards.

What is sent to Cequence. For each request: its headers and URL, the response status and headers, and the inspected body copies, masked first with your tenant's Sensitive Data rules. Your traffic filters decide whether a request is reported at all. Until the rules have been fetched, analytics are held back rather than sent unmasked.

Installation

Prerequisites

• Kong Gateway 3.4 or later, Enterprise or open source, on Linux (amd64 or arm64) with glibc 2.28 or later. Every Kong Gateway image and package qualifies. (Kong 3.11 and later cannot run Wasm, so this plugin, not Defender for Envoy, is the path for Kong.)
• Outbound HTTPS from every Kong node to your Cequence tenant: edge.<tenant>.cequence.cloud and auth.<tenant>.cequence.cloud, where <tenant> is your tenant name, such as acme.1.
• Your tenant's name, client ID and client secret, from Cequence.
• The defender-for-kong release bundle.

1. Add Defender to your gateway

With Docker or Kubernetes, build an image from the unpacked bundle:

docker build -t kong-with-defender .
docker build --build-arg KONG_IMAGE=kong/kong-gateway:3.11 -t kong-with-defender .
docker buildx build --platform linux/arm64 -t kong-with-defender .

Use your own Kong image as KONG_IMAGE if you already build one. The image enables the plugin and declares the shared memory it needs:

KONG_PLUGINS=bundled,cequence-defender
KONG_NGINX_HTTP_LUA_SHARED_DICT=cequence_defender 32m

If your deployment already sets either variable, add Defender's values to yours: a later setting replaces the image's.

On a host or VM, from the unpacked bundle, as root:

cd plugin
luarocks make --deps-mode=all kong-plugin-cequence-defender-*.rockspec
mkdir -p /usr/local/lib/defender
cp ../lib/linux-amd64/libdefender_kong.so /usr/local/lib/defender/

Use lib/linux-arm64 on an arm64 host. Then add to kong.conf and restart Kong:

plugins = bundled,cequence-defender
nginx_http_lua_shared_dict = cequence_defender 32m

Hybrid mode and Kong Konnect. Install the plugin on the control plane and on every data plane: the control plane needs it to accept the configuration, the data planes to run it. In Konnect, upload the plugin's schema.lua as a custom plugin and run data planes built from the image above.

2. Enable the plugin

In Kong's declarative configuration, as in the bundle's kong.yml.example. For a tenant named acme.1:

plugins:
  - name: cequence-defender
    config:
      edge_url: https://edge.acme.1.cequence.cloud
      auth_url: https://auth.acme.1.cequence.cloud/auth/realms/cequence/protocol/openid-connect/token
      client_id: <client id>
      client_secret: "{vault://env/cequence-client-secret}"
      instance_id: <a name for this gateway fleet>

With a database, send the same settings to the Admin API (POST /plugins) or apply them with decK. On Kubernetes with the Kong Ingress Controller, put them in a KongClusterPlugin with plugin: cequence-defender and the label global: "true".

• client_secret accepts a Kong vault reference, so the secret need not be stored in Kong's configuration.
• Enable the plugin on a service or a route instead of globally to protect only that service or route.
• If a load balancer in front of Kong carries the client's address in a header, set client_ip_header to it; otherwise Defender uses the connecting address.
• To enforce geo-match policies (country, ASN, organization), point geo_mmdb_dir at a directory of MaxMind databases.

The bundle's README.md lists every setting.

3. Check it before you go live

1. Set diagnostics: true on a test gateway and request /__end/status through Kong. Within a few seconds of starting, policies_loaded shows your tenant's policy count.
2. Send a request that one of your policies blocks, and check it is blocked. If you run Kong's Prometheus plugin, blocked requests are counted in kong_http_requests_total with code="403" and source="kong".
3. Set diagnostics back to false. The status page is readable by anyone who can reach the route.

Kong Manager lists cequence-defender under Plugins, with its configuration; the client secret shows as *****.

On Kong Gateway 3.16, a route declared without protocols accepts only HTTPS and answers plain HTTP with 426. To test over plain HTTP, give the route protocols: ["http", "https"].

Upgrades and rollback

Each release publishes a new defender-for-kong bundle, with the plugin and its engine together. Your plugin configuration lives in Kong and does not need to change.

1. Install the new bundle the way you installed the first one:
2. Docker or Kubernetes: build a new image from the new bundle, with a new tag, for example docker build -t kong-with-defender:<version> ., and roll your Kong Deployment or containers onto it.
3. Host or VM: from the new bundle, run the same luarocks make and copy the new libdefender_kong.so over the old one, as in step 1.
4. Hybrid mode: upgrade the control plane as well as the data planes.
5. Restart Kong nodes one at a time, so your load balancer always has nodes serving. A restarted node fetches your policies again within a few seconds and forwards requests unchanged until it has them; each restart can lose a few seconds of that node's unsent analytics.
6. Check /__end/status as in "Check it before you go live".

To roll back, install the previous bundle (or redeploy the previous image tag) and restart the nodes the same way.

Performance and sizing

Measured on a 4 vCPU host at 1,000 requests a second with two Kong workers, a policy set of about 6,000 policies, analytics and masking on, and 1 KB responses. Cost scales with request rate; more policies, larger bodies or more Sensitive Data rules raise it. Measure with your own traffic before sizing production.

Most of the added CPU is building and masking each request's analytics. With telemetry off, Defender adds about 0.17 core per 1,000 requests a second. Give Kong's workers CPU headroom: the 95th-percentile figure above was taken near saturation, and latency stays closest to the median with spare CPU.

Cost

Cequence charges nothing for the infrastructure. Defender runs inside your existing Kong nodes, with no extra service and no Kong license change: the plugin works on Kong Gateway Enterprise and open source. Plan for the extra CPU and memory in "Performance and sizing".

Availability

• If Cequence is slow or unreachable, your traffic is unaffected. Defender keeps enforcing the policies it last received, and sends analytics once Cequence is reachable again.
• If Defender cannot run (the shared memory is not declared, or the engine is missing), Kong forwards every request unchanged and logs why once per worker.
• If you need Defender off the path at once, disable or delete the plugin's configuration. Kong stops running Defender immediately, with no restart.
• A fresh install blocks nothing until your tenant's first policy publish arrives.

Known limits

• block, add-header, challenge, rate-limit and honeytrap redirect policies are all enforced. Your tenant's traffic-policy configuration, including allow-filters, applies.
• Rate limits are counted per Kong node, shared by all of its workers. Across a fleet of nodes, each node counts on its own.
• A biometric challenge needs a biometric token issuer configured in your tenant; without one the request is forwarded. Token issuers that sign with ES512 or ES256K keys are not supported.
• Konnect Dedicated Cloud Gateways are not supported: they cannot load Defender's engine. Self-managed data planes in Konnect are supported.
• Each Kong worker holds the analytics it has not yet sent; a reload or restart can lose a few seconds of them. Enforcement is not affected.

If something is wrong

Kong's error log says what is wrong, on lines starting with defender:.

The bundle's README.md has the full settings reference.

Removing it

Disable or delete the plugin's configuration. Kong stops running Defender at once. To unload the plugin as well, remove cequence-defender from plugins (or KONG_PLUGINS) at your next restart.