iptables-ruby 0.2.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3cdee7f713d4749034b6106e46c562312fccbaf2
+  data.tar.gz: 24934051d8029a1798b7b8d5319274d68c2b5cce
+SHA512:
+  metadata.gz: 1bb21c4234d7b3880faa9c16aefac00b474856938f1ea2975e482238f9771b37bf24fca3af16dec71303d11db8302ed7f2785e3e37de0de898cee712562f8c9d
+  data.tar.gz: 5ef4fc170a0121d151963910e332ad064d622de4d1ce11e8592deca2cfaf383010cef6e496bb6cc4a5fb67ed2f5d99db966ef86d6cac69c4f25da71949baa86d

data/.gitignore

@@ -0,0 +1,6 @@
+*.swp
+coverage/*
+pkg
+rdoc
+Gemfile.lock
+.rbenv-version

data/CHANGELOG

@@ -0,0 +1,23 @@
+0.2.4
+- Fix comparison corner case.
+- Nagios example script can read iptables output from file.
+- Fix Ruby 1.9-unfriendly bugs
+
+0.2.3
+- Compare two iptables.
+- Add documentation.
+- Add Nagios example script
+- Add example policy files.
+
+0.2.2
+- Generate multi-table output correctly.
+
+0.2.1
+- Properly handle merging on top of a policy with a nil table.
+
+0.2.0
+- New Rule parameter: "has_primitive":
+- Do not evaluate or add a rule if it requires a non-existent primitive.
+
+0.1.0
+- initial release

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'diff-lcs'
+gem 'simplecov'
+gem 'rake'
+gem 'rdoc'

data/Generate.md

@@ -0,0 +1,278 @@
+# Generating a firewall
+
+A complete, generated firewall requires several JSON configuration
+sections. These can either be compiled into one long JSON file or split
+into separate files. An example usable firewall has been included within
+this gem's `examples/policy` directory.
+
+# Example JSON configuration files
+
+## macros.json
+
+This file defines macros, which are reusable rules or sets of rules.
+Each macro consists of an identifier (example `accept-established`), and
+its expansion. For more on rules, see section `Rules`.
+
+## policy.json
+
+This file defines policy, which is the "top-level" configuration
+for your **desired** iptables rules. 
+
+Assuming you are using configuration-management software such as
+[http://www.opscode.com/chef](Chef), you can set one policy for all of
+your hosts, and then customize your policy per host using rules (see
+`rules.json`) and primitives (see `primitives.json`).
+
+The policy file is a hash of the four "standard" iptables tables:
+`filter`, `mangle`, `nat`, and `raw`. Each of these can in turn either
+be a hash configuring the table, or `null`. 
+
+### `null`
+
+If `null`, the policy for that table will be "whatever is already
+defined". For example, the example configuration file shows 
+`"mangle": null`, which means: "if there is a `mangle` table, use its
+rules, otherwise leave this table undefined".
+
+### hash
+
+If a hash, the table must contain a hash of table names. These will be
+the standard tables for the corresponding iptables table. For instance,
+`filter` should minimally contain `INPUT`, `FORWARD`, and `OUTPUT`.
+Other user-defined tables may also be defined/named.
+
+Each defined table must have a `policy`. This can either be `DROP`,
+`ACCEPT`, or `-`.
+
+Each defined table must also have a `rules` section. This must be an
+array of firewall rules. For more on rules, see section `Rules`.
+
+## policy6.json
+
+This is the same as `policy.json`, but defines ipv6 rules.
+
+## primitives.json
+
+Primitives are values that can be interpolated into other parts of your
+firewall. For more on how these interpolations are used, see section
+`Interpolation`.
+
+## rules.json
+
+`rules` can be an empty hash, or contain any of the named iptables
+tables (`filter`, `nat`, etc). Any named table is **added** to the rules
+defined by policy (see example `policy.json`).
+
+If a table is **not** found in policy, it is added to the generated
+firewall. It is advised to define at least all standard chains for the
+table. For instance, `nat` should minimally contain `INPUT`, `OUTPUT`,
+`POSTROUTING` and `PREROUTING`, and each of these should minimally
+contain a `policy` definition.
+
+If a table **is** found in policy, each specified chain can either
+override or modify the existing table within the policy. 
+
+### Overriding Chain Policy
+
+Set `"policy": "ACCEPT"` or any other valid policy.
+
+### Overriding Chain Rules
+
+Set `"rules": []`. In this case, rules will be reset to be empty.
+Alternately, fill the array with rules (see section `Rules`).
+
+### Adding Chain Rules
+
+Set `"additions": []`. Rules (see section `Rules`) added into this array
+will be added at node addition points within the policy rules (see
+section `additions`).
+
+## services.json
+
+This file defines services that you will be using within your firewall.
+See section `Rules` on how to define each service.
+
+Once defined, a service may be used within policy, rules, or macros.
+
+# Rules
+
+Rules fall within an array, and can consist of strings or hashes.
+
+## String Rules
+
+A policy that is a string is inserted as-is into the policy
+firewall, preceded by `-A the_chain_name`. A very simple firewall could
+consist solely of string rules.
+
+## Hash rules
+
+Other kinds of rules are defined as hashes, with the hash key denoting
+the type of rule:
+
+### `comment`
+
+This is shorthand for an iptables comment:
+
+    "comment": "comment1"
+
+becomes
+
+    -A chain_name -m comment --comment "comment1"
+
+The `chain_name` is the name of the chain in which the `comment` rule is
+found.
+
+### `interpolated`
+
+See section "Interpolating strings"
+
+### `macro`
+
+This inserts the requested macro (see section `macros.json`) into the
+rules.
+
+### `node_addition_points`
+
+See section "`additions` and `node_addition_points`"
+
+### `service`
+
+This inserts the requested service (see section `services.json`) into
+the rules.
+
+### `service_tcp`
+
+This takes an integer or string as an argument and inserts a permitted
+inbound TCP port into the rules:
+
+    "service_tcp": 8080
+
+becomes
+
+    -A chain_name -p tcp -m tcp --sport 1024:65535 --dport 8080 -m state --state NEW,ESTABLISHED -j ACCEPT
+
+Port ranges such as `"8080:8090"` can also be used. The `chain_name` is
+the name of the chain in which the `service_tcp` rule is found.
+
+### `service_udp`
+
+This is identical to `service_tcp`, except that it inserts a permitted
+inbound UDP port.
+
+### `ulog`
+
+This is shorthand for an iptables logging statement:
+
+    "ulog": ""
+
+becomes
+
+    -A chain_name -m limit --limit 1/sec --limit-burst 2 -j ULOG --ulog-prefix "chain_name:"
+
+This can also use `-p tcp`:
+
+    "ulog": "-p tcp"
+
+becomes
+
+    -A chain_name -p tcp -m limit --limit 1/sec --limit-burst 2 -j ULOG --ulog-prefix "chain_name:"
+
+The `chain_name` is the name of the chain in which the `ulog` rule is
+found.
+
+# Interpolation
+
+Primitives (see section `primitives.json`) are available within your
+configuration using the `<%%>` notation within an `interpolated` rule.
+
+## Interpolating strings
+
+An example usage is:
+
+     "interpolated": "-s <% internet.subnet.other %> -d <% internet.address %> -i <% internet.device %> -j ACCEPT"
+
+Depending upon the defined primitives, the above rule could expand into:
+
+     -s 192.0.2.0/24 -d 198.51.100.10/32 -i eth0 -j ACCEPT
+
+## Interpolating arrays
+
+Primitives that are defined as an array, such as `iana_reserved` in the
+example `primitives.json`, will expand into multiple rules. For instance
+
+     "interpolated": "-s <% iana_reserved %> -j DROP"
+
+would expand into
+
+    -s 0.0.0.0/8 -j DROP
+    -s 5.0.0.0/8 -j DROP
+    -s 10.0.0.0/8 -j DROP
+    -s 36.0.0.0/7 -j DROP
+    -s 39.0.0.0/8 -j DROP
+    -s 42.0.0.0/8 -j DROP
+    -s 49.0.0.0/8 -j DROP
+    -s 100.0.0.0/6 -j DROP
+    -s 104.0.0.0/7 -j DROP
+    -s 106.0.0.0/8 -j DROP
+    -s 127.0.0.0/8 -j DROP
+    -s 179.0.0.0/8 -j DROP
+    -s 185.0.0.0/8 -j DROP
+    -s 240.0.0.0/4 -j DROP
+    -s 169.254.0.0/16 -j DROP
+    -s 172.16.0.0/12 -j DROP
+    -s 192.0.2.0/24 -j DROP
+    -s 192.88.99.0/24 -j DROP
+    -s 192.168.0.0/16 -j DROP
+
+
+# `additions` and `node_addition_points`
+
+Since adding rules to a policy firewall is very common, there is a
+shorthand for adding rules to one or more policy chains at predefined
+points.
+
+For instance, you may define the following policy (see `Rules`):
+
+    "policy": {
+      (other chains)
+      "in_public": {
+        "policy": "ACCEPT",
+        "rules": {
+          { "comment": "comment1" },
+          {
+            "node_addition_points": [
+              "in_public",
+              "in_*"
+            ]
+          }
+          { "comment": "comment2" },
+        }
+      }
+    }
+
+You may then also choose to define the following rules:
+
+    "rules": {
+      "filter": {
+        "in_public": {
+          "additions": [
+            "comment": "public"
+          ]
+        },
+        "in_*": {
+          "additions": [
+            "comment": "all"
+          ]
+        }
+      }
+    }
+
+The `rules` defined within the `in_public` chain or `in_*`
+pseudo-chain would be added at the `node_addition_points` within the
+table. So the generated firewall would contain:
+
+    -A in_public -m comment --comment "comment1"
+    -A in_public -m comment --comment "public"
+    -A in_public -m comment --comment "all"
+    -A in_public -m comment --comment "comment2"
+

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Library of Congress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+Description
+===========
+
+Iptables-gem is a Ruby API for parsing, generating, and comparing Linux
+iptables rules. It is configured using JSON and oriented toward use
+within configuration-management software such as
+[http://www.opscode.com/chef/](Chef).
+
+Requirements
+============
+
+## Ruby:
+
+* Ruby: 1.8
+* Likely also works on 1.9, but testing is giving me fits so I am ignoring it for now
+
+## Platforms:
+
+The following platforms and versions are tested:
+
+* Ubuntu 10.04, 12.04
+* CentOS 6.4, Red Hat 6.4
+
+Ruby Usage
+==========
+
+Install this gem and `require iptables`. In the examples below,
+`/path/to/json/` refers to the directory containing JSON policy files.
+See [Generate.md](the firewall generation documentation) for information
+on setting these up. There are also example configuration files in
+`examples/policy/*.json`.
+
+## Generate a firewall
+
+You will first need to create JSON firewall configuration files. See the
+`Generating a Firewall` section below for details. Once this is done,
+you can generate a firewall like so:
+
+     config = IPTables::Configuration.new
+     config.parse_files('/path/to/json/')
+     policy_fw = config.converge_firewall
+     puts policy_fw.as_array
+
+## Compare two firewalls
+
+You can determine whether a proposed/policy firewall and the
+currently-applied firewall are identical:
+
+     config = IPTables::Configuration.new
+     config.parse_files('/path/to/json/')
+     policy_fw = config.converge_firewall
+     active_fw = IPTables::Tables.new(%x/iptables-save/)
+     comparison = IPTables::TablesComparison.new(active_fw, policy_fw)
+     comparison.equal?
+
+Alternately, you can compare firewalls using only `iptables-save` output:
+
+     active_fw = IPTables::Tables.new(%x/iptables-save/)
+     other_fw = IPTables::Tables.new(File.readlines('/path/to/another/saved/firewall'))
+     comparison = IPTables::TablesComparison.new(active_fw, policy_fw)
+     comparison.equal?
+
+If two firewalls are the same **except** for embedded firewall comments,
+you can ignore comments:
+
+     comparison.ignore_comments
+     comparison.equal?
+
+If you want to see **exactly** how two firewalls differ:
+
+     comparison.as_array
+
+## Log
+
+If you want to see debug messages, turn on logging:
+
+     require 'logger'
+     $log = Logger.new(STDOUT)
+     $log.level = Logger::DEBUG
+     config = IPTables::Configuration.new
+     config.parse_files('/path/to/json/')
+     policy_fw = config.converge_firewall
+
+Generating a Firewall
+=====================
+
+An explanation of generating a firewall can be found within
+[Generate.md](the firewall generation documentation). An example set of
+configuration files to create a basic working firewall can be found in
+`examples/policy/*.json`.
+
+Included Scripts
+================
+
+## Nagios
+
+The `bin` directory contains a Nagios helper script written in Ruby to
+compare the running firewall against a "policy" firewall. To try it from
+within the gem source directory (that is, without first installing the
+gem), first copy `examples/policy` to a temporary location and edit the
+policy files to taste. Then change to the `bin` directory and run:
+
+`./check_firewall.rb -l=/path/to/iptables/gem/lib/ -v -c=/path/to/policy/`
+
+The above example includes debugging information which makes it
+unsuitable for use with Nagios. For "live" use with Nagios, you would
+want to install this gem and run:
+
+`check_firewall.rb -c=/path/to/policy/`
+
+Tests
+=====
+
+To run unit tests:
+
+* change to iptables directory
+* run `rake`
+* examine coverage reports in directory `coverage`
+
+Future
+======
+
+Changes/Features I would like to see:
+
+* Is ipv6 even working?
+* Write policy in YAML **or** JSON
+* Deprecate `requires_primitive`: these should be ignored if there is no matching interpolation
+* Deprecate `interpolated`: these should be properly handled inside **any** kind of rule
+* Deprecate `comment` and `ulog`? These seem like they ought to be macros.
+* `ulog` has `-p tcp` but this seems awkward; is it even useful?
+* Do other stuff like ebtables too? Not sure it's in scope here. Certainly the gem name would need to be reconsidered.
+* Generate better error messages when we encounter failures parsing configurations.
+* Move development/testing/coverage environment to Ruby 1.9
+
+License and Authors
+===================
+
+* Author:: Kurt Yoder <kyoder@loc.gov>
+
+See LICENSE file for project license information.