Fail2Ban Setup on Debian – Enhance Your System Security

Q: Other Services

Fail2Ban has many 'preconfigured' filters and actions for many services, which can easily be adjusted to suit your needs. SSH and HTTP/HTTPS services are most commonly configured to listen on public IP addresses; thus, attacks against them are also most common. Simply put, those services can be accessed by anybody who has access to the public network, aka the Internet. I'm not saying Fail2Ban cannot help you prevent attacks against other services like MySQL, for instance. But if you configured MySQL to listen on the public IP address, I'm sorry, you're doing it wrong. I'm saying that sometimes, protection is not required if the service can be configured without being exposed to the public network.

Author:

Željko Jagušt

Publish Date:

November 29, 2023

Categories:

Applications

System Administration & DevOps

Estimated Reading Time:

36 minutes

Welcome to the Fail2Ban Setup on Debian guide, where we delve into the critical steps to fortify your system’s security.

Table of Content

Introduction

In an era of increasing cyber threats, configuring Fail2Ban on your Debian Linux (or any other Linux) system is a proactive measure to safeguard against unauthorized access and malicious activities. Follow our step-by-step instructions to implement Fail2Ban efficiently, enhancing your server’s resilience and ensuring a robust defense against potential attacks. Let’s embark on a journey to bolster the security of your Debian environment and keep your system protected from emerging threats.

Prerequisites

Fail2Ban can be installed on (almost) any Linux distribution, and I will use the latest version of Debian for this guide. Usually, Fail2Ban is much more common in server environments where one or more fixed IP addresses are present, so consider that before installing it (maybe you don’t need it). As usual, we have a couple of articles that can help you with the installation of the Debian server:

Debian 11 Server – Minimal Installation Guide

Follow this guide for a Debian 11 Server minimal installation, providing a solid foundation for any server setup or project you want to build.

Debian 11 Server – Initial Customization Guide

Discover introductory steps to streamline performance, security, and administration in our Debian Server Initial Customization guide.

Fail2Ban Setup

Fail2Ban is an intrusion prevention software that primarily aims to prevent brute-force attacks. On Linux servers, the most common “exposed” services/ports are SSH (port 22) and HTTP/HTTPS (port 80/443); thus, the majority of “attacks” attempted are against those two. As an example, I will show you how to use Fail2Ban to protect your server from these most common attacks in this guide.

Other Services

Fail2Ban has many “preconfigured” filters and actions for many services, which can easily be adjusted to suit your needs. SSH and HTTP/HTTPS services are most commonly configured to listen on public IP addresses; thus, attacks against them are also most common. Simply put, those services can be accessed by anybody who has access to the public network, aka the Internet.

I’m not saying Fail2Ban cannot help you prevent attacks against other services like MySQL, for instance. But if you configured MySQL to listen on the public IP address, I’m sorry, you’re doing it wrong. I’m saying that sometimes, protection is not required if the service can be configured without being exposed to the public network.

Fail2Ban Installation

The fail2Ban package is available in the main Debian repository, and installing it is straightforward. Just execute the following command in the Terminal:

apt install fail2ban python3-systemd

I am doing this on the latest version of Debian Linux, and at the moment, that is Debian 12. In Debian 12, all logging differed from “classic” Syslog, which is now handled by systemd-journald service. Due to that, the Fail2Ban service will fail to start after the installation is complete, and it will report the following error:

ERROR   Failed during configuration: Have not found any log file for sshd jail

In the next section of this guide, I will show you how to resolve this and all other configuration options.

Fail2Ban Configuration

In this section, I will show you how to configure a few general Fail2Ban settings, filters, and actions to prevent attacks on SSH and HTTP/HTTPS services.

Main Configuration Files

The two “main” Fail2Ban configuration files are /etc/fail2ban/fail2ban.conf and /etc/fail2ban/jail.conf. The first defines some general options for the Fail2Ban service, and the second configures protection for various services. The documentation states that we should not modify those files and instead use .local files, and I will show you how to do that.

The general options file fail2ban.conf, in most cases, requires no modifications. Optionally, you can add allowipv6 = no if you don’t use an IPv6 network, to omit the following message:

WARNING 'allowipv6' not defined in 'Definition'. Using default one: 'auto'

As for jail.conf file, I suggest opening a new override file /etc/fail2ban/jail.local and setting a few general options that will be valid for all filters that will be in use. You can open that file and set the following options:

[DEFAULT]

## MISC
bantime = 86400
findtime = 3600
maxretry = 5
backend = systemd

## ACTIONS
mta = sendmail
destemail = root
sender = F2B-Alerts-<fq-hostname>
action = %(action_xarf)s

Let’s observe those options. In the example above, if the violating host (IP) is discovered five times (maxretry) in one hour (findtime = 3600), it will be banned from accessing the server during the next 24 hours (bantime = 86400).

The default backend is the “location” where Fail2Ban will look for violating hosts. In the older versions of Debian Linux, Fail2Ban checked logs in the/var/log directory when Syslog handled logs. In the latest version of Debian, logs are handled by systemd-journald service; thus, backend = systemd.

