Skip to main content

Install in Docker

The repository ships Dockerfiles that compile everything from pinned sources — NGINX, ngx_json_guard, libmodsecurity, ModSecurity-nginx and the OWASP Core Rule Set — so the image you run is the image the benchmarks ran against.

Build the WAF image​

cd /path/to/ngx_json_guard
make docker-build # docker build -f docker/Dockerfile -t ngx_json_guard:test .

What ends up inside (versions pinned in benchmark/native/versions.env):

ComponentVersion
NGINX1.26.2
ngx_json_guardbuilt from this repo
libmodsecurity3.0.13
ModSecurity-nginx1.0.3
OWASP CRS4.25.0

The entrypoint runs nginx -t before starting. Effective ordering (guard before ModSecurity in PREACCESS) is checked by the integration suite below: a malformed body must get the guard's 400, and the same body on the unguarded /noguard/ route must not.

Run the integration tests​

make docker-test # scripts/run_docker_integration.sh

This brings up the full stack (NGINX + guard + ModSecurity + CRS + echo backends) and asserts a matrix of expected status codes: valid bodies 200, malformed 400, over-limit 413, SQLi 403 — across routes, content types, methods, and keep-alive reuse (12 cases).

Run it with your own upstream​

The compose stack in docker/docker-compose.api.yml wires NGINX to four fixture upstreams (JSON, XML, form, web). To point it at your app, mount your own NGINX config:

services:
waf:
image: ngx_json_guard:test
ports: ["8080:8080"]
volumes:
- ./my-nginx.conf:/etc/nginx/nginx.conf:ro
# your app reachable at app:9000 from this network
extra_hosts:
- "app:host-gateway"

A minimal my-nginx.conf with the guard in front of ModSecurity:

load_module modules/ngx_http_json_guard_module.so;
load_module modules/ngx_http_modsecurity_module.so;

events { worker_connections 1024; }

http {
modsecurity on;
modsecurity_rules_file /etc/nginx/modsec/main.conf;

server {
listen 8080;

location /api/ {
json_guard on;
json_guard_max_depth 64;
proxy_pass http://app:9000;
}
}
}

Benchmark images​

Two more images exist for reproducing the benchmark results:

  • ngx_json_guard_api:test — fixture upstream apps (docker/Dockerfile.api)
  • ngx_json_guard_coraza:test — Caddy + Coraza 3.7.0 + CRS for the cross-engine comparison (benchmark/Dockerfile.coraza)
make cross-waf-full # all eight engine profiles (~90 min + build time)
make waf-correctness # 21-case constrained run
make waf-perf # 175-request mixed run

Reports, per-request JSON, and cgroup snapshots land under artifacts/. Note that run_waf_perf.sh expects the API upstreams from docker/docker-compose.api.yml to be running in the same compose project:

docker compose -f docker/docker-compose.api.yml up -d \
json_api xml_api form_api web_app

Notes​

  • Container resource limits in the benchmark compose files (2 vCPU / 4 GiB) are what make the published numbers reproducible; keep them if you fork the harness.
  • The images are benchmark/reference builds. For production, prefer building your own image from the same Dockerfiles with your NGINX version, and pin to a released tag of this module.