rack-defense 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3ece635cf91bb8348db49468754161d10d7263d8
+  data.tar.gz: 9e83f747514c973078fde57e36f370d1429e8188
+SHA512:
+  metadata.gz: c2c434565856a67d7dba649a8d17fc140242e086038c4f61fc6f08e05a6215779f8f76f0baf2fcc0a0fd5e9ff2fcacedb0ba9cc5e737ef21fbd417b29792e2fe
+  data.tar.gz: 78d36f081d9084174c7922d48977f48cf2e38eabf800ddbcff5d17388eb312175d0c32e63765eef393b0054568a535bd716eee06fb955316d80615b53d511c70

data/README.md

@@ -0,0 +1,129 @@
+Rack::Defense
+=============
+
+A Rack middleware for throttling and filtering requests.
+
+[![Code Climate](https://codeclimate.com/github/Sinbadsoft/rack-defense/badges/gpa.svg)](https://codeclimate.com/github/Sinbadsoft/rack-defense) [![Build Status](https://travis-ci.org/Sinbadsoft/rack-defense.svg)](https://travis-ci.org/Sinbadsoft/rack-defense)
+[![Dependency Status](https://gemnasium.com/Sinbadsoft/rack-defense.svg)](https://gemnasium.com/Sinbadsoft/rack-defense)
+
+Rack::Defense is a Rack middleware that allows you to easily add request rate limiting and request filtering to your Rack based application (Ruby On Rails, Sinatra etc.).
+
+* Throttling (aka rate limiting) happens on __sliding window__ using the provided period, request criteria and maximum request number. It uses Redis to track the request rate.
+
+* Request filtering allows to reject requests based on provided critera.
+
+Rack::Defense has a small footprint and only two dependencies: [rack](https://github.com/rack/rack) and [redis](https://github.com/redis/redis-rb).
+
+## Getting started
+
+Install the rack-defense gem; or add it to you Gemfile with bundler:
+
+```ruby
+# In your Gemfile
+gem 'rack-defense'
+```
+Tell your app to use the Rack::Defense middleware. For Rails 3+ apps:
+```
+# In config/application.rb
+config.middleware.use Rack::Defense
+```
+
+Or for Rackup files:
+```
+# In config.ru
+use Rack::Defense
+```
+
+Add a `rack-defense.rb` file to `config/initalizers/`:
+```ruby
+# In config/initializers/rack-defense.rb
+Rack::Defense.setup do |config|
+  # your configuration here
+end
+```
+
+## Throttling
+The Rack::Defense middleware evaluates the throttling criterias (lambadas) against the incoming request. If the return value is falsy, the request is not throttled. Otherwise, the returned value is used as a key to throttle the request. The returned key could be the request IP, user name, API token or any discriminator to throttle the requests against.
+
+### Examples
+
+Throttle POST requests for path `/login` with a maximum rate of 3 request per minute per IP
+```ruby
+Rack::Defense.setup do |config|
+  config.throttle('login', 3, 60 * 1000) do |req|
+    req.ip if req.path == '/login' && req.post?
+  end
+end
+```
+
+Throttle GET requests for path `/image` with a maximum rate of 50 request per second per API token
+```ruby
+Rack::Defense.setup do |config|
+  config.throttle('api', 50, 1000) do |req|
+    req.env['HTTP_AUTHORIZATION'] if %r{^/api/} =~ req.path
+  end 
+end
+```
+
+### Redis Configuration
+
+Rack::Defense uses Redis to track request rates. By default, the `REDIS_URL` environment variable is used to setup the store. If not set, it falls back to host `127.0.0.1` port `6379`.
+The redis store can be setup with either a connection url: 
+```ruby
+Rack::Defense.setup do |config|
+  store = "redis://:p4ssw0rd@10.0.1.1:6380/15"
+end
+```
+or directly with a connection object:
+```ruby
+Rack::Defense.setup do |config|
+  store = Redis.new(host: "10.0.1.1", port: 6380, db: 15)
+end
+```
+
+## Filtering
+
+Rack::Defense can reject requests based on arbitrary properties of the request. Matching requests are filtered.
+
+### Examples
+Allow only a whitelist of ips for a given path:
+```ruby
+Rack::Defense.setup do |config|
+  config.ban('ip_whitelist') do |req|
+    req.path == '/protected' && !['192.168.0.1', '127.0.0.1'].include?(req.ip)
+  end
+end
+```
+
+Allow only requests with a known API authorization token:
+```ruby
+Rack::Defense.setup do |config|
+  config.ban('allow_only_ip_list') do |req|
+    %r{^/api/} =~ req.path && Redis.current.sismember('apitokens', req.env['HTTP_AUTHORIZATION'])
+  end
+end
+```
+
+## Response configuration
+
+By default, Rack::Defense returns `429 Too Many Requests` and `403 Forbidden` respectively for throttled and banned requests. These responses can be fully configured in the setup:
+
+```ruby
+Rack::Defense.setup do |config|
+  config.banned_response =
+    ->(env) { [404, {'Content-Type' => 'text/plain'}, ["Not Found"]] }
+    
+  config.throttled_response =
+    ->(env) { [503, {'Content-Type' => 'text/plain'}, ["Service Unavailable"]] }
+  end
+end
+```
+
+## License
+
+Copyright [Sinbadsoft](http://www.sinbadsoft.com).
+
+Licensed under the [MIT License](http://opensource.org/licenses/MIT).
+
+
+

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+
+task :default => :test

data/lib/rack/defense.rb

@@ -0,0 +1,70 @@
+require 'rack'
+require 'redis'
+
+class Rack::Defense
+  autoload :ThrottleCounter, 'rack/defense/throttle_counter'
+
+  class Config
+    attr_accessor :banned_response
+    attr_accessor :throttled_response
+    attr_reader :bans
+    attr_reader :throttles
+
+    def initialize
+      @throttles, @bans = {}, {}
+      self.banned_response = ->(env) { [403, {'Content-Type' => 'text/plain'}, ["Forbidden\n"]] }
+      self.throttled_response = ->(env) { [429, {'Content-Type' => 'text/plain'}, ["Retry later\n"]] }
+    end
+
+    def throttle(name, max_requests, period, &block)
+      counter = ThrottleCounter.new(name, max_requests, period, store)
+      throttles[name] = lambda do |req|
+        key = block.call(req)
+        key && counter.throttle?(key)
+      end
+    end
+
+    def ban(name, &block)
+      bans[name] = block
+    end
+
+    def store=(value)
+      @store = value.is_a?(String) ? Redis.new(url: value) : value
+    end
+
+    def store
+      # Redis.new uses REDIS_URL environment variable by default as URL.
+      # See https://github.com/redis/redis-rb
+      @store ||= Redis.new
+    end
+  end
+
+  class << self
+    attr_accessor :config
+
+    def setup(&block)
+      self.config = Config.new
+      yield config
+    end
+
+    def ban?(req)
+      config.bans.any? { |name, filter| filter.call(req) }
+    end
+
+    def throttle?(req)
+      config.throttles.any? { |name, filter| filter.call(req) }
+    end
+  end
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    klass, config = self.class, self.class.config
+    req = ::Rack::Request.new(env)
+    return config.banned_response.call(env) if klass.ban?(req)
+    return config.throttled_response.call(env) if klass.throttle?(req)
+    @app.call(env)
+  end
+end

data/lib/rack/defense/throttle_counter.rb

@@ -0,0 +1,36 @@
+module Rack
+  class Defense
+    class ThrottleCounter
+
+      KEY_PREFIX = 'rack-defense'
+
+      attr_accessor :logger
+      attr_accessor :name
+
+      def initialize(name, max_requests, time_period, store)
+        @name, @max_requests, @time_period = name.to_s, max_requests.to_i, time_period.to_i
+        @store = store
+      end
+
+      def throttle?(key, timestamp=nil)
+        timestamp ||= (Time.now.utc.to_f * 1000).to_i
+        @store.eval SCRIPT,
+          ["#{KEY_PREFIX}:#{@name}:#{key}"],
+          [timestamp, @max_requests, @time_period]
+      end
+
+      SCRIPT = <<-LUA_SCRIPT
+      local key = KEYS[1]
+      local timestamp, max_requests, time_period = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
+      if redis.call('rpush', key, timestamp) <= max_requests then
+        return false
+      else
+        return (timestamp - tonumber(redis.call('lpop', key))) <= time_period
+      end
+      LUA_SCRIPT
+
+      private_constant :SCRIPT
+
+    end
+  end
+end

data/lib/rack/defense/version.rb

@@ -0,0 +1,5 @@
+module Rack
+  class Defense
+    VERSION = '0.1.0'
+  end
+end

data/spec/defense_ban_spec.rb

@@ -0,0 +1,35 @@
+require_relative 'spec_helper'
+describe 'Rack::Defense::ban' do
+  before do
+    #
+    # configure the Rack::Defense middleware with a ban
+    # strategy.
+    #
+    Rack::Defense.setup do |config|
+      # allow only given ips on path
+      config.ban('allow_only_ip_list') do |req|
+        req.path == '/protected' && !['192.168.0.1', '127.0.0.1'].include?(req.ip)
+      end
+    end
+  end
+  it 'ban matching requests' do
+    check_request(:get, '/protected','192.168.0.2')
+    check_request(:post, '/protected','192.168.0.3')
+    check_request(:patch, '/protected','192.168.0.2')
+    check_request(:delete, '/protected','192.168.0.2')
+  end
+  it 'allow non matching request' do
+    check_request(:get, '/protected','192.168.0.1')
+    check_request(:get, '/protected','127.0.0.1')
+    check_request(:get, '/protectedx','192.168.0.5')
+    check_request(:post, '/allowed','192.168.0.5')
+  end
+
+  def check_request(verb, path, ip)
+    send verb, path, {}, 'REMOTE_ADDR' => ip
+    expected_status = path == '/protected' && !['192.168.0.1', '127.0.0.1'].include?(ip) ?
+      status_banned : status_ok
+    assert_equal expected_status, last_response.status
+  end
+end
+

data/spec/defense_throttle_spec.rb

@@ -0,0 +1,119 @@
+require_relative 'spec_helper'
+
+describe 'Rack::Defense::throttle' do
+  PERIOD = 60 * 1000 # in milliseconds
+
+  before do
+    @start_time = Time.utc(2015, 10, 30, 21, 0, 0)
+
+    #
+    # configure the Rack::Defense middleware with two throttling
+    # strategies.
+    #
+    Rack::Defense.setup do |config|
+      # allow only 3 post requests on path '/login' per PERIOD per ip
+      config.throttle('login', 3, PERIOD) do |req|
+        req.ip if req.path == '/login' && req.post?
+      end
+
+      # allow only 50 get requests on path '/search' per PERIOD per ip
+      config.throttle('res', 30, PERIOD) do |req|
+        req.ip if req.path == '/search' && req.get?
+      end
+
+      # allow only 5 get requests on path /api/* per PERIOD per authorization token
+      config.throttle('api', 5, PERIOD) do |req|
+        req.env['HTTP_AUTHORIZATION'] if %r{^/api/} =~ req.path
+      end
+    end
+  end
+  it 'allow ok post' do
+    check_post_request
+  end
+  it 'allow ok get' do
+    check_get_request
+  end
+  it 'ban get requests higher than acceptable rate' do
+    10.times do |period|
+      50.times { |offset| check_get_request(offset + period*PERIOD) }
+    end
+  end
+  it 'ban post requests higher than acceptable rate' do
+    10.times do |period|
+      7.times { |offset| check_post_request(offset + period*PERIOD) }
+    end
+  end
+  it 'not have side effects between differrent throttle rules with mixed requests' do
+    10.times do |period|
+      50.times do |offset|
+        check_get_request(offset + period*PERIOD)
+        check_post_request(offset + period*PERIOD)
+      end
+    end
+  end
+  it 'not have side effects between request filtered by the same rule but with different keys' do
+    10.times do |period|
+      50.times do |offset|
+        check_get_request(offset + period*PERIOD, ip='192.168.0.1')
+        check_get_request(offset + period*PERIOD, ip='192.168.0.2')
+      end
+    end
+  end
+  it 'allow unfiltered requests' do
+    50.times do |offset|
+      time = @start_time + offset
+      Timecop.freeze(time) do
+        # the rule matches the '/search' path and not '/searchx'
+        get '/searchx', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        assert_equal status_ok, last_response.status
+
+        # the rule matches only get requests and not post
+        post '/search', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        assert_equal status_ok, last_response.status
+      end
+    end
+    10.times do |offset|
+      time = @start_time + offset
+      Timecop.freeze(time) do
+        # the rule matches only post and not get
+        get '/login', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        assert_equal status_ok, last_response.status
+      end
+    end
+  end
+  it 'not have side effects between unfiltered and filtered requests' do
+    50.times do |offset|
+      time = @start_time + offset
+      Timecop.freeze(time) do
+        get '/searchx', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        assert_equal status_ok, last_response.status
+        get '/search', {}, 'REMOTE_ADDR' => '192.168.0.1'
+        assert_equal offset < 30 ? status_ok : status_throttled, last_response.status
+      end
+    end
+  end
+  it 'should work with key in http header' do
+    10.times do |offset|
+      check_request(:get, '/api/action', offset, 5,
+        '192.168.0.1',
+        'HTTP_AUTHORIZATION' => 'token api_token_here')
+    end
+  end
+
+  def check_get_request(time_offset=0, ip='192.168.0.1', path='/search')
+    check_request(:get, path, time_offset, 30, ip)
+  end
+
+  def check_post_request(time_offset=0, ip='192.168.0.1', path='/login')
+    check_request(:post, path, time_offset, 3, ip)
+  end
+
+  def check_request(verb, path, time_offset, max_requests, ip, headers={})
+    Timecop.freeze(@start_time + time_offset) do
+      send verb, path, {}, headers.merge('REMOTE_ADDR' => ip)
+      expected_status = (time_offset % PERIOD) >= max_requests ? status_throttled : status_ok
+      assert_equal expected_status, last_response.status, "offset #{time_offset}"
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+require 'minitest/autorun'
+require 'rack/test'
+require 'redis'
+require 'timecop'
+require 'rack/defense'
+
+class MiniTest::Spec
+  include Rack::Test::Methods
+
+  def status_ok; 200 end
+  def status_throttled; 429 end
+  def status_banned; 403 end
+
+  def app
+    Rack::Builder.new {
+      use Rack::Defense
+      run ->(env) { [200, {}, ['Hello World']] }
+    }.to_app
+  end
+
+  before do
+    Timecop.safe_mode = true
+    keys = Redis.current.keys("#{Rack::Defense::ThrottleCounter::KEY_PREFIX}:*")
+    Redis.current.del *keys if keys.any?
+  end
+end

data/spec/throttle_counter_spec.rb

@@ -0,0 +1,48 @@
+require_relative 'spec_helper'
+
+describe Rack::Defense::ThrottleCounter do
+  before do
+    @counter = Rack::Defense::ThrottleCounter.new('upload_photo', 5, 10, Redis.current)
+    @key = '192.168.0.1'
+  end
+
+  describe '.throttle?' do
+    it 'allow request number max_requests if after period' do
+      do_max_requests_minus_one
+      refute @counter.throttle? @key, 11
+    end
+    it 'block request number max_requests if in period' do
+      do_max_requests_minus_one
+      assert @counter.throttle? @key, 10
+    end
+    it 'allow consecutive valid periods' do
+      (0..20).each { |i| do_max_requests_minus_one(11 * i) }
+    end
+    it 'block consecutive invalid requests' do
+      do_max_requests_minus_one
+      (0..20).each { |i| assert @counter.throttle?(@key, 10 + i) }
+    end
+    it 'use a sliding window and not reset count after each full period' do
+      [5, 6, 7, 8, 9].each { |t| refute @counter.throttle?(@key, t), "timestamp #{t}" }
+      [12, 13, 14, 15].each { |t| assert @counter.throttle?(@key, t), "timestamp #{t}"}
+    end
+    it 'should unblock after blocking requests' do
+      do_max_requests_minus_one
+      assert @counter.throttle? @key, 10
+      assert @counter.throttle? @key, 11
+      refute @counter.throttle? @key, 16
+    end
+    it 'should include throttled(blocked) request into the request count' do
+      [0, 1, 2, 3, 4].each { |t| refute @counter.throttle?(@key, t), "timestamp #{t}" }
+      assert @counter.throttle? @key, 10
+      [16, 17, 18, 19].each { |t| refute @counter.throttle?(@key, t), "timestamp #{t}" }
+      assert @counter.throttle? @key, 20
+    end
+  end
+
+  def do_max_requests_minus_one(offset=0)
+    [0, 2, 3, 5, 9].map { |t| t + offset }.each do |t|
+      refute @counter.throttle?(@key, t), "timestamp #{t}"
+    end
+  end
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: rack-defense
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chaker Nakhli
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: A rack middleware for throttling and filtering requests
+email:
+- chaker.nakhli@sinbadsoft.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/rack/defense.rb
+- lib/rack/defense/throttle_counter.rb
+- lib/rack/defense/version.rb
+- spec/defense_ban_spec.rb
+- spec/defense_throttle_spec.rb
+- spec/spec_helper.rb
+- spec/throttle_counter_spec.rb
+homepage: http://github.com/sinbadsoft/rack-defense
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Throttle and filter requests
+test_files:
+- spec/spec_helper.rb
+- spec/throttle_counter_spec.rb
+- spec/defense_ban_spec.rb
+- spec/defense_throttle_spec.rb