Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

cffirehol

Firewall provider for cfnetwork based on FireHOL generator
Project URLRSS FeedReport issues

22,960 downloads

1,711 latest version

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

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.3.2 (latest)
  • 1.3.1
  • 1.3.0
  • 1.2.0
  • 1.1.0
  • 1.0.0
  • 0.12.2
  • 0.12.1
  • 0.12.0
  • 0.11.5
  • 0.11.4
  • 0.11.3
  • 0.11.2
  • 0.11.1
  • 0.11.0
  • 0.10.2
  • 0.10.1
  • 0.10.0
  • 0.9.12
  • 0.9.11
  • 0.9.10
  • 0.9.9
  • 0.9.7
  • 0.9.6
  • 0.9.5
  • 0.9.4
  • 0.9.2
  • 0.9.1
  • 0.9.0
released Nov 12th 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >=4.7.0 <7.0.0
  • ,

Start using this module

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

Add this module to your Puppetfile:

mod 'codingfuture-cffirehol', '1.3.2'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add codingfuture-cffirehol
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install codingfuture-cffirehol --version 1.3.2

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.

Download

Documentation

codingfuture/cffirehol — version 1.3.2 Nov 12th 2019

cffirehol

Description

This is not a standalone module. Please use with codingfuture/cfnetwork

Allmost all configuration is done through abstract cfnetwork::* resources, except for FireHOL-specific stuff.

By default, firewall is disabled!

Features:

  • Generic iptables
  • SYNPROXY support
  • Static & dynamic blacklists with whitelist exceptions
  • Single Packet Authorization (SPA) secure port knocking with fwknopd
  • Dynamic blacklists

The proper deployment procedure should be:

  • Add codingfuture/cfnetwork and codingfuture/cffirehol to R10K Puppetfile (or install manually)
  • Add related configuration to Hiera (strongly encouraged)
  • Deploy configuration
  • Verify network interfaces are properly configured
  • Verify that /etc/firehol/firehol.conf is properly configured
  • TRY firehol with: /sbin/firehol try
  • Ensure that at least new SSH connections work
  • Update Hiera to enable cffirehol
  • Deploy and pray ;)

Technical Support

Setup

Up to date installation instructions are available in Puppet Forge: https://forge.puppet.com/codingfuture/cffirehol

Please use librarian-puppet or cfpuppetserver module to deal with dependencies.

There is a known r10k issue RK-3 which prevents automatic dependencies of dependencies installation.

Examples

Please check codingufuture/puppet-test for example of a complete infrastructure configuration and Vagrant provisioning.

Implementation details

cffirehol has providers for cfnetwork resource types. On every puppet catalog apply, cffirehol read all defined resources from /etc/firehol/.firehol.json. Upon catalog apply is complete, a new JSON is generated. ONLY IF, new JSON does not byte-to-byte match the original one, a new /etc/firehol/firehol.conf is generated with both files getting rewritten.

If files get rewritten and cffirehol is enabled, /sbin/firehol start is executed. Custom Debian/Ubuntu packages for the latest FireHOL and dependencies are available at FireHOL Backports in Launchpad

Note: At the moment, firehol.conf generation is relatively messy and needs to be rewritten accompanied by unit tests

Notes of Firewall port knocking

There are various port knocking techniques, but interest is only most secure approaches like Single Packet Authorization. fwknop project was chosen as one of the most mature, used and maintained. However, only a very limited subset of the functionality is used for security reasons.

The daemon runs under unprivileged user and is only allowed to manipulate ipsets based on SPA packet received in UDP server mode.

Current configuration:

  • AES-256
  • HMAC-SHA-256
  • UDP with port from cffirehol::fwknop::port
  • User name and keys come from cffirehol::knocker configuration
  • IP is automatically added to whitelist ipset

Suggested .fwknoprc configuration:

[default]
WGET_CMD /usr/bin/wget
SPA_SERVER_PROTO udp
USE_HMAC Y
HMAC_DIGEST_TYPE sha256
RESOLVE_IP_HTTPS Y
# just a placeholder for SPA format
ACCESS tcp/1

[<server_name>]
SPA_SERVER <server_address>
SPA_SERVER_PORT <ffirehol::fwknop::port>
SPOOF_USER <cffirehol::knocker::user>
KEY_BASE64 <cffirehol::knocker::key_b64>
HMAC_KEY_BASE64 <cffirehol::knocker::hmac_key_b64>

Suggested command line:

fwknop -R -n myserver -A tcp/22

Knocking remote

In some cases, a dynamic IP is assigned to client hosts on every boot. This functionality checks access every 60 seconds and issues fwknop request, if it's unable to connect to test_port on target host within 3 seconds.

Classes and resources types

class cffirehol

The main class. Normally, it is included by bi-directional dependency from cfnetwork based on $firewall_provider parameter.

Options:

  • enable = false - if true, FireHOL will be enabled upon deployment. Note: /etc/firehol/firehol.conf is always generated
  • custom_headers = [] - optional, add custom FireHOL configuration headers
  • synproxy_public = true - protect TCP services with SYNPROXY on all public interfaces. Please see cfnetwork for definition of public interface.
  • knockers = {} - create resources of cffirehol::knocker when key is username.
  • knock_remote = {} - create knocking client.
    • user - user name for fwknop,
    • host - target host,
    • port - target fwknop UDP port,
    • test_port - target TCP port to check access,
    • key_b64 - fwknop key in Base64 encoding,
    • hmac_key_b64 - fwknop HMAC key in Base64 encoding.

class ffirehol::debian

Debian and Ubuntu specific FireHOL package configuration

  • firehol_apt_url = 'http://ppa.launchpad.net/andvgal/firehol-bpo/ubuntu' - repo with required packages
  • firehol_apt_release = 'trusty' - OS release Note: it is safe to use these Ubuntu packages on Debian of corresponding version (e.g. trusty & jessie have the same roots)

class `cffirehol::fwknop

Configuration of fwknopd FireWall knocking service.

  • enable = false - enable fwknopd daemon
  • port = 62201 - UDP port to use for fwknopd

type cffirehol::knocker

Configuration of firewall knocking user.

  • key_b64 - Base64 encoded key for message digest
  • hmac_key_b64 - Base64 encoded key for HMAC
  • user = $title - arbitrary user name for access check
  • ipset = 'cfauth_admin' - ipset to use for dynamic IP add, can be array of IP sets
  • 'timeout = 36060' - timeout to remove IP after (3 hours by default, 0 - disable)

type cffirehol::dynblacklist

Configuration of dynamic blacklist.

  • enable = false - enables cffirehol::dynblacklist
  • blacklists4 = ['dependencies of firehol-level1'] - list of blacklists to enable for IPv4
    • NOTE: there is problem of enabling list with dependency on other lists
  • blacklists6 = [] - list of blacklists to enable for IPv6
  • blacklist_cron = { minute => '*/10' } - cron resource default configuration for automatic updates
  • addon_ipsets = {} - list of "name" => "conf file content" to extend built-in blacklist config
  • custom_update = undef - arbitrary command to generate $custom_*_file files
  • custom_netset4_file = undef - path to external IPv4 blacklist, if any
  • custom_netset6_file = undef - path to external IPv6 blacklist, if any