Fail2ban: Difference between revisions

From NixOS Wiki
imported>Nix
m add Software/Applications subcategory
imported>Occhioverde
Document all the availabe Fail2ban module options
Line 1: Line 1:
Fail2ban is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.
[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.


== Basic Fail2ban Usage ==
== Basic Usage ==
This option will enable Fail2ban and use the default settings.
The Fail2ban [[NixOS modules|NixOS module]] can be found under <source lang="nix" enclose="none">services.fail2ban</source>; from now on (unless differently specified), all options described are prefixed with this namespace.
 
The service can be enabled by setting <source lang="nix" enclose="none">enable</source> to <source lang="nix" enclose="none">true</source>:
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
   services.fail2ban.enable = true;
   services.fail2ban.enable = true; # Enables Fail2ban
</syntaxHighlight>
</syntaxHighlight>


== Customization ==
=== Configuration ===
The 'maxretry' option allows you to specify how many failures are required for an IP address to be blocked. To prevent being locked out accidentally, the 'ignoreIP' option can be used to prevent IP addresses and IP ranges from being blocked. In this example, common LAN IP address ranges and loopback IP address ranges are being ignored as well as the specific IP '8.8.8.8'.
The Fail2ban NixOS module exposes different parameters needed to adjust the configuration:
 
* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.
* To prevent being locked out accidentally, the 'ignoreIP' option can be used to prevent IP addresses and IP ranges from being blocked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "nixos.wiki" (note that the loopback addresses "127.0.0.0/8" and "::1" are added by default).
* <source lang="nix" enclose="none">bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of tries. Note that the bantime can be increased for every violation by setting <source lang="nix" enclose="none">bantime-increment.enable</source> to <source lang="nix" enclose="none">true</source>; the bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" enclose="none">ban.Time * math.exp(float(ban.Count+1)*banFactor)/math.exp(1*banFactor)</source> with <source lang="nix" enclose="none">bantime-increment.formula</source>, the multipliers with <source lang="nix" enclose="none">bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" enclose="none">bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" enclose="none">bantime-increment.overalljails</source>
* <source lang="nix" enclose="none">banaction</source> specifies which one among the actions contained in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source> should be the default banning action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
* <source lang="nix" enclose="none">extraPackages</source> can receive a list of derivations whose outputs are needed by Fail2ban actions
* <source lang="nix" enclose="none">jails</source> contains the configuration of each Fail2ban “jail”. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter applied to a log file triggers more than a certain number of times in a certain time period. Actions are defined in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source>, while filters are defined in <source lang="nix" enclose="none">/etc/fail2ban/filter.d</source>.
* <source lang="nix" enclose="none">extraSettings</source> can contain parameters that are automatically applied to every jail config (i.e., in the <source lang="ini" enclose="none">[DEFAULT]</source> section)
 
<syntaxHighlight lang=nix>
<syntaxHighlight lang=nix>
   services.fail2ban = {
   services.fail2ban = {
     enable = true;
     enable = true;
     maxretry = 5;
     maxretry = 5; # Observe 5 violations before banning an IP
     ignoreIP = [
     ignoreIP = [
       "127.0.0.0/8"
       # Whitelisting some subnets:
       "10.0.0.0/8"  
       "10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"
      "172.16.0.0/12"  
       "8.8.8.8" # Whitelists a specific IP
      "192.168.0.0/16"
      "nixos.wiki" # Resolves the IP via DNS
       "8.8.8.8"
     ];
     ];
    bantime = "24h"; # Set bantime to one day
    bantime-increment = {
      enable = true; # Enable increment of bantime after each violation
      formula = "ban.Time * math.exp(float(ban.Count+1)*banFactor)/math.exp(1*banFactor)";
      multipliers = "1 2 4 8 16 32 64";
      maxtime = "168h"; # Do not ban for more than 1 week
      overalljails = true; # Calculate the bantime based on all the violations
    };
    jails = {
      apache-nohome-iptables = ''
        # Block an IP address if it accesses a non-existent
        # home directory more than 5 times in 10 minutes,
        # since that indicates that it's scanning.
        filter = apache-nohome
        action = iptables-multiport[name=HTTP, port="http,https"]
        logpath = /var/log/httpd/error_log*
        backend = auto
        findtime = 600
        bantime  = 600
        maxretry = 5
      '';
    };
   };
   };
</syntaxHighlight>
</syntaxHighlight>


[[Category:Applications]]
[[Category:Applications]]

Revision as of 14:09, 2 July 2023

Fail2ban is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.

Basic Usage

The Fail2ban NixOS module can be found under services.fail2ban; from now on (unless differently specified), all options described are prefixed with this namespace.

The service can be enabled by setting enable to true:

  services.fail2ban.enable = true; # Enables Fail2ban

Configuration

The Fail2ban NixOS module exposes different parameters needed to adjust the configuration:

  • The maxretry option allows you to specify how many failures are required for an IP address to be blocked.
  • To prevent being locked out accidentally, the 'ignoreIP' option can be used to prevent IP addresses and IP ranges from being blocked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "nixos.wiki" (note that the loopback addresses "127.0.0.0/8" and "::1" are added by default).
  • bantime specifies for how much time an IP address is blocked after reaching the maximum number of tries. Note that the bantime can be increased for every violation by setting bantime-increment.enable to true; the bantime increment can then be customized by specifying a formula (in Python) like ban.Time * math.exp(float(ban.Count+1)*banFactor)/math.exp(1*banFactor) with bantime-increment.formula, the multipliers with bantime-increment.multipliers, the maximum bantime with bantime-increment.maxtime and the indication to consider the bans issued throughout multiple jails with bantime-increment.overalljails
  • banaction specifies which one among the actions contained in /etc/fail2ban/action.d should be the default banning action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
  • extraPackages can receive a list of derivations whose outputs are needed by Fail2ban actions
  • jails contains the configuration of each Fail2ban “jail”. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter applied to a log file triggers more than a certain number of times in a certain time period. Actions are defined in /etc/fail2ban/action.d, while filters are defined in /etc/fail2ban/filter.d.
  • extraSettings can contain parameters that are automatically applied to every jail config (i.e., in the [DEFAULT] section)
  services.fail2ban = {
    enable = true;
    maxretry = 5; # Observe 5 violations before banning an IP
    ignoreIP = [
      # Whitelisting some subnets:
      "10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"
      "8.8.8.8" # Whitelists a specific IP
      "nixos.wiki" # Resolves the IP via DNS
    ];
    bantime = "24h"; # Set bantime to one day
    bantime-increment = {
      enable = true; # Enable increment of bantime after each violation
      formula = "ban.Time * math.exp(float(ban.Count+1)*banFactor)/math.exp(1*banFactor)";
      multipliers = "1 2 4 8 16 32 64";
      maxtime = "168h"; # Do not ban for more than 1 week
      overalljails = true; # Calculate the bantime based on all the violations
    };
    jails = {
      apache-nohome-iptables = ''
        # Block an IP address if it accesses a non-existent
        # home directory more than 5 times in 10 minutes,
        # since that indicates that it's scanning.
        filter = apache-nohome
        action = iptables-multiport[name=HTTP, port="http,https"]
        logpath = /var/log/httpd/error_log*
        backend = auto
        findtime = 600
        bantime  = 600
        maxretry = 5
      '';
    };
  };