xavier-bouncer 0.0.1

data/README.rdoc

@@ -0,0 +1,57 @@
+= Bouncer
+
+A simple blacklist based access filtering middleware for Rack.  
+
+It allows for easy filtering of IP addresses and User Agent strings.
+This filter is primarily aimed at quickly blocking abusive users or bots.  
+It is suitable for websites with moderate traffic suffering from a handful of abusive clients and 
+will come handy for anyone who doesn't want to fiddle with obscure web server configuration directives.
+
+== Usage
+
+For instance, to add this middleware to your Rails app, in <tt>environment.rb</tt>:
+
+  # Require the gem, use rake gems:install to install it
+  config.gem 'xavier-bouncer', :lib => 'bouncer', :source => 'http://gems.github.com'
+
+  # Add the middleware to the stack and configure it
+  config.middleware.add 'Bouncer', :deny_ip_address => ["1.2.3.4", /^10\.0\./], :deny_user_agent => /msnbot/
+
+The black list can be either a single or an array with a combination of strings, regular expressions and Proc objects.
+If any of the given conditions are met, the client will be greeted with an HTTP 403 response (access denied).
+
+
+== Similar Middleware
+
+If you are after more advanced features, you may want to have a look at:
+
+- {HttpBL}[http://github.com/bpalmen/httpbl/tree/master], an advanced IP filtering middleware
+- {rack-useragent}[http://github.com/bebanjo/rack-useragent/tree/master], another User Agent filter
+- {rack-honeypot}[http://github.com/sunlightlabs/rack-honeypot/tree/master], a spambot trap
+
+If you are seriously under attack, you may want to have a look at {ModSecurity}[http://www.modsecurity.org/].
+
+== MIT Licence
+
+Copyright (c) 2009 Xavier Defrang
+
+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/lib/bouncer.rb

@@ -0,0 +1,79 @@
+
+class Bouncer
+
+  # See configure for available options
+  def initialize(app, options = {})
+    @app = app
+    configure(options)
+  end
+  
+  # Accepted options are: :deny_user_agents and :deny_ip_address
+  # Both accept a single or an array of String, Regexp or Proc objects
+  # If a string is given, IP address will be matched by prefix (i.e. '127.0' will match '127.0.0.1' and '127.0.2.1')
+  def configure(options = {})
+    @user_agent_checks = [options[:deny_user_agent]].flatten.compact
+    @ip_address_checks = [options[:deny_ip_address]].flatten.compact
+  end
+  
+  def call(env)
+    dup._call(env)
+  end
+  
+  def _call(env)
+    if access_denied?(env)
+      deny_access
+    else
+      @app.call(env)
+    end
+  end
+  
+  def access_denied?(env)
+    ip_denied?(env['REMOTE_ADDR']) || user_agent_denied?(env['HTTP_USER_AGENT'])
+  end
+    
+  def ip_denied?(ip)
+    ip && @ip_address_checks.any? { |check| match_ip?(check, ip) }  
+  end
+  
+  def match_ip?(check, ip)
+    case check
+    when Regexp
+      check =~ ip
+    when String
+      ip[0, check.size] == check
+    when Proc
+      check.call(ip)
+    else
+      false
+    end
+  end
+
+  def user_agent_denied?(ua)
+    ua ||= ''
+    @user_agent_checks.any? { |check| match_user_agent?(check, ua) }  
+  end
+  
+  def match_user_agent?(check, ua)
+    case check
+    when Regexp
+      check =~ ua
+    when String
+      ua == check
+    when Proc
+      check.call(ua)
+    else
+      false
+    end    
+  end
+
+  # Used for testing
+  attr_reader :user_agent_checks
+  attr_reader :ip_address_checks
+
+  protected
+  
+  def deny_access
+    [403, {"Content-Type" => "text/html"}, ["<h1>403 Forbidden</h1>"]]
+  end
+ 
+end

data/test/bouncer_test.rb

@@ -0,0 +1,118 @@
+
+require 'test/unit'
+require File.join(File.dirname(__FILE__), '../lib/bouncer.rb')
+
+class App
+  
+  def call(env)
+    [200, {"Content-Type" => "text/plain"}, "OK"]
+  end
+  
+end
+
+class BouncerTest < Test::Unit::TestCase
+
+  EXAMPLE_CONFIGURATION = {
+    :deny_ip_address => ['127.0.0.1', /^10\.\d+\.\d+\.\d+/, lambda { |ip| ip =~ /\.13$/ } ],
+    :deny_user_agent => ["", "msnbot", /daodao/, lambda { |ua| ua.length == 3 } ],
+  }
+  
+  def setup
+    @app = App.new
+    @bouncer = Bouncer.new(@app)
+  end
+  
+  def test_default_options
+    default_status_assertions
+    assert_nothing_raised { @bouncer.call({}) }
+  end
+  
+  def test_configure_with_no_options
+    @bouncer.configure
+    default_status_assertions
+  end
+  
+  def test_configure
+    @bouncer.configure(EXAMPLE_CONFIGURATION)
+    assert_equal 3, @bouncer.ip_address_checks.size
+    assert_equal 4, @bouncer.user_agent_checks.size
+  end
+  
+  def test_match_ip
+    assert @bouncer.match_ip?("127.0.0.1", "127.0.0.1")
+    assert @bouncer.match_ip?("127.0", "127.0.0.1")
+    assert @bouncer.match_ip?("127.0", "127.0.2.1")
+    assert @bouncer.match_ip?(/^127/, "127.0.0.1")
+    assert @bouncer.match_ip?(/^127\.0\.0.\d+/, "127.0.0.1")
+    assert @bouncer.match_ip?(lambda { |ip| ip == '127.0.0.1' }, "127.0.0.1")
+    assert !@bouncer.match_ip?("127.0.0.1", "127.0.0.2")
+    assert !@bouncer.match_ip?("127.0", "127.1.0.0")
+    assert !@bouncer.match_ip?(/10\.0/, "127.1.0.0")
+    assert !@bouncer.match_ip?(lambda { |ip| false }, "127.0.0.1")    
+  end
+  
+  def test_match_user_agent
+    assert @bouncer.match_user_agent?("daodao larbin@unspecified.email", "daodao larbin@unspecified.email")
+    assert !@bouncer.match_user_agent?("daodao", "daodao larbin@unspecified.email")
+    assert @bouncer.match_user_agent?(/daodao/, "daodao larbin@unspecified.email")
+    assert @bouncer.match_user_agent?(/larbin/, "daodao larbin@unspecified.email")
+  end
+  
+  def test_ip_denied
+    @bouncer.configure(EXAMPLE_CONFIGURATION)
+    assert @bouncer.ip_denied?('127.0.0.1')
+    assert @bouncer.ip_denied?('10.2.3.4')
+    assert @bouncer.ip_denied?('10.20.30.40')
+    assert !@bouncer.ip_denied?('127.0.0.2')
+    assert !@bouncer.ip_denied?(nil)
+    assert !@bouncer.ip_denied?('')
+  end
+
+  def test_user_agent_denied
+    @bouncer.configure(EXAMPLE_CONFIGURATION)
+    assert @bouncer.user_agent_denied?('')
+    assert @bouncer.user_agent_denied?(nil)
+    assert @bouncer.user_agent_denied?('msnbot')
+    assert @bouncer.user_agent_denied?('daodao larbin@unspecified.email')
+    assert @bouncer.user_agent_denied?('daodao')
+    assert @bouncer.user_agent_denied?('123')
+    assert !@bouncer.user_agent_denied?('GoogleBot')
+    assert !@bouncer.user_agent_denied?('Mozilla/5.0 (Windows; U; Windows NT 5.1; en) AppleWebKit/526.9 (KHTML, like Gecko) Version/4.0dp1 Safari/526.8')
+  end
+  
+  def test_allowed_request
+    @bouncer.configure(EXAMPLE_CONFIGURATION)
+    @env = {
+      'REMOTE_ADDR' => '1.2.3.4',
+      'PATH_INFO'   => '/path',
+      'HTTP_USER_AGENT'  => 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en) AppleWebKit/526.9 (KHTML, like Gecko) Version/4.0dp1 Safari/526.8'
+    }
+    assert_equal 200, @bouncer.call(@env).first
+  end
+  
+  def test_denied_request
+      @bouncer.configure(EXAMPLE_CONFIGURATION)
+      @env = {
+        'REMOTE_ADDR' => '1.2.3.4',
+        'PATH_INFO'   => '/path',
+        'HTTP_USER_AGENT'  => 'msnbot'
+      }
+      assert_equal 403, @bouncer.call(@env).first
+  end
+  
+  def test_configuration_with_single_items
+    @bouncer.configure(:deny_ip_address => '127.0.0.1', :deny_user_agent => /msnbot/)
+    assert @bouncer.ip_denied?('127.0.0.1')
+    assert !@bouncer.ip_denied?('10.0.0.1')
+    assert @bouncer.user_agent_denied?('msnbot')
+    assert !@bouncer.user_agent_denied?('Safari')
+  end
+  
+  protected
+  
+  def default_status_assertions
+    assert @bouncer.ip_address_checks.empty?
+    assert @bouncer.user_agent_checks.empty?
+  end
+  
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: xavier-bouncer
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Xavier Defrang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-07 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Rack middleware for simple access filtering by IP address or User Agent
+email: xavier.defrang@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- lib/bouncer.rb
+- test/bouncer_test.rb
+has_rdoc: true
+homepage: http://github.com/xavier/bouncer
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Rack middleware for simple access filtering by IP address or User Agent
+test_files: 
+- test/bouncer_test.rb