Optionally, once the violating host is discovered and banned, you can configure Fail2Ban to email the root user (destmail = root). You can check those emails (if any) by listing the contents of the /var/mail/root file. You must configure an email relay if you want to receive those emails to one of your “real” email addresses. To see how to do that, you can check our guide:

Send Mail – Gmail Relay Setup on Debian Linux

Effortlessly send mail from your Debian Linux server using Gmail as a reliable relay. Follow our step-by-step guide for DMA configuration.

SSH Configuration

Most brute-force attacks against SSH involve the “attacker” trying to “guess” a login password. Usually, a bot is installed on the attacking side and is supplied with a list of the most common usernames/passwords, which are then used to attempt to log in to the target server. A very efficient method to protect against such attacks is to deny a password login and configure a private/public key pair, which is then used to log in to the server (if you read our prerequisites articles, you should have that in place).

Unfortunately, this will not stop the attacker (bot) from attempting to log in by using a password (although it can’t). This is where Fail2Ban comes into play. When you install Fail2Ban on Debian, SSH protection is enabled by default. A configuration or “jail” can be found at /etc/fail2ban/jail.d/defaults-debian.conf. It uses a filter with all the actions defined (how the violators will be blocked) whose configuration can be found in /etc/fail2ban/filter.d/sshd.conf file. Usually, you don’t have to do anything about the configuration; everything will work as-is. Optionally (and something I highly suggest), you can set the jail/filter to “aggressive” mode, so it protects you from any possible scenario. To do that, open /etc/fail2ban/jail.d/defaults-debian.conf and add the following option to the bottom of the file:

mode = agressive

Once you do that, save the file and restart the Fail2Ban service:

systemctl restart fail2ban.service

With this in place, if a proper public/private key pair is not used to log in to the server, Fail2Ban will block any other attempts. It will automatically set a rule in the iptables firewall, dropping any connection attempt from the offending IP and denying all traffic from that IP.

SSH Configuration – Repeating Offenders

Once the violating IP is discovered, it is banned according to the rules set in the main configuration file (/etc/fail2ban/jail.conf). This can be modified either in the main configuration “override” file (/etc/fail2ban/jail.local – see Main Configuration Files section above) or in a jail-specific configuration file (set in /etc/fail2ban/jail.d directory). For my SSH configuration above, ban rules will be applied according to the options I’ve set in /etc/fail2ban/jail.local file; if the violating IP is discovered five times in one hour, it will be banned for the next 24 hours.

After 24 hours, the ban will expire, and the attack on your server will resume until the attacking host IP gets banned again. Usually, brute-force bots are configured to attempt to “break in” the server until they succeed. So, blocking the same attacking IP will be performed by Fail2Ban literally in an endless loop.

Fail2Ban has mechanisms to configure jails and banning a bit “smarter” (i.e., check bantime.increment, bantime.rndtime, bantime.maxtime, bantime.formula and other options in /etc/fail2ban/jail.conf file), but what I like to do regarding such “repeating” offenders is to create a new jail/filter that will handle those. It looks like this: if an IP is banned by a default SSH filter five times in one year, that IP is banned permanently. Done!

To do that, a “helper” file that will store such repeating IPs must be created first. You can do it by executing the following in the Terminal:

touch /etc/fail2ban/ip.blocklist.repeatoffender
chmod 770 /etc/fail2ban/ip.blocklist.repeatoffender

Next, an action file must be defined. It will store all the actions a repeat offender filter will perform. To create one, open a new file /etc/fail2ban/action.d/repeatoffender.conf and paste in the following content:

# Fail2Ban configuration file – repeat offenders
[INCLUDES]
before = iptables-common.conf

[Definition]
# Option:  actionstart
# Notes.:  command executed once at the start of Fail2Ban.
# Values:  CMD
#
actionstart = iptables -N f2b-<name>
              iptables -A f2b-<name> -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-<name>
              # Establish chain and blocks for saved IPs
              iptables -N f2b-ip-blocklist
              iptables -A f2b-ip-blocklist -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-ip-blocklist
              cat /etc/fail2ban/ip.blocklist.<name> |grep -v ^\s*#|awk ‘{print $1}’ | while read IP; do iptables -I f2b-ip-blocklist 1 -s $IP -j REJECT –reject-with icmp-port-unreachable; done

# Option:  actionstop
# Notes.:  command executed once at the end of Fail2Ban
# Values:  CMD
#
actionstop = iptables -D <chain> -p <protocol> -j f2b-<name>
             iptables -F f2b-<name>
             iptables -X f2b-<name>
             # Remove chain and blocks for saved IPs to prevent duplicates on service restart
             iptables -D <chain> -p <protocol> -j f2b-ip-blocklist
             iptables -F f2b-ip-blocklist
             iptables -X f2b-ip-blocklist

# Option:  actioncheck
# Notes.:  command executed once before each actionban command
# Values:  CMD
#
actioncheck = iptables -n -L <chain> | grep -q ‘f2b-<name>[ \t]’

# Option:  actionban
# Notes.:  command executed when banning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionban = VERIFY=”<ip>*”
            ADD=”<ip>        # f2b/$( date ‘+%%Y-%%m-%%d %%T’ ): Perma-Banned”
            FILE=/etc/fail2ban/ip.blocklist.<name>
            grep -q “$VERIFY” “$FILE” || iptables -I f2b-<name>  1 -s <ip> -j DROP
            grep -q “$VERIFY” “$FILE” || echo “$ADD” >> “$FILE”

