Table of Contents

• Overview
• This is a SIMP module
• Module Description
• Setup
  • Beginning with simp_firewalld
• Usage
  • Opening a specific port
  • Allowing a range of TCP ports over IPv4
  • Allowing full access from a specific node
• Reference
• Limitations
• Development
  • Acceptance tests

Overview

simp_firewalld provides a profile class and defined type to manage the system's firewalld with "safe" defaults and safety checks for firewalld rules. It uses the puppet/firewalld module to update the system's firewalld configuration.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, submit them to our bug tracker.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

Module Description

On systems containing the firewalld service, simp_firewalld manages the system's firewalld configuration with "safe" defaults and safety checks for firewalld rules.

• The puppet/firewalld module is used to update the system's firewalld configuration.

Setup

Beginning with simp_firewalld

Start by classifying the node with simp_firewalld and start adding rules with simp_firewalld::rule:

  include 'simp_firewalld'

  # Add rules with simp_firewalld::rule
  simp_firewalld::rule { 'allow_all_ssh':
    trusted_nets => ['all'],
    protocol     => tcp,
    dports       => 22
  }

See the Usage section and REFERENCE.md file for examples of setting firewall rules.

Usage

Opening a specific port

  simp_firewalld::rule { 'allow_all_ssh':
    trusted_nets => ['all'],
    protocol     => tcp,
    dports       => 22
  }

Note that when using simp_firewalld::rule as part of the full SIMP framework, the trusted_nets parameter will default to the value of $simp_options::trusted_nets:

  simp_firewalld::rule { 'allow_ssh_to_trusted_nets':
    protocol     => tcp,
    dports       => 22
  }

Allowing a range of TCP ports over IPv4

simp_firewalld::rule { 'allow_tcp_range':
  trusted_nets => ['192.168.1.0/24'],
  dports       => ['1024:60000'],
  apply_to     => 'ipv4',
}

Allowing full access from a specific node

Using simp_firewalld::rules:

simp_firewalld::rules => {
  'allow_all_to_central_management' => {
    'trusted_nets' => ['10.10.35.100'],
    'protocol'     => 'all',
  }
}

Using simp_firewalld::rules via hieradata:

simp_firewalld::rules:
  allow_all_to_central_management:
    trusted_nets:
      - '10.10.35.100'
    protocol: 'all'

Using simp_firewalld::rule directly:

simp_firewalld::rule { 'allow_all_to_central_management':
  trusted_nets => ['10.10.35.100'],
  protocol     => 'all',
}

Reference

See REFERENCE.md

Limitations

• This module is intended to be used on a Redhat Enterprise Linux-compatible distribution such as EL7 and EL8.
• IPv6 support has not been fully tested, use with caution

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests, run the following:

bundle install
bundle exec rake beaker:suites[default]

Please refer to the SIMP Beaker Helpers documentation for more information.

Reference

Table of Contents

Classes

• simp_firewalld: This is a firewalld profile that sets "safe" defaults as is usual in SIMP modules

Defined types

• simp_firewalld::rule: Add firewalld rules with various safety checks

Data types

• Simp_firewalld::ApplyTo: Valid families to which rules should apply
• Simp_firewalld::DestPort: A firewalld::rule compatible port range or Array
• Simp_firewalld::PortRange: A firewalld-compatible Port Range

Classes

simp_firewalld

If you want to override any element not present in the firewalld class resource below then you should use Hiera directly on the firewalld class.

Examples

creating a new rule via class declaration:

simp_firewalld::rules => {
  'allow_port_22' => {
    'protocol' => 'tcp',
    'dports'   => 22,
  }
}

same example, but with hieradata

simp_firewalld::rules:
  allow_port_22:
    protocol: tcp
    dports: 22

Parameters

The following parameters are available in the simp_firewalld class:

• rules
• firewall_backend
• enable
• complete_reload
• lockdown
• default_zone
• log_denied
• enable_tidy
• tidy_dirs
• tidy_prefix
• tidy_minutes
• simp_zone_purge_rich_rules
• simp_zone_purge_services
• simp_zone_purge_ports
• simp_zone_interfaces
• simp_zone_target
• simp_zone_masquerade
• package_ensure

