/fail2ban-formula

Primary LanguageSaltStackMIT LicenseMIT

fail2ban-formula

Travis CI Build Status Semantic Release

fail2ban scans log files for malicious activity and executes actions based on what it finds.

Table of Contents

General notes

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute for more details.

Available states

fail2ban

Install the fail2ban package and enable the service.

fail2ban.config

Creates a jail.local config file based on pillar data to override configuration in the default jail.conf file and enables creation of all configuration files based on content blocks in pillar. See pillar.example for reference and consult the fail2ban documentation.

The following states provide an alternate approach to managing fail2ban. Tested in Ubuntu 14/16 and CentOS 6/7.

fail2ban.ng

Meta state for inclusion of all ng states.

fail2ban.ng.install

Install the fail2ban package.

fail2ban.ng.config

Configure fail2ban creating a jail.local file based on pillar data that overrid jail.conf. It also creates a file.local per action/filter. Either in jails, actions or filters is possible to setup a source_path options to upload your configuration directly (see pillar.example). It is also possible to remove either actions or filters setting up enabled: False in it section (see pillar.example).

Keep in mind that in ng states lookup, config, jails, actions and filters are at the same level (in the old states, all the sections are under lookup:

fail2ban:
  ng:
    lookup:
    config:
    jails:
    actions:
    filters:

Keep in mind also that in ng states change the syntax for the actions and filters adding a new config section and enabled option (optional):

fail2ban:
  ng:
    actions:
      name-of-action:
        enabled: True/False # OPTIONAL
        config:
          Definition:
              actionban:
              actionunban:
          Init:
              whatever:
    filters:
      name-of-filter:
        enabled: True/False # OPTIONAL
        config:
          Definition:
              failregex:

It is also possible to specify the source file for config, jails, actions and filters instead of using the template:

fail2ban:
  ng:
    config:
      source_path: salt://path-to-fail2ban-config-file
    jails:
      source_path: salt://path-to-fail2ban-config-file
    actions:
      name-of-action:
        config:
          source_path: salt://path-to-action-file
    filters:
      name-of-filter:
        config:
          source_path: salt://path-to-filter-file

fail2ban.ng.service

Manage fail2ban service. It is also possible to disable the service using the following pillar configuration:

fail2ban:
  ng:
    enabled: False

Testing

Linux testing is done with kitchen-salt.

Requirements

  • Ruby
  • Docker
$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

bin/kitchen converge

Creates the docker instance and runs the fail2ban main state, ready for testing.

bin/kitchen verify

Runs the inspec tests on the actual instance.

bin/kitchen destroy

Removes the docker instance.

bin/kitchen test

Runs all of the stages above in one go: i.e. destroy + converge + verify + destroy.

bin/kitchen login

Gives you SSH access to the instance for manual testing.