# Option:  actionunban
# Notes.:  command executed when unbanning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionunban = # Do nothing becasuse their IP is in the blocklist file

# To manually unban from the ip blocklist file run this command:
# Be warned that if the ip is in log rotated files it must be whitelisted
#
# sed -i ‘/^<ip>/d’ /etc/fail2ban/ip.blocklist.repeatoffender
#

[Init]
# Default name of the chain
#
name = default

# Option:  protocol
# Notes.:  internally used by config reader for interpolations.
# Values:  [ tcp | udp | icmp | all ] Default: tcp
#
protocol = all

# Option:  chain
# Notes    specifies the iptables chain to which the fail2ban rules should be
#          added
# Values:  STRING  Default: INPUT
chain = INPUT

# Fail2Ban configuration file - repeat offenders
[INCLUDES]
before = iptables-common.conf

[Definition]
# Option:  actionstart
# Notes.:  command executed once at the start of Fail2Ban.
# Values:  CMD
#
actionstart = iptables -N f2b-<name>
              iptables -A f2b-<name> -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-<name>
              # Establish chain and blocks for saved IPs
              iptables -N f2b-ip-blocklist
              iptables -A f2b-ip-blocklist -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-ip-blocklist
              cat /etc/fail2ban/ip.blocklist.<name> |grep -v ^\s*#|awk '{print $1}' | while read IP; do iptables -I f2b-ip-blocklist 1 -s $IP -j REJECT --reject-with icmp-port-unreachable; done

# Option:  actionstop
# Notes.:  command executed once at the end of Fail2Ban
# Values:  CMD
#
actionstop = iptables -D <chain> -p <protocol> -j f2b-<name>
             iptables -F f2b-<name>
             iptables -X f2b-<name>
             # Remove chain and blocks for saved IPs to prevent duplicates on service restart
             iptables -D <chain> -p <protocol> -j f2b-ip-blocklist
             iptables -F f2b-ip-blocklist
             iptables -X f2b-ip-blocklist

# Option:  actioncheck
# Notes.:  command executed once before each actionban command
# Values:  CMD
#
actioncheck = iptables -n -L <chain> | grep -q 'f2b-<name>[ \t]'

# Option:  actionban
# Notes.:  command executed when banning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionban = VERIFY="<ip>*"
            ADD="<ip>        # f2b/$( date '+%%Y-%%m-%%d %%T' ): Perma-Banned"
            FILE=/etc/fail2ban/ip.blocklist.<name>
            grep -q "$VERIFY" "$FILE" || iptables -I f2b-<name>  1 -s <ip> -j DROP
            grep -q "$VERIFY" "$FILE" || echo "$ADD" >> "$FILE"

# Option:  actionunban
# Notes.:  command executed when unbanning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionunban = # Do nothing becasuse their IP is in the blocklist file

# To manually unban from the ip blocklist file run this command:
# Be warned that if the ip is in log rotated files it must be whitelisted
#
# sed -i '/^<ip>/d' /etc/fail2ban/ip.blocklist.repeatoffender
#

[Init]
# Default name of the chain
#
name = default

# Option:  protocol
# Notes.:  internally used by config reader for interpolations.
# Values:  [ tcp | udp | icmp | all ] Default: tcp
#
protocol = all

# Option:  chain
# Notes    specifies the iptables chain to which the fail2ban rules should be
#          added
# Values:  STRING  Default: INPUT
chain = INPUT

With the actions defined, a filter can be created. To do so, open a new file /etc/fail2ban/filter.d/repeatoffender.conf and paste in the following content:

# Fail2Ban configuration file - repeat offenders
# This filter monitors the fail2ban log file, and permanently
# bans the ip addresses of persistent attackers.

[Definition]
_daemon = repeatoffender
failregex = fail2ban.actions\s+.+:\s+NOTICE\s+\[(?:.*)\]\s+Ban\s+<HOST>
ignoreregex = fail2ban\.actions\s+\[.+\]:\s+NOTICE\s+\[%(_daemon)s\]\s+Ban\s+<HOST>

A jail can be defined now that the filter and related actions are in place. Open a new file /etc/fail2ban/jail.d/repeatoffender.conf and paste in the following content:

[repeatoffender]
enabled  = true
backend = auto
mode     = agressive
filter   = repeatoffender
action   = repeatoffender[name=repeatoffender]
           sendmail-whois[name=Repeat-Offender, dest=root, sender=F2B-Alerts-<fq-hostname>]
logpath  = /var/log/fail2ban.log*
maxretry = 5
findtime = 31536000
bantime  = -1

In my example above, I’ve set findtime to 31536000 seconds, which is one year. I’ve also set logpath to /var/log/fail2ban.log*, and the * at the end will instruct Fail2Ban to examine all logs named as “fail2ban.log” and anything that might be behind that (default is fail2ban.log.1, fail2ban.log.2 and so on). According to that, I reconfigured the Fail2Ban log rotation file to match my jail settings. I’ve set the log rotation period to monthly (log will be rotated once a month) and retention to 12 (12 months of logs will be saved). To do the same, open /etc/logrotate.d/fail2ban file, and adjust the values accordingly:

