Public web servers still receive exploit probes for bugs that were fixed years ago. A request for an old PHP-CGI path or a Log4Shell string may be irrelevant to a fully patched application, but it is not harmless background noise when one nginx instance fronts many applications with different owners and patch cycles.
nginx-http-shield-module adds a narrow filter for that problem. It recognizes fixed exploit forms in request targets, selected headers and eligible request bodies. It can log a match, reject it, export metrics and optionally feed a separate abuse-reporting service. It does not try to understand an application’s business logic.
Use Shield as a floor, not as a WAF replacement. A full WAF such as Coraza or ModSecurity with OWASP CRS can enforce broader policy and cover application-specific attack shapes. Shield is intentionally smaller: a compiled set of high-signal patterns and structural checks, with no runtime rule language.
What Shield actually inspects
The current source defines 30 categories. Its literal tables contain 651 entries representing 650 unique byte strings, plus six multi-term rules with 12 terms. Four categories are structural checks rather than literal lookups: httpoxy’s request-borne Proxy header, an excessive number of byte ranges, encoded control bytes in the path, and dot-prefixed path segments.
The categories cover recognizable exploit forms such as SQL injection sequences, path traversal, CRLF injection, Log4Shell and Shellshock payloads, Java and PHP deserialization gadgets, webshell filenames, cloud-metadata destinations and fixed n-day exploit paths. A hit means that a configured category recognized a byte form. It does not prove that the backend was vulnerable, and the absence of a hit does not prove that the request was safe.
Inspection is context-sensitive. The request target receives both a whole-target pass and a path-only recovery pass for categories that should not match in a query. User-Agent is inspected broadly, while Referer deliberately excludes the sensitive-file category. Content-Type receives a much smaller set. Cookie inspection is limited to injection-shaped categories. Destination-like headers such as X-Original-URL receive target-style normalization. That separation avoids treating every header as if it were a URL.
For literal matching, Shield lowercases a raw view and also scans a once-percent-decoded lowercase view. A plus sign becomes a space only in form-style data: the query portion of a request target and application/x-www-form-urlencoded bodies. A literal plus in a path or opaque header stays a plus. Percent-encoded %2B also remains a literal plus after decoding. This distinction matters because globally folding plus signs changes the meaning of non-form inputs.

