pmiles / puppet-suricata Goto Github PK

Puppet-Suricata

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with suricata
   • What suricata affects
   • Setup requirements
   • Beginning with suricata
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

The Puppet-Suricata module installs and manages the Open Source IDS / IPS / NSM engine Suricata.

Suricata is a widely used IDS/NSM engine. This puppet module takes care of the whole lifecycle including installing, configuration and service managment. The goal of this puppet module is to not limit any configuration options that Suricata provides.

• Configuration files and directories (created and written to)
• Packages/service/configuration files for Suricata.
• Log files from Suricata

To have the Puppet-Suricata module installed with a basic setup, declare the suricata class.

  include '::suricata'

The Puppet modules applies a default configuration based on your operating system. By default it will use your first interface as montior interafce for Suricata and applies a minimal suricata.yaml configuration. For more configuration option please see the suricata.yaml on the Suricata Github clone repository and the Suricata Documentation.

Suricata have only class to use and this is suricata class. The class do have many configuration options, but most of them is default to a normal suricata setup.

###Just want minimal Suricata config?

  include '::suricata'

###Using RHEL and dont want this module do install epel?

  class { ::suricata:
    configure_epel => false,
  }

###Don't want this module to manager suricatas user, and run with your own?

  class { ::suricata:
    manage_user => false,
    user        => user,
    group       => user,
  }

###Add more interfaces to listen on? Or dont listen on any?

Default does this module use the first interfaces found in the fact 'interfaces'.

  class { ::suricata: 
    interfaces => "eth0, eth1, eth2",
  }

Setting interfaces to undef will not add any interfaces to the commandline options to suricata.

  class { ::suricata:
    interfaces => undef,
  }

###Want to add more commandline options to Suricata?

  class {::suricata:
    cmd_options => '--af-packet=eth0',  
  }

###Merge your suricata configuration with the basic one this module provides?

The hash below will change the configuration of the rules-files to the value below.

  class {::suricata:
    main_config => { 'rules-files' =>  [
                      'emerging-attack_response.rules',
                      'emerging-chat.rules',
                      'emerging-current_events.rules',
                      'emerging-dns.rules'
                     ]
                   }
  }

This configuration can also be done in hiera.

  class {::suricata: }

suricata::main_config:
  rule-files:
   - emerging-attack_response.rules
   - emerging-chat.rules
   - emerging-current_events.rules
   - emerging-dns.rules

###Don't use the basic configuration and write the configuration from scratch

If you don't want to merge your configuration with the modules this can be turned off. Then only the configuration you add as a hash or hiera will be used.

  class {::suricata:
    basic_configuration_enabled = false,
  }

###Add a lua script to Suricatas script folder

This modules includes a resource for adding scripts. This resource adds the script to lua-output directory inside suricatas configuration directory and sets the correct permissions.

  suricata::script { 'stats.lua':
    ensure => 'present',
    source => 'puppet:///modules/module/stats.lua',
  }

Classes

Public Classes

• suricata: Main class, includes all other classes.

Private Classes

• suricata::install:
• suricata::config:
• suricata::service:

Public Defined Classes

• suricata::script

Parameters within suricata class

####ensure

Choose whether suricata should be present, absent, latest or version Defaults to 'present'

####package_name

Name of suricata package in repo

Defaults to 'suricata'

####config_dir

Directory of configuration files

Defaults to '/etc/suricata'

####config_name

Name of suricata main configuration

Defaults to 'suricata.yaml'

####log_dir Directory of suricatas log files

Defaults to '/var/log/suricata'

####service_ensure

Choose whether suricata service is running or stopped

Defaults to 'running'

####service_enable

Choose to enable suricata at startup or not

Defaults to true

####service_provider

Which service provider suricatas service will use

Default depends on os

####manage_user

Choose wheter this module will manage the user

Defaults to true

####user

Name of user that suricata is running as and owner of configuration files

Defaults to 'suricata'

####group

Name of users group

Defaults to 'suricata'

####user_shell

Path to user shell

Default depends on os

####bin_path

Path to suricatas binary file

Default depends on os

####basic_configuration_enabled

Choose whether to apply the modules included basic configuration

Defaults to true

####configure_epel

Choose whether this module will install epel from offical repository

Default to true if os is RHEL

####interfaces

A string of comma-separated interfaces

Defaults to the first interfaces found in the interface fact

####cmd_options

A string of additonal commandline options

Defaults to undef

####main_config

A hash of suricatas main configuration options

####classification_config

An array of suricatas classification configuration options

####reference_config

An array of suricatas reference configuration options

####threshold_config

An array of suricatas threshold configuration options

Parameters within suricata::script defined type

####source

Puppet URI to where the script is stored

####ensure

Choose whether the script should be present or absent

Defaults to present

####script_name

Name of the script

Default to the name of the instance

This module is currently limitied to RHEL version 7, Debian 8 and Ubuntu 16.04 with Puppet version 4.8 or greater. Currently tested on CentOS 7 with Puppet 4.8

We are happy to recieve comits as long as they follow the rules and guidelines below. If you want to fork the module somewhere else this is also fine as long as you mention or link the original module along with the documentation and code.

Rules:

• All code must follow the Puppet Style Guide.
• Added code must pass the included tests. If you add new fuctions, please create puppet tests for these.
• Make sure not to break any existing code or functions of this module.
• New functions must be documented in the Github repository.
• All commits must follow the Github Commit Guide.

Guide:

1. Fork the repo.
2. Run the tests to verify that the module works as intended.
3. Add new code, bugfixes and documentation if needed.
4. Make sure that all the tests pass.
5. Push to your fork and submit a pull request.
6. Create an issue on Github if you have any problems.