/var/log/fail2ban.log {

    # weekly
    monthly
    # rotate 4
    rotate 12
    # compress

    # delaycompress
    missingok
    notifempty
    postrotate
        fail2ban-client flushlogs 1>/dev/null
    endscript

    # If fail2ban runs as non-root it still needs to have write access
    # to logfiles.
    # create 640 fail2ban adm
    create 640 root adm
}

To finish, restart the Fail2Ban service, and repeat offender jail will start with its work. To depict the scale of possible attacks and the importance of these security measures and tools, such as Fail2ban, I have this filter running on a small public VPS. For the four years since it has been active, it has banned more than 48000 unique IP addresses. That is a huge number, so huge that Iptables and my VPS couldn’t handle such a large number, and I had to reset the filter.

HTTP/HTTPS Configuration

When we are talking about HTTP/HTTPS and attacks on web servers in general, the most common ones are DDOS attacks. The other typical case “can’t” be quite considered as an attack. However, it can still disrupt the normal operations of a web server: poorly configured (mostly on purpose) web crawlers whose crawl rate is way above something that can be considered normal.

The most common web server “services” on Linux are Apache and Nginx, and I will show you how to configure a Fail2Ban filter for the latter. Under the presumption that you are running a self-hosted web server with Nginx running on it, I highly recommend installing Nginx Ultimate Bad Bot & Referrer Blocker by Mitchell Krog. Combined with the Fail2Ban, you can protect your Nginx web server against (almost) all possible attacks.

No Web Server

If you set this filter/jail without running a web server “service,” Fail2Ban will fail to start due to non-existent logs. You can skip this section altogether if you don’t plan to use a web server.

To start with this, you must know where Nginx stores logs. Usually, I have a general Nginx log written in the /var/log/nginx/access.log file, and I have separate logs for each domain (website) I’m hosting on the server. Their logs are written in /home/websites/$DOMAIN/logs/access.log, where $DOMAIN stands for the domain of the website.

Once you determine where Nginx stores logs, you can start with the Fail2Ban configuration. First, you must create a “helper” file to store violating IP addresses. To do so, execute the following commands in the Terminal:

touch /etc/fail2ban/ip.blocklist.nginx.repeatoffender
chmod 770 /etc/fail2ban/ip.blocklist.nginx.repeatoffender

Now, you can define an action file. To create one, open a new file /etc/fail2ban/action.d/nginx-repeatoffender.conf and paste in the following content:

[INCLUDES]
before = iptables-common.conf

[Definition]
# Option:  actionstart
# Notes.:  command executed once at the start of Fail2Ban.
# Values:  CMD
#

actionstart = iptables -N f2b-<name>
              iptables -A f2b-<name> -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-<name>
              # Sort and Check for Duplicate IPs in our text file and Remove Them
              sort -u /etc/fail2ban/ip.blocklist.nginx.repeatoffender -o /etc/fail2ban/ip.blocklist.nginx.repeatoffender
              # Persistent banning of IPs reading from our ip.blocklist.nginx.repeatoffender text file
              # and adding them to IPTables on our jail startup command
              cat /etc/fail2ban/ip.blocklist.nginx.repeatoffender | while read IP; do iptables -I f2b-<name> 1 -s $IP -p tcp -m multiport –dports 80,443 -j DROP; done

# Option:  actionstop
# Notes.:  command executed once at the end of Fail2Ban
# Values:  CMD
#

actionstop = iptables -D <chain> -p <protocol> -j f2b-<name>
             iptables -F f2b-<name>
             iptables -X f2b-<name>

# Option:  actioncheck
# Notes.:  command executed once before each actionban command
# Values:  CMD
#

actioncheck = iptables -n -L <chain> | grep -q ‘f2b-<name>[ \t]’

# Option:  actionban
# Notes.:  command executed when banning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#

actionban = <iptables> -I f2b-<name> 1 -s <ip> -p tcp -m multiport –dports 80,443 -j DROP
            # Add the new IP ban to our nginx.repeatoffender file
            echo ‘<ip>’ >> /etc/fail2ban/ip.blocklist.nginx.repeatoffender

# Option:  actionunban
# Notes.:  command executed when unbanning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionunban = <iptables> -D f2b-<name> -s <ip> -p tcp -m multiport –dports 80,443 -j DROP
            # Remove IP from our nginx.repeatoffender file
            sed -i -e ‘/<ip>/d’ /etc/fail2ban/ip.blocklist.nginx.repeatoffender

[Init]

[INCLUDES]
before = iptables-common.conf

[Definition]
# Option:  actionstart
# Notes.:  command executed once at the start of Fail2Ban.
# Values:  CMD
#

actionstart = iptables -N f2b-<name>
              iptables -A f2b-<name> -j RETURN
              iptables -I <chain> -p <protocol> -j f2b-<name>
              # Sort and Check for Duplicate IPs in our text file and Remove Them
              sort -u /etc/fail2ban/ip.blocklist.nginx.repeatoffender -o /etc/fail2ban/ip.blocklist.nginx.repeatoffender
              # Persistent banning of IPs reading from our ip.blocklist.nginx.repeatoffender text file
              # and adding them to IPTables on our jail startup command
              cat /etc/fail2ban/ip.blocklist.nginx.repeatoffender | while read IP; do iptables -I f2b-<name> 1 -s $IP -p tcp -m multiport --dports 80,443 -j DROP; done

