Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

windows_firewall

puppet windows firewall module
Project URLRSS FeedReport issues

18,746 downloads

8,969 latest version

4.3 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

  • 0.3.4 (latest)
  • 0.3.3
  • 0.3.2
  • 0.3.1
  • 0.3.0
  • 0.2.1
  • 0.2.0
  • 0.1.5
  • 0.1.4
  • 0.1.3
  • 0.1.2
  • 0.1.1
  • 0.1.0
  • 0.0.8
  • 0.0.7
  • 0.0.6
  • 0.0.5
  • 0.0.4
  • 0.0.3
  • 0.0.2
  • 0.0.1
released Jan 23rd 2017
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >=3.7.2 <5.0.0

Start using this module

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

Add this module to your Puppetfile:

mod 'thoward-windows_firewall', '0.3.4'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add thoward-windows_firewall
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install thoward-windows_firewall --version 0.3.4

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

thoward/windows_firewall — version 0.3.4 Jan 23rd 2017

windows_firewall

####Table of Contents

  1. Overview - What is windows_firewall module?
  2. Module Description - What does this module do?
  3. Setup - Basics of getting started with windows_firewall
  4. Usage - Classes, defined types, and their parameters available for configuration
  5. Implementation - An under-the-hood peek at what this module is doing
  6. Limitations - OS compatibility, etc.
  7. Release Notes - Notes on the most recent updates to the module

##Overview This is a module that will manage the Microsoft Windows Firewall and its rules.

##Module Description

The windows_firewall module will primarily manage the state of the windows firewall application on your windows system. Also applies rules defined in hiera data source.

###Rule Enforcement Process +---------------------------------------------------------------------------------+ | | | +--+ | | v | | | +-------------------+ | | REMOVE |Rule Definitions| ADD | | +-----------+----------------+-----------+ | | v v | | +-------------------------------------+ +-------------------------------------+ | | | | | | | | | +------------------+ N +--------+ | | +------------------+ N +--------+ | | | | |Rule Name Present?+--->| Done! | | | |Rule Name Present?+--->|Add Rule| | | | | +--------+---------+ +--------+ | | +--------+---------+ +--------+ | | | | | ^ | | | | | | | Y | | | | Y | | | | | v | | | v | | | | +----------------------------+---+ | | +--------------------------------+ | | | | |Remove all matching rule names. | | | |Do all matching rule names match| | | | | +--------------------------------+ | | |definition property values? | | | | | | | +--------+--------------+--------+ | | | +-------------------------------------+ | | | | | | | Y| N| | | +-------------+-------------------------+ | v v | | | | | +-------------+ +--------------+ | | | | | |Are matching | |Set property | | | v | | |rule names | |values for all| | | +---------------------------+ | | |greater than |<---+matching rule | | | |Disable all rule names that| | | |one? | |names. | | | |do not exist in client's | | | +-+------+----+ +--------------+ | | |stored catalog. | | | | | | | +---------------------------+ | | N| Y| | | | | | v | | | | | +----------------------------+ | | | | | | De-duplicate matching rule | | | | | | | names. | | | | | | +---+------------------------+ | | | | | | | | | | | | | | | | v v | | | | +----------+ | | | | | Done! | | | | | +----------+ | | | | | | | +-------------------------------------+ | | | +-----------------------------------------+

##Setup

###What windows_firewall affects:

  • windows firewall profile and policy.
  • windows firewall rules.

###Beginning with windows_firewall

The windows_firewall resource allows you to manage the firewall profile state and their policy.

class { 'windows_firewall': 
    profile_state => 'on',
    in_policy     => 'BlockInbound',
    out_policy    => 'AllowOutbound',
    rule_key      => 'windows_networks',
    purge_rules   => true,
}

Windows_firewall loads rules from hiera stored as hashes using key defined in 'rule_key'.

Rules can be defined using json or yaml data resource. Below is a json example:

{
  "windows_networks": {
    "Rule 1": {
      "description": "This is rule 1.",
      "remote_addresses": "10.1.2.3,10.7.8.9",
      "local_ports": "1000,1010"
    },
    "Rule 2": {
      "description": "This is rule 2.",
      "remote_addresses": "10.4.5.6-10.4.5.150",
      "local_ports": "2000-2500"
    },
    "Rule 3": {
      "description": "This is rule 3.",
      "remote_addresses": "10.1.100.1/24",
      "local_ports": "3030",
      "interfaces": "Ethernet"
    }
  }
}

###Tools

####tools\generate_rule_definitions.ps1 Powershell script for generating JSON baseline rules from pre-existing enabled advfirewall rules on a Windows system.

####hieradata\base_windows_rules.json A pre-generated json hiera resource to get started.

##Usage

###Classes

####windows_firewall

Parameters within windows_firewall:

#####profile_state Determines whether or not service profiles are enabled. If not included, module will assume that windows firewall profiles should be enabled. Valid values are 'on' and 'off'.

