{"id":13781490,"url":"https://github.com/sous-chefs/firewall","last_synced_at":"2025-05-16T13:04:49.089Z","repository":{"id":2725685,"uuid":"3720591","full_name":"sous-chefs/firewall","owner":"sous-chefs","description":"Development repository for the firewall cookbook","archived":false,"fork":false,"pushed_at":"2025-01-30T14:21:21.000Z","size":711,"stargazers_count":100,"open_issues_count":28,"forks_count":152,"subscribers_count":52,"default_branch":"main","last_synced_at":"2025-05-08T04:28:22.188Z","etag":null,"topics":["chef","chef-cookbook","chef-resource","firewall","hacktoberfest","managed-by-terraform"],"latest_commit_sha":null,"homepage":"https://supermarket.chef.io/cookbooks/firewall","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sous-chefs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"sous-chefs"}},"created_at":"2012-03-14T18:13:54.000Z","updated_at":"2025-03-29T22:18:10.000Z","dependencies_parsed_at":"2023-12-23T09:05:08.948Z","dependency_job_id":"4c2751e5-7996-4463-b07b-5ce23ee086a6","html_url":"https://github.com/sous-chefs/firewall","commit_stats":{"total_commits":463,"total_committers":72,"mean_commits":6.430555555555555,"dds":0.7278617710583153,"last_synced_commit":"36129889eecce9b0147cd1accc95d898e062184f"},"previous_names":["chef-cookbooks/firewall"],"tags_count":90,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Ffirewall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Ffirewall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Ffirewall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sous-chefs%2Ffirewall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sous-chefs","download_url":"https://codeload.github.com/sous-chefs/firewall/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754437,"owners_count":21958863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chef","chef-cookbook","chef-resource","firewall","hacktoberfest","managed-by-terraform"],"created_at":"2024-08-03T18:01:26.442Z","updated_at":"2025-05-16T13:04:49.053Z","avatar_url":"https://github.com/sous-chefs.png","language":"Ruby","funding_links":["https://opencollective.com/sous-chefs"],"categories":["Resources"],"sub_categories":["Security"],"readme":"# firewall Cookbook\n\n[![Cookbook Version](https://img.shields.io/cookbook/v/firewall.svg)](https://supermarket.chef.io/cookbooks/firewall)\n[![CI State](https://github.com/sous-chefs/firewall/workflows/ci/badge.svg)](https://github.com/sous-chefs/firewall/actions?query=workflow%3Aci)\n[![OpenCollective](https://opencollective.com/sous-chefs/backers/badge.svg)](#backers)\n[![OpenCollective](https://opencollective.com/sous-chefs/sponsors/badge.svg)](#sponsors)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n\nProvides a set of primitives for managing firewalls and associated rules.\n\nPLEASE 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.\n\n## Maintainers\n\nThis 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](https://sous-chefs.org/) or come chat with us on the Chef Community Slack in [#sous-chefs](https://chefcommunity.slack.com/messages/C2V7B88SF).\n\n## Requirements\n\n- Chef Infra Client 15.5+\n\n```ruby\ndepends 'firewall'\n```\n\n## Supported firewalls and platforms\n\n- [UFW (Uncomplicated Firewall)](https://help.ubuntu.com/community/UFW)\n- [Firewalld](https://firewalld.org/)\n- [IPTables](https://manpages.debian.org/stable/iptables/iptables.8.en.html)\n- [Windows Firewall](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/)\n- [nftables](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page)\n\nThe default firewall solution used on Linux is based on the platform family:\n\n| Platform Family | Default Firewall Solution |\n|-----------------|---------------------------|\n| `amazon`        | firewalld                 |\n| `debian`        | ufw                       |\n| `fedora`        | firewalld                 |\n| `rhel`          | firewalld                 |\n| `suse`          | firewalld                 |\n| `ubuntu`        | ufw                       |\n| `windows`       | windows                   |\n| Other           | iptables                  |\n\nIf you'd like to use a firewall solution other than the platform's default, set the `default['firewall']['solution']`\nattribute to the desired firewall:\n\n```ruby\n# firewalld\ndefault['firewall']['solution'] = 'firewalld'\n\n# iptables\ndefault['firewall']['solution'] = 'iptables'\n\n# ufw\ndefault['firewall']['solution'] = 'ufw'\n```\n\n### nftables\n\nIn order to use nftables, just use the resource `nftables` and\n`nftables_rule`.  These resources are written in more modern design\nstyles and are not configurable by node attributes.\n\n### Supported operating systems\n\nSee the [kitchen.yml](https://github.com/sous-chefs/firewall/blob/main/kitchen.yml) for the full matrix of platforms\nthis cookbook is tested on.\n\n## Quickstart\n\nTo simply open a port in the system's default firewall:\n\n```ruby\ninclude_recipe 'firewall'\n\nfirewall_rule 'ssh' do\n  port 22\nend\n```\n\n## How it works\n\nThe most basic use involves two resources, `firewall` and `firewall_rule`. The typical usage scenario is as follows:\n\n- include the `'firewall::default'` recipe or run the `:install` action on the `firewall` resource named `'default'`, which installs appropriate packages and configures services to start on boot and starts them.\n- run the `:create` action on every `firewall_rule` resource, which adds to the list of rules that should be configured on the firewall. How the rules are implemented depends on the firewall platform:\n  - **firewalld**: `firewall_rule` implements the rules under the hood as firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html) in the system's default zone.\n  - **iptables, ufw, windows**: `firewall_rule` automatically sends a delayed notification to the `firewall['default']` resource to run the `:restart` action.\n    - when the delayed `:restart` notification on the `firewall` resource fires, if any rules are different than the last run, the provider will update the current state of the firewall rules to match the expected rules.\n\nThere is a fundamental mismatch between the idea of a Chef action and the action that should be taken on a firewall\nrule. For this reason, the Chef action for a `firewall_rule` may be `:create` (the rule should be present in the\nfirewall) but the action taken on a packet in a firewall (`DROP`, `ACCEPT`, etc) is denoted as a `command` property on\nthe `firewall_rule` resource.\n\nThe same points hold for the `nftables`- and `nftables_rule`-resources.\n\n## iptables considerations\n\nIf you need to use a table other than `*filter`, the best way to do so is like so:\n\n```ruby\nnode.default['firewall']['iptables']['defaults'][:ruleset] = {\n  '*filter' =\u003e 1,\n  ':INPUT DROP' =\u003e 2,\n  ':FORWARD DROP' =\u003e 3,\n  ':OUTPUT ACCEPT_FILTER' =\u003e 4,\n  'COMMIT_FILTER' =\u003e 100,\n  '*nat' =\u003e 101,\n  ':PREROUTING DROP' =\u003e 102,\n  ':POSTROUTING DROP' =\u003e 103,\n  ':OUTPUT ACCEPT_NAT' =\u003e 104,\n  'COMMIT_NAT' =\u003e 200\n}\n```\n\nNote -- 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.\n\nThen it's trivial to add additional rules to the `*nat` table using the raw parameter:\n\n```ruby\nfirewall_rule \"postroute\" do\n  raw \"-A POSTROUTING -o eth1 -p tcp -d 172.28.128.21 -j SNAT --to-source 172.28.128.6\"\n  position 150\nend\n```\n\nNote that any line starting with `COMMIT` will become just `COMMIT`, as hash\nkeys must be unique but we need multiple commit lines.\n\n## nftables\n\nPlease read the documentation for the\n[`nftables` resource](documentation/resource_nftables.md) and the\n[`nftables_rule` resource](documentation/resource_nftables_rule.md)\n\n## firewalld\n\nFor most rules it's sufficient to simply use the `firewall_rule` resource which is a platform-agnostic way to add\nfirewall rules. On firewalld systems it adds rules to the default zone as firewalld [rich\nrules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html). See the\n[`firewall_rule`](#firewall_rule) section for examples.\n\nSee the [`firewalld` resources](documentation/README.md) documentation for advanced firewalld configuration.\n\n## Recipes\n\n### `firewall::default`\n\nThe default recipe creates a firewall resource with action install.\n\n### `firewall::disable_firewall`\n\nUsed to disable platform specific firewall. Many clouds have their own firewall configured outside of the OS instance such as AWS Security Groups.\n\n## Attributes\n\n- `default['firewall']['solution'] = \u003cfirewalld|iptables|ufw\u003e`, sets the firewall solution to use on Linux platforms. Defaults to the default firewall solution used by the platform family. See [Supported firewalls and platforms](#supported-firewalls-and-platforms) for more info.\n- `default['firewall']['allow_ssh'] = false`, set true to open port 22 for SSH when the default recipe runs\n- `default['firewall']['allow_mosh'] = false`, set to true to open UDP ports 60000 - 61000 for [Mosh][0] when the default recipe runs\n- `default['firewall']['allow_winrm'] = false`, set true to open port 5989 for WinRM when the default recipe runs\n- `default['firewall']['allow_loopback'] = false`, set to true to allow all traffic on the loopback interface\n- `default['firewall']['allow_icmp'] = false`, set true to allow icmp protocol on supported OSes (note: ufw and windows implementations don't support this)\n- `default['firewall']['ufw']['defaults']` hash for template `/etc/default/ufw`\n- `default['firewall']['iptables']['defaults']` hash for default policies for 'filter' table's chains`\n- `default['firewall']['windows']['defaults']` hash to define inbound / outbound firewall policy on Windows platform\n- `default['firewall']['allow_established'] = true`, set to false if you don't want a related/established default rule on iptables\n- `default['firewall']['ipv6_enabled'] = true`, set to false if you don't want IPv6 related/established default rule on iptables (this enables ICMPv6, which is required for much of IPv6 communication)\n\n## Resources\n\n### `firewall`\n\nIt's not recommended to use this resource directly. Instead simply `include_recipe 'firewall'` and then add your desired\n`firewall_rule` resources. See the [`firewall_rule`](#firewall_rule) section for examples.\n\n***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.\n\n#### Actions\n\n- `:install` (*default action*): Install and Enable the firewall. This will ensure the appropriate packages are installed and that any services have been started.\n- `:reload`: *firewalld only*. Reloads the runtime state to match the permanent configuration. All runtime-only rules are flushed out.\n- `:disable`: Disable the firewall. Drop any rules and put the node in an unprotected state. Flush all current rules. Also erase any internal state used to detect when rules should be applied.\n- `:flush`: *Except firewalld*. Flush all current rules. Also erase any internal state used to detect when rules should be applied.\n\n#### Properties\n\n- `enabled` (default to `true`): If set to `false`, all actions will no-op on this resource. This is a way to prevent\n  included cookbooks from configuring a firewall.\n- `ipv6_enabled` (default to `true`): *Iptables only*. If set to false, firewall will not perform any ipv6 related work.\n- `log_level`: UFW only. Level of verbosity the firewall should log at. valid values are: :low, :medium, :high, :full, :off. default is :low.\n- `package_options`: Pass additional options to the package manager when installing the firewall.\n\n```ruby\n# all defaults\nfirewall 'default'\n\n# enable platform default firewall\nfirewall 'default' do\n  action :install\nend\n\n# increase logging past default of 'low'\nfirewall 'default' do\n  log_level :high\n  action    :install\nend\n```\n\n### `firewall_rule`\n\n#### Actions\n\n- `:create`: Create the firewall rule and notify the firewall to reload after the rule has been saved. On firewalld systems, the rules are added to the default zone as firewalld [rich rules](https://firewalld.org/documentation/man-pages/firewalld.richlanguage.html).\n\n#### Properties\n\n```ruby\nfirewall_rule 'name' do\n  firewall_name   String            # Default: 'default'\n  command         Symbol            # Default: :allow\n  protocol        Integer, Symbol   # Default: :tcp\n  source          String\n  source_port     Integer, Array, Range\n  port            Integer, Array, Range\n  dest_port       Integer, Array, Range\n  destination     String\n  position        Integer           # Default: 50\n  description     String            # Default: 'name' unless specified\n\n  # Firewall-specific properties\n  zone            String            # Firewall: firewalld\n  logging         Symbol            # Firewall: ufw\n  redirect_port   Integer           # Firewall: iptables, firewalld\n  dest_interface  String            # Firewall: iptables, windows\n  interface       String            # Firewall: iptables, ufw, windows\n  include_comment true, false       # Firewall: iptables, ufw. Default: true\n  stateful        Symbol, Array     # Firewall: iptables, ufw\n  raw             String            # Firewall: iptables, ufw\n  direction       Symbol            # Firewall: iptables, ufw, windows. Default: :in\n  notify_firewall true, false       # Firewall: iptables, ufw, windows. Default: true\n  program         String            # Firewall: windows\n  service         String            # Firewall: windows\nend\n```\n\nFirewall-agnostic properties that can be used with `firewall_rule` on any firewall system:\n\n- `firewall_name`: the matching firewall resource that this rule applies to. Default value: `default`\n- `description` (*default: same as rule name*): Used to provide a comment that will be included when adding the firewall rule.\n- `command`: What action to take on a particular packet\n   - `:allow` (*default action*): the rule should allow matching packets\n   - `:deny`: the rule should deny (drop) matching packets\n   - `:reject`: the rule should reject matching packets\n   - `:masquerade`: Masquerade the matching packets\n   - `:redirect`: Redirect the matching packets\n   - `:log`: Configure logging\n- `protocol`: `:tcp` (*default*), `:udp`, `:icmp`, `:none`, or protocol number. Using protocol numbers is not supported\n  using the ufw provider (default for debian/ubuntu systems).\n- `source` (*Default is `0.0.0.0/0` or `Anywhere`*): source ip address or subnet to filter.\n- `source_port` (*Default is nil*): source port for filtering packets.\n- `port` or `dest_port`: target port number (ie. `22` to allow inbound SSH), an array of incoming port numbers (ie.\n  `[80,443]` to allow inbound HTTP \u0026 HTTPS), or a range of incoming ports `(12000..12100)`.\n- `destination`: ip address or subnet to filter on packet destination, must be a valid IP\n- `position` (*default: 50*): **relative** position to insert rule at. Position may be any integer between 0 \u003c n \u003c 100 (exclusive), and more than one rule may specify the same position.\n\nAdditional properties for advanced firewall rules that tied to specific firewall solutions. **Note: These properties are *not* firewall-agnostic, so you must ensure they are used only on the appropriate firewall solutions**:\n\n- `zone`: (*firewalld*), a string, such as `public` that the rule will be applied. Defaults to the system's configured\n  default zone.\n- `logging` (*ufw*): may be added to enable logging for a particular rule. valid values are: `:connections`, `:packets`.\n  In the ufw provider, `:connections` logs new connections while `:packets` logs all packets.\n- `redirect_port` (*iptables, firewalld*): redirected port for rules with command `:redirect`.\n- `dest_interface` (*iptables, windows*): interface where packets may be destined to go.\n- `interface` (*iptables, ufw, windows*): (source) interface to apply rule (ie. `eth0`).\n- `include_comment` (*iptables, ufw*): Used to optionally exclude the comment in the rule. Default: `true`.\n- `stateful` (*iptables, ufw*): a symbol or array of symbols, such as ``[:related, :established]` that will be passed to the state module in iptables or firewalld.\n- `raw` (*iptables, ufw*): Used to pass an entire rule as a string, omitting all other parameters. This line will be directly loaded by `iptables-restore`/fed directly into `ufw` on the command line.\n- `direction` (*iptables, ufw, windows*): Direction of the rule. Valid values are: `:in` (*default*), `:out`, `:pre`,\n`:post`.\n- `notify_firewall` (*iptables, ufw, windows*): Notify the firewall to recalculate (and potentially reapply) the\n  `firewall_rule`(s) it finds. Default: `true`\n\n#### Examples\n\n```ruby\ninclude_recipe 'firewall'\n\n# open standard ssh port\nfirewall_rule 'ssh' do\n  port     22\n  command  :allow\nend\n\n# open standard http port to tcp traffic only; insert as first rule\nfirewall_rule 'http' do\n  port     80\n  protocol :tcp\n  position 1\n  command   :allow\nend\n\n# open UDP ports 60000..61000 for mobile shell (mosh.org), note\n# that the protocol attribute is required when using port_range\nfirewall_rule 'mosh' do\n  protocol    :udp\n  port        60000..61000\n  command     :allow\nend\n\n# open multiple ports for http/https, note that the protocol\n# attribute is required when using ports\nfirewall_rule 'http/https' do\n  protocol :tcp\n  port     [80, 443]\n  command   :allow\nend\n\n# firewalld example of opening port 22 on public zone\nfirewall_rule 'ssh' do\n  port    22\n  zone    \"public\"\n  command :allow\nend\n```\n\n## Troubleshooting\n\nTo figure out what the position values are for current rules, print the hash that contains the weights:\n\n```ruby\nrequire pp\ndefault_firewall = resources(:firewall, 'default')\npp default_firewall.rules\n```\n\n## Development\n\nThis section details \"quick development\" steps. For a detailed explanation, see [[Contributing.md]].\n\n1. Clone this repository from GitHub:\n\n`$ git clone git@github.com:chef-cookbooks/firewall.git`\n\n1. Create a git branch\n\n`$ git checkout -b my_bug_fix`\n\n1. Install dependencies:\n\n`$ bundle install`\n\n1. Make your changes/patches/fixes, committing appropiately\n1. **Write tests**\n1. Run the tests:\n\n- `bundle exec foodcritic -f any .`\n- `bundle exec rspec`\n- `bundle exec rubocop`\n- `bundle exec kitchen test`\n\nIn detail:\n\n- Foodcritic will catch any Chef-specific style errors\n- RSpec will run the unit tests\n- Rubocop will check for Ruby-specific style errors\n- Test Kitchen will run and converge the recipes\n\n## Contributors\n\nThis project exists thanks to all the people who [contribute.](https://opencollective.com/sous-chefs/contributors.svg?width=890\u0026button=false)\n\n### Backers\n\nThank you to all our backers!\n\n![https://opencollective.com/sous-chefs#backers](https://opencollective.com/sous-chefs/backers.svg?width=600\u0026avatarHeight=40)\n\n### Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website.\n\n![https://opencollective.com/sous-chefs/sponsor/0/website](https://opencollective.com/sous-chefs/sponsor/0/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/1/website](https://opencollective.com/sous-chefs/sponsor/1/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/2/website](https://opencollective.com/sous-chefs/sponsor/2/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/3/website](https://opencollective.com/sous-chefs/sponsor/3/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/4/website](https://opencollective.com/sous-chefs/sponsor/4/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/5/website](https://opencollective.com/sous-chefs/sponsor/5/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/6/website](https://opencollective.com/sous-chefs/sponsor/6/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/7/website](https://opencollective.com/sous-chefs/sponsor/7/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/8/website](https://opencollective.com/sous-chefs/sponsor/8/avatar.svg?avatarHeight=100)\n![https://opencollective.com/sous-chefs/sponsor/9/website](https://opencollective.com/sous-chefs/sponsor/9/avatar.svg?avatarHeight=100)\n\n[0]: https://mosh.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Ffirewall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsous-chefs%2Ffirewall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsous-chefs%2Ffirewall/lists"}