# Option:  actionstop
# Notes.:  command executed once at the end of Fail2Ban
# Values:  CMD
#

actionstop = iptables -D <chain> -p <protocol> -j f2b-<name>
             iptables -F f2b-<name>
             iptables -X f2b-<name>

# Option:  actioncheck
# Notes.:  command executed once before each actionban command
# Values:  CMD
#

actioncheck = iptables -n -L <chain> | grep -q 'f2b-<name>[ \t]'

# Option:  actionban
# Notes.:  command executed when banning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#

actionban = <iptables> -I f2b-<name> 1 -s <ip> -p tcp -m multiport --dports 80,443 -j DROP
            # Add the new IP ban to our nginx.repeatoffender file
            echo '<ip>' >> /etc/fail2ban/ip.blocklist.nginx.repeatoffender

# Option:  actionunban
# Notes.:  command executed when unbanning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    See jail.conf(5) man page
# Values:  CMD
#
actionunban = <iptables> -D f2b-<name> -s <ip> -p tcp -m multiport --dports 80,443 -j DROP
            # Remove IP from our nginx.repeatoffender file
            sed -i -e '/<ip>/d' /etc/fail2ban/ip.blocklist.nginx.repeatoffender

[Init]

Now, a filter can be defined. To do so, open a new file /etc/fail2ban/filter.d/nginx-repeatoffender.conf and paste in the following content:

[Definition]

_daemon = fail2ban\.actions\s*

# The name of the jail that this filter is used for. In jail.conf, name the
# jail using this filter 'nginx-repeatoffender', or change this line!
_jailname = nginx-repeatoffender
failregex = ^<HOST> \- \S+ \[\] \"(GET|POST|HEAD) .* \S+\" (?:400|401|403|444) .+$
ignoreregex =

With the filter and its actions defined, a jail can now be configured. To do so, please open a new file /etc/fail2ban/jail.d/nginx-repeatoffender.conf and paste in the following content:

[nginx-repeatoffender]
enabled = true
backend = auto
mode    = agressive
logpath = /var/log/nginx/*access.log
          /home/websites/*/logs/access.log
filter = nginx-repeatoffender
action = nginx-repeatoffender[name=nginx-repeatoffender]
         sendmail-whois[name=Nginx Repeat-Offender, dest=root, sender=F2B-Alerts-<fq-hostname>]
bantime  = 86400   ; 1 day
findtime = 604800   ; 1 week
maxretry = 15

You can restart the Fail2Ban service now to make it all work. This filter will monitor all logs defined in /etc/fail2ban/jail.d/nginx-repeatoffender.conf jail (logpath option) and block all attempts that result in statuses 400, 401, 403, and 444, and according to options set for findtime and maxretry.

Optional – Abuse Reports

In the Main Configuration Files section above in this guide, I mentioned an option to report the violating host/IP address to the organization “in charge” of that host or IP address. Fail2Ban can be instructed to use a special action (action = %(action_xarf)s) to do that. Before I show you how to do it, let’s examine what information Fail2Ban needs to send such a report.

First of all, a violating IP address must be banned by Fail2Ban. Once an IP address gets banned, Fail2Ban will use whois to find relevant information to generate an abuse report. Let’s examine how that works by looking at an imaginary IP address that gets banned by Fail2Ban:

$ whois XX.XXX.XXX.XXX
% This is the RIPE Database query service.
% The objects are in RPSL format.
%
% The RIPE Database is subject to Terms and Conditions.
% See https://apps.db.ripe.net/docs/HTML-Terms-And-Conditions

% Note: this output has been filtered.
%       To receive output for a database update, use the "-B" flag.

% Information related to 'XX.XXX.XXX.0 - XX.XXX.XXX.255'

% Abuse contact for 'XX.XXX.XXX.0 - XX.XXX.XXX.255' is '[email protected]'

inetnum:        XX.XXX.XXX.0 - XX.XXX.XXX.255
netname:        AUTH-ORG
country:        XX
org:            ORG-PLXXX-RIPE
admin-c:        PLXXXXX-RIPE
tech-c:         PLXXXXX-RIPE
status:         ASSIGNED PA
mnt-by:         IP-RIPE
created:        XXXX-XX-XXT20:14:04Z
last-modified:  XXXX-XX-XXT20:14:07Z
source:         RIPE

organisation:   ORG-PLXXX-RIPE
org-name:       Auth Org LLC
org-type:       OTHER
address:        xx-xx Xxxxxxx, x. XXXX, xx. 000
address:        000000 Utopia Square
address:        Utopia
abuse-c:        PLXXXXX-RIPE
mnt-ref:        IP-RIPE
mnt-by:         IP-RIPE
created:        XXXX-XX-XXT20:10:41Z
last-modified:  XXXX-XX-XXT20:10:41Z
source:         RIPE # Filtered

