Home

Awesome

firewall Cookbook

Cookbook Version CI State OpenCollective OpenCollective License

Provides a set of primitives for managing firewalls and associated rules.

PLEASE NOTE - The resource/providers in this cookbook are under heavy development. An attempt is being made to keep the resource simple/stupid by starting with less sophisticated firewall implementations first and refactor/vet the resource definition with each successive provider.

Maintainers

This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit sous-chefs.org or come chat with us on the Chef Community Slack in #sous-chefs.

Requirements

depends 'firewall'

Supported firewalls and platforms

Tested on:

By default, Ubuntu chooses ufw. To switch to iptables, set this in an attribute file:

default['firewall']['ubuntu_iptables'] = true

By default, Red Hat & CentOS >= 7.0 chooses firewalld. To switch to iptables, set this in an attribute file:

default['firewall']['redhat7_iptables'] = true

In order to use nftables, just use the resource nftables and nftables_rule. These resources are written in more modern design styles and are not configurable by node attributes.

Considerations that apply to all firewall providers and resources

This cookbook comes with two resources, firewall and firewall rule. The typical usage scenario is as follows:

There is a fundamental mismatch between the idea of a chef action and the action that should be taken on a firewall rule. For this reason, the chef action for a firewall_rule may be :nothing (the rule should not be present in the firewall) or :create (the rule should be present in the firewall), but the action taken on a packet in a firewall (DROP, ACCEPT, etc) is denoted as a command parameter on the firewall_rule resource.

The same points hold for the nftables- and nftables_rule-resources.

iptables considerations

If you need to use a table other than *filter, the best way to do so is like so:

node.default['firewall']['iptables']['defaults'][:ruleset] = {
  '*filter' => 1,
  ':INPUT DROP' => 2,
  ':FORWARD DROP' => 3,
  ':OUTPUT ACCEPT_FILTER' => 4,
  'COMMIT_FILTER' => 100,
  '*nat' => 101,
  ':PREROUTING DROP' => 102,
  ':POSTROUTING DROP' => 103,
  ':OUTPUT ACCEPT_NAT' => 104,
  'COMMIT_NAT' => 200
}

Note -- in order to support multiple hash keys containing the same rule, anything found after the underscore will be stripped for: :OUTPUT :INPUT :POSTROUTING :PREROUTING COMMIT. This allows an example like the above to be reduced to just repeated lines of COMMIT and :OUTPUT ACCEPT while still avoiding duplication of other things.

Then it's trivial to add additional rules to the *nat table using the raw parameter:

firewall_rule "postroute" do
  raw "-A POSTROUTING -o eth1 -p tcp -d 172.28.128.21 -j SNAT --to-source 172.28.128.6"
  position 150
end

Note that any line starting with COMMIT will become just COMMIT, as hash keys must be unique but we need multiple commit lines.

nftables

Please read the documentation for the nftables resource and the nftables_rule resource

default

The default recipe creates a firewall resource with action install.

disable_firewall

Used to disable platform specific firewall. Many clouds have their own firewall configured outside of the OS instance such as AWS Security Groups.

firewalld

A firewalld specific recipe creates a firewall resource with action install with the default zone (default: drop)

Attributes

Resources

There is a separate folder for firewalld resources.

firewall

NB: The name 'default' of this resource is important as it is used for firewall_rule providers to locate the firewall resource. If you change it, you must also supply the same value to any firewall_rule resources using the firewall_name parameter.

Actions

Parameters

# all defaults
firewall 'default'

# enable platform default firewall
firewall 'default' do
  action :install
end

# increase logging past default of 'low'
firewall 'default' do
  log_level :high
  action    :install
end

firewall_rule

Actions

Parameters

# open standard ssh port
firewall_rule 'ssh' do
  port     22
  command  :allow
end

# open standard http port to tcp traffic only; insert as first rule
firewall_rule 'http' do
  port     80
  protocol :tcp
  position 1
  command   :allow
end

# restrict port 13579 to 10.0.111.0/24 on eth0
firewall_rule 'myapplication' do
  port      13579
  source    '10.0.111.0/24'
  direction :in
  interface 'eth0'
  command    :allow
end

# specify a protocol number (supported on centos/redhat)
firewall_rule 'vrrp' do
  protocol    112
  command      :allow
end

# use the iptables provider to specify protocol number on debian/ubuntu
firewall_rule 'vrrp' do
  provider    Chef::Provider::FirewallRuleIptables
  protocol    112
  command      :allow
end

# can use :raw command with UFW provider for VRRP
firewall_rule "VRRP" do
  command   :allow
  raw "allow to 224.0.0.18"
end

# open UDP ports 60000..61000 for mobile shell (mosh.org), note
# that the protocol attribute is required when using port_range
firewall_rule 'mosh' do
  protocol   :udp
  port       60000..61000
  command     :allow
end

# open multiple ports for http/https, note that the protocol
# attribute is required when using ports
firewall_rule 'http/https' do
  protocol :tcp
  port     [80, 443]
  command   :allow
end

# firewalld example of opening port 22 on public zone
firewall_rule 'ssh' do
  port    22
  zone    "public"
  command :allow
end

firewall 'default' do
  enabled false
  action :nothing
end

Providers

Different providers will determine the current state of the rules differently -- parsing the output of a command, maintaining the state in a file, or some other way. If the firewall is adjusted from outside of chef (non-idempotent), it's possible that chef may be caught unaware of the current state of the firewall. The best workaround is to add a :flush action to the firewall resource as early as possible in the chef run, if you plan to modify the firewall state outside of chef.

Troubleshooting

To figure out what the position values are for current rules, print the hash that contains the weights:

require pp
default_firewall = resources(:firewall, 'default')
pp default_firewall.rules

Development

This section details "quick development" steps. For a detailed explanation, see [[Contributing.md]].

  1. Clone this repository from GitHub:

$ git clone git@github.com:chef-cookbooks/firewall.git

  1. Create a git branch

$ git checkout -b my_bug_fix

  1. Install dependencies:

$ bundle install

  1. Make your changes/patches/fixes, committing appropiately
  2. Write tests
  3. Run the tests:

In detail:

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers!

https://opencollective.com/sous-chefs#backers

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website.

https://opencollective.com/sous-chefs/sponsor/0/website https://opencollective.com/sous-chefs/sponsor/1/website https://opencollective.com/sous-chefs/sponsor/2/website https://opencollective.com/sous-chefs/sponsor/3/website https://opencollective.com/sous-chefs/sponsor/4/website https://opencollective.com/sous-chefs/sponsor/5/website https://opencollective.com/sous-chefs/sponsor/6/website https://opencollective.com/sous-chefs/sponsor/7/website https://opencollective.com/sous-chefs/sponsor/8/website https://opencollective.com/sous-chefs/sponsor/9/website