# OpenResty Web Application Firewall

> High-performance web platform with Lua scripting and ModSecurity WAF.

- Category: Web Servers & Reverse Proxies
- Difficulty: advanced
- Components: openresty, modsecurity, prometheus, grafana
- Tags: openresty, nginx, waf, lua, security
- Source: https://docker.recipes/web-servers/openresty-waf

## Overview

OpenResty is a high-performance web platform built on Nginx that extends the server with LuaJIT scripting capabilities, enabling developers to write complex web application logic directly within the web server. Originally created by Yichun Zhang at CloudFlare, OpenResty transforms Nginx from a simple reverse proxy into a programmable application server capable of handling complex routing, authentication, rate limiting, and data processing tasks at wire speed. The platform has become the backbone for many high-traffic applications requiring sub-millisecond response times and sophisticated request handling logic.

This stack combines OpenResty's programmable web server with OWASP ModSecurity's industry-standard Web Application Firewall, creating a powerful security-first web platform. ModSecurity provides real-time application attack detection and prevention using the OWASP Core Rule Set, while OpenResty's Lua scripting enables custom security logic, dynamic routing, and request transformation. The integration allows security policies to be implemented both at the WAF layer for standard threats and in Lua for application-specific security requirements, creating multiple layers of protection.

This combination is ideal for organizations requiring enterprise-grade web application security with the flexibility to implement custom business logic at the edge. Security teams benefit from ModSecurity's comprehensive attack detection, while developers can leverage OpenResty's Lua environment to build sophisticated API gateways, implement OAuth flows, perform real-time data enrichment, and create custom caching strategies. The included Prometheus and Grafana stack provides deep visibility into both security events and application performance metrics.

## Features

- LuaJIT-powered request processing enabling sub-millisecond custom logic execution within Nginx
- OWASP ModSecurity Core Rule Set with configurable paranoia levels for SQL injection, XSS, and attack prevention
- Real-time security metrics collection with ModSecurity audit logs exported to Prometheus
- Lua-based dynamic routing and request transformation without external application servers
- Integrated anomaly scoring system with configurable inbound/outbound thresholds for adaptive security
- Custom Lua script hot-reloading for zero-downtime security policy and business logic updates
- TLS termination with certificate management and HTTP/2 support through OpenResty
- Grafana dashboards for WAF attack visualization and OpenResty performance monitoring

## Use cases

- API gateway with custom authentication and rate limiting for microservices architectures
- High-traffic e-commerce platforms requiring real-time fraud detection and request filtering
- SaaS applications needing tenant-specific routing and security policies implemented in Lua
- Financial services requiring PCI DSS compliance with comprehensive web application protection
- Gaming platforms implementing custom session management and anti-bot protection logic
- Healthcare applications requiring HIPAA-compliant request logging and data sanitization
- Edge computing deployments where business logic execution must happen closest to users

## Prerequisites

- Docker Engine 20.10+ with at least 2GB RAM available for OpenResty and ModSecurity processing
- Basic understanding of Nginx configuration syntax and HTTP request/response flow
- Lua programming knowledge for implementing custom security and business logic in OpenResty
- Familiarity with OWASP security principles and ModSecurity rule syntax for WAF customization
- Ports 80, 443, 3000, and 9090 available on the host system for web traffic and monitoring
- SSL/TLS certificates placed in ./certs directory for HTTPS termination if required

## docker-compose.yml

```yaml
services:
  openresty:
    image: openresty/openresty:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/usr/local/openresty/nginx/conf/nginx.conf:ro
      - ./lua:/usr/local/openresty/nginx/lua:ro
      - ./certs:/etc/nginx/certs:ro
      - openresty_logs:/usr/local/openresty/nginx/logs
    networks:
      - openresty-net
    restart: unless-stopped

  modsecurity:
    image: owasp/modsecurity-crs:nginx
    environment:
      - PARANOIA=1
      - ANOMALY_INBOUND=5
      - ANOMALY_OUTBOUND=4
      - BACKEND=http://app:8080
    volumes:
      - ./modsec-rules:/etc/modsecurity.d/owasp-crs/rules:ro
    networks:
      - openresty-net
    restart: unless-stopped

  app:
    image: traefik/whoami:latest
    networks:
      - openresty-net
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    networks:
      - openresty-net
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - prometheus
    networks:
      - openresty-net
    restart: unless-stopped

volumes:
  openresty_logs:
  prometheus_data:
  grafana_data:

networks:
  openresty-net:
    driver: bridge
```

## .env

```bash
# Grafana
GRAFANA_PASSWORD=secure_grafana_password

# ModSecurity
PARANOIA_LEVEL=1
```

## Usage notes

- OpenResty at http://localhost
- ModSecurity WAF protection enabled
- Write custom Lua scripts in /lua folder
- Grafana at http://localhost:3000

## Troubleshooting

- ModSecurity blocks legitimate requests: Reduce PARANOIA level from 1 to 0 or adjust ANOMALY_INBOUND threshold above 5
- OpenResty Lua scripts fail to load: Check file permissions in ./lua directory and ensure files are readable by container user
- High memory usage in OpenResty: Tune lua_shared_dict sizes in nginx.conf and implement proper Lua garbage collection
- ModSecurity rules not updating: Restart the modsecurity container and verify custom rules in ./modsec-rules are valid
- Prometheus missing ModSecurity metrics: Enable mod_security audit logging and configure nginx-lua-prometheus module
- Grafana dashboards show no data: Verify Prometheus is scraping OpenResty metrics endpoint and ModSecurity exporter is running

