# Fail2ban [TOC] ## Installation - Installing Fail2ban on a Debian based system ```bash= sudo apt-get install fail2ban ``` - The following software are optional but recommended - iptables - `sudo apt-get install iptables` - shorewall - `sudo apt-get install shorewall` - tcp-wrappers - a working `mail` command - Gamin (File Alteration Monitor) - Files under `/etc/fail2ban/` ``` action.d fail2ban.d jail.conf paths-arch.conf paths-debian.conf fail2ban.conf filter.d jail.d paths-common.conf paths-opensuse.conf ``` > - `.d` means it's a directory > - All of `.conf` should write via root permission :::info More details for [**path of file**](https://hackmd.io/ChjFSVSLRJ-E7vRnnvGswQ#Path-of-File) ::: ## Terms in Fail2ban ### Filter - Defines a **regular expression**. > Must match a pattern corresponding to a log-in failure or any other expression. :::info More details for [**filter**](https://hackmd.io/ChjFSVSLRJ-E7vRnnvGswQ#Filters) ::: ### Action - Defines **commands** which are executed at different moments. - The directory `action.d` contains different scripts defining actions. - The actions are executed at well-defined moments during the execution of Fail2ban. ### Jail - A combination of one filter and several actions. - Fail2ban can handle several jails at the same time. :::info More details for [**jail**](https://hackmd.io/ChjFSVSLRJ-E7vRnnvGswQ#Jails) ::: ### Client & Server (Including several commands) - Fail2ban is composed of 2 parts: a client and a server. #### **Server** - Multi-threaded - **Listens on a Unix socket for commands** - Knows nothing about the configuration files > At start-up, the server is in a "default" state in which no jails are defined. - Options for the script `fail2ban-server` > Should not be used directly except in case of debugging. - `-b`: start in background - `-f`: start in foreground - `-s <FILE>`: used to set the socket path > It is possible to run several instances of Fail2ban on different sockets. However, this should be not required because Fail2ban can run several jails concurrently. - `-x`: force execution of the server to delete the socket file before start-up > If `fail2ban-server` crashes, it is possible that the socket file has not been removed correctly. > If the socket file of a running server is removed, it is not possible to communicate with this server anymore. - `-h` or `--help`: display this help message - `-V` or `--version`: print the version #### **Client** - The **frontend** of Fail2ban. - Connects to the server socket file and **sends commands** in order to **configure and operate the server**. > Client can also start the server. - **Read the configuration files** or **send a single command** to the server using either the command line or the interactive mode. > Interactive mode is activated with the `-i` option. - Options for the script `fail2ban-client` - Same as options used in `fail2ban-server` - `-s <FILE>`: socket path >　This option overrides the socket option set in `fail2ban.conf`. - `-x` force execution of the server - `-h` or `--help`: display this help message - `-V` or `--version`: print the version - Others - `-c <DIR>`: configuration directory > The default configuration directory is `/etc/fail2ban` but can be override with this option. - `-d`: dump configuration > For debugging, prints the configuration parsed by fail2ban-client. The output corresponds to the stream sent to the server. - `-i`: interactive mode - `-v`: increase verbosity - `-q`: decrease verbosity - Commands for client's internal use - Start ```bash= fail2ban-client start ``` - The client will first try to fork a server instance, then waits for the server to start-up by sending ping requests to it. - Reload ```bash= fail2ban-client reload ``` - The client will tell the server to stop all jails, parses the configuration files again and send the commands to the server. - This is useful when a new configuration must be loaded without shutting down the server or when debugging the server. - Stop ```bash= fail2ban-client stop ``` - Status ```bash= status [jail] ``` - Display the status of this jail. > Without a jail name, the global status of the server is returned. :::info A list with all [**commands**](https://www.fail2ban.org/wiki/index.php/Commands) ::: ## Configuration ### Path of File - The standard path for the configuration is in `/etc/fail2ban`. > This can be set with the `-c` option of `fail2ban-client`. - Typical configuration ``` /etc/fail2ban/ ├── action.d │ ├── dummy.conf │ ├── hostsdeny.conf │ ├── iptables.conf │ ├── mail-whois.conf │ ├── mail.conf │ └── shorewall.conf ├── fail2ban.conf ├── fail2ban.local ├── filter.d │ ├── apache-auth.conf │ ├── apache-noscript.conf │ ├── couriersmtp.conf │ ├── postfix.conf │ ├── proftpd.conf │ ├── qmail.conf │ ├── sasl.conf │ ├── sshd.conf │ └── vsftpd.conf ├── jail.conf └── jail.local ``` - Every `.conf` file can be overridden with a file named `.local`. - The `.conf` file is read first, then `.local`, with later settings overriding earlier ones. :::danger Modifications should take place in the `.local` and not in the `.conf`. This avoids merging problem when upgrading. ::: - The file `fail2ban.conf` contains general settings for the `fail2ban-server` daemon. > Can also specify here the socket path used for communication between the client and the server. ### Jails - `jail.conf` contains the **declaration of jails**. > By default, some sections are inserted as templates. > Enable the sections of interest and adapt to local configuration. - Filter and actions are combined to create jails. - Only one filter is allowed per jail, but it is possible to specify several actions, on separate lines. #### Options in jail - filter - **Name of the filter** to be used by the jail to detect matches. - In the `filter.d` shows a few default filters that don't occur in the standard `jail.conf` which come with the sources. - logpath - **Path to the log file** which is provided to the filter - Default path: `/var/log/messages` - maxretry - **Number of matches** (i.e. value of the counter) which triggers ban action on the IP. - Default value: 3 - findtime - The counter is set to zero if no match is found within "findtime" seconds. - Default value: 600 sec - bantime - Duration (in seconds) for IP to be banned for. - Negative number for "permanent" ban. - Default value: 600 sec :::warning Always remember to adjust `logpath` to your log-file. ::: #### Example of the `ssh-iptables` section: ``` [ssh-iptables] enabled = true filter = sshd action = iptables[name=SSH, port=ssh, protocol=tcp] # mail-whois[name=SSH, dest=yourmail@mail.com] logpath = /var/log/auth.log maxretry = 5 ``` > With these settings a few things will happen: > 1. the section ssh-iptables is enabled. > 2. the filter `sshd.conf` in sub-directory `filter.d` will be processed. > 3. the action(s) described in `iptables.conf` (sub-directory in `action.d`) will be executed if the outcome of the filter process is true. In this example, the additional action `mail-whois.conf` is commented out. > 4. the log file to be scanned by the filter is `auth.log`. #### Example of the `ssh-ddos` section: ``` [ssh-ddos] enabled = true port = ssh,sftp filter = sshd-ddos logpath = /var/log/messages maxretry = 2 ``` ### Filters - The directory `filter.d` contains mainly **regular expressions** which are used to detect break-in attempts, password failures, etc. #### Failregex (Fail regular expressions) - A failregex can have multiple lines, any one of which may match a line of the log file. - In every line of failregex, the part that matches the hostname or IP address must be wrapped in a `(?P<host> ... )` sandwich. - The `<host>` tag is how you tell fail2ban which host was connecting, so it has to be present in every line of failregex. > If it's not, fail2ban will issue an error message about "No 'host' group". - Use the predefined entity `<HOST>` in your regexes as a convenience. > `<HOST>` is an alias for `(?:::f{4,6}:)?(?P<host>\S+)`, which matches either a hostname or an IPv4 address. - In the action scripts, the tag `<ip>` will be replaced by the IP address of the host that was matched in the `<host>` tag. - In order for a logline to match your failregex, it actually has to match in two parts - the beginning of the line has to match a **timestamp pattern or regex** - the remainder of the line has to match **failregex**. - If the failregex is anchored with a leading `^`, then the anchor refers to the start of the remainder of the line, after the timestamp and intervening whitespace. #### Example for `filter.d/sshd.conf` ``` failregex = Authentication failure for .* from <HOST> Failed [-/\w]+ for .* from <HOST> ROOT LOGIN REFUSED .* FROM <HOST> [iI](?:llegal|nvalid) user .* from <HOST> ``` ## Implementation - Install ```bash= sudo apt-get install fail2ban sudo apt-get install iptables sudo apt-get install shorewall ``` > ubuntu 18.04 already installed `iptables` package - Files already in /etc/fail2ban ``` /etc/fail2ban/ ├── fail2ban.d ├── jail.d │ └── defaults-debian.conf ├── filter.d │ ├── apache-auth.conf │ ├── apache-noscript.conf │ ├── couriersmtp.conf │ ├── postfix.conf │ ├── proftpd.conf │ ├── qmail.conf │ ├── sasl.conf │ ├── sshd.conf │ └── ... ├── action.d │ ├── dummy.conf │ ├── hostsdeny.conf │ ├── iptables.conf │ ├── mail-whois.conf │ ├── mail.conf │ └── ... ├── fail2ban.conf ├── jail.conf ├── paths-arch.conf ├── paths-debian.conf ├── paths-common.conf └── paths-opensuse.conf ``` - Filter used in my `jail.local` - sshd ``` [sshd] enabled = true port = ssh filter = sshd logpath = /var/log/auth.log maxretry = 5 findtime = 300 bantime = 1200 ``` - sshd.conf ``` [] ``` ## Reference - Official - [Man page](https://www.fail2ban.org/wiki/index.php/Main_Page) - [MANUAL 0 8](https://www.fail2ban.org/wiki/index.php/MANUAL_0_8) - [Commands](https://www.fail2ban.org/wiki/index.php/Commands) - [Regular expression operations in Python](https://docs.python.org/3/library/re.html) - Blogger's note - [NTHU Network Systems Division](https://net.nthu.edu.tw/2009/security:fail2ban) - [How to install Fail2ban on Ubuntu](https://upcloud.com/community/tutorials/install-fail2ban-ubuntu/) - [fail2ban： 新手老手 root 網管都要練的金鐘罩](https://newtoypia.blogspot.com/2016/04/fail2ban.html) - [How to ban web crawler using fail2ban](https://serverfault.com/questions/524807/how-to-ban-web-crawler-using-fail2ban)