fail2ban

Role Name

Ansible Galaxy Build Status
An ansible role to install and manage Fail2ban

Requirements

Ansible version 2.6 or later

Installation

Ansible Galaxy

Use ansible-galaxy install sakibmoon.fail2ban

Git

Use git clone https://github.com/sakibmoon/ansible-role-fail2ban.git

Basic Usage

Install and enable fail2ban and configure ssh with fail2ban

    - hosts: servers
      vars:
        fail2ban_services:
          - name: "sshd"
            enabled: "true"
            port: "ssh"
            filter: "sshd"
            logpath: "/var/log/auth.log"
            maxretry: 6       
      roles:
         - sakibmoon.fail2ban

See Role Variables and Example Playbook for more complex Usecase and how you can finetune all the options

Role Variables

Service Monitor Options

fail2ban_services
A list of Services to monitor by fail2ban. Every list option must contain service name, logpath. Only specify the settings you want to change. The rest of the configuration will come from global jail configuration as seen/set here.

Service options:

name: Name of the Service
logpath: Logpath of the service to monitor
port: Comma separated ports to monitor
enabled: Whether to enable this jail

Action List

fail2ban_actionlist
A list of action to create. The actions are saved in /etc/fail2ban/action.d/ directory. A single action can contain following options:

name: Action name. The name of the file.
sections: A list of sections like Definition, Init etc wchih contains dictionary of entries
file_ext: (Optional) The file extionsion. Can be either local or conf. Default: local

Example:

    fail2ban_actionlist:
      - name: toy-action1
        sections:
          - name: Definition
            options:
              - name: actionstart
                value: "ActionStart value"
              - name: actionflush
                value: "Actionflush value"
          - name: Init
            options:
              - name: timeout
                value: "timeout value"
        file_ext: "local"
      - name: toy-action2
        sections:
          - name: INCLUDES
            options:
              - name: before
                value: something-to-include.local
          - name: Definition
            options:
              - name: actionstart
                value: "ActionStart value"
              - name: actionflush
                value: "Actionflush value"
          - name: Init
            options:
              - name: timeout
                value: "timeout value"

Filter List

fail2ban_filterlist
A list of filter to create. The filter is saved in /etc/fail2ban/action.d/ directory. The format is same as fail2ban_actionlist as shown above.

Fail2ban Configuration Options

Variable Name Fail2ban Option Name Option Values Default Value Description
fail2ban_confpath [FILE] /etc/fail2ban/fail2ban.local The path where fail2ban configuration are written.
fail2ban_loglevel loglevel CRITICAL
ERROR
WARNING
INFO
DEBUG
\
[0-3]
ERROR for version > 0.8.x
1 for version 0.8.x
Set the log level output.
fail2ban_logtarget logtarget [FILE]
STDOUT
STDERR
SYSLOG
/var/log/fail2ban.log Set the log target. Only one log target can be specified.
If you change logtarget from the default value and you are using logrotate -- also adjust or disable rotation in the corresponding configuration file (e.g. /etc/logrotate.d/fail2ban on Debian systems)
fail2ban_syslogsocket syslogsocket auto
[FILE]
auto Set the syslog socket file.
Only used when logtarget is SYSLOG. auto uses platform.system() to determine predefined paths
fail2ban_socket socket [FILE] /var/run/fail2ban/fail2ban.sock Set the socket file.
This is used to communicate with the daemon. Do not remove this file when Fail2ban runs. It will not be possible to communicate with the server afterwards.
fail2ban_pidfile pidfile [FILE] /var/run/fail2ban/fail2ban.pid Set the PID file. This is used to store the process ID of the fail2ban server.
fail2ban_dbfile dbfile None
:memory:
[FILE]
/var/lib/fail2ban/fail2ban.sqlite3 Set the file for the fail2ban persistent data to be stored.
A value of :memory: means database is only stored in memory and data is lost when fail2ban is stopped.
A value of None disables the database.
fail2ban_dbpurgeage dbpurgeage [ SECONDS ] 86400 Sets age at which bans should be purged from the database
fail2ban_dbmaxmatches dbmaxmatches [ INT ] 20 Number of matches stored in database per ticket.
fail2ban_stacksize stacksize [ SIZE ] 0 This specifies the stack size (in KiB) to be used for subsequently created threads, and must be 0 or a positive integer value of at least 32.