role:           Auth Org LLC
nic-hdl:        PLXXXXX-RIPE
address:        xx-xx Xxxxxxx, x. XXXX, XX. 000
address:        000000 Utopia Square
address:        Utopia
abuse-mailbox:  [email protected]
phone:          +0 000 1111111
mnt-by:         IP-RIPE
created:        XXXX-XX-XXT20:09:34Z
last-modified:  XXXX-XX-XXT20:10:30Z
source:         RIPE # Filtered

% Information related to 'XX.XXX.XXX.0/24AS000000'

route:          XX.XXX.XXX.0/24
origin:         AS000000
mnt-by:         IP-RIPE
created:        XXXX-XX-XXT19:15:16Z
last-modified:  XXXX-XX-XXT19:15:16Z
source:         RIPE

% This query was served by the RIPE Database Query Service version 1.108 (ABERDEEN)

GDPR – Redacted Data

Due to the fact that I live in Croatia and Zack’s is hosted in an EU country, please accept my apologies for using “redacted” data. According to the EU GDPR law, IP addresses and all related data are considered personal data and, as such, cannot be published publicly.

Looking at the example above, Fail2Ban will generate the report and send it to an abuse email (abuse-mailbox: [email protected]) extracted from results given by the whois output. To put this to work, open a new file /etc/fail2ban/action.d/xarf-login-attack.conf and paste in the following content:

[Definition]

# bypass ban/unban for restored tickets
norestored = 1

#actionban = oifs=${IFS}; IFS=.;SEP_IP=( <ip> ); set — ${SEP_IP}; ADDRESSES=$(dig +short -t txt -q $4.$3.$2.$1.abuse-contacts.abusix.org); IFS=${oifs}
actionban = oifs=${IFS};
            RESOLVER_ADDR=”%(addr_resolver)s”
            if [ “<debug>” -gt 0 ]; then echo “try to resolve $RESOLVER_ADDR”; fi
            ADDRESSES=$(dig +short +tcp -t txt -q $RESOLVER_ADDR | tr -d ‘”‘)
            IFS=,; ADDRESSES=$(echo $ADDRESSES)
            IFS=${oifs}
            IP=<ip>
            FROM=<sender>
            SERVICE=<service>
            FAILURES=<failures>
            REPORTID=<time>@<fq-hostname>
            TLP=<tlp>
            PORT=<port>
            DATE=`LC_ALL=C date –date=@<time> +”%%a, %%d %%h %%Y %%T %%z”`
            if [ ! -z “$ADDRESSES” ]; then
                oifs=${IFS}; IFS=,; ADDRESSES=$(echo $ADDRESSES)
                IFS=${oifs}
                (printf — %%b “<header>\n<message>\n<report>\n\n”;
                 date ‘+Note: Local timezone is %%z (%%Z)’;
                 #printf — %%b “\n<ipmatches>\n\n<footer>”) | <mailcmd> <mailargs> ${ADDRESSES//,/\” \”}
                 printf — %%b “\n<ipmatches>\n\n<footer>”) | <mailcmd> <mailargs> $ADDRESSES
            fi

# Server as resolver used in dig command
#
addr_resolver = <ip-rev>abuse-contacts.abusix.org

# Option: boundary
# Notes:  This can be overwritten to be safe for possible predictions
boundary = bfbb0f920793ac03cb8634bde14d8a1e

_boundary = Abuse<time>-<boundary>

# Option: header
# Notes:  This is really a fixed value
#header  = Subject: abuse report about $IP – $DATE\nAuto-Submitted: auto-generated\nX-XARF: PLAIN\nContent-Transfer-Encoding: 7bit\nContent-Type: multipart/mixed; charset=utf8;\n  boundary=Abuse-bfbb0f920793ac03cb8634bde14d8a1e;\n\n–Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8;\n
header  = Subject: abuse report about $IP – $DATE\nAuto-Submitted: auto-generated\nX-XARF: PLAIN\nContent-Transfer-Encoding: 7bit\nContent-Type: multipart/mixed; charset=utf8;\n  boundary=%(_boundary)s;\n\n–%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8;\n

# Option: footer
# Notes:  This is really a fixed value and needs to match the report and header
#         mime delimiters
#footer = \n\n–Abuse-bfbb0f920793ac03cb8634bde14d8a1e–
footer = \n\n–%(_boundary)s–

# Option: report
# Notes:  Intended to be fixed
#report =  –Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8; name=\”report.txt\”;\n\n—\nReported-From: $FROM\nCategory: abuse\nReport-ID: $REPORTID\nReport-Type: login-attack\nService: $SERVICE\nVersion: 0.2\nUser-Agent: Fail2ban v0.9\nDate: $DATE\nSource-Type: ip-address\nSource: $IP\nPort: $PORT\nSchema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json\nAttachment: text/plain\nOccurances: $FAILURES\nTLP: $TLP\n\n\n–Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf8; name=\”logfile.log\”;
report =  –%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8; name=\”report.txt\”;\n\n—\nReported-From: $FROM\nCategory: abuse\nReport-ID: $REPORTID\nReport-Type: login-attack\nService: $SERVICE\nVersion: 0.2\nUser-Agent: Fail2ban v0.9\nDate: $DATE\nSource-Type: ip-address\nSource: $IP\nPort: $PORT\nSchema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json\nAttachment: text/plain\nOccurances: $FAILURES\nTLP: $TLP\n\n\n–%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf8; name=\”logfile.log\”;

