Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

windows_firewall

Manage the windows firewall with Puppet (netsh)
Project URLRSS FeedReport issues

26,689 downloads

4,643 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.

Version information

  • 0.5.0 (latest)
  • 0.4.0
  • 0.3.0
  • 0.2.4
  • 0.2.3
  • 0.2.2
  • 0.2.1
  • 0.2.0
  • 0.1.1
  • 0.1.0
released Mar 4th 2020
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
  • windows
This module has been deprecated by its author since Jan 4th 2021.

The author has suggested webalex-windows_firewall as its replacement.

Start using this module

Documentation

geoffwilliams/windows_firewall — version 0.5.0 Mar 4th 2020

Build Status

windows_firewall

Table of Contents

  1. Description
  2. Usage - Configuration options and additional functionality
  3. Limitations - OS compatibility, etc.
  4. Development - Guide for contributing to the module

Description

Manage the windows firewall with Puppet (netsh and PowerShell as required).

Features

  • Create/edit/delete individual firewall rules (windows_firewall_rule)
  • Enable/disable firewall groups (windows_firewall_group)
  • Adjust global settings (windows_firewall_global)
  • Adjust per-profile settings (windows_firewall_profile)

Usage

windows_firewall_rule

Manage individual firewall rules

Listing firewall rules

The type and provider is able to enumerate the firewall rules existing on the system:

C:\>puppet resource windows_firewall_rule
...
windows_firewall_rule { '{FCC26AEB-5C68-481A-96DA-8A404F73714C}':
  ensure                => 'present',
  action                => 'allow',
  description           => 'Mail and Calendar',
  direction             => 'inbound',
  display_group         => 'Mail and Calendar',
  display_name          => 'Mail and Calendar',
  edge_traversal_policy => 'allow',
  enabled               => 'true',
  icmp_type             => 'any',
  interface_type        => ['any'],
  local_address         => 'any',
  local_port            => 'any',
  profile               => ['domain', 'private', 'public'],
  program               => 'Any',
  protocol              => 'any',
  remote_address        => 'any',
  remote_port           => 'any',
}

You can limit output to a single rule by passing its name as an argument, eg:

C:\>puppet resource windows_firewall_rule winrm
windows_firewall_rule { 'winrm':
  ensure                => 'present',
  action                => 'allow',
  direction             => 'inbound',
  display_name          => 'winrm',
  edge_traversal_policy => 'block',
  enabled               => 'true',
  interface_type        => ['any'],
  local_address         => 'any',
  local_port            => '5985',
  profile               => ['domain', 'private', 'public'],
  protocol              => 'tcp',
  remote_address        => 'any',
  remote_port           => 'any',
}

Ensuring a rule

The basic syntax for ensuring rules is: 

windows_firewall_rule { "name of rule":
  ensure => present,
  ...
}

If a rule with the same name but different properties already exists, it will be deleted and re-created to ensure it is defined correctly. To delete a rule, set ensure => absent.

Managing ICMP

windows_firewall_rule { "puppet - all icmpv4":
  ensure    => present,
  direction => "inbound",
  action    => "allow",
  protocol  => "icmpv4",
}

You can also create a rule that only allows a specific ICMP type and code:

windows_firewall_rule { "puppet - allow icmp echo":
  ensure    => present,
  direction => "inbound",
  action    => "allow",
  protocol  => "icmpv4",
  icmp_type => "8:10",
}

You need to create one rule for each icmp_type value (see limitations).

Managing Ports

Use the local_port and remote_port properties to set the ports a rule refers to. You can set an individual ports, a range or combination:

windows_firewall_rule { "puppet - allow ports 1000-2000":
  ensure     => present,
  direction  => "inbound",
  action     => "allow",
  protocol   => "tcp",
  local_port => "80,443,4243,5000-5010",
}

Managing local/remote addresses

Use the local_address and remote_address properties to target rules at particular address. You can use individual or multiple addresses:

windows_firewall_rule { "puppet - multiple remote and local addresses":
  ensure         => present,
  direction      => "inbound",
  action         => "allow",
  protocol       => "tcp",
  profile        => ["private", "domain"],
  local_port     => 7777,
  remote_port    => 7777,
  local_address  => "192.168.1.1,10.10.10.10",
  remote_address => "192.168.1.2,192.168.2.11",
}

