Testing filters for fail2ban

Question

I'm creating a custom filter for fail2ban, so I can lock out bots attacking my webserver. How do I test the filter rules to make sure they match what they're supposed to match and nothing more?

Answer 1

Fail2ban comes with a tool fail2ban-regex for this exact purpose. You run it like this:

fail2ban-regex [OPTIONS] LOG REGEX [IGNOREREGEX]

where LOG, REGEX and IGNOREREGEX (optional) can be either strings or files. Note that if you have a filter file that defines both a fail expression and an ignore expression, you need to specify the file twice, once as the parameter REGEX and once as the parameter IGNOREREGEX.

Example:

To test both expressions in a filter like this:

# /etc/fail2ban/filter.d/fltr.local

[Definition]

failregex = ^\[\] foo

ignoreregex = ^\[\] bar

you'd run the command like this:

fail2ban-regex /var/log/your.log /etc/fail2ban/filter.d/fltr.local /etc/fail2ban/filter.d/fltr.local

The "Results" section of the output shows how many lines of the log file were matched or ignored (if you specified an ignore expression), and also which lines were missed (not matched by any expression).

...
Results
=======

Failregex: 5 total
|-  #) [# of hits] regular expression
|   1) [5] ^\[\] foo
`-

Ignoreregex: 2 total
|-  #) [# of hits] regular expression
|   1) [2] \[\] bar
`-

...

|- Ignored line(s):
|  [2020-06-29T08:04:58+02:00] bar some
|  [2020-06-29T08:10:01+02:00] bar or other
`-
|- Missed line(s):
|  [2020-06-29T07:28:03+02:00] baz xyz
|  [2020-06-29T13:34:55+02:00] - foobar
`-

Add the option --print-no-ignored and/or --print-no-missed to omit the lists of ignored/missed lines at the end. Add the option --print-all-matched, --print-all-ignored and/or --print-all-missed to expand collapsed lists of matched, ignored, or missing lines.

For more information on developing and testing fail2ban filters see here.