nginx-waf-lua

OpenResty/Lua integration library for nginx-waf.

Overview

nginx-waf-lua provides a Lua library for OpenResty that reads nginx-waf IP list files, provides fast IP lookups, custom block responses, and runtime list management.

Features

• Read nginx-waf IP list files
• Fast IP matching (IPv4/IPv6 + CIDR)
• Shared dict caching for performance
• Custom block response handling
• Runtime block/unblock with TTL
• Drop-in access phase handler

Quick Start

-- In OpenResty nginx.conf
lua_shared_dict waf_cache 10m;

init_by_lua_block {
    local waf = require("resty.waf")
    waf.init({
        lists_dir = "/etc/nginx/waf-lists",
        shared_dict = "waf_cache",
    })
}

access_by_lua_block {
    local waf = require("resty.waf")
    waf.check_request()
}

API

local waf = require("resty.waf")

waf.init(opts)                  -- Initialize with options
waf.is_blocked(ip)              -- Check if IP is blocked
waf.is_allowed(ip)              -- Check if IP is allowed
waf.check_request()             -- Full access phase handler
waf.block(ip, opts)             -- Block IP at runtime
waf.unblock(ip)                 -- Unblock IP

Installation

From OBS packages

Available for Fedora, openSUSE, Debian, and Ubuntu via OBS.

From source

make install PREFIX=/usr/local/openresty

From LuaRocks (future)

luarocks install nginx-waf-lua

Related Projects

nginx-waf Ecosystem

• nginx-waf - Core nginx module (required)
• nginx-waf-api - REST API for list management
• nginx-waf-feeds - Threat feed updater
• nginx-waf-ui - Web management interface

Other Nginx Modules

• nginx-torblocker - Control access from Tor exit nodes
• nginx-cf-realip - Automatic Cloudflare IP list fetcher for real client IP restoration
• nginx-gone - Return HTTP 410 Gone for permanently removed URIs

License

BSD 3-Clause License - see LICENSE.md for details.