$ opm get nemethhh/lua-resty-clienthello-ratelimit

lua-resty-clienthello-ratelimit

lua-resty-clienthello-ratelimit is a three-tier TLS ClientHello rate limiter for OpenResty and Apache APISIX.

It is designed to run in ssl_client_hello_by_lua* and reject abusive TLS handshakes before normal HTTP request processing begins. The limiter combines:

• T0: IP blocklist in a shared dictionary

• T1: per-IP leaky-bucket rate limiting

• T2: per-SNI-domain leaky-bucket rate limiting

The repository includes:

• a platform-agnostic core module

• an OpenResty adapter with nginx-lua-prometheus metrics support

• an APISIX adapter that hooks into ssl_client_hello_phase

• Dockerized unit, APISIX integration, and OpenResty integration test suites

Repository layout

    lib/resty/clienthello/ratelimit/
      init.lua        core limiter
      config.lua      config validation
      metrics.lua     cached inc_counter builder (shared by both adapters)
      openresty.lua   OpenResty adapter
      apisix.lua      APISIX adapter
    
    examples/
      nginx.conf              example OpenResty config
      apisix-config.yaml      example APISIX config fragment
      apisix-plugin-shim.lua  example APISIX plugin shim
    
    t/
      unit/                   Busted unit tests
      integration/            APISIX integration tests
      openresty-integration/  OpenResty integration tests

How it works

For each TLS ClientHello:

1. The core module extracts the raw client IP address via FFI.

2. It checks whether that IP is already in the blocklist shared dict.

3. It applies a per-IP rate limit.

4. If an SNI is present, it applies a per-domain rate limit.

5. If the per-IP limiter rejects a client, the IP is automatically added to the blocklist for block_ttl seconds.

Configuration is required — there are no defaults. You must specify at least one rate-limiting tier:

| Tier | Key | Required fields | | --- | --- | --- | | Per-IP (T0+T1) | per_ip | rate (number > 0), burst (number >= 0), block_ttl (number > 0) | | Per-domain (T2) | per_domain | rate (number > 0), burst (number >= 0) |

Shared dictionaries (names are fixed):

| Dict | Purpose | | --- | --- | | tls-hello-per-ip | Per-IP rate limiter state | | tls-hello-per-domain | Per-SNI rate limiter state | | tls-ip-blocklist | Auto-blocked IPs with TTL |

Tested versions

| Component | Version | | --- | --- | | OpenResty | openresty/openresty:jammy (1.25.x) | | Apache APISIX | 3.15.0 |

Requirements

For local development and test execution:

• Docker with Compose support

• make

• openssl on the host, for generating the self-signed integration-test certificate

For runtime use:

• Lua 5.1 compatible environment

• OpenResty with ssl_client_hello_by_lua*

• resty.limit.req

• ngx.ssl.clienthello

• resty.core

Optional metrics integrations:

• nginx-lua-prometheus for the OpenResty adapter

• APISIX Prometheus plugin for the APISIX adapter

Installation

Install via OPM:

    opm get nemethhh/lua-resty-clienthello-ratelimit

Or copy the lib/ tree into your OpenResty/APISIX Lua path manually:

    cp -r lib/resty /usr/local/openresty/lualib/

This provides the following Lua modules:

• resty.clienthello.ratelimit

• resty.clienthello.ratelimit.config

• resty.clienthello.ratelimit.metrics

• resty.clienthello.ratelimit.openresty

• resty.clienthello.ratelimit.apisix

Core module

The core module is platform-agnostic and exposes new(opts, metrics) plus check().

    local limiter = require("resty.clienthello.ratelimit")
    
    local lim, warnings = limiter.new({
        per_ip = { rate = 2, burst = 4, block_ttl = 10 },
        per_domain = { rate = 5, burst = 10 },
    }, my_metrics_adapter)
    
    local rejected, reason = lim:check()
    if rejected then
        -- reason is one of: "blocklist", "per_ip", "per_domain"
    end

Notes:

• check() must run in ssl_client_hello_by_lua* context.

• If client IP extraction fails, the limiter currently returns false and allows the handshake to continue.

• If no SNI is present, only the blocklist and per-IP layers are applied.

The optional metrics adapter is expected to expose:

    {
        inc_counter = function(name, labels) ... end
    }