rules

Data type: Hash

A hash of firewalld::rules that should be created

firewall_backend

Data type: Enum['iptables','nftables']

Allows you to set the backend that firewalld will use.

enable

Data type: Boolean

Activate the firewalld management capabilties.

• The class will not be enabled if firewalld is not detected on the remote system. This can be overridden by setting this option to true explicitly in Hiera.

Default value: 'firewalld' in pick($facts['simplib__firewalls'], 'none')

complete_reload

Data type: Boolean

The current firewalld module has the capability to perform a complete reload of firewalld which breaks any existing connections. This is extremely dangerous and this class overrides and disables this capability by default.

• Set to true to re-enable this capability.

Default value: false

lockdown

Data type: Boolean

Set firewalld in lockdown mode which disallows manipulation by applications.

• This makes sense to do by default since puppet is meant to be authoritative on the system.

Default value: true

default_zone

Data type: String[1]

The 'default zone' to set on the system.

This is set to 99_simp so that regular, alternative, zone manipulation can occur without interference.

IMPORTANT: If this is set to anything besides 99_simp, all rules in this module will NOT apply to the default zone! This module is set to only populate 99_simp zone rules.

Default value: '99_simp'

log_denied

Data type: Enum['off', 'all','unicast','broadcast','multicast']

What types of logs to process for denied packets.

@see LogDenied in firewalld.conf(5)

Default value: 'unicast'

enable_tidy

Data type: Boolean

Enable the Tidy resources that help keep the system clean from cruft

Default value: true

tidy_dirs

Data type: Array[Stdlib::Absolutepath]

The directories to target for tidying

Default value:

[
                                                                                      '/etc/firewalld/icmptypes',
                                                                                      '/etc/firewalld/ipsets',
                                                                                      '/etc/firewalld/services',
                                                                                    ]

tidy_prefix

Data type: String[1]

The name match to use for tidying files

Default value: 'simp_'

tidy_minutes

Data type: Integer[1]

Number of minutes to consider a configuration file 'stale' for the purposes of tidying.

Default value: 10

simp_zone_purge_rich_rules

Data type: Boolean

If true, any unmanaged rich rules will be removed from the zone

Default value: true

simp_zone_purge_services

Data type: Boolean

If true, any unmanaged services will be removed from the zone

Default value: true

simp_zone_purge_ports

Data type: Boolean

If true, any unmanaged ports will be removed from the zone

Default value: true

simp_zone_interfaces

Data type: Array[Optional[String[1]]]

The network interfaces to which the underlying 99_simp zone should apply

Default value: []

simp_zone_target

Data type: Enum['default', 'ACCEPT', 'REJECT', 'DROP']

The default target for the 99_simp zone

Default value: 'DROP'

simp_zone_masquerade

Data type: Boolean

Whether to add or remove masquerading from the 99_simp zone

Default value: false

package_ensure

Data type: String[1]

The 'ensure' value for package resources

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

Defined types

simp_firewalld::rule

Add firewalld rules with various safety checks

Parameters

The following parameters are available in the simp_firewalld::rule defined type:

• trusted_nets
• protocol
• dports
• icmp_blocks
• order
• apply_to
• prefix
• zone

trusted_nets

Data type: Simplib::Netlist

The networks/hosts to which the rule applies

Default value: simplib::lookup('simp_options::trusted_nets', { 'default_value' => ['127.0.0.1'] })

protocol

Data type: Enum['ah', 'esp', 'icmp', 'tcp', 'udp', 'all']

The network protocol to which the rule applies

dports

Data type: Optional[Simp_firewalld::DestPort]

The ports to which the rule applies

Default value: undef

icmp_blocks

Data type: Optional[Variant[Array[String],String]]

The ICMP Blocks to which the rule applies

Default value: undef

order

Data type: Integer[0]

The order in which the rule should appear

Due to the way firewalld works, this may not do what you expect unless the version of firewalld explicitly supports it.

• 1 is the minimum and 9999999 is the maximum