# Option: Message
# Notes:  This can be modified by the users
message = Dear Sir/Madam,\n\nWe have detected abuse from the IP address $IP, which according to abusix.com is on your network. We would appreciate if you would investigate and take action as appropriate.\n\nLog lines are given below, but please ask if you require any further information.\n\n(If you are not the correct person to contact about this please accept our apologies – your e-mail address was extracted from the whois record by an automated process.)\n\n This mail was generated by Fail2Ban in a X-ARF format! You can find more information about x-arf at http://www.x-arf.org/specification.html.\n\nThe recipient address of this report was provided by the Abuse Contact DB by abusix.com. abusix.com does not maintain the content of the database. All information which we pass out, derives from the RIR databases and is processed for ease of use. If you want to change or report non working abuse contacts please contact the appropriate RIR. If you have any further question, contact abusix.com directly via email (info@abusix.com). Information about the Abuse Contact Database can be found here: https://abusix.com/global-reporting/abuse-contact-db\nabusix.com is neither responsible nor liable for the content or accuracy of this message.\n

# Option:  loglines
# Notes.:  The number of log lines to search for the IP for the report
loglines = 9000

# Option:  mailcmd
# Notes.:  Your system mail command. It is passed the recipient
# Values:  CMD
#
mailcmd =  /usr/sbin/sendmail

# Option:  mailargs
# Notes.:  Additional arguments to mail command. e.g. for standard Unix mail:
#          CC reports to another address:
#              -c me@example.com
#          Appear to come from a different address – the ‘–‘ indicates
#          arguments to be passed to Sendmail:
#              — -f me@example.com
# Values:  [ STRING ]
#
mailargs = -f <sender>

# Option:  tlp
# Notes.:  Traffic light protocol defining the sharing of this information.
#          http://www.trusted-introducer.org/ISTLPv11.pdf
#          green is share to those involved in network security but it is not
#          to be released to the public.
tlp = green

# ALL of the following parameters should be set so the report contains
# meaningful information

# Option: service
# Notes.: This is the service type that was attacked. e.g. ssh, pop3
service = unspecified

# Option:  logpath
# Notes:   Path to the log files which contain relevant lines for the abuser IP
# Values:  Filename(s) space separated and can contain wildcards (these are
#          greped for the IP so make sure these aren’t too long
logpath = /dev/null

# Option:  sender
# Notes.:  This is the sender that is included in the XARF report
sender = fail2ban@example.com

# Option:  port
# Notes.:  This is the port number that received the login-attack
port = 0

[Definition]

# bypass ban/unban for restored tickets
norestored = 1

#actionban = oifs=${IFS}; IFS=.;SEP_IP=( <ip> ); set -- ${SEP_IP}; ADDRESSES=$(dig +short -t txt -q $4.$3.$2.$1.abuse-contacts.abusix.org); IFS=${oifs}
actionban = oifs=${IFS};
            RESOLVER_ADDR="%(addr_resolver)s"
            if [ "<debug>" -gt 0 ]; then echo "try to resolve $RESOLVER_ADDR"; fi
            ADDRESSES=$(dig +short +tcp -t txt -q $RESOLVER_ADDR | tr -d '"')
            IFS=,; ADDRESSES=$(echo $ADDRESSES)
            IFS=${oifs}
            IP=<ip>
            FROM=<sender>
            SERVICE=<service>
            FAILURES=<failures>
            REPORTID=<time>@<fq-hostname>
            TLP=<tlp>
            PORT=<port>
            DATE=`LC_ALL=C date --date=@<time> +"%%a, %%d %%h %%Y %%T %%z"`
            if [ ! -z "$ADDRESSES" ]; then
                oifs=${IFS}; IFS=,; ADDRESSES=$(echo $ADDRESSES)
                IFS=${oifs}
                (printf -- %%b "<header>\n<message>\n<report>\n\n";
                 date '+Note: Local timezone is %%z (%%Z)';
                 #printf -- %%b "\n<ipmatches>\n\n<footer>") | <mailcmd> <mailargs> ${ADDRESSES//,/\" \"}
                 printf -- %%b "\n<ipmatches>\n\n<footer>") | <mailcmd> <mailargs> $ADDRESSES
            fi

# Server as resolver used in dig command
#
addr_resolver = <ip-rev>abuse-contacts.abusix.org

# Option: boundary
# Notes:  This can be overwritten to be safe for possible predictions
boundary = bfbb0f920793ac03cb8634bde14d8a1e

_boundary = Abuse<time>-<boundary>

# Option: header
# Notes:  This is really a fixed value
#header  = Subject: abuse report about $IP - $DATE\nAuto-Submitted: auto-generated\nX-XARF: PLAIN\nContent-Transfer-Encoding: 7bit\nContent-Type: multipart/mixed; charset=utf8;\n  boundary=Abuse-bfbb0f920793ac03cb8634bde14d8a1e;\n\n--Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8;\n
header  = Subject: abuse report about $IP - $DATE\nAuto-Submitted: auto-generated\nX-XARF: PLAIN\nContent-Transfer-Encoding: 7bit\nContent-Type: multipart/mixed; charset=utf8;\n  boundary=%(_boundary)s;\n\n--%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8;\n

