alpaca 0.9.0 → 1.0.0

data/README.md

@@ -1,16 +1,21 @@
 ## Alpaca (outta nowhere)
 
-![Alpaca](https://raw.github.com/jeffchao/alpaca/master/alpaca.jpeg)
+[![Gem Version](https://badge.fury.io/rb/alpaca.png)](http://badge.fury.io/rb/alpaca)
+[![Build Status](https://travis-ci.org/jeffchao/alpaca.png?branch=master)](https://travis-ci.org/jeffchao/alpaca)
+[![Dependency Status](https://gemnasium.com/jeffchao/alpaca.png)](https://gemnasium.com/jeffchao/alpaca.png)
+[![Coverage Status](https://coveralls.io/repos/jeffchao/alpaca/badge.png)](https://coveralls.io/r/jeffchao/alpaca)
 
 Alpaca (outta nowhere) is a rack middleware that allows developers to quickly and easily configure and manage a whitelist and/or blacklist. The motivation for Alpaca is to address use cases around security concerns such as malicious clients, denial of service, or adding an extra layer of security to an API or a subset of API endpoints.
 
-In progress
+![Alpaca](https://raw.github.com/jeffchao/alpaca/master/alpaca.jpeg)
+
+Features
 ----------
 
-~~Global-level whitelist and blacklist~~
-~~Configuration and management via YAML~~
-~~Whitelist-by-default, blacklist-by-default~~
-Controller-level whitelist and blacklist via `before_filter`
+- Global-level whitelisting and blacklisting at the rack layer
+- Controller-level whitelisting and blacklisting via `before_filter`
+- Per-action whitelisting and blacklisting at the controller level
+- Configuration management via YAML
 
 Getting started
 ----------
@@ -44,11 +49,69 @@ use Rack::Alpaca
 Usage
 ----------
 
-Alpaca supports whitelisting and blacklisting single IP addresses (e.g., `0.0.0.1`), hostnames (e.g., `localhost`), and range of IP addresses with subnet masks (e.g., `198.18.0.0/15`, `2001:db8::/32`). You may use IPv4 or IPv6. You can make changes in `config/alpaca.yml` to either list.
+Alpaca supports:
+
+- whitelisting and blacklisting single IP addresses (e.g., `0.0.0.1`)
+- hostnames (e.g., `127.0.0.1` also affects `localhost`)
+- range of IP addresses via subnet masks (e.g., `198.18.0.0/15`, `2001:db8::/32`).
+
+### Global-level whitelisting and blacklisting
+
+You may use IPv4 or IPv6. Make changes in `config/alpaca.yml` by adding or removing IPs to and from either list. Your file should resemble the following:
+
+```yaml
+whitelist:
+  - 0.0.0.1
+  - 198.18.0.0/15
+  - "::/128"
+blacklist:
+  - 0.0.0.1
+  - 0.0.0.2
+  - "2001:db8::/32"
+default: allow
+```
+
+Depending on your strategy, you may choose to enforce an allow-by-default or deny-by-default approach. You can use the `default` key in the configuration file with either `allow` or `deny` as its value.
+
+**A note about precedence**: If an IP exists in both the whitelist and blacklist, then whitelist will take precedence and allow the IP.
+
+### Controller-level whitelisting and blacklisting
+
+There exists two methods for handling IPs at the controller level. You must have your global-level default set to `allow` for it to be useful. This is because a global-level `deny` would have already blocked all IPs at the rack layer.
+
+```ruby
+before_filter :enable_whitelist_and_deny_by_default
+
+# or
+
+before_filter :enable_blacklist_and_allow_by_default
+```
+
+You may optionally attach this filter to specific method(s):
+
+```ruby
+before_filter :enable_whitlist_and_deny_by_default, only: [:create, :update]
+```
+
+Lastly, you may add additional IPs that were not previously defined in your alpaca.yml`:
+
+```ruby
+before_filter only: [:create, :update] { |f| f.enable_whitelist_and_deny_by_default(['0.0.0.1']) }
+```
+
+### Example setups
+
+Given that some configuration permuations may be unecessary or illogical, the following is a table of typical use cases. The cells represent the resulting behavior:
 
-Depending on your strategy, you may choose to enforce a whitelist-by-default or blacklist-by-default approach. You can use the `default` key in the configuration file with either `whitelist` or `blacklist` as its value.
+|     | global allow-by-default | global deny-by-default |
+| --- | ----------------------- | ---------------------- |
+| **no controller filter** | all IPs allowed | all IPs denied |
+| **controller filter whitelist, no added IPs** | IPs in whitelist from `alpaca.yml` allowed for controller. All other IPs denied for controller. All IPs allowed everywhere else | all IPs denied |
+| **controller filter whitelist, added IPs** | IPs in whitelist from `alpaca.yml` and arguments to filter allowed for controller. All other IPs denied for controller. All IPs allowed everywhere else | all IPs denied |
+| **controller filter blacklist, no added IPs** | IPs in blacklist from `alpaca.yml` denied for controller. All other IPs allowed for controller. All IPs allowed everywhere else | all IPs denied |
+| **controller filter blacklist, added IPs** | IPs in blacklist from `alpaca.yml` and arguments denied for controller. All other IPs allowed for controller. All IPs allowed everywhere else | all IPs denied |
 
-Performance (WIP)
+Performance
 ----------
 
 Through initial testing, Alpaca does not appear to cause noticeable overhead. Future tests under different types of load will be documented here.

data/lib/alpaca.rb

@@ -1,54 +1,5 @@
 require 'rack'
 require 'yaml'
 require 'ipaddr'
-
-module Rack
-  module Alpaca
-    class << self
-      attr_reader :whitelist, :blacklist, :default
-
-      def new (app)
-        @app = app
-        config = YAML.load_file('config/alpaca.yml')
-        @whitelist ||= config['whitelist'].map { |ip| IPAddr.new(ip) }.freeze
-        @blacklist ||= config['blacklist'].map { |ip| IPAddr.new(ip) }.freeze
-        @default = config['default']
-
-        self
-      end
-
-      def call (env)
-        req = Rack::Request.new(env)
-
-        if whitelisted?('whitelist', req)
-          @app.call(env)
-        elsif blacklisted?('blacklist', req)
-          [503, {}, ["Request blocked\n"]]
-        else
-          default_strategy(env)
-        end
-      end
-
-      private
-
-      def default_strategy (env)
-        if @default == 'whitelist'
-          @app.call(env)
-        elsif @default == 'blacklist'
-          [503, {}, ["Request blocked\n"]]
-        else
-          raise 'Unknown default strategy'
-        end
-      end
-
-      def check (type, req)
-        instance_variable_get("@#{type}").any? do |ip|
-          ip.include?(req.ip)
-        end
-      end
-
-      alias_method :whitelisted?, :check
-      alias_method :blacklisted?, :check
-    end
-  end
-end
+require 'alpaca/controller_additions'
+require 'rack/alpaca'

data/lib/alpaca/controller_additions.rb

@@ -0,0 +1,40 @@
+module Alpaca
+  # These are additional helper methods that are added to
+  # ApplicationController. In particular, this module contains
+  # filters that should be used as before_filters.
+  module ControllerAdditions
+    def enable_whitelist_and_deny_by_default (additional_ips = [])
+      render_blocked_request unless whitelisted?(additional_ips)
+    end
+
+    def enable_blacklist_and_allow_by_default (additional_ips = [])
+      if blacklisted?(additional_ips)
+        render_blocked_request
+      end
+    end
+
+    private
+
+    def whitelisted? (additional_ips)
+      additional_ips.any? { |ip| IPAddr.new(ip).include?(request.ip) } ||
+        Rack::Alpaca.whitelist.any? { |ip| ip.include?(request.ip) }
+    end
+
+    def blacklisted? (additional_ips)
+      additional_ips.any? { |ip| IPAddr.new(ip).include?(request.ip) } ||
+        Rack::Alpaca.blacklist.any? { |ip| ip.include?(request.ip) }
+    end
+
+    def render_blocked_request
+      render text: "Request blocked\n",
+             status: :service_unavailable,
+             content_type: 'text/plain'
+    end
+  end
+end
+
+if defined?(ActionController::Base)
+  ActionController::Base.instance_eval do
+    include Alpaca::ControllerAdditions
+  end
+end

data/lib/rack/alpaca.rb

@@ -0,0 +1,51 @@
+module Rack
+  module Alpaca
+    class << self
+      attr_reader :whitelist, :blacklist
+      attr_accessor :default
+
+      def new (app)
+        @app = app
+        config = YAML.load_file('config/alpaca.yml')
+        @whitelist ||= config['whitelist'].map { |ip| IPAddr.new(ip) }.freeze
+        @blacklist ||= config['blacklist'].map { |ip| IPAddr.new(ip) }.freeze
+        @default = config['default']
+
+        self
+      end
+
+      def call (env)
+        req = Rack::Request.new(env)
+
+        if whitelisted?('whitelist', req)
+          @app.call(env)
+        elsif blacklisted?('blacklist', req)
+          [503, {}, ["Request blocked\n"]]
+        else
+          default_strategy(env)
+        end
+      end
+
+      private
+
+      def default_strategy (env)
+        if @default == 'allow'
+          @app.call(env)
+        elsif @default == 'deny'
+          [503, {}, ["Request blocked\n"]]
+        else
+          raise 'Unknown default strategy'
+        end
+      end
+
+      def check (type, req)
+        instance_variable_get("@#{type}").any? do |ip|
+          ip.include?(req.ip)
+        end
+      end
+
+      alias_method :whitelisted?, :check
+      alias_method :blacklisted?, :check
+    end
+  end
+end

data/lib/rack/alpaca/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module Alpaca
-    VERSION = '0.9.0'.freeze
+    VERSION = '1.0.0'
   end
 end

data/spec/alpaca_controller_additions_spec.rb

@@ -0,0 +1,54 @@
+require_relative 'spec_helper'
+
+describe 'Alpaca::ControllerAdditions' do
+  before do
+    @ips = ["0.0.0.1", "198.18.0.0/15", "0.0.0.3"].map { |ip| IPAddr.new(ip) }
+  end
+
+  it 'should initialize with controller additions' do
+    controller = FooController.new
+    controller.methods.must_include(:enable_whitelist_and_deny_by_default)
+    controller.methods.must_include(:enable_blacklist_and_allow_by_default)
+  end
+
+  describe 'with global allow-by-default' do
+    describe '#enable_whitelist_and_deny_by_default' do
+      it 'should only permit IPs on the whitelist' do
+        @ips[0...-1].each do |ip|
+          get '/', {}, 'REMOTE_ADDR' => ip.to_s
+          last_response.status.must_equal 200
+          last_response.body.must_equal 'foo'
+        end
+
+        get '/foo', {}, 'REMOTE_ADDR' => @ips.last.to_s
+        last_response.status.must_equal 503
+        last_response.body.must_equal "Request blocked\n"
+      end
+
+      describe 'with additional IPs' do
+        it 'should permit IPs on the whitelist and arguments' do
+          @ips = @ips[0...-1].push('0.0.0.4')
+          @ips[0..-1].each do |ip|
+            get '/baz', {}, 'REMOTE_ADDR' => ip.to_s
+            last_response.status.must_equal 200
+            last_response.body.must_equal 'baz'
+          end
+        end
+      end
+    end
+
+    describe '#enable_blacklist_and_allow_by_default' do
+      it 'should allow all IPs except ones on the blacklist' do
+        @ips[1..-1].each do |ip|
+          get '/', {}, 'REMOTE_ADDR' => ip.to_s
+          last_response.status.must_equal 200
+          last_response.body.must_equal 'foo'
+        end
+
+        get '/bar', {}, 'REMOTE_ADDR' => @ips.first.to_s
+        last_response.status.must_equal 503
+        last_response.body.must_equal "Request blocked\n"
+      end
+    end
+  end
+end

data/spec/rack_alpaca_spec.rb

@@ -64,4 +64,18 @@ describe 'Rack::Alpaca' do
       end
     end
   end
+
+  describe 'allow-by-default' do
+    before do
+      @ips = ["0.0.0.1", "198.18.0.0/15", "::/128"].map { |ip| IPAddr.new(ip) }
+    end
+
+    it 'should permit any IP address' do
+      @ips.each do |ip|
+        get '/', {}, 'REMOTE_ADDR' => ip.to_s
+        last_response.status.must_equal 200
+        last_response.body.must_equal 'foo'
+      end
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,3 +1,12 @@
+require 'simplecov'
+require 'coveralls'
+
+SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+  SimpleCov::Formatter::HTMLFormatter,
+  Coveralls::SimpleCov::Formatter
+]
+SimpleCov.start
+
 require "rubygems"
 require "bundler/setup"
 
@@ -8,12 +17,51 @@ require "rack/test"
 require 'active_support'
 require "alpaca"
 
+require_relative 'support/action_controller'
+require_relative 'support/foo_controller'
+require_relative 'support/bar_controller'
+require_relative 'support/baz_controller'
+
 class Minitest::Spec
   include Rack::Test::Methods
 
   def app
     Rack::Builder.new {
       use Rack::Alpaca
+
+      map '/foo' do
+        run lambda { |env|
+          controller = ::FooController.new
+          controller.request = Rack::Request.new(env)
+          controller.response = Rack::Response.new
+          controller.process('foo')
+
+          controller.response.finish
+        }
+      end
+
+      map '/bar' do
+        run lambda { |env|
+          controller = ::BarController.new
+          controller.request = Rack::Request.new(env)
+          controller.response = Rack::Response.new
+          controller.process('bar')
+
+          controller.response.finish
+        }
+      end
+
+      map '/baz' do
+        run lambda { |env|
+          controller = ::BazController.new
+          controller.request = Rack::Request.new(env)
+          controller.response = Rack::Response.new
+          controller.process('baz')
+
+          controller.response.finish
+        }
+      end
+
       run lambda { |env| [200, {}, ['foo']] }
     }.to_app
   end

data/spec/support/action_controller.rb

@@ -0,0 +1,27 @@
+require_relative 'filters'
+
+module ActionController
+  class Metal
+    attr_accessor :request, :response
+
+    def process (action)
+      send(action)
+    end
+
+    def render (*args)
+      response.status = Rack::Utils.status_code(args.first[:status])
+      response.body = [args.first[:text]]
+      response
+    end
+  end
+
+  class Base < Metal
+    include Filters
+  end
+end
+
+if defined?(ActionController::Base)
+  ActionController::Base.instance_eval do
+    include Alpaca::ControllerAdditions
+  end
+end

data/spec/support/bar_controller.rb

@@ -0,0 +1,6 @@
+class BarController < ActionController::Base
+  before_filter :enable_blacklist_and_allow_by_default
+
+  def bar
+  end
+end

data/spec/support/baz_controller.rb

@@ -0,0 +1,7 @@
+class BazController < ActionController::Base
+  before_filter :enable_whitelist_and_deny_by_default, ['0.0.0.4']
+
+  def baz
+    render({ status: :ok, text: "baz", content_type: 'text/plain' })
+  end
+end

data/spec/support/filters.rb

@@ -0,0 +1,22 @@
+module Filters
+  def self.included (base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def before_filters
+      @before_filters ||= []
+    end
+
+    def before_filter (*args)
+      method = args.shift
+      ips = args.shift
+      before_filters << (ips.nil? ? [method] : [method, ips])
+    end
+  end
+
+  def process (action)
+    self.class.before_filters.each { |method, ips| ips.nil? ? send(method) : send(method, ips) }
+    super
+  end
+end

data/spec/support/foo_controller.rb

@@ -0,0 +1,6 @@
+class FooController < ActionController::Base
+  before_filter :enable_whitelist_and_deny_by_default
+
+  def foo
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alpaca
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-21 00:00:00.000000000 Z
+date: 2013-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -75,6 +75,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -97,13 +113,21 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/alpaca/controller_additions.rb
 - lib/alpaca.rb
 - lib/rack/alpaca/version.rb
+- lib/rack/alpaca.rb
 - lib/rails/generators/alpaca/install/install_generator.rb
 - Rakefile
 - README.md
+- spec/alpaca_controller_additions_spec.rb
 - spec/rack_alpaca_spec.rb
 - spec/spec_helper.rb
+- spec/support/action_controller.rb
+- spec/support/bar_controller.rb
+- spec/support/baz_controller.rb
+- spec/support/filters.rb
+- spec/support/foo_controller.rb
 homepage: http://github.com/jeffchao/alpaca
 licenses: []
 post_install_message: 
@@ -130,5 +154,11 @@ signing_key:
 specification_version: 3
 summary: Whitelist and blacklist IPs
 test_files:
+- spec/alpaca_controller_additions_spec.rb
 - spec/rack_alpaca_spec.rb
 - spec/spec_helper.rb
+- spec/support/action_controller.rb
+- spec/support/bar_controller.rb
+- spec/support/baz_controller.rb
+- spec/support/filters.rb
+- spec/support/foo_controller.rb