Global Jail Configuration Options

Variable Name Fail2ban Option Name Option Values Default Value Description
fail2ban_jailpath [FILE] /etc/fail2ban/jail.local The file to write Fail2ban jail default configuration
fail2ban_ignoreself ignoreself boolean
true
false
true Indicates the banning of own IP addresses should be prevented.
fail2ban_ignoreip ignoreip List of IP address list of IPs not to ban. They can include a DNS resp. CIDR mask too. The option affects additionally to ignoreself (if true) and don't need to contain own DNS resp. IPs of the running host.
fail2ban_ignorecommand ignorecommand /path/to/command External command that will take an tagged arguments to ignore, e.g. , and return true if the IP is to be ignored. False otherwise.
fail2ban_ignorecache ignorecache disabled provide cache parameters for ignore failure check (caching of the result from ignoreip, ignoreself and ignorecommand)
fail2ban_bantime bantime [ SECONDS ] 600 Effective ban duration (in seconds).
fail2ban_findtime findtime [ SECONDS ] 600 time interval (in seconds) before the current time where failures will count towards a ban.
fail2ban_maxretry maxretry [ INT ] 5 The number of failures before a host get banned.
fail2ban_backend backend pyinotify
gamin
polling
systemd
auto
auto Specifies the backend used to get files modification.
fail2ban_usedns usedns yes
warn
no
raw
warn Specifies if jails should trust hostnames in logs, warn when DNS lookups are performed, or ignore all hostnames in logs
fail2ban_logencoding logencoding auto
ascii
utf-8
etc.
auto Specifies the encoding of the log files handled by the jail. Default value of auto uses current system locale.
fail2ban_mode mode normal
ddos
extra
aggressive
normal The mode of the filter
fail2ban_filter filter filter name %(__name__)s[mode=%(mode)s] The filter to use by the jail.
By default jails have names matching their filter name
fail2ban_logtimezone logtimezone UTC
UTC+0200
GMT-0100
etc.
Force the time zone for log lines that don't have one.
If this option is not specified, log lines from which no explicit time zone has been found are interpreted by fail2ban in its own system time zone.
fail2ban_banaction banaction iptables, iptables-new, iptables-multiport, shorewall, etc iptables-multiport Default banning action. It is used to define action_* variables. Can be overridden globally or per section within jail.local file
fail2ban_banaction_allports banaction_allports iptables, iptables-new, iptables-multiport, shorewall, etc iptables-allports the same as banaction but for some "allports" jails like "pam-generic" or "recidive"
fail2ban_action action %(action_)s Choose default action. To change, just override value of 'action' with the interpolation to the chosen action shortcut (e.g. action_mw, action_mwl, etc) or chose action(s) from /etc/fail2ban/action.d/ without the .conf/.local extension.
fail2ban_failregex failregex Python Regualr Expression regex (Python regular expression) to be added to the filter's failregexes (see failregex in section FILTER FILES for details).
fail2ban_ignoreregex ignoreregex regex which, if the log line matches, would cause Fail2Ban not consider that line. This line will be ignored even if it matches a failregex of the jail or any of its filters.
fail2ban_maxmatches maxmatches [INT] max number of matched log-lines the jail would hold in memory per ticket. By default it is the same value as maxretry of jail (or default)

Dependencies

No dependencies

Supported Platforms

This role should work on any Redhat or Debian based linux distribution. It's tested on the following platforms

  • CentOS 8
  • CentOS 7
  • Ubuntu 18.04
  • Ubuntu 16.04
  • Debian 10
  • Debian 9

Example Playbook

The followng playbook install, enable fail2ban and add ssh jail

    - hosts: servers
      vars:
        fail2ban_services:
          - name: "sshd"
            enabled: "true"
            port: "ssh"
            filter: "sshd"
            logpath: "/var/log/auth.log"
            maxretry: 6       
      roles:
         - sakibmoon.fail2ban

License

MIT

Author Information

This role was created by sakibmoon @2020

About

An ansible role to install and manage Fail2ban

Install
ansible-galaxy install sakibmoon/ansible-role-fail2ban
GitHub repository
License
mit
Downloads
538
Owner