Managing Programs

windows_firewall_rule { "puppet - allow messenger":
  ensure    => present,
  direction => "inbound",
  action    => "allow",
  program   => "C:\\programfiles\\messenger\\msnmsgr.exe",
}

Creating rules in specific profiles

windows_firewall_rule { "puppet - open port in specific profiles":
  ensure     => present,
  direction  => "inbound",
  action     => "allow",
  protocol   => "tcp",
  profile    => ["private", "domain"],
  local_port => "666",
}

Purging rules

You can choose to purge unmanaged rules from the system (be careful! - this will remove any rule that is not manged by Puppet including those created by Windows itself):

resources { "windows_firewall_rule":
  purge => true,
}

windows_firewall_rule { "puppet - allow all":
  ensure     => present,
  direction  => "inbound",
  action     => "allow",
  protocol   => "tcp",
  local_port => "any",
}

windows_firewall_group

Enable/Disable named groups of firewall rules. Not that it is only possible to enable/disable existing groups, not create or edit them.

Enabling a group of rules

windows_firewall_group { "File and Printer Sharing":
  enabled => true,
}

Disabling a group of rules

windows_firewall_group { "File and Printer Sharing":
  enabled => false,
}

windows_firewall_global

Global settings always exist (there is no ensure).

Displaying settings

You can use puppet resource windows_firewall_global to check what Puppet thinks the current values are:

C:\vagrant>puppet resource windows_firewall_global
windows_firewall_global { 'global':
  authzcomputergrp          => 'none',
  authzcomputergrptransport => 'none',
  authzusergrp              => 'none',
  authzusergrptransport     => 'none',
  boottimerulecategory      => 'windows firewall',
  consecrulecategory        => 'windows firewall',
  defaultexemptions         => ['dhcp', 'neighbordiscovery'],
  firewallrulecategory      => 'windows firewall',
  forcedh                   => 'yes',
  ipsecthroughnat           => 'serverbehindnat',
  keylifetime               => '485min,0sess',
  saidletimemin             => '6',
  secmethods                => 'dhgroup2:aes128-sha1,dhgroup2:3des-sha1',
  statefulftp               => 'disable',
  statefulpptp              => 'disable',
  stealthrulecategory       => 'windows firewall',
  strongcrlcheck            => '1',
}

Note: some properties are read-only.

Managing global settings

A single resource with an arbitrary title should be used to manage the desired settings, eg:

windows_firewall_global { 'global':
  authzcomputergrp          => 'none',
  authzusergrp              => 'none',
  defaultexemptions         => ['neighbordiscovery','dhcp'],
  forcedh                   => 'yes',
  ipsecthroughnat           => 'serverbehindnat',
  keylifetime               => '485min,0sess',
  saidletimemin             => '6',
  secmethods                => 'dhgroup2:aes128-sha1,dhgroup2:3des-sha1',
  statefulftp               => 'disable',
  statefulpptp              => 'disable',
  strongcrlcheck            => '1',
}

windows_firewall_profile

There are three firewall profiles that the module supports:

  • private
  • domain
  • public

Depending on the network the node is connected to, one of these profiles will be active. They map to three Puppet resources which cannot be ensured:

  • Windows_firewall_profile[private]
  • Windows_firewall_profile[domain]
  • Windows_firewall_profile[public]

Displaying settings

Use puppet resource windows_firewall_profile to see what puppet thinks the settings are:

