sneak
dfb44c5546
The old README opened with project history and one list of a hundred settings. The new one leads with what smallwebwaf is, what it protects against, how to build and deploy it, how it sits in front of the app, what happens to a request, the settings most deployments touch, how to check it works and how to develop it. The reference material, every setting, bans, rule files, the Core Rule Set, the admin endpoints, the request log, alerts, metrics, state files, lookups, reputation sources, the image and gitea, moves to files under docs/, each linked from the README. Every statement was checked against the code on next. Model: fable-5-1
1.9 KiB
The Core Rule Set
The OWASP Core Rule Set 4.25.0 runs on each request after the rule files, unless
SWWAF_WAF_MODE is off. It reads the method, the URL with its query, and the
headers. Once SWWAF_WAF_BODY_LIMIT is set, it also reads a body that is form
data, multipart, JSON or XML. No answer is inspected. The settings are under
"Attack detection" in settings.md. The same section of
SPEC.md says why bodies are not read by default, and gives the
six changes smallwebwaf makes to the Core Rule Set, with the reason for each.
Each rule that matches adds to the request's score. A score at or over
SWWAF_WAF_ANOMALY_THRESHOLD is a match. A match is refused with 403 while
SWWAF_WAF_MODE is block, and let through while it is detect. Either way
the log line gives the rule ids and the score, and a waf_block alert is sent.
A request with more than 1000 query parameters or body fields adds 5 to its
score, since Coraza reads only the first 1000. The Core Rule Set inspects only a
request that every earlier check let through. It skips a path under
SWWAF_WAF_EXEMPT_PATHS and a client in SWWAF_ALLOW_NETS. An engine error on
a request forwards the request, and is logged and counted.
Body inspection suits apps whose forms carry no code. In front of a code forge
it refuses issue and comment text, wiki pages and files saved in the web editor
that hold shell commands or code. The log line names the rule ids, which
SWWAF_WAF_DISABLED_RULES can switch off. A body the Core Rule Set cannot parse
adds 5 to the score. So does a multipart body cut by the limit in the middle of
a part's header. The client has until SWWAF_CLIENT_REQUEST_TIMEOUT runs out to
send the part that is read. Any other body, such as a git push, reaches the app
uninspected.
gitea.md records what the Core Rule Set still refuses in front of
gitea, with and without body inspection.