alpaca 0.9.0

data/README.md

@@ -0,0 +1,59 @@
+## Alpaca (outta nowhere)
+
+![Alpaca](https://raw.github.com/jeffchao/alpaca/master/alpaca.jpeg)
+
+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
+----------
+
+~~Global-level whitelist and blacklist~~
+~~Configuration and management via YAML~~
+~~Whitelist-by-default, blacklist-by-default~~
+Controller-level whitelist and blacklist via `before_filter`
+
+Getting started
+----------
+
+Install standalone or add to your Gemfile:
+
+```ruby
+gem 'alpaca'
+```
+
+Run `bundle install` to install the gem.
+
+Afer you install Alpaca, run the generator to create a default config file:
+
+```ruby
+rails generate alpaca:install
+```
+
+Add Alpaca to your middleware stack in `config/application.rb`:
+
+```ruby
+config.middleware.use Rack::Alpaca
+```
+
+or if you are not using rails, but in another Rack application, in `config.ru`:
+
+```ruby
+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.
+
+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.
+
+Performance (WIP)
+----------
+
+Through initial testing, Alpaca does not appear to cause noticeable overhead. Future tests under different types of load will be documented here.
+
+Author
+----------
+
+Jeff Chao, @thejeffchao, http://thejeffchao.com

data/Rakefile

@@ -0,0 +1,9 @@
+require "rubygems"
+require "bundler/setup"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+
+task default: :test

data/lib/alpaca.rb

@@ -0,0 +1,54 @@
+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

data/lib/rack/alpaca/version.rb

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

data/lib/rails/generators/alpaca/install/install_generator.rb

@@ -0,0 +1,13 @@
+module Alpaca
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../../../../../config', __FILE__)
+
+      desc 'Copies an Alpaca configuration file to your application.'
+
+      def copy_configuration
+        copy_file 'alpaca.yml', 'config/alpaca.yml'
+      end
+    end
+  end
+end

data/spec/rack_alpaca_spec.rb

@@ -0,0 +1,67 @@
+require_relative 'spec_helper'
+
+describe 'Rack::Alpaca' do
+  it 'should permit localhost' do
+    get '/', {}, 'REMOTE_ADDR' => '127.0.0.1'
+    last_response.status.must_equal 200
+    last_response.body.must_equal 'foo'
+  end
+
+  describe 'Whitelist' do
+    before do
+      @ips = ["0.0.0.1", "198.18.0.0/15", "::/128"].map { |ip| IPAddr.new(ip) }
+    end
+
+    it 'should have a whitelist' do
+      Rack::Alpaca.whitelist.class.must_equal Array
+      Rack::Alpaca.whitelist.each { |ip| ip.class.must_equal IPAddr }
+      Rack::Alpaca.whitelist.must_equal @ips
+    end
+
+    it 'should permit IP addresses on the whitelist' do
+      Rack::Alpaca.whitelist.each do |ip|
+        get '/', {}, 'REMOTE_ADDR' => ip.to_s
+        last_response.status.must_equal 200
+        last_response.body.must_equal 'foo'
+      end
+    end
+
+    describe 'an IP on whitelist and blacklist' do
+      it 'should permit the IP address' do
+        get '/', {}, 'REMOTE_ADDR' => '0.0.0.1'
+        last_response.status.must_equal 200
+        last_response.body.must_equal 'foo'
+      end
+    end
+  end
+
+  describe 'Blacklist' do
+    before do
+      @ips = ["0.0.0.1", "0.0.0.2", "2001:db8::/32"].map { |ip| IPAddr.new(ip) }
+    end
+
+    it 'should have a blacklist' do
+      Rack::Alpaca.blacklist.class.must_equal Array
+      Rack::Alpaca.whitelist.each { |ip| ip.class.must_equal IPAddr }
+      Rack::Alpaca.blacklist.must_equal @ips
+    end
+
+    it 'should reject IP addresses on the blacklist' do
+      Rack::Alpaca.blacklist.each do |ip|
+        get '/', {}, 'REMOTE_ADDR' => ip.to_s
+        unless Rack::Alpaca.whitelist.include? ip
+          last_response.status.must_equal 503
+          last_response.body.must_equal "Request blocked\n"
+        end
+      end
+    end
+
+    describe 'an IP on whitelist and blacklist' do
+      it 'should permit the IP address' do
+        get '/', {}, 'REMOTE_ADDR' => '0.0.0.1'
+        last_response.status.must_equal 200
+        last_response.body.must_equal 'foo'
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+require "rubygems"
+require "bundler/setup"
+
+require "minitest/autorun"
+require "minitest/pride"
+
+require "rack/test"
+require 'active_support'
+require "alpaca"
+
+class Minitest::Spec
+  include Rack::Test::Methods
+
+  def app
+    Rack::Builder.new {
+      use Rack::Alpaca
+      run lambda { |env| [200, {}, ['foo']] }
+    }.to_app
+  end
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: alpaca
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeff Chao
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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
+    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'
+description: A rack middleware for whitelisting and blacklisting IPs
+email: jeffchao@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/alpaca.rb
+- lib/rack/alpaca/version.rb
+- lib/rails/generators/alpaca/install/install_generator.rb
+- Rakefile
+- README.md
+- spec/rack_alpaca_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/jeffchao/alpaca
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Whitelist and blacklist IPs
+test_files:
+- spec/rack_alpaca_spec.rb
+- spec/spec_helper.rb