Difference between revisions of "Fail2ban"

From ArchWiki
Jump to: navigation, search
(Custom SSH jail: fail2ban has IPv6 support)
(simplification and beautification of wikilinks (interactive))
(Tag: wiki-scripts)
 
(54 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
[[Category:Firewalls]]
 
[[Category:Secure Shell]]
 
[[Category:Secure Shell]]
 +
{{Related articles start}}
 +
{{Related|sshguard}}
 +
{{Related|Security}}
 +
{{Related articles end}}
 
[[ja:Fail2ban]]
 
[[ja:Fail2ban]]
 
[[ro:Fail2ban]]
 
[[ro:Fail2ban]]
 
[[ru:Fail2ban]]
 
[[ru:Fail2ban]]
{{Warning|Using an IP blacklist will stop trivial attacks but it relies on an additional daemon and successful logging (the partition containing /var can become full, especially if an attacker is pounding on the server). Additionally, if the attacker knows your IP address, they can send packets with a spoofed source header and get you locked out of the server. [[SSH keys]] provide an elegant solution to the problem of brute forcing without these problems.}}
+
[http://www.fail2ban.org/wiki/index.php/Main_Page Fail2ban] scans log files (e.g. {{ic|/var/log/httpd/error_log}}) and bans IPs that show the malicious signs like too many password failures, seeking for exploits, etc. Generally Fail2Ban is then used to update firewall rules to reject the IP addresses for a specified amount of time, although any arbitrary other action (e.g. sending an email) could also be configured.  
  
[http://www.fail2ban.org/wiki/index.php/Main_Page Fail2ban] scans various textual log files and bans IP that makes too many password failures by updating firewall rules to reject the IP address, similar to [[Sshguard]].
+
{{Warning|Using an IP banning software will stop trivial attacks but it relies on an additional daemon and successful logging. Additionally, if the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address banned. Make sure to specify your IP in {{ic|ignoreip}}.}}
 
 
{{Warning|For correct function it is essential that the tool parses the IP addresses in the log correctly. You should always '''test''' the log filters work as intended per application you want to protect.}}
 
  
 
== Installation ==
 
== Installation ==
Line 13: Line 16:
 
[[Install]] {{Pkg|fail2ban}}.
 
[[Install]] {{Pkg|fail2ban}}.
  
If you want Fail2ban to send an email when someone has been banned, you have to configure [[SSMTP]] (for example).
+
== Usage ==
 +
 
 +
[[#Configuration|Configure]] fail2ban and [[enable]]/[[start]] {{ic|fail2ban.service}}.
 +
 
 +
=== fail2ban-client ===
  
=== systemd ===
+
The fail2ban-client allows monitoring jails (reload, restart, status, etc.), to view all available commands:
  
[[Enable]] the {{ic|fail2ban.service}} unit.
+
$ fail2ban-client
  
== Hardening ==
+
To view all enabled jails:
  
Currently, fail2ban must be run as root. Therefore, you may wish to consider hardening the process with systemd. Ref:[http://0pointer.de/blog/projects/security.html systemd for Administrators, Part XII]
+
# fail2ban-client status
  
=== Capabilities ===
+
To check the status of a jail, e.g. for ''sshd'':
  
For added security, consider limiting fail2ban capabilities by specifying {{ic|CapabilityBoundingSet}} in the [[Systemd#Editing provided units|drop-in configuration file]] for the provided {{ic|fail2ban.service}}:
+
{{hc|# fail2ban-client status sshd|<nowiki>
 +
Status for the jail: sshd
 +
|- Filter
 +
|  |- Currently failed: 1
 +
|  |- Total failed:    9
 +
| `- Journal matches:  _SYSTEMD_UNIT=sshd.service + _COMM=sshd
 +
`- Actions
 +
  |- Currently banned: 1
 +
  |- Total banned:    1
 +
  `- Banned IP list:  0.0.0.0
 +
</nowiki>}}
  
{{hc|/etc/systemd/system/fail2ban.service.d/capabilities.conf|2=
+
== Configuration ==
[Service]
+
 
CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_NET_ADMIN CAP_NET_RAW
+
Due to the possibility of the {{ic|/etc/fail2ban/jail.conf}} file being overwritten or improved during a distribution update, it is recommended to [[Create]] {{ic|/etc/fail2ban/jail.local}} file. For example to change default ban time to 1 day:
}}
+
 
 +
{{hc|/etc/fail2ban/jail.local|<nowiki>
 +
[DEFAULT]
 +
bantime = 1d
 +
</nowiki>}}
 +
 
 +
Or create separate ''name.local'' files under the {{ic|/etc/fail2ban/jail.d}} directory, e.g. {{ic|/etc/fail2ban/jail.d/sshd.local}}.
 +
 
 +
[[Restart]] {{ic|fail2ban.service}} to apply the configuration changes.
  
In the example above, {{ic|CAP_DAC_READ_SEARCH}} will allow fail2ban full read access, and {{ic|CAP_NET_ADMIN}} and {{ic|CAP_NET_RAW}} allow setting of firewall rules with [[iptables]]. Additional capabilities may be required, depending on your fail2ban configuration. See {{man|7|capabilities}} for more info.
+
=== Enabling jails ===
 +
By default all jails are disabled. [[Append]] {{ic|1=enabled = true}} to the jail you want to use, e.g. to enable the [[OpenSSH]] jail:
  
=== Filesystem Access ===
+
{{hc|/etc/fail2ban/jail.local|2=
 +
[sshd]
 +
enabled = true
 +
}}
  
{{Note|On some systems this might lead to fail2ban not working. So, first try without, before hardening fail2ban}}
+
See [[#Custom SSH jail]].
  
Consider limiting file system read and write access by using ''ReadOnlyDirectories'' and ''ReadWriteDirectories'', under the {{ic|[Service]}} section. For example:
+
=== Receive an alert e-mail ===
ReadOnlyDirectories=/
 
ReadWriteDirectories=/var/run/fail2ban /var/lib/fail2ban /var/spool/postfix/maildrop /tmp /var/log/fail2ban
 
In the example above, this limits the file system to read-only, except for {{ic|/var/run/fail2ban}} for pid and socket files, and {{ic|/var/spool/postfix/maildrop}} for [[postfix]] sendmail. Again, this will be dependent on you system configuration and fail2ban configuration. The {{ic|/tmp}} directory is needed for some fail2ban actions. Note that adding {{ic|/var/log/fail2ban}} is necessary if you want fail2ban to log its activity. Make sure all the directories exist, or you will get error code 226 on starting the service. And modify logtarget in {{ic|/etc/fail2ban/fail2ban.conf}}:
 
logtarget = /var/log/fail2ban/fail2ban.log
 
  
== Configuration ==
+
If you want to receive an e-mail when someone has been banned, you have to configure an SMTP client (e.g. [[msmtp]]) and change default action, as given below.
  
{{Note|Due to the possibility of the {{ic|jail.conf}} file being overwritten or improved during a distribution update, it is recommended to provide customizations in a {{ic|jail.local}} file, or separate ''.conf'' files under the {{ic|jail.d/}} directory, e.g. {{ic|jail.d/ssh-iptables.conf}}.}}
+
{{hc|/etc/fail2ban/jail.local|<nowiki>
 +
[DEFAULT]
 +
destemail = yourname@example.com
 +
sender = yourname@example.com
  
=== Default jails ===
+
# to ban & send an e-mail with whois report to the destemail.
 +
action = %(action_mw)s
  
Jails for many different services are already present in {{ic|/etc/fail2ban/jail.conf}} but not enabled by default. You can copy the section headers into a .local file of your choice, enable them (and optionally override settings).
+
# same as action_mw but also send relevant log lines
 +
#action = %(action_mwl)s
 +
</nowiki>}}
  
=== Paths ===
+
=== Firewall and services ===
  
There is currently basic support for archlinux, to activate that configuration, add or alter the following section in the {{ic|jail.local}} file:
+
Most [[firewalls]] and services should work out of the box. See {{ic|/etc/fail2ban/action.d/}} for examples, e.g. [https://github.com/fail2ban/fail2ban/blob/master/config/action.d/ufw.conf ufw.conf].
[INCLUDES]
 
before = paths-arch.conf
 
  
[[Restart]] {{ic|fail2ban.service}} to test your configuration. Watch out for "file not found errors" from ''fail2ban-client'' if the fail2ban service fails to start. Adjust the paths {{ic|paths-arch.conf}} or {{ic|jail.local}} as needed. Many of the default jails might not work out of the box.
+
== Tips and tricks ==
  
 
=== Custom SSH jail ===
 
=== Custom SSH jail ===
  
Edit {{ic|/etc/fail2ban/jail.d/jail.conf}}, add this section and update the list of trusted IP addresses.
+
{{Warning|If the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address locked out of the server. [[SSH keys]] provide an elegant solution to the problem of brute forcing without these problems.}}
 +
 
 +
Edit {{ic|/etc/fail2ban/jail.d/sshd.local}}, add this section and update the list of trusted IP addresses in {{ic|ignoreip}}.
  
 
If your firewall is [[iptables]]:
 
If your firewall is [[iptables]]:
[DEFAULT]
 
bantime = 1d
 
ignoreip = 127.0.0.1/8
 
 
 
  [sshd]
 
  [sshd]
 
  enabled  = true
 
  enabled  = true
 
  filter  = sshd
 
  filter  = sshd
  action  = iptables[name=SSH, port=ssh, protocol=tcp]
+
  banaction = iptables
            sendmail-whois[name=SSH, dest=your@mail.org, sender=fail2ban@mail.com]
 
 
  backend  = systemd
 
  backend  = systemd
 
  maxretry = 5
 
  maxretry = 5
 
  findtime = 1d
 
  findtime = 1d
 
  bantime  = 2w
 
  bantime  = 2w
 +
ignoreip = 127.0.0.1/8
 +
 +
fail2ban has IPv6 support since version 0.10. Adapt your firewall accordingly, e.g. start and enable {{ic|ip6tables.service}}.
 +
 +
{{Note|If your firewall is [[shorewall]], replace {{ic|iptables}} with {{ic|shorewall}}. You can also set {{ic|BLACKLIST}} to {{ic|ALL}} in {{ic|/etc/shorewall/shorewall.conf}}, otherwise the rule added to ban an IP address will affect only new connections.}}
 +
 +
{{Note|It may be necessary to set {{ic|LogLevel VERBOSE}} in {{ic|/etc/ssh/sshd_config}} to allow full fail2ban monitoring as otherwise password failures may not be logged correctly.}}
 +
 +
=== Service hardening ===
 +
 +
Currently, fail2ban must be run as ''root''. Therefore, you may wish to consider hardening the process with [[systemd]].
 +
 +
Create a [[Systemd#Drop-in files|drop-in]] configuration file for {{ic|fail2ban.service}}:
 +
 +
{{hc|/etc/systemd/system/fail2ban.service.d/override.conf|2=
 +
[Service]
 +
PrivateDevices=yes
 +
PrivateTmp=yes
 +
ProtectHome=read-only
 +
ProtectSystem=strict
 +
NoNewPrivileges=yes
 +
ReadWritePaths=-/var/run/fail2ban
 +
ReadWritePaths=-/var/lib/fail2ban
 +
ReadWritePaths=-/var/log/fail2ban
 +
ReadWritePaths=-/var/spool/postfix/maildrop
 +
CapabilityBoundingSet=CAP_AUDIT_READ CAP_DAC_READ_SEARCH CAP_NET_ADMIN CAP_NET_RAW
 +
}}
 +
 +
The {{ic|CapabilityBoundingSet}} parameters {{ic|CAP_DAC_READ_SEARCH}} will allow fail2ban full read access to every directory and file, {{ic|CAP_NET_ADMIN}} and {{ic|CAP_NET_RAW}} allow setting of firewall rules with [[iptables]]. See {{man|7|capabilities}} for more info.
  
fail2ban has IPv6 support since version 0.10. Adapt your firewall accordingly, e.g. start and enable ip6tables.service.
+
By using {{ic|1=ProtectSystem=strict}} the [[filesystem]] hierarchy will only be read-only, {{ic|ReadWritePaths}} allows fail2ban to have write access on required paths.
  
{{Note|If your firewall is [[shorewall]], replace {{ic|1=iptables[name=SSH, port=ssh, protocol=tcp]}} with {{ic|shorewall}}. You can also set {{ic|BLACKLIST}} to {{ic|ALL}} in {{ic|/etc/shorewall/shorewall.conf}}, otherwise the rule added to ban an IP address will affect only new connections.}}
+
[[Create]] {{ic|/etc/fail2ban/fail2ban.local}} with the correct {{ic|logtarget}} path:
 +
{{hc|/etc/fail2ban/fail2ban.local|<nowiki>
 +
[Definition]
 +
logtarget = /var/log/fail2ban/fail2ban.log
 +
</nowiki>}}
  
Also do not forget to add/change:
+
Finally, [[Systemd#Using_units|reload systemd daemon]] to apply the changes of the unit and [[restart]] {{ic|fail2ban.service}}.
LogLevel VERBOSE
 
in your {{ic|/etc/ssh/sshd_config}}. Else, password failures are not logged correctly.
 
  
 
== See also ==
 
== See also ==
  
* [[sshguard]]
+
* [http://www.the-art-of-web.com/system/fail2ban-action-whitelist/ Using a Fail2Ban Jail to Whitelist a User]
 +
* [http://www.the-art-of-web.com/system/fail2ban-filters/ Optimising your Fail2Ban filters]
 +
* [http://www.the-art-of-web.com/system/fail2ban-sendmail/ Fail2Ban and sendmail]
 +
* [http://www.the-art-of-web.com/system/fail2ban/ Fail2Ban and iptables]
 +
* [http://www.the-art-of-web.com/system/fail2ban-howto/ Fail2Ban 0.8.3 Howto]
 +
* [http://www.the-art-of-web.com/system/fail2ban-log/ Monitoring the fail2ban log]

Latest revision as of 09:23, 3 July 2018

Fail2ban scans log files (e.g. /var/log/httpd/error_log) and bans IPs that show the malicious signs like too many password failures, seeking for exploits, etc. Generally Fail2Ban is then used to update firewall rules to reject the IP addresses for a specified amount of time, although any arbitrary other action (e.g. sending an email) could also be configured.

Warning: Using an IP banning software will stop trivial attacks but it relies on an additional daemon and successful logging. Additionally, if the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address banned. Make sure to specify your IP in ignoreip.

Installation

Install fail2ban.

Usage

Configure fail2ban and enable/start fail2ban.service.

fail2ban-client

The fail2ban-client allows monitoring jails (reload, restart, status, etc.), to view all available commands:

$ fail2ban-client

To view all enabled jails:

# fail2ban-client status

To check the status of a jail, e.g. for sshd:

# fail2ban-client status sshd
Status for the jail: sshd
|- Filter
|  |- Currently failed: 1
|  |- Total failed:     9
|  `- Journal matches:  _SYSTEMD_UNIT=sshd.service + _COMM=sshd
`- Actions
   |- Currently banned: 1
   |- Total banned:     1
   `- Banned IP list:   0.0.0.0

Configuration

Due to the possibility of the /etc/fail2ban/jail.conf file being overwritten or improved during a distribution update, it is recommended to Create /etc/fail2ban/jail.local file. For example to change default ban time to 1 day:

/etc/fail2ban/jail.local
[DEFAULT]
bantime = 1d

Or create separate name.local files under the /etc/fail2ban/jail.d directory, e.g. /etc/fail2ban/jail.d/sshd.local.

Restart fail2ban.service to apply the configuration changes.

Enabling jails

By default all jails are disabled. Append enabled = true to the jail you want to use, e.g. to enable the OpenSSH jail:

/etc/fail2ban/jail.local
[sshd]
enabled = true

See #Custom SSH jail.

Receive an alert e-mail

If you want to receive an e-mail when someone has been banned, you have to configure an SMTP client (e.g. msmtp) and change default action, as given below.

/etc/fail2ban/jail.local
[DEFAULT]
destemail = yourname@example.com
sender = yourname@example.com

# to ban & send an e-mail with whois report to the destemail.
action = %(action_mw)s

# same as action_mw but also send relevant log lines
#action = %(action_mwl)s

Firewall and services

Most firewalls and services should work out of the box. See /etc/fail2ban/action.d/ for examples, e.g. ufw.conf.

Tips and tricks

Custom SSH jail

Warning: If the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address locked out of the server. SSH keys provide an elegant solution to the problem of brute forcing without these problems.

Edit /etc/fail2ban/jail.d/sshd.local, add this section and update the list of trusted IP addresses in ignoreip.

If your firewall is iptables:

[sshd]
enabled  = true
filter   = sshd
banaction = iptables
backend  = systemd
maxretry = 5
findtime = 1d
bantime  = 2w
ignoreip = 127.0.0.1/8

fail2ban has IPv6 support since version 0.10. Adapt your firewall accordingly, e.g. start and enable ip6tables.service.

Note: If your firewall is shorewall, replace iptables with shorewall. You can also set BLACKLIST to ALL in /etc/shorewall/shorewall.conf, otherwise the rule added to ban an IP address will affect only new connections.
Note: It may be necessary to set LogLevel VERBOSE in /etc/ssh/sshd_config to allow full fail2ban monitoring as otherwise password failures may not be logged correctly.

Service hardening

Currently, fail2ban must be run as root. Therefore, you may wish to consider hardening the process with systemd.

Create a drop-in configuration file for fail2ban.service:

/etc/systemd/system/fail2ban.service.d/override.conf
[Service]
PrivateDevices=yes
PrivateTmp=yes
ProtectHome=read-only
ProtectSystem=strict
NoNewPrivileges=yes
ReadWritePaths=-/var/run/fail2ban
ReadWritePaths=-/var/lib/fail2ban
ReadWritePaths=-/var/log/fail2ban
ReadWritePaths=-/var/spool/postfix/maildrop
CapabilityBoundingSet=CAP_AUDIT_READ CAP_DAC_READ_SEARCH CAP_NET_ADMIN CAP_NET_RAW

The CapabilityBoundingSet parameters CAP_DAC_READ_SEARCH will allow fail2ban full read access to every directory and file, CAP_NET_ADMIN and CAP_NET_RAW allow setting of firewall rules with iptables. See capabilities(7) for more info.

By using ProtectSystem=strict the filesystem hierarchy will only be read-only, ReadWritePaths allows fail2ban to have write access on required paths.

Create /etc/fail2ban/fail2ban.local with the correct logtarget path:

/etc/fail2ban/fail2ban.local
[Definition]
logtarget = /var/log/fail2ban/fail2ban.log

Finally, reload systemd daemon to apply the changes of the unit and restart fail2ban.service.

See also