Body inspection has a budget
shield_body is on by default, but Shield does not scan every possible upload format. It admits forms, multipart data, JSON, text types, XML, GraphQL, NDJSON, JSON text sequences and YAML. A missing Content-Type is treated as scannable. Unknown and binary media types are not.
shield_max_body sets the decoded inspection budget and defaults to 8 KiB. Shield reads and scans the body prefix whether nginx kept it in memory or placed it in a temporary file. If a body is larger than the budget, the prefix is still inspected and an incomplete-inspection counter is incremented. The remaining bytes are not examined. Size alone does not reject the request.
That is an important rollout detail. The setting is an inspection and resource budget, not an upload-size limit. Keep nginx’s normal request-size controls for enforcement. On a dedicated upload endpoint, either accept prefix-only coverage or disable body inspection there. Raising the cap increases synchronous work in an nginx worker, so measure the deployed build and traffic mix before changing it.
Compressed request bodies need an explicit shield_gzip on. Shield accepts a single gzip content-coding token, limits the encoded input separately with shield_max_encoded_body (64 KiB by default), and enforces bounded inflate work. It supports concatenated gzip members up to the implementation limit of 64. Unsupported coding stacks, malformed streams and exhausted decode budgets are recorded as incomplete inspection; the raw bytes can still be checked. A decoded prefix that fits the body budget is inspected normally.
Failure is different from a cap
Shield distinguishes a documented boundary from an internal inability to inspect. A body beyond a configured cap is incomplete, not an error. A request-body file read failure or allocation failure is an inspection error.
In block mode, an inspection error returns 500 and records a fail-closed event. In detect mode, it is logged and the request continues because detect mode never changes the response. Unsupported compression and a body that extends beyond the inspected prefix are not converted into 500 responses. Operators can therefore tell resource failures apart from expected budget limits through the exported counters.
Start with detect mode
Build the dynamic module against the exact nginx or Angie source used for the target binary, then load it near the top of the configuration:
./configure --add-dynamic-module=/path/to/nginx-http-shield-module
make modules
load_module modules/ngx_http_shield_module.so;
http {
shield detect;
shield_log /var/log/nginx/shield.json;
server {
location / {
shield detect; # off | detect | block
shield_body on; # on by default
shield_max_body 8k; # inspected decoded prefix
shield_status 403; # 403 | 404 | 419 | 429 | 444
}
location /uploads/ {
shield_body off;
}
}
}
Run in detect mode long enough to cover the application’s ordinary traffic, including administration, uploads, APIs and scheduled clients. Review category, source and location rather than copying attacker-controlled request bytes into a terminal. If a legitimate application form overlaps a category, use shield_skip in the narrowest suitable location. A child shield_skip list replaces an inherited non-empty list; it does not append to it, and an empty child list does not clear the parent.
Move stable locations to shield block after reviewing the observations. The configured status defaults to 403; nginx’s 444 connection close is also available. Keep detect mode on uncertain routes instead of treating one quiet test window as proof that false positives are impossible.
Shield also has opt-in application profiles for selected request forms associated with newer CVEs. These profiles are off by default and belong only on matching application locations. They are narrow filters, not virtual patches for every route, encoding or deployment condition. Upgrade the affected application even when a profile is enabled.
Cost is bounded, not free
The literal engine uses Aho-Corasick automatons. For the compiled tables, each raw or decoded view is walked linearly in the inspected bytes rather than sweeping the buffer once per signature. This removes a signature-by-signature hot path, but it does not make inspection costless. Normalization uses request-pool buffers, body decoding has explicit budgets, and nginx performs the work synchronously in a worker.
Adding patterns can also increase configuration-time automaton construction and the module’s read-only memory footprint. Exact latency depends on the processor, compiler, nginx build, enabled views and request mix. Benchmark those conditions directly. Historical scan-core numbers without their hardware and build context are not a sound capacity plan.
Logs, counters and bans
shield_log writes one JSON object per event to a file or syslog target. The record includes bounded operational context such as category, source, mode and request line. Attacker-controlled bytes are escaped. Command-pipe targets are rejected, so logging does not turn a request into process execution.
A shared shield_stats_zone exposes Prometheus or OpenMetrics output through a status location. Counters separate detections, blocks, incomplete body or gzip inspection, failures, bans and reporter-relevant events. Scrape the endpoint privately and alert on changes in rate, not only on a lifetime total. Incomplete inspection and internal failure deserve separate alerts because they imply different responses.
The optional ban zone keeps abusive clients in shared memory and can reject them before repeating the full application path. It is an operational control, not an identity system: source addresses can be shared, proxied or spoofed when the real-IP boundary is wrong. Validate trusted proxy configuration before using an address for bans or third-party reports.
AbuseIPDB reporting stays out of nginx
The repository includes an optional AbuseIPDB reporter. It tails Shield’s JSON log in a separate hardened systemd service, so nginx does not hold an API key or wait for a network API. Start it with --dry-run and verify its input and permissions before allowing reports.
The reporter suppresses private, loopback, link-local, multicast, reserved and unspecified addresses. Its public comment contains the method and first path segment, with query strings and absolute-target authorities removed. That boundary reduces the risk of forwarding tokens, email addresses or tenant-specific paths to a third party.
Successful reports are deduplicated per address for 15 minutes, and a daily cap resets at UTC midnight. The state is persisted across restarts. Rate-limit responses honor a bounded Retry-After; server and network failures use backoff and retry the same line. Other client-side API errors are treated as permanent for that record. These controls align with AbuseIPDB’s reporting rules, but the operator remains responsible for the data sent and the applicable account limit.
Where Shield stops
Shield cannot determine whether a backend authorization check is correct, recognize every encoding layer, decompress data behind the application, or cover a new exploit before a matching high-signal form is added. It does not scan an unlimited body, and some content types are deliberately excluded. XML external-entity coverage recognizes implemented SYSTEM forms; it is not general XML parsing and does not claim PUBLIC declaration coverage.
Keep applications patched. Put a full WAF in front of applications that need broad virtual patching. Use Shield for the smaller job it can perform predictably: catch known exploit-shaped traffic early, record what it did, and expose the limits when inspection was partial.
The source, configuration reference, test suites and deployment helpers are available in the nginx-http-shield-module repository. Read the directive inheritance notes before rollout, then begin with shield detect.
Is nginx-http-shield-module a replacement for ModSecurity or Coraza?
No. Shield is a fixed, bounded exploit filter. A full WAF provides broader application policy and virtual-patching coverage. Use Shield as a baseline and add a WAF where the application needs one.
How should I roll out Shield?
Start with shield detect, review normal traffic for every relevant route, narrow any shield_skip setting to the affected location, and then move stable locations to shield block. Do not assume one test window proves that all legitimate traffic is covered.
What happens when a request body is larger than shield_max_body?
Shield still inspects the prefix up to the configured budget, which defaults to 8 KiB. It records incomplete inspection for the remainder. Body size alone does not block the request, and shield_max_body is not an upload-size limit.
Does Shield inspect gzip request bodies?
Only when shield_gzip is enabled. Encoded input, decoded output, member count and inflate work are bounded. Unsupported or malformed encodings are recorded as incomplete inspection rather than being treated as a clean fully inspected body.
Does Shield turn every plus sign into a space?
No. Plus-to-space folding applies only to form-style data: the query portion of a request target and form-urlencoded bodies. Paths and opaque headers keep literal plus signs, and percent-encoded %2B remains a plus after decoding.
Does nginx contact AbuseIPDB during a request?
No. The optional reporter is a separate service that reads Shield’s JSON log. It suppresses non-public addresses, strips query data from comments, persists deduplication and cap state, and applies API backoff outside nginx workers.
Related reading
- Auto-ban abusive clients in NGINX with the error-abuse module: add a rate-based response to repeated errors.
- Run Coraza WAF with NGINX: broader request policy for applications that need it.
- Install ModSecurity with OWASP CRS: the established ruleset route.
- Understand JA3 and JA4 TLS fingerprints: a separate signal below HTTP.