Forge Home


PSAD Management with Puppet


13,664 latest version

3.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.2.1 (latest)
  • 1.2.0
  • 1.1.2
  • 1.1.0
  • 1.0.0
  • 0.1.0
released May 18th 2017
This version is compatible with:
  • Puppet 3.x
  • , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'tedivm-psad', '1.2.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add tedivm-psad
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install tedivm-psad --version 1.2.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



tedivm/psad — version 1.2.1 May 18th 2017


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
  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


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.


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 => ['', '']
  firewall_priorty => 850


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 => ['', '']

This can also be configured using Hiera.

# Common.yaml
    - ''
# DatacenterA.yaml
    - ''

How do I block attackers?

In Puppet:

class { 'psad' :
  config => {
    enable_auto_ids => 'Y'

In Hiera:

  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 => {
    "" => {
      'level' => 0
    "" => {
      'level' => 5
    "" => {
      'level' => 5,
      'proto' => 'tcp'

Using Hiera you can split your configurations up into different files.

# Common.yaml
    level: '0'
# DatacenterA.yaml
    level: '5'
    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:

    - '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.



####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.


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


Set specific PSAD values to override PSAD defaults in it's config file. Each value here comes directly from the PSAD Configuration.


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.


Set location of dependent binary if they're in nonstandard locations.


Set this to add the logging rules to the firewall.


Set this to change the priority of the logging rules in the firewall.


Set this to add a cronjob to update PSADs signatures daily.


This module has been built on and tested against Puppet 3.4 and higher.

The module has been tested on:

  • Debian
  • Ubuntu


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.