C:\vagrant>puppet resource windows_firewall_profile
windows_firewall_profile { 'domain':
  filename                   => '%systemroot%\system32\logfiles\firewall\pfirewall.log',
  firewallpolicy             => 'blockinbound,allowoutbound',
  inboundusernotification    => 'disable',
  localconsecrules           => 'n/a (gpo-store only)',
  localfirewallrules         => 'n/a (gpo-store only)',
  logallowedconnections      => 'disable',
  logdroppedconnections      => 'disable',
  maxfilesize                => '4096',
  remotemanagement           => 'disable',
  state                      => 'on',
  unicastresponsetomulticast => 'enable',
}
windows_firewall_profile { 'private':
  filename                   => '%systemroot%\system32\logfiles\firewall\pfirewall.log',
  firewallpolicy             => 'blockinbound,allowoutbound',
  inboundusernotification    => 'disable',
  localconsecrules           => 'n/a (gpo-store only)',
  ...

Note that some settings are read-only

Turning profile firewalls on/off

Use the state property on some or all of the profiles:

windows_firewall_profile { 'private':
  state => false, # off
}

windows_firewall_profile { ['public', 'domain']:
  state => true, # on
}

The values true/on or false/off are acceptable. If supplying data from YAML files in Hiera, on and off will be implicitly
converted to boolean

Managing settings

Manage the settings for each of the three profiles you want to manage. To set everything to the same value, use an array for title:

windows_firewall_profile { ['domain', 'private']:
  inboundusernotification    => 'enable',
  firewallpolicy             => 'allowinbound,allowoutbound',
  logallowedconnections      => 'enable',
  logdroppedconnections      => 'enable',
  maxfilesize                => '4000',
  remotemanagement           => 'enable',
  state                      => 'on',
  unicastresponsetomulticast => 'disable',
}

Troubleshooting

  • Try running puppet in debug mode (--debug)
  • To reset firewall to default rules: netsh advfirewall reset You need this if your getting no rules match errors or errors from global settings
  • You may get missing parameter errors from Puppet after upgrading the module. These can normally be fixed by removing older versions and restarting Puppet Master
  • Print all firewall rules using netsh netsh advfirewall firewall show rule all verbose
  • Print all firewall rules as read by Puppet powershell -file lib\ps\windows_firewall\ps-bridge.ps1 show
  • Print firewall global settings netsh advfirewall show global
  • Print firewall profile settings netsh advfirewall show allprofiles
  • Use the "Windows Firewall with advanced security" program if you would like a GUI to view/edit firewall status
  • Help on how to create firewall rules
  • Help on how to change global settings (obtained from: netsh advfirewall set global)
  • Help on how to change profile settings (obtained from: netsh advfirewall set private)

Limitations

  • Will not work on non-English versions of Windows

  • netsh is used to enumerate most rules and is very fast. In some cases netsh will be unable to resolve names for some rules so we fallback to PowerShell instead. This is handled by the ps-bridge.ps1

  • Enumerate rules using PowerShell API is very slow. There's not much more that can be done about this short of deleting the offending rules.

  • Deleting (purging) rules is very slow (~5-10 minutes) This is because deleting these rules with PowerShell is slow. There's not much that can be done about this but once unwanted rules are deleted (Windows 10 ships with ~300 rules) future operations will be a lot faster

  • Requires the netsh advfirewall command and PowerShell

  • Property names match those used by PowerShell (groups, rules) and netsh for everything else so there is inconsistency in the equivalent puppet property names and values (some names are run-together, others separated by underscores). This is deliberate and makes the module code much simpler as names map exactly

  • It is not possible to edit the grouping for rules (netsh does not support this)

  • It is not possible to edit the localfirewallrules or localconsecrules for profiles (this needs corresponding group policy)

  • The Windows Advanced Firewall GUI allows multiple individual types to be set for ICMPv4 and ICMPv6 however this does not seem to be possible through the netsh CLI. Therefore you must create individual rules if for each type you wish to allow if you want to limit a rule in this way, eg:

    windows_firewall_rule { "allow icmp echo":
  ensure    => present,
  protocol  => "icmpv4",
  icmp_type => "8",
  action    => "allow",
}

windows_firewall_rule { "allow icmp time exceeded":
  ensure    => present,
  protocol  => "icmpv4",
  icmp_type => "11",
  action    => "allow",
}

Development

PRs accepted :)

Testing

Automatic testing using PDQTest 2. Needs to be run in a throw-away VM since its impossible to manage the firewall in containerised Windows:

https://social.msdn.microsoft.com/Forums/en-US/3c5be919-765b-4ea6-936b-60f3ac0986aa/windows-firewall-service-is-stopped-on-windows-container