firewool 0.1.1 → 0.1.2

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Chris Dillon, http://squarism.com/
+
+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.rdoc

@@ -2,20 +2,23 @@
 Firewool is an IP firewall for rails.  You set what IPs to block and what IPs to allow.  Specifics below.
 
 == Why would I need this?
-- A layer 7 firewall is too expensive.
-- Anonymous authentication doesn't equate to all access authorization.
+Using authentication to protect your app is great but sometimes you just want to do some simple IP filtering.  Firewool can help you in the following use cases:
+- You have a report job that needs to hit /users/report and you want to restrict access without authentication, ie: you don't want to create a "report" user which might get reported on or otherwise makes you a sad panda.
+- A simple firewall with IP/ports (layer 3) can't protect rails URLs.
+- A layer 7 firewall which can protect URLs is too expensive / hard to set up.
 - Belt and suspenders style double security check.
+- You killed your network guy and no one knows.
 
 == Install
 gem install firewool
 
 - Tested on rails 3.0.4.
+- Tested on ruby 1.9.2 / 1.8.7.
 - Untested on rails 2.x.  Probably won't work because no engines.
 
 == Configuration
-Add firewool and dependency to Gemfile:
+Add firewool dependency to Gemfile:
  gem 'firewool'
- gem 'ipaddress'
   
 Create a configuration file in config/firewool.yml
 
@@ -24,7 +27,7 @@ Create a configuration file in config/firewool.yml
 	
  development:
    ip_restriction: true
-	 allow: [ 192.168.0.0/16 ]
+   allow: [ 127.0.0.1 ]
 
  test:
    ip_restriction: false
@@ -63,33 +66,36 @@ IPs can be spoofed so in the case of strong security, you'll want to use this wi
 == Quick Network Primer
 So how do I write the rules when I'm not a network guy?  No problem, let's go through some examples.
 
-First, the IP is four numbers separated by periods.  Each number is called an ocet.  The slash number (like /16 up above) is how many octets match.  So to match every usable IP from 10.0.0.1 to 10.0.0.254, we can just say:
- 10.0.0.0/24 (matches 10.0.0.*)
-   10.0.0.1      (match)
-   10.0.0.204    (match)
-   10.0.1.1      (no match)
-   7.8.9.10      (no match)
+First, the IP is four numbers separated by periods.  Each number is called an ocet.  The slash number (like /16 up above) is how many octets match.  So to match every usable IP from 10.0.0.1 to 10.0.0.254, we can just say: 10.0.0.0/24 instead of naming all 253 ips one at a time.
+
+10.0.0.0/24 matches 10.0.0.* so the following happens:
+ 10.0.0.1      (match)
+ 10.0.0.204    (match)
+ 10.0.1.1      (no match)
+  7.8.9.10     (no match)
 
 If we just want to match one IP we can use the /32 or just specify the IP by itself.
  192.168.0.1/32  (matches only 192.168.0.1)
-   192.168.0.1     (matches only 192.168.0.1, same meaning as /32)
-   5.0.0.0/8       (matches 5.*.*.*)
-   5.6.0.0/16      (matches 5.6.*.*)
-   5.6.0.0/24      (matches 5.6.0.*)
-   5.6.7.0/24      (matches 5.6.7.*)
+
+Some more examples:
+ 192.168.0.1     (matches only 192.168.0.1, same meaning as /32)
+ 5.0.0.0/8       (matches 5.*.*.*)
+ 5.6.0.0/16      (matches 5.6.*.*)
+ 5.6.0.0/24      (matches 5.6.0.*)
+ 5.6.7.0/24      (matches 5.6.7.*)
     
-These are the simplest examples of this notation (called CIDR if you want to read more) but it's enough to build a few use cases.  Let's say we want to allow anyone from our company network but block anyone coming from Evil Hackers' Inc.  Our company's external network is 5.6.7.* (ie: what users see when they go to whatismyip.com from inside their network) and let's say that Evil Hackers' proxy is 58.14.0.0.  This would be our firewool.yml config:
+These are the simplest examples of this notation (called CIDR if you want to read more) but it's enough to build a few use cases.  Let's say we want to allow our customers in but block anyone coming from Evil Hackers' Inc.  Our customer's external network is 5.6.7.* (ie: what they see when they go to whatismyip.com) and let's say that Evil Hackers' proxy is 58.14.0.0.  This would be our firewool.yml config:
  production:
    ip_restriction: true
    allow: [ 5.6.7.0/24 ]
    deny:  [ 58.14.0.0/16 ]
     