#####in_policy Determines inbound policy for all profiles. If not included, module will assume that inbound policy is BlockInbound. Valid values are 'AllowInbound' and 'BlockInbound'.

#####out_policy Determines outbound policy for all profiles. If not included, module will assume that outbound policy is AllowOutbound. Valid values are 'AllowOutbound' and 'BlockOutbound'.

#####rule_key Determines what key name is used to load firewall rules from hiera.

#####purge_rules Determines whether or not to purge unmanaged firewall_rule resources on system. Valid values are 'true' and 'false'.

###Rule Parameters

Available parameters for rule definition:

#####ensure Determines whether or not the firewall exception is 'present' or 'absent'. Defaults to 'present'.

#####description A description of the rule. Defaults to ''.

#####application_name Sets path for application rule applies to. Defaults to ''.

#####service_name Sets name for service rule applies to. Defaults to ''.

#####protocol Sets the protocol to be included in rule. Following protocol names are valid:

  • 'ICMPv4'
  • 'IGMP'
  • 'TCP' (Default)
  • 'UDP'
  • 'IPv6'
  • 'IPv6Route'
  • 'IPv6Frag'
  • 'GRE'
  • 'ICMPv6'
  • 'IPv6NoNxt'
  • 'IPv6Opts'
  • 'VRRP'
  • 'PGM'
  • 'L2TP'

#####local_ports Defines local ports to be included in rule. Defaults to ''.

#####remote_ports Defines remote ports to be included in rule. Defaults to ''.

#####local_addresses Specifies local hosts that can use this rule. Defaults to ''.

#####remote_addresses Specifies remote hosts that can use this rule. Defaults to ''.

#####icmp_types_and_codes Specifies types and codes if protocol is ICMP. Format is 'Type:Code'. Do not attempt to set if protocol is not ICMP.

#####direction Sets the direction of the exception rule, either: 'In' or 'Out'. Defaults to 'In'.

#####interfaces Sets network interfaces rule applies to. Accepts a comma delimited list of network interface friendly names. Defaults to ''.

#####interface_types Sets interface types rule applies to. Following interface types are valid:

  • 'Wireless'
  • 'Lan'
  • 'RemoteAccess'
  • 'All' (Default)

Multiple types can be set by comma delimitation.

#####enabled Determines whether the exception is enabled, either: 'True' or 'False'. Defaults to 'True'.

#####grouping Defines the group name rule belongs to. Defaults to ''.

#####profiles Sets profiles rule applies to. Following profile names are valid:

  • 'Domain' (Default)
  • 'Private' (Default)
  • 'Public' (Default)

Multiple profiles can be set by comma delimitation.

#####edge_traversal Specifies whether traffic for rule traverses an edge device, either: 'True' or 'False'. Defaults to 'False'.

#####action Sets the action type of rule, either: 'Allow' or 'Block'. Defaults to 'Allow'.

#####edge_traversal_options Specifies edge traversal options. Following options are valid:

  • 'Block' (Default)
  • 'Allow'
  • 'Defer to App'
  • 'Defer to User'

##Implementation

###Custom Types

[firewall_rule]

Checks for following:

  • 'Puppet defined rule that does not match system rule counterpart property values.'
  • 'Puppet defined rule name on system does not occur more than once.'
  • 'Puppet defined rule that does not match ensured state found on system.'
$defaults = {
    protocol               => 6,
    description            => "",
    application_name       => "",
    service_name           => "",
    local_ports            => "",
    remote_ports           => "",
    local_addresses        => "",
    remote_addresses       => "",
    icmp_types_and_codes   => "",
    direction              => 1,
    interfaces             => "",
    interface_types        => 'All',
    enabled                => true,
    grouping               => "",
    profiles               => 2147483647,
    edge_traversal         => false,
    action                 => 1,
    edge_traversal_options => 0,
}

create_resources(firewall_rule, hiera_hash('windows_networks'), $defaults)

##Reference

###Classes ####Public Classes

  • windows_firewall: Main class of module for managing state of windows firewall profiles and their policies.

##Limitations

This module is tested on the following platforms:

  • Windows Server 2012 R2
  • Windows Server 2012
  • Windows Server 2008 R2
  • Windows Server 2008

##Development Submit issues or pull requests to GitHub

##Release-Notes

  • 0.3.4 (robklg) - Fix escape characters in firewall rule name.
  • 0.3.3 (amgarstang) - Remove dependency on win_facts module.
  • 0.3.2 puppet notice generated on rule de-dupe.
  • 0.3.0 provider and type re-written. postrun_facts dropped. purge_rules added.
  • 0.2.1 updated JSON rule generator tool.
  • 0.2.0 updated to ruby-centric code base. Powershell dep removed.
  • 0.1.5 (pcallewaert) - fixes firewall_policy breaks facts on linux
  • 0.0.8 option to update facts post configuration added
  • 0.0.4 switch over to hiera to store rules