psad

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with psad
   • What psad affects
   • Setup requirements
   • Beginning with psad
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
8. 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.

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

####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 to config in the PSAD class.