-Now we'd want to be careful that 5.6.7.* was really where our users are coming from.  If people that we want to keep out are coming from 5.6.7.200 then we'd want to tighten up our rule a little bit and not allow all of the 5.6.7.0 network in.  Maybe we research what our IP block really is, or add only the IPs we know about as /32 IPs.
+Now we'd want to be careful that 5.6.7.* was really where our users are coming from.  If another group of people that we want to keep out are coming from 5.6.7.200 then we'd want to tighten up our rule a little bit and not allow all of the 5.6.7.* network in because .200 is in 5.6.7.*.  So we would research what our customer's IP block really is, or add only the IPs we know about as individual IPs.
 
-As a special case, 0.0.0.0 means *.*.*.*, or all IPs.
+As a special case, 0.0.0.0 means *.*.*.*, or all IPs.  Also a special case, 127.0.0.1 means localhost which is good to leave in your development allow section so you can develop your app with firewool on.
 
-== Pretty up
+== Pretty Up
 If 403.html doesn't exist in your public directory, then a blocked user will simply see "Public Access Denied." which isn't that great.  Create a 403.html file in public, you can use this {403.html template as an example}[https://github.com/squarism/firewool/blob/master/test/dummy/public/403.html].
 
 == Thanks to
-Bluemonk for his awesome ipaddress gem.
+{Bluemonk}[https://github.com/bluemonk] for his awesome ipaddress gem.  And {sinisterchipmunk}[https://github.com/sinisterchipmunk] for his help in understanding how to test rails 3 gems quickly.

data/lib/firewool.rb

@@ -1,5 +1,6 @@
 require 'active_support/core_ext'
 require 'ipaddress'
+require 'singleton'
 
 # rails engine setup
 require File.join(File.dirname(__FILE__), "firewool/railtie.rb")
@@ -11,10 +12,21 @@ module Firewool
   end
   
   class Config
+    include Singleton
     attr_reader :yaml_config
+    attr_accessor :filesystem_hits  # track how many times we read the yml
+    
+    def load_config
+      @filesystem_hits += 1
+      YAML.load_file("#{Rails.root.to_s}/config/firewool.yml")
+    end
+
+    def yaml_config
+      @@yaml_config ||= self.load_config
+    end
     
     def initialize
-      @yaml_config = YAML.load_file("#{Rails.root.to_s}/config/firewool.yml")
+      @filesystem_hits = 0
     end
   end
 

data/lib/firewool/hook.rb

@@ -1,12 +1,12 @@
 module Firewool
   module Hook
     def acts_as_firewalled
-      @firewool_config = Firewool::Config.new
+      @firewool_config = Firewool::Config.instance
       include Firewool::InstanceMethods
     end
 
     def firewool_config
-      @firewool_config.yaml_config || self.superclass.instance_variable_get('@firewool_config').yaml_config
+      @firewool_config
     end
   end
 end

data/lib/firewool/instance_methods.rb

@@ -14,7 +14,7 @@ module Firewool
     end
 
     def ip_allow?(ip)
-      firewool_config = self.class.firewool_config[Rails.env]
+      firewool_config = self.class.firewool_config.yaml_config[Rails.env]
     
       if firewool_config['ip_restriction']
         # get our policy from the conf file

data/lib/firewool/railtie.rb

@@ -7,6 +7,7 @@ module Firewool
   class Railtie < Rails::Railtie
     # nothing here right now
     config.to_prepare do
+      # puts Firewool::Config.instance
       # p "hook added"
       #ApplicationController.send(:extend, Firewool::Hook)
     end

data/lib/firewool/version.rb

@@ -1,3 +1,3 @@
 module Firewool
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/test/dummy/Gemfile

@@ -12,6 +12,7 @@ gem 'rails', '~>3.0.4'
 
 # Deploy with Capistrano
 # gem 'capistrano'
+gem 'firewool', :path => '../../'
 
 # To use debugger (ruby-debug for Ruby 1.8.7+, ruby-debug19 for Ruby 1.9.2+)
 # gem 'ruby-debug'

data/test/dummy/app/controllers/dummy_controller.rb

@@ -2,4 +2,8 @@ class DummyController < ApplicationController
   include Firewool
   acts_as_firewalled
   before_filter :ip_filter
+  
+  def index
+    render :text => "This is the index method on DummyController"
+  end
 end

data/test/dummy/app/controllers/foo_controller.rb

@@ -0,0 +1,11 @@
+# intentionally not including Firewool, test including from ApplicationController instead
+
+class FooController < ApplicationController
+  include Firewool
+  acts_as_firewalled
+  before_filter :ip_filter
+  
+  def index
+    render :text => "This is the index method on FooController"
+  end
+end

data/test/dummy/app/helpers/foo_helper.rb

@@ -0,0 +1,2 @@
+module FooHelper
+end

data/test/dummy/app/views/foo/index.html.erb

@@ -0,0 +1,2 @@
+<h1>Foo#index</h1>
+<p>Find me in app/views/foo/index.html.erb</p>

data/test/dummy/config/routes.rb

@@ -1,10 +1,14 @@
 Dummy::Application.routes.draw do
+  get "foo/index"
+
   # The priority is based upon order of creation:
   # first created -> highest priority.
 
   # Sample of regular route:
   #   match 'products/:id' => 'catalog#view'
   # Keep in mind you can assign values other than :controller and :action
+  match 'dummy' => 'dummy#index'
+  match 'foo' => 'foo#index'
 
   # Sample of named route:
   #   match 'products/:id/purchase' => 'catalog#purchase', :as => :purchase

data/test/dummy/test/functional/foo_controller_test.rb

@@ -0,0 +1,9 @@
+require 'test_helper'
+
+class FooControllerTest < ActionController::TestCase
+  test "should get index" do
+    get :index
+    assert_response :success
+  end
+
+end

data/test/dummy/test/unit/helpers/foo_helper_test.rb

@@ -0,0 +1,4 @@
+require 'test_helper'
+
+class FooHelperTest < ActionView::TestCase
+end

data/test/firewool_test.rb

@@ -10,7 +10,7 @@ class FirewoolTest < ActionController::TestCase
   dc = DummyController.new
 
   # get our configuration, which we'll change later for certain tests
-  conf_file = dc.class.firewool_config[Rails.env]
+  conf_file = dc.class.firewool_config.yaml_config[Rails.env]
   
   # test basic module includes/extends  
   context "The controller" do
@@ -30,9 +30,9 @@ class FirewoolTest < ActionController::TestCase
   # test policy enforcement
   context "The Firewool" do
     should "allow valid IPs while blocking invalid IPs" do
-      # reset the configuration, this is weird that I have to 
-      # , I thought this would go in order
-      dc.class.firewool_config[Rails.env]["allow"] = ["192.168.0.0/16"]
+      # this is weird that I have to reset the configuration,
+      # I thought this would go in order
+      conf_file["allow"] = ["192.168.0.0/16"]
       assert_equal false, dc.ip_allow?("172.168.0.1")
       assert_equal false, dc.ip_allow?("12.168.0.1")
       assert_equal false, dc.ip_allow?("0.0.0.0")
@@ -42,18 +42,44 @@ class FirewoolTest < ActionController::TestCase
   
   context "The Firewool" do
     should "allow valid IPs when using a default allow" do
-      dc.class.firewool_config[Rails.env]["allow"] = ["0.0.0.0"]
+      conf_file["allow"] = ["0.0.0.0"]
       assert_equal true, dc.ip_allow?("12.168.0.1")
     end
   end
   
   context "The Firewool" do
     should "allow and disallow correctly with a default allow" do
-      dc.class.firewool_config[Rails.env]["allow"] = ["0.0.0.0"]
-      # puts dc.class.firewool_config[Rails.env]
+      conf_file["allow"] = ["0.0.0.0"]
       assert_equal true, dc.ip_allow?("12.168.0.1")
       assert_equal true, dc.ip_allow?("192.168.0.1")
       assert_equal false, dc.ip_allow?("172.16.0.1")
     end
   end
 end
+
+
+class FooTest < ActionController::TestCase
+  tests FooController
+  fc = FooController.new
+  
+  # conf_file = $firewool_config[Rails.env]
+  conf_file = fc.class.firewool_config.yaml_config[Rails.env]
+  
+  # test reading firewool.yml config file
+  context "The Firewool" do
+    should "have the configuration loaded" do
+      assert conf_file.key?("ip_restriction"), "Should have the ip_restriction in firewool conf file"
+      assert conf_file.key?("allow"), "Should have the ip_ranges_allowed in firewool conf file"
+    end
+  end
+  
+  context "The Firewool" do
+    should "not hit the filesystem more than once when loading the conf file" do
+      assert_equal 1, fc.class.firewool_config.filesystem_hits
+      fc = FooController.new
+      fc = FooController.new
+      assert_equal 1, fc.class.firewool_config.filesystem_hits
+    end
+  end
+  
+end

metadata

@@ -2,7 +2,7 @@
 name: firewool
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Chris Dillon
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-15 00:00:00 -05:00
+date: 2011-02-21 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,6 +47,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- MIT-LICENSE.txt
 - README.rdoc
 - Rakefile
 - firewool.gemspec
@@ -61,8 +62,11 @@ files:
 - test/dummy/Rakefile
 - test/dummy/app/controllers/application_controller.rb
 - test/dummy/app/controllers/dummy_controller.rb
+- test/dummy/app/controllers/foo_controller.rb
 - test/dummy/app/helpers/application_helper.rb
 - test/dummy/app/helpers/dummy_helper.rb
+- test/dummy/app/helpers/foo_helper.rb
+- test/dummy/app/views/foo/index.html.erb
 - test/dummy/app/views/layouts/application.html.erb
 - test/dummy/config.ru
 - test/dummy/config/application.rb
@@ -100,9 +104,11 @@ files:
 - test/dummy/public/stylesheets/.gitkeep
 - test/dummy/script/rails
 - test/dummy/test/functional/dummy_controller_test.rb
+- test/dummy/test/functional/foo_controller_test.rb
 - test/dummy/test/performance/browsing_test.rb
 - test/dummy/test/test_helper.rb
 - test/dummy/test/unit/helpers/dummy_helper_test.rb
+- test/dummy/test/unit/helpers/foo_helper_test.rb
 - test/dummy/vendor/plugins/.gitkeep
 - test/firewool_test.rb
 - test/test_helper.rb
@@ -142,8 +148,11 @@ test_files:
 - test/dummy/Rakefile
 - test/dummy/app/controllers/application_controller.rb
 - test/dummy/app/controllers/dummy_controller.rb
+- test/dummy/app/controllers/foo_controller.rb
 - test/dummy/app/helpers/application_helper.rb
 - test/dummy/app/helpers/dummy_helper.rb
+- test/dummy/app/helpers/foo_helper.rb
+- test/dummy/app/views/foo/index.html.erb
 - test/dummy/app/views/layouts/application.html.erb
 - test/dummy/config.ru
 - test/dummy/config/application.rb
@@ -181,9 +190,11 @@ test_files:
 - test/dummy/public/stylesheets/.gitkeep
 - test/dummy/script/rails
 - test/dummy/test/functional/dummy_controller_test.rb
+- test/dummy/test/functional/foo_controller_test.rb
 - test/dummy/test/performance/browsing_test.rb
 - test/dummy/test/test_helper.rb
 - test/dummy/test/unit/helpers/dummy_helper_test.rb
+- test/dummy/test/unit/helpers/foo_helper_test.rb
 - test/dummy/vendor/plugins/.gitkeep
 - test/firewool_test.rb
 - test/test_helper.rb