• The following ordering ranges are suggested (but not enforced):

  • 1 -> ESTABLISHED,RELATED rules
  • 2-5 -> Standard ACCEPT/DENY rules
  • 6-10 -> Jumps to other rule sets
  • 11-20 -> Pure accept rules
  • 22-30 -> Logging and rejection rules

Default value: 11

apply_to

Data type: Simp_firewalld::ApplyTo

The address family to which to apply this rule

• ipv4 -> iptables
• ipv6 -> ip6tables
• all -> Both
• auto -> Try to figure it out from the rule, defaults to all

Default value: 'auto'

prefix

Data type: Optional[String[1]]

This will be prepended to all created components

• This is important for being able to tidy rules later on.
• Will default to $simp_firewalld::tidy_prefix if set and simp_ otherwise

Default value: undef

zone

Data type: Optional[String[1]]

The zone to which to apply the rule

• Will default to $simp_firewalld::default_zone if set and 99_simp otherwise

Default value: undef

Data types

Simp_firewalld::ApplyTo

Valid families to which rules should apply

Alias of Enum['ipv4', 'ipv6', 'all', 'auto']

Simp_firewalld::DestPort

A firewalld::rule compatible port range or Array

Alias of Variant[Simplib::Port, Simp_firewalld::PortRange, Array[Variant[Simplib::Port, Simp_firewalld::PortRange]]]

Simp_firewalld::PortRange

A firewalld-compatible Port Range

Alias of Pattern['^([0-5]?\d?\d?\d?\d|6[0-4]\d\d\d|65[0-4]\d\d|655[0-2]\d|6553[0-5]):([0-5]?\d?\d?\d?\d|6[0-4]\d\d\d|65[0-4]\d\d|655[0-2]\d|6553[0-5])$']

• Thu Jan 18 2024 Mike Riddle mike@sicura.us - 0.10.0

• Made the 99_simp zone purge parameters toggle-able

• Thu Nov 30 2023 Sean Peterson ________@gmail.com - 0.9.0

• Add $simp_zone_masquerade parameter

• Mon Oct 23 2023 Steven Pritchard steve@sicura.us - 0.8.0

• [puppetsync] Add EL9 support

• Mon Oct 23 2023 Steven Pritchard steve@sicura.us - 0.8.0

• [puppetsync] Add EL9 support

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.7.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Mon Oct 02 2023 Steven Pritchard steve@sicura.us - 0.6.0

• Use firewalld_custom_service instead of firewalld::custom_service for compatibility with puppet-firewalld >= 5.0.0
• Support stdlib 9
• Support Puppet 8
• Drop support for Puppet 6

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 0.5.0

• Add AlmaLinux 8 support

• Mon Aug 14 2023 Mike Riddle mike@sicura.us - 0.4.2

• Moved the common.yaml to the top level data directory so it will actually be read

• Mon Aug 07 2023 Mike Riddle mike@sicura.us - 0.4.1

• Allow the simp_firewalld class to take in rules via hieradata

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 0.4.0

• Add RockyLinux 8 support

• Thu Jan 19 2023 Michael Riddle mike@sicura.us - 0.3.2

• Support RHEL 9
• Added a default hieradata file for more flexibility

• Sun Feb 13 2022 Trevor Vaughan trevor@sicura.us - 0.3.1

• Support Amazon Linux 2
• Work around upstream bug:
  • puppet-firewalld needs to have an autorequire on firewalld_custom_service if one is declared.

• Tue Dec 21 2021 Kendall Moore kendall@sicura.us - 0.3.0

• Changed default backend to nftables for RHEL 8

• Wed Jun 16 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 0.2.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Sat Dec 19 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 0.1.3

• Removed EL6 support

• Tue Nov 17 2020 Trevor Vaughan tvaughan@onyxoint.com - 0.1.2

• Ensure that the firewall backend is not set on systems without multiple backends

• Thu Jul 30 2020 Adam Yohrling adam.yohrling@onyxpoint.com - 0.1.1

• Add support for ESP and AH protocol rules

• Thu May 21 2020 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.0

• Initial module release