# Option: footer
# Notes:  This is really a fixed value and needs to match the report and header
#         mime delimiters
#footer = \n\n--Abuse-bfbb0f920793ac03cb8634bde14d8a1e--
footer = \n\n--%(_boundary)s--

# Option: report
# Notes:  Intended to be fixed
#report =  --Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8; name=\"report.txt\";\n\n---\nReported-From: $FROM\nCategory: abuse\nReport-ID: $REPORTID\nReport-Type: login-attack\nService: $SERVICE\nVersion: 0.2\nUser-Agent: Fail2ban v0.9\nDate: $DATE\nSource-Type: ip-address\nSource: $IP\nPort: $PORT\nSchema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json\nAttachment: text/plain\nOccurances: $FAILURES\nTLP: $TLP\n\n\n--Abuse-bfbb0f920793ac03cb8634bde14d8a1e\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf8; name=\"logfile.log\";
report =  --%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf-8; name=\"report.txt\";\n\n---\nReported-From: $FROM\nCategory: abuse\nReport-ID: $REPORTID\nReport-Type: login-attack\nService: $SERVICE\nVersion: 0.2\nUser-Agent: Fail2ban v0.9\nDate: $DATE\nSource-Type: ip-address\nSource: $IP\nPort: $PORT\nSchema-URL: http://www.x-arf.org/schema/abuse_login-attack_0.1.2.json\nAttachment: text/plain\nOccurances: $FAILURES\nTLP: $TLP\n\n\n--%(_boundary)s\nMIME-Version: 1.0\nContent-Transfer-Encoding: 7bit\nContent-Type: text/plain; charset=utf8; name=\"logfile.log\";

# Option: Message
# Notes:  This can be modified by the users
message = Dear Sir/Madam,\n\nWe have detected abuse from the IP address $IP, which according to abusix.com is on your network. We would appreciate if you would investigate and take action as appropriate.\n\nLog lines are given below, but please ask if you require any further information.\n\n(If you are not the correct person to contact about this please accept our apologies - your e-mail address was extracted from the whois record by an automated process.)\n\n This mail was generated by Fail2Ban in a X-ARF format! You can find more information about x-arf at http://www.x-arf.org/specification.html.\n\nThe recipient address of this report was provided by the Abuse Contact DB by abusix.com. abusix.com does not maintain the content of the database. All information which we pass out, derives from the RIR databases and is processed for ease of use. If you want to change or report non working abuse contacts please contact the appropriate RIR. If you have any further question, contact abusix.com directly via email ([email protected]). Information about the Abuse Contact Database can be found here: https://abusix.com/global-reporting/abuse-contact-db\nabusix.com is neither responsible nor liable for the content or accuracy of this message.\n

# Option:  loglines
# Notes.:  The number of log lines to search for the IP for the report
loglines = 9000

# Option:  mailcmd
# Notes.:  Your system mail command. It is passed the recipient
# Values:  CMD
#
mailcmd =  /usr/sbin/sendmail

# Option:  mailargs
# Notes.:  Additional arguments to mail command. e.g. for standard Unix mail:
#          CC reports to another address:
#              -c [email protected]
#          Appear to come from a different address - the '--' indicates
#          arguments to be passed to Sendmail:
#              -- -f [email protected]
# Values:  [ STRING ]
#
mailargs = -f <sender>

# Option:  tlp
# Notes.:  Traffic light protocol defining the sharing of this information.
#          http://www.trusted-introducer.org/ISTLPv11.pdf
#          green is share to those involved in network security but it is not
#          to be released to the public.
tlp = green

# ALL of the following parameters should be set so the report contains
# meaningful information

# Option: service
# Notes.: This is the service type that was attacked. e.g. ssh, pop3
service = unspecified

# Option:  logpath
# Notes:   Path to the log files which contain relevant lines for the abuser IP
# Values:  Filename(s) space separated and can contain wildcards (these are
#          greped for the IP so make sure these aren't too long
logpath = /dev/null

# Option:  sender
# Notes.:  This is the sender that is included in the XARF report
sender = [email protected]

# Option:  port
# Notes.:  This is the port number that received the login-attack
port = 0

Remember, this will only work if an option action = %(action_xarf) is set in the /etc/fail2ban/jail.local file. If it is, restart the Fail2Ban service, and abuse reporting should start sending reports automatically.

To conclude, I can’t promise everything above will work as described in this guide. Some modifications may be required, but making the necessary adjustments should be easy. Thank you for reading, and please share the article if you liked it.

Server Environment (4)

Ubuntu (14)

Spread The Word

Cancel Reply

May 28, 2024 Reply
Tony
Thanks a lot, very nice guide to hardening fail2ban,
1. April 15, 2025 Reply
  Guido
  Thanks alot for this guide. I followed the fail2ban guide and incorporated it to my VPS
  1. Author
    April 16, 2025 Reply
    Željko Jagušt
    Hello Guido,
    Thank you for your feedback. I am so glad to hear that fail2ban works for you.

Latest on Zack's

MONTHLY POLL

Loading ...