Introduction
Fail2ban is an Intrusion Detection/Prevention System (IDS/IPS), a great tool that helps you keep “unwanted” guests at bay. It’s mainly used to stop, prevent or slow down bruteforce attacks, but can be used to limit the number of requests per unit of time (backend, API,..).
It scans/monitor log files and bans IPs that show malicious signs, like too many password failures, probing, bruteforcing attempts, etc. You can specify which service and log to monitor, how many attempts per unit of time (second/hour…), define regex (regular expression) patterns, etc.
Out of the box it comes with filters for various services: Apache, ssh, nginx, asterisk, proftp, mysql… Here we’ll quickly go through Fail2ban setup.
Fail2Ban Setup
Install process it is relatively straightforward.
RedHat (CentOS)
Update, Install with EPEL repository:
yum updateyum install epel-releaseyum install fail2ban
Debian (Ubuntu)
Update & install:
$ apt-get update $ apt-get install fail2ban
Fail2ban Configuration Files
Relevant File2Ban Configuration files and dirs:
- /etc/fail2ban/filter.d/: Contains predefined (regex) fail2ban filters
- /etc/fail2ban/jail.conf: Not recommended to be updated, use custom jails
- /etc/fail2ban/jail.local: Your customized Jails (or customisation.local)
- /etc/fail2ban/fail2ban.conf: Main Configuration File
Fail2ban Definitions
Before we continue, it’s probably good idea to define what’s what:
filter: a filter defines a regular expression which must match a pattern corresponding to a log-in failure or any other expressionaction: an action defines several commands which are executed at different momentsjail: a jail is a combination of one filter and one or several actions. Fail2ban can handle several jails at the same timeclient: refers to the script fail2ban-clientserver: refers to the script fail2ban-server
Fail2ban Server is multi-threaded, listens on a Unix socket for commands. Knows nothing about configuration files.
-b start in background -f start in foreground -s <FILE> socket path -x force execution of the server -h, --help display this help message -V, --version print the version
Fail2ban Client is basically the frontend, operate the servers. Reads the configuration files, or accept individual commands via interactive mode.
-c <DIR> configuration directory -s <FILE> socket path -d dump configuration. For debugging -i interactive mode -v increase verbosity -q decrease verbosity -x force execution of the server -h, --help display this help message -V, --version print the version
Examples:
$ fail2ban-client set loglevel 1 $ fail2ban-client set logtarget STDERR $ fail2ban-client status |- Number of jails: 1 `- Jail list: sshd $ fail2ban-client status sshd Status for the jail: sshd |- Filter | |- Currently failed: 2 | |- Total failed: 42635 | |- File list: /var/log/auth.log `- Actions |- Currently banned: 0 |- Total banned: 863 |- Banned IP list:
Fail2ban Main Configuration
loglevel: The level of detail that Fail2ban’s logs provide:- 1 (error)
- 2 (warn)
- 3 (info)
- 4 (debug).
logtarget: Logs actions into a specific file. The default value of/var/log/fail2ban.logputs all logging into the defined file. Alternately, you can change the value to:STDOUT: output any dataSTDERR: output any errorsSYSLOG: message-based loggingFILE: output to a file
socket: The location of the socket file.pidfile: The location of the PID file.
Fail2ban Jail Options
filter: ame of the filter to be used by the jail to detect matches. Each single match by a filter increments the counter within the jaillogpath: Path to the log file which is provided to the filtermaxretry: Number of matches (i.e. value of the counter) which triggers ban action on the IP.bantime: Duration (in seconds) for IP to be banned for. Negative number for “permanent” ban.enabled: True or false. Defines if filter is turned on or notport: The port used by the serviceignoreip: IP(s) that should be ignored by fail2banfindtime: Time range fail2ban will pay attention to when looking at the logs.backend: Defines how fail2ban monitor logs. It will try pinotify, gaming and finaly pooling.destemail: Address to send email notifications tosendername: From field for notification emailssender: Email address from which Fail2ban will send emails.mta: MTA used to send notification mailsprotocol:banaction: Action to be used when ban is triggered. Check /etc/fail2ban/action.d/
Let’s explain one example:
/etc/fail2ban/jail.local [sshd] enabled = true port = ssh filter = sshd action = iptables[name=SSH, port=ssh, protocol=tcp] logpath = /var/log/secure findtime = 120 maxretry = 5 bantime = 3600
Log path can vary, adjust it on your system (OS). Based on rules above, we’re monitoring SSH log (/var/log/secure), and we’re banning anyone (for 1 hour, 3600 seconds) who fails to log 5 times within 2 minutes (120 seconds). Rules are pretty straight forward. We’ve specified “sshd” filter, so if you go to /etc/fail2ban/filter.d/sshd.conf, you’ll se a number of failregex rules, used to match login attempts from log file.
To whitelist (ignore) an IP, add them to the ignoreip line:
ignoreip = 127.0.0.1/8
Custom Fail2ban PhpMyAdmin filter (Jail & Regex)
The best way to learn is to try and write your own filters. I’ll show you an example for Custom Fail2ban PhpMyAdmin filter. First, we need the jail in our jail.local file:
[phpmyadmin] enabled = true port = http,https filter = phpmyadmin action = iptables-multiport[name=PHPMYADMIN, port="http,https", protocol=tcp] logpath = /var/log/nginx/access.log bantime = 3600 findtime = 60 maxretry = 3
Next we need that filter. Check your web server (Apache/nginx) logs:
/var/log/nginx/access.log.1:121.169.192.227 - - [19/Sep/2018:01:41:23 +0000] "GET /phpmyadmin/index.php?pma_username=root&pma_password=root&server=1 HTTP/1.1" 200 10050 "-" "Mozilla/5.0" /var/log/nginx/access.log.1:121.169.192.227 - - [19/Sep/2018:01:41:23 +0000] "GET /phpmyadmin/index.php?pma_username=root&pma_password=toor&server=1 HTTP/1.1" 200 10050 "-" "Mozilla/5.0" /var/log/nginx/access.log.1:121.169.192.227 - - [19/Sep/2018:01:41:23 +0000] "GET /phpmyadmin/index.php?pma_username=root&pma_password=r00t&server=1 HTTP/1.1" 200 10050 "-" "Mozilla/5.0"
The IP 121.169.192.227 is trying to bruteforce its way in (well known malicious IP). We’ll try to make their life a bit more difficult. Make a file in your /etc/fail2ban/filter.d/phpmyadmin.conf, and insert:
[Definition] failregex = ^<HOST> -.*"(GET|POST).*/phpmyadmin/index\.php\?pma_username=root&pma_password=.*$ ignoreregex =
The above regex is matching the lines we’ve seen in the logs. This will ban anyone for 1 hour if they fail to login more than 3x in 60 seonds. When done, restart fail2ban:
$ service fail2ban restart
or reload:
$ fail2ban-client reload phpmyadmin
Fail2ban testing regex
When you finish creating some filter it’s good idea to test it before activating it. For that we have fail2ban-regex:
$ fail2ban-regex /var/log/nginx/access.log /etc/fail2ban/filter.d/phpmyadmin.conf Running tests ============= Use failregex filter file : phpmyadmin, basedir: /etc/fail2ban Use log file : /var/log/nginx/access.log Use encoding : UTF-8 Results ======= Failregex: 56 total |- #) [# of hits] regular expression | 1) [56] ^<HOST> -.*"(GET|POST).*/phpmyadmin/index\.php\?pma_username=root&pma_password=.*$ `- Ignoreregex: 0 total Date template hits: |- [# of hits] date format | [4078] Day(?P<_sep>[-/])MON(?P=_sep)Year[ :]?24hour:Minute:Second(?:\.Microseconds)?(?: Zone offset)? `- Lines: 4078 lines, 0 ignored, 56 matched, 4022 missed [processed in 0.33 sec] Missed line(s): too many to print. Use --print-all-missed to print all 4022 lines
We have a match. In case filter/regex is wrong, we’ll probably end up with no matches:
Lines: 3315 lines, 0 ignored, 0 matched, 3315 missed [processed in 0.23 sec] Missed line(s): too many to print. Use --print-all-missed to print all 3315 lines
Fail2ban Email Alerts
I didn’t experiment with this much, but its probably worth mentioning that you have Email Alert option. Adjust email setings:
destemail: Destination Email address, where you would like to receive the emails.sendername: Name under which the email will shows up.sender: Email address from which Fail2ban will send emails.
Use fail2ban predefined actions.d/sendmail-whois:
[sendmail] enabled = true filter = sendmail action = iptables-multiport[name=sendmail, port="pop3,imap,smtp,pop3s,imaps,smtps", protocol=tcp] sendmail-whois[name=sendmail, dest=user@domain.com] logpath = /var/log/maillog
Another example:
[ssh] enabled = true port = ssh filter = sshd action = iptables-multiport[name=ssh,port=["ssh"|”22,4422”],protocol=tcp] mail[name=SSH,dest=dstEmail@domain.com,sender="info@domain.com"] logpath = /var/log/auth.log maxretry = 3 bantime = 600
Conclusion
I hope we managed to clarify more than a few things with this Fail2ban setup tutorial. Fail2ban is a great IDS/IPS tool, doing its job well. Depending on the traffic and findtime span it can cause significant load on CPU. Personally I didn’t experiance significant problems. If CPU load increases, try changing the backend parameter to to pooling or similar. Experiment. Since fail2ban relies on log file parsing, it doesn’t do anything to “prevent” initial attack, it only responds to predefined conditions and rules. It’s actively maintaned and we’re definitely recomending you to try it out.