Getting Started with RouteWarden for NGINX & OpenResty

RouteWarden for NGINX (github.com/routewarden/nginx-warden) provides zero-dependency Lua middleware for OpenResty and NGINX servers equipped with lua-nginx-module. It executes inside worker processes during the access_by_lua phase to filter malicious requests before reverse-proxying.

---

Prerequisites

• OpenResty (v1.19+ recommended) OR
• Standard NGINX compiled with:
  • lua-nginx-module (v0.10.15+)
  • ngx_devel_kit (NDK)
  • LuaJIT 2.1

---

Installation Methods

Deploy RouteWarden via Dockerfile, container run, Docker Compose, or manual package integration:

Diff

FROM openresty/openresty:alpine# Copy RouteWarden into OpenResty Lua library search pathCOPY lib/resty/routewarden /usr/local/openresty/site/lualib/resty/routewarden# Copy your NGINX configurationCOPY nginx.conf /etc/nginx/conf.d/default.conf

---

Configuration

RouteWarden can be configured directly in OpenResty's init_by_lua_block or defined via routewarden.json as your universal security policy:

Diff

{  "$schema": "https://routewarden.github.io/cli/schema.json",  "enabled": true,  "enableDefaultPatterns": true,  "enableDefaultAllowPatterns": true,  "methods": ["GET", "HEAD"],  "allowedIps": ["127.0.0.1", "10.0.0.0/8"],  "response": {    "mode": "json",    "statusCode": 403,    "body": "{\"error\":\"Forbidden\",\"message\":\"Sensitive route protected by RouteWarden\"}"  }}

Using routewarden.json Directly via Generate Pipeline

If you maintain routewarden.json as your single source of truth across Git repositories or multi-gateway environments, use the RouteWarden CLI (rwarden) to validate rules offline and compile directly into OpenResty Lua configuration tables during your deployment pipeline:

# 1. Validate schema compliance, regex patterns, and CIDRsrwarden validate --config routewarden.json# 2. Compile directly into OpenResty Lua configuration tablerwarden generate --target nginx --config routewarden.json > /etc/nginx/lua/routewarden_conf.lua

---

Verification

Test edge security enforcement against benign requests, sensitive file probes, double URL-encoded evasion attempts, and trusted IP exemptions:

curl -I http://localhost/index.html# HTTP/1.1 200 OK

---

Next Steps

• Use the RouteWarden CLI (rwarden) to validate schemas and test paths offline.
• Review NGINX Configuration Reference for all directives and options.
• Read Production Recipes & Blueprints for Kubernetes Ingress and Docker configurations.