FAQ: including the rules, and the errors that come with getting it wrong

[fabriziosalmi]

This thread collects the questions that come up repeatedly in issues, with the answer and the reasoning behind it. If yours is not here, reply below.

Full guides live on the documentation site; this is the short form.

---

Which files am I supposed to include in Nginx?

Only the two aggregate files, each in its own context:

http {
    include /etc/nginx/waf_patterns/nginx/waf_maps.conf;
}

server {
    include /etc/nginx/waf_patterns/nginx/waf_rules.conf;
}

Not the per-category files, and not a glob such as include .../nginx/*.conf.

Why does including a category file fail?

Because attack.conf, xss.conf, bots.conf and the others contain both map directives, which Nginx only accepts in the http block, and if directives, which it only accepts in server or location. No single include context satisfies both, so whichever you pick produces "if" directive is not allowed here or "map" directive is not allowed here.

Reported in #17, #8 and #6.

Nginx says "too long parameter, probably missing terminating character"

Nginx caps a single configuration parameter at 4096 characters, and some generated regular expressions exceed it. It is not a quoting mistake in your file: the line really is that long.

The occurrence in xss.conf was fixed in #7. A later report against waf_maps.conf is open and lists the offending lines: #22.

Nothing is blocked on HAProxy

Almost always an ACL comparing the request against the literal path of the file rather than loading the patterns from it. These two lines look similar and behave completely differently:

# Wrong: compares the request against the string "/etc/haproxy/waf/waf.acl"
acl waf_attack path_reg /etc/haproxy/waf/waf.acl

# Right: loads the patterns from the file with -f
acl waf_match path,url_dec -m reg -i -f /etc/haproxy/waf/waf.acl

Same for the bot list. Reported in #14, which also led to fixes in owasp2json.py, json2haproxy.py and import_haproxy_waf.py.

HAProxy rejects include inside a frontend

HAProxy has no include directive there. Keep the acl lines in haproxy.cfg and point them at the generated files with -f, which is what the shipped ACL archives are for.

Does this work with Caddy?

Not through this project. Caddy has its own implementation: caddy-waf. The Caddy importer that used to live here was removed, so issues about it in the tracker predate that split.

Will it block Google and other search engines?

No. The bad-bot list targets SEO crawlers, AI training bots and known scanners, and explicitly allows Google, Bing, DuckDuckGo, Yandex and Baidu. Adjust the generated blocklist or the source lists in badbots.py for a stricter or looser policy.

How often are the rules updated?

Daily. A scheduled workflow re-fetches the upstream Core Rule Set, regenerates every backend and publishes a release. Pin a specific release if you need reproducible deployments, since latest moves.

I edited a file under waf_patterns/ and my change disappeared

That directory holds generated output and is rebuilt by the daily workflow. Changes belong in the converter that produced the file, json2nginx.py and its siblings, or upstream in owasp2json.py when the problem affects every backend.

How do I check my configuration before deploying it?

nginx -t
apachectl configtest
haproxy -c -f /etc/haproxy/haproxy.cfg

Then confirm the limit actually fires, because a config that parses is not the same as a config that blocks. A Traefik middleware no router references is silently inert.

---

Questions welcome below. Bugs and feature requests still belong in issues.