Version information
This version is compatible with:
- Puppet 3.x
- , ,
Start using this module
Add this module to your Puppetfile:
mod 'tedivm-psad', '1.2.1'
Learn more about managing modules with a PuppetfileDocumentation
psad
Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with psad
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Release notes - Who built this and where to find updates
Overview
This module blocks port scans from occurring by installing and configuring PSAD, the port scan active defense application. The module works for Puppet 3+ and is currently tested on Debian and Ubuntu (more to come!).
Module Description
PSAD is a staple of system security. It integrates with your existing firewall to detect traffic to unauthorized ports and block them at their source. In addition PSAD uses special signatures to detect attack types that occur.
Although PSAD has a variety of configurations to customize it's behavior, the real value in PSAD is in how it works with your existing firewall. To whitelist a new range of IPs in PSAD you simply whitelist them in your firewall directly. For these reasons a propery configured firewall is vital, although this module will take care of adding it's own required rules in.
Setup
What psad affects
- Installs PSAD package.
- Updates psad.conf and autold files.
- Enables PSAD service.
- Adds three new chains to firewall.
- Adds logging rules to firewall.
- Adds cronjob for daily signature updates.
- Requires mailer for notifications and may install one if not present.
- Will block addresses from attempted port scans.
Setup Requirements
A properly configured firewall is a must- all allowed destinations should be explicitly placed into the firewall rules or traffic to them could result in blocked hosts.
A mailer of some variety is required to send notifications. With most package managers this means PSAD will also install a mailer if you have not done so already, so it is highly advisable that you configure that separately.
Beginning with psad
The simplest way to get started is to simple include the "psad" class.
include psad
You can also pass parameters for custom behavior.
class { 'psad' :
$config => {
email_addresses => ['root@localhost.com', 'security@example.com']
},
firewall_priorty => 850
}
Usage
All interaction with the psad module can do be done through the main psad class.
How do I set up the firewall for PSAD?
PSAD inserts logging rules into the system firewall and then keeps track of what machines are hitting that logging point to build it's database of threats. All allowed rules must be higher in the chain than the logging rule.
I just want PSAD, what's the minimum I need?
After setting up your firewall simply include the PSAD class.
include psad
How do I change the destination for email notifications?
class { 'psad' :
config => {
email_addresses => ['root@localhost.com', 'security@example.com']
}
}
This can also be configured using Hiera.
# Common.yaml
psad::config:
email_addresses:
- 'root@localhost.com'
# DatacenterA.yaml
psad::config:
email_addresses:
- 'security@example.com'
How do I block attackers?
In Puppet:
class { 'psad' :
config => {
enable_auto_ids => 'Y'
}
}
In Hiera:
psad::config:
enable_auto_ids: 'Y'
Can I whitelist or blacklist hosts?
The autodl parameter allows you to set danger levels for specific addresses, protocols and ports.
class { 'psad' :
autodl => {
"127.0.0.1" => {
'level' => 0
},
"192.0.2.34" => {
'level' => 5
},
"203.0.113.0/24" => {
'level' => 5,
'proto' => 'tcp'
},
}
}
Using Hiera you can split your configurations up into different files.
# Common.yaml
psad::autodl:
'127.0.0.1':
level: '0'
# DatacenterA.yaml
psad::autodl:
'192.0.2.34':
level: '5'
#DatacenterB.yaml
psad::autodl:
'203.0.113.0/24':
level: '5'
proto: 'tcp'
How do I change the priority of the logging rules?
In Puppet:
class { 'psad' :
firewall_priority => 850
}
In Hiera:
psad::firewall_priority: 850
What if I want to add the logging rules in myself?
In Puppet:
class { 'psad' :
firewall_enable => false
}
In Hiera:
psad::firewall_enable: false
How does blocking work?
PSAD adds hosts that meet the criteria for blocking using firewall rules. The length of time a host is blocked depends on it's "danger level", which is calculated using SNORT rules and by counting how many packets they've sent to closed ports.
This module comes with some default values to be used as a starting point.
Danger Level | Ports Scanned | Time Blocked |
---|---|---|
0 | 0 | 0 |
1 | 5 | 300 |
2 | 50 | 3600 |
3 | 150 | 21600 |
4 | 1500 | 86400 |
5 | 10000 | Permanently |
Users keep getting blocked from my mail servers!
Some applications, such as Thunderbird, try to be "helpful" by autoconfiguring themselves. For mail clients like Thunderbird this can involve attempting to connect to different ports associated with the domain of the email address it is trying to configure, and if those ports are not open it can look like a port scan. Consider whitelisting those particular ports setting the IGNORE_PORTS value.
In Puppet:
class { 'psad' :
config => {
ignore_ports => ['tcp/25', 'tcp/113']
}
}
In Hiera:
psad::config:
ignore_ports:
- 'tcp/25'
- 'tcp/113'
I'm locked out of my machine!
Find someone who isn't locked out and have them run "psad -F" as root. Then whitelist your machine.
Reference
Classes
####Public Classes
- psad: Main class, includes all other classes.
####Private Classes
- psad::config: Handles the configuration and autold files.
- psad::cron: Handles the signature update cronjob.
- psad::firewall: Handles the firewall logging rules.
- psad::install: Handles the installation of PSAD.
- psad::params: Contains variables and defaults used throughout the module.
- psad::service: Handles the PSAD service.
Parameters
Parameter | Type | Default |
---|---|---|
config | hash | PSAD Config |
autodl | hash | Empty |
commands | hash | OS Specific |
firewall_enable | bool | true |
firewall_priority | int | 895 |
cronjob_enable | bool | true |
####config
Set specific PSAD values to override PSAD defaults in it's config file. Each value here comes directly from the PSAD Configuration.
####autodl
Set automatic danger levels for specific hosts, protocols and ports. Danger levels of 0 act as a whitelist, while levels of 5 will result in the host being blocked.
####commands
Set location of dependent binary if they're in nonstandard locations.
####firewall_enable
Set this to add the logging rules to the firewall.
####firewall_priority
Set this to change the priority of the logging rules in the firewall.
####cronjob_enable
Set this to add a cronjob to update PSADs signatures daily.
Limitations
This module has been built on and tested against Puppet 3.4 and higher.
The module has been tested on:
- Debian
- Ubuntu
Development
Contributions are always welcome! Please visit this module's home on Github.
Release Notes
This package is maintained by Robert Hafner. Notices and updates can be found on his blog.
##2017-05-18 - Release 1.2.1
Summary
This is a bugfix release.
##2017-05-18 - Release 1.2.0
Summary
This release focuses on cross compatibility and improving the defaut settings.
Features
-
Automatically selects the best options for Redhat and Debian family systems.
-
Signature updates now occur using SSL instead of HTTP.
-
The default value of "enable_auto_ids" has been switched to off, requiring users to explicitly turn on blocking. This way they can test first and check through the PSAD logs for any errors.
-
The default auto_dl has been set to level two, which is a little more lenient than level one.
-
The default packet number for level two has been set to 50, from 15.
-
The default blocking time for level one is now five minutes.
-
New configuration options for later versions of PSAD are supported.
##2015-01-07 - Release 1.1.2
Summary
This release focuses on code quality improvements and service robustness.
Features
- Improved handling of PSAD status checks.
- Code Formatting Improvements based around puppet-lint.
- Fleshed out comments in the PSAD class.
##2014-10-09 - Release 1.1.0
Summary
This update takes into account user feedback and adds better support for IPv6.
Features
- Further improved handling of array values in PSAD configuration.
- Rewrote templates using community suggested best practices.
- Added logging for IPv6 firewalls.
- Reworked class dependencies to prevent PSAD error email on first run.
Backwards-incompatible Changes:
- Tightened up default settings to ensure that blocking works out of the box.
##2014-10-06 - Release 1.0.0
Summary
This is the first stable release of this module. This update primarily updated documentation.
Features
- Improved handling of array values in PSAD configuration.
Backwards-incompatible Changes:
- Changed the
options
parameter toconfig
in the PSAD class.
Dependencies
- puppetlabs-firewall (>= 1.0.0)
Copyright (c) 2014, Robert Hafner All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Stash Project nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Robert Hafner BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.