The bundled resty.clienthello.ratelimit.metrics module provides make_cached_inc_counter(prometheus, exptime) which builds this adapter efficiently — prometheus counter objects and label value arrays are cached after the first call per unique name/labels pair. Both adapters use this builder internally.

Important invariant: labels tables passed to inc_counter must be module-level constants (the same table reference on every call). Per-request label tables cause unbounded cache growth.

OpenResty usage

An example configuration is available in examples/nginx.conf.

Minimal setup:

    http {
        lua_shared_dict tls-hello-per-ip     1m;
        lua_shared_dict tls-hello-per-domain 1m;
        lua_shared_dict tls-ip-blocklist     1m;
        lua_shared_dict prometheus-metrics   1m;
    
        init_worker_by_lua_block {
            require("resty.clienthello.ratelimit.openresty").init({
                per_ip = { rate = 2, burst = 4, block_ttl = 10 },
                per_domain = { rate = 5, burst = 10 },
                prometheus_dict = "prometheus-metrics",
                -- metrics_exptime = 300,  -- optional: counter TTL in seconds (default 300)
            })
        }
    
        server {
            listen 443 ssl;
    
            ssl_certificate     /path/to/server.crt;
            ssl_certificate_key /path/to/server.key;
    
            ssl_client_hello_by_lua_block {
                require("resty.clienthello.ratelimit.openresty").check()
            }
        }
    }

The OpenResty adapter:

• initializes the core limiter once per worker

• optionally initializes nginx-lua-prometheus

• exposes adapter.prometheus so a /metrics location can call collect()

• rejects a handshake with ngx.exit(ngx.ERROR) when a limit is hit

APISIX usage

Example files:

• examples/apisix-config.yaml

• examples/apisix-plugin-shim.lua

The APISIX adapter is loaded as a custom plugin shim:

    local adapter = require("resty.clienthello.ratelimit.apisix")
    return adapter

Add the shim as apisix/plugins/tls-clienthello-limiter.lua, then update APISIX config:

    apisix:
      extra_lua_path: "/path/to/custom-plugins/?.lua"
    
    plugins:
      - tls-clienthello-limiter
    
    nginx_config:
      http:
        custom_lua_shared_dict:
          tls-hello-per-ip: 1m
          tls-hello-per-domain: 1m
          tls-ip-blocklist: 1m
    
    plugin_attr:
      tls-clienthello-limiter:
        per_ip:
          rate: 2
          burst: 4
          block_ttl: 10
        per_domain:
          rate: 5
          burst: 10
        # metrics_exptime: 300  # optional: counter TTL in seconds (default: no expiry)

The APISIX adapter:

• reads settings from plugin_attr.tls-clienthello-limiter

• builds a metrics adapter on top of APISIX Prometheus, when available

• monkey-patches apisix.ssl_client_hello_phase

• restores the original phase handler in destroy()

Metrics

Depending on traffic patterns and configuration, the limiter can emit:

• tls_clienthello_blocked_total

• tls_clienthello_passed_total

• tls_clienthello_rejected_total

• tls_ip_autoblock_total

• tls_clienthello_no_sni_total

Typical labels include:

• reason=blocklist

• layer=per_ip

• layer=per_domain

Testing

The repository ships with three Docker-based test targets:

    make unit
    make integration
    make openresty-integration

Or run everything:

    make all

What each target does:

• make unit: builds t/unit/Dockerfile and runs Busted specs for the core module

• make integration: generates test certificates, starts APISIX plus a test runner, and executes TLS handshake plus metrics tests

• make openresty-integration: generates test certificates, starts OpenResty plus a test runner, and executes equivalent adapter tests

Generated artifacts:

• t/integration/certs/server.crt

• t/integration/certs/server.key

• t/integration/conf/apisix.yaml

Cleanup:

    make clean

Test endpoints

The integration harness exposes these ports on the host:

| Stack | Port | Purpose | | --- | --- | --- | | APISIX | 9443 | TLS test listener | | APISIX | 9091 | Prometheus metrics | | APISIX | 9092 | healthz | | OpenResty | 19443 | TLS test listener | | OpenResty | 19092 | metrics and healthz |

License

MIT. See LICENSE.