Install on Linux
Two ways to run ngx_json_guard on a Linux host: as a dynamic module
against your existing NGINX, or built statically into a custom NGINX.
If you just want to evaluate the parser itself, no NGINX is needed at all.
Build the dynamic module
Dynamic modules must match your runtime NGINX: same version, and
preferably the same configure arguments (nginx -V prints them). Build
against an NGINX source tree of the exact same version:
# 1. Get NGINX sources matching your runtime version
curl -O https://nginx.org/download/nginx-1.26.2.tar.gz
tar xf nginx-1.26.2.tar.gz
cd nginx-1.26.2
# 2. Configure with --with-compat and the module
./configure --with-compat \
--add-dynamic-module=/path/to/ngx_json_guard
# 3. Build only modules
make modules
# 4. Install the .so where your NGINX loads modules from
cp objs/ngx_http_json_guard_module.so /etc/nginx/modules/
If your NGINX was built with additional arguments (check nginx -V),
pass the same ones to ./configure — --with-compat relaxes some of the
matching requirements but not all.
Build statically
For a custom NGINX build:
cd /path/to/nginx-1.26.2
./configure --add-module=/path/to/ngx_json_guard
make
make install
Enable in nginx.conf
# top of nginx.conf, before events {}
load_module modules/ngx_http_json_guard_module.so;
http {
server {
listen 80;
location /api/ {
json_guard on;
proxy_pass http://app;
}
}
}
Requests to /api/ with a JSON Content-Type now get structural
validation. Malformed JSON is answered with 400, structural limit
violations with 413. See the
configuration reference for every directive.
Verify it works
# Valid body → passes to upstream
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Content-Type: application/json' \
-d '{"ok": true}' http://localhost/api/echo
# Malformed body → 400 from the guard
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Content-Type: application/json' \
-d '{"ok": true,}' http://localhost/api/echo
# Depth over the default limit (100) → 413 from the guard
python3 -c "print('['*200 + ']'*200)" | \
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Content-Type: application/json' \
--data-binary @- http://localhost/api/echo
Expected: 200, 400, 413.
To observe the guard's own cost per request, log the timer variable:
log_format guard '$status inspection_us=$json_guard_inspection_us';
access_log /var/log/nginx/guard.log guard;
Standalone parser (no NGINX)
The streaming parser is pure C with no NGINX dependency. Build and run the unit suite, including an ASan/UBSan build:
cd /path/to/ngx_json_guard
make test # 75 parser tests
make test-asan # same suite under AddressSanitizer + UBSan
Quick parser benchmark:
make bench-micro
Output is median-of-15 parse passes per payload size; expect roughly linear time in body size and flat memory regardless of body size.
Distribution notes
- Debian/Ubuntu NGINX: distro packages are built with their own
module directory (
/usr/lib/nginx/modules) and specific configure flags; match them exactly or rebuild NGINX. - Official NGINX images: see Install in Docker — the repo ships a Dockerfile that compiles NGINX + the module + ModSecurity + CRS in one image.
- ABI compatibility is the recurring gotcha with dynamic modules: if
NGINX reports a version mismatch on
load_module, the module was not built against the same version/flags as the running binary.