rack-attack 2.1.1 → 2.2.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZmExMGQ3ZWEwMTBlMWY1N2ViNjgyMDM0YTI5Njc4ODQzZjU0NmQ3MQ==
-  data.tar.gz: !binary |-
-    MDJmYTBjNWE4NTAzNzQ0Yjg1MjQ4MWE5ZDE1YzU4OWU4YTkxZDBkMA==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    ZDJmYWJjMzhhYTdkZTYxMjM0ZDY2OGQ0ZjA2NzQ2ZGU2YTBiOWY2N2EwYTA2
-    MGIzNTBiMjAwMDhhYWE2YzMyZTI0OTk3MGM5MjU4NmQzYTc4YzdmNDYxNzcx
-    OTljOTVjNGE4YTQ1ZDQyMzY2MDdiMjUyZGFhNjFjNzc0NDBiZWQ=
-  data.tar.gz: !binary |-
-    Y2E5NGViNGQxMGFmMTM0ZWM2N2YzYWQ4Yjg4ZTkyMDdkNTY5NGVjOWUwNzEx
-    M2ViYWJlZWFiNTcxNGIwODk0Nzk5MDY5YjA5N2Y2MjE5ZjYxYTkzNzcyMWFk
-    NjQ4YzVhZGY0N2U2NzE1NjQwODkyYzIzMDFmZDMxYmM0ZmVlM2U=
+SHA1:
+  metadata.gz: 30436667301e528e76d76b7454ad73ca9dd08a08
+  data.tar.gz: 72e275cb98d8e38b478c4db4d7fa5bdb4759c7ab
+SHA512:
+  metadata.gz: d2a8d0690b58f15a6f512077408fa40cec5c7e23b39ebc470a53a753273f1497e3605930106d2c16dd41a8b3edef39a3e9b66b0fd4778b871c5ab0017e2bd4ac
+  data.tar.gz: 2a097e071cafcdb11cf36d4150c459723877a852b7920fdf3ed5fa74cedf1ea3d19b25357d0bd31c3b47c48d3a938575e877aade034e8fc7f5eba882101385b5

data/README.md

@@ -10,23 +10,30 @@ Throttle state is stored in a configurable cache (e.g. `Rails.cache`), presumabl
 
 Install the [rack-attack](http://rubygems.org/gems/rack-attack) gem; or add it to you Gemfile with bundler:
 
+```ruby
     # In your Gemfile
     gem 'rack-attack'
-
+```
 Tell your app to use the Rack::Attack middleware.
 For Rails 3 apps:
 
+```ruby
     # In config/application.rb
     config.middleware.use Rack::Attack
+```
 
 Or for Rackup files:
 
+```ruby
     # In config.ru
     use Rack::Attack
+```
 
 Optionally configure the cache store for throttling:
 
+```ruby
     Rack::Attack.cache.store = ActiveSupport::Cache::MemoryStore.new # defaults to Rails.cache
+```
 
 Note that `Rack::Attack.cache` is only used for throttling; not blacklisting & whitelisting. Your cache store must implement `increment` and `write` like [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).
 
@@ -41,6 +48,7 @@ The Rack::Attack middleware compares each request against *whitelists*, *blackli
 
 The algorithm is actually more concise in code: See [Rack::Attack.call](https://github.com/kickstarter/rack-attack/blob/master/lib/rack/attack.rb):
 
+```ruby
     def call(env)
       req = Rack::Request.new(env)
 
@@ -55,6 +63,7 @@ The algorithm is actually more concise in code: See [Rack::Attack.call](https://
         @app.call(env)
       end
     end
+```
 
 ## About Tracks
 
@@ -62,20 +71,24 @@ The algorithm is actually more concise in code: See [Rack::Attack.call](https://
 
 ## Usage
 
-Define whitelists, blacklists, throttles, and tracks as blocks that return truthy values if matched, falsy otherwise.
+Define whitelists, blacklists, throttles, and tracks as blocks that return truthy values if matched, falsy otherwise. In a Rails app 
+these go in an initializer in `config/initializers/`.
 A [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) object is passed to the block (named 'req' in the examples).
 
 ### Whitelists
 
+```ruby
     # Always allow requests from localhost
     # (blacklist & throttles are skipped)
     Rack::Attack.whitelist('allow from localhost') do |req|
       # Requests are allowed if the return value is truthy
       '127.0.0.1' == req.ip
     end
+```
 
 ### Blacklists
 
+```ruby
     # Block requests from 1.2.3.4
     Rack::Attack.blacklist('block 1.2.3.4') do |req|
       # Request are blocked if the return value is truthy
@@ -86,9 +99,31 @@ A [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) objec
     Rack::Attack.blacklist('block bad UA logins') do |req|
       req.path == '/login' && req.post? && req.user_agent == 'BadUA'
     end
+```
+
+#### Fail2Ban
+
+`Fail2Ban.filter` can be used within a blacklist to block all requests from misbehaving clients.
+This pattern is inspired by [fail2ban](http://www.fail2ban.org/wiki/index.php/Main_Page).
+See the [fail2ban documentation](http://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Jail_Options) for more details on
+how the parameters work.
+
+```ruby
+    # Block requests containing '/etc/password' in the params.
+    # After 3 blocked requests in 10 minutes, block all requests from that IP for 5 minutes.
+    Rack::Attack.blacklist('fail2ban pentesters') do |req|
+      # `filter` returns truthy value if request fails, or if it's from a previously banned IP
+      # so the request is blocked
+      Rack::Attack::Fail2Ban.filter(req.ip, :maxretry => 3, :findtime => 10.minutes, :bantime => 5.minutes) do
+        # The count for the IP is incremented if the return value is truthy.
+        CGI.unescape(req.query_string) =~ %r{/etc/passwd}
+      end
+    end
+```
 
 ### Throttles
 
+```ruby
     # Throttle requests to 5 requests per second per ip
     Rack::Attack.throttle('req/ip', :limit => 5, :period => 1.second) do |req|
       # If the return value is truthy, the cache key for the return value
@@ -101,12 +136,15 @@ A [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) objec
     end
 
     # Throttle login attempts for a given email parameter to 6 reqs/minute
+    # Return the email as a discriminator on POST /login requests
     Rack::Attack.throttle('logins/email', :limit => 6, :period => 60.seconds) do |req|
-      req.path == '/login' && req.post? && req.params['email']
+      req.params['email'] if req.path == '/login' && req.post?
     end
+```
 
 ### Tracks
 
+```ruby
     # Track requests from a special user agent
     Rack::Attack.track("special_agent") do |req|
       req.user_agent == "SpecialAgent"
@@ -119,12 +157,13 @@ A [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) objec
         STATSD.increment("special_agent")
       end
     end
-
+```
 
 ## Responses
 
 Customize the response of blacklisted and throttled requests using an object that adheres to the [Rack app interface](http://rack.rubyforge.org/doc/SPEC.html).
 
+```ruby
     Rack::Attack.blacklisted_response = lambda do |env|
       [ 503, {}, ['Blocked']]
     end
@@ -139,10 +178,13 @@ Customize the response of blacklisted and throttled requests using an object tha
 
       [ 503, {}, [body]]
     end
+```
 
 For responses that did not exceed a throttle limit, Rack::Attack annotates the env with match data:
 
+```ruby
     request.env['rack.attack.throttle_data'][name] # => { :count => n, :period => p, :limit => l }
+```
 
 ## Logging & Instrumentation
 
@@ -150,9 +192,17 @@ Rack::Attack uses the [ActiveSupport::Notifications](http://api.rubyonrails.org/
 
 You can subscribe to 'rack.attack' events and log it, graph it, etc:
 
+```ruby
     ActiveSupport::Notifications.subscribe('rack.attack') do |name, start, finish, request_id, req|
       puts req.inspect
     end
+```
+
+## Testing
+
+A note on developing and testing apps using Rack::Attack - if you are using throttling in particular, you will 
+need to enable the cache in your development environment. See [Caching with Rails](http://guides.rubyonrails.org/caching_with_rails.html) 
+for more on how to do this. 
 
 ## Performance
 

data/lib/rack/attack.rb

@@ -6,6 +6,8 @@ module Rack::Attack
   autoload :Whitelist, 'rack/attack/whitelist'
   autoload :Blacklist, 'rack/attack/blacklist'
   autoload :Track,     'rack/attack/track'
+  autoload :StoreProxy,'rack/attack/store_proxy'
+  autoload :Fail2Ban,  'rack/attack/fail2ban'
 
   class << self
 

data/lib/rack/attack/cache.rb

@@ -11,15 +11,7 @@ module Rack
 
       attr_reader :store
       def store=(store)
-        # RedisStore#increment needs different behavior, so detect that
-        # (method has an arity of 2; must call #expire separately
-        if defined?(::ActiveSupport::Cache::RedisStore) && store.is_a?(::ActiveSupport::Cache::RedisStore)
-          # ActiveSupport::Cache::RedisStore doesn't expose any way to set an expiry,
-          # so use the raw Redis::Store instead
-          @store = store.instance_variable_get(:@data)
-        else
-          @store = store
-        end
+        @store = StoreProxy.build(store)
       end
 
       def count(unprefixed_key, period)
@@ -29,15 +21,18 @@ module Rack
         do_count(key, expires_in)
       end
 
+      def read(unprefixed_key)
+        store.read("#{prefix}:#{unprefixed_key}")
+      end
+
+      def write(unprefixed_key, value, expires_in)
+        store.write("#{prefix}:#{unprefixed_key}", value, :expires_in => expires_in)
+      end
+
       private
       def do_count(key, expires_in)
-        # Workaround Redis::Store's interface
-        if defined?(::Redis::Store) && store.is_a?(::Redis::Store)
-          result = store.incr(key)
-          store.expire(key, expires_in)
-        else
-          result = store.increment(key, 1, :expires_in => expires_in)
-        end
+        result = store.increment(key, 1, :expires_in => expires_in)
+
         # NB: Some stores return nil when incrementing uninitialized values
         if result.nil?
           store.write(key, 1, :expires_in => expires_in)

data/lib/rack/attack/fail2ban.rb

@@ -0,0 +1,43 @@
+module Rack
+  module Attack
+    class Fail2Ban
+      class << self
+        def filter(discriminator, options)
+          bantime   = options[:bantime]   or raise ArgumentError, "Must pass bantime option"
+          findtime  = options[:findtime]  or raise ArgumentError, "Must pass findtime option"
+          maxretry  = options[:maxretry]  or raise ArgumentError, "Must pass maxretry option"
+
+          if banned?(discriminator)
+            # Return true for blacklist
+            true
+          elsif yield
+            fail!(discriminator, bantime, findtime, maxretry)
+          end
+        end
+
+        private
+        def fail!(discriminator, bantime, findtime, maxretry)
+          count = cache.count("fail2ban:count:#{discriminator}", findtime)
+          if count >= maxretry
+            ban!(discriminator, bantime)
+          end
+
+          # Return true for blacklist
+          true
+        end
+
+        def ban!(discriminator, bantime)
+          cache.write("fail2ban:ban:#{discriminator}", 1, bantime)
+        end
+
+        def banned?(discriminator)
+          cache.read("fail2ban:ban:#{discriminator}")
+        end
+
+        def cache
+          Rack::Attack.cache
+        end
+      end
+    end
+  end
+end

data/lib/rack/attack/store_proxy.rb

@@ -0,0 +1,51 @@
+require 'delegate'
+
+module Rack
+  module Attack
+    class StoreProxy
+      def self.build(store)
+        # RedisStore#increment needs different behavior, so detect that
+        # (method has an arity of 2; must call #expire separately
+        if defined?(::ActiveSupport::Cache::RedisStore) && store.is_a?(::ActiveSupport::Cache::RedisStore)
+          # ActiveSupport::Cache::RedisStore doesn't expose any way to set an expiry,
+          # so use the raw Redis::Store instead
+          store = store.instance_variable_get(:@data)
+        end
+
+        if defined?(::Redis::Store) && store.is_a?(::Redis::Store)
+          RedisStoreProxy.new(store)
+        else
+          store
+        end
+      end
+
+      class RedisStoreProxy < SimpleDelegator
+        def initialize(store)
+          super(store)
+        end
+
+        def read(key)
+          self.get(key)
+        end
+
+        def write(key, value, options={})
+          if (expires_in = options[:expires_in])
+            self.setex(key, expires_in, value)
+          else
+            self.set(key, value)
+          end
+        end
+
+        def increment(key, amount, options={})
+          count = nil
+          self.pipelined do
+            count = self.incrby(key, amount)
+            self.expire(key, options[:expires_in]) if options[:expires_in]
+          end
+          count.value if count
+        end
+
+      end
+    end
+  end
+end

data/lib/rack/attack/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module Attack
-    VERSION = '2.1.1'
+    VERSION = '2.2.0'
   end
 end

data/spec/fail2ban_spec.rb

@@ -0,0 +1,121 @@
+require_relative 'spec_helper'
+describe 'Rack::Attack.Fail2Ban' do
+  before do
+    # Use a long findtime; failures due to cache key rotation less likely
+    @cache = Rack::Attack.cache
+    @findtime = 60
+    @bantime  = 60
+    Rack::Attack.cache.store = ActiveSupport::Cache::MemoryStore.new
+    @f2b_options = {:bantime => @bantime, :findtime => @findtime, :maxretry => 2}
+    Rack::Attack.blacklist('pentest') do |req|
+      Rack::Attack::Fail2Ban.filter(req.ip, @f2b_options){req.query_string =~ /OMGHAX/}
+    end
+  end
+
+  describe 'discriminator has not been banned' do
+    describe 'making ok request' do
+      it 'succeeds' do
+        get '/', {}, 'REMOTE_ADDR' => '1.2.3.4'
+        last_response.status.must_equal 200
+      end
+    end
+
+    describe 'making failing request' do
+      describe 'when not at maxretry' do
+        before { get '/?foo=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4' }
+        it 'fails' do
+          last_response.status.must_equal 503
+        end
+
+        it 'increases fail count' do
+          key = "rack::attack:#{Time.now.to_i/@findtime}:fail2ban:count:1.2.3.4"
+          @cache.store.read(key).must_equal 1
+        end
+
+        it 'is not banned' do
+          key = "rack::attack:fail2ban:1.2.3.4"
+          @cache.store.read(key).must_be_nil
+        end
+      end
+
+      describe 'when at maxretry' do
+        before do
+          # maxretry is 2 - so hit with an extra failed request first
+          get '/?test=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4'
+          get '/?foo=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4'
+        end
+
+        it 'fails' do
+          last_response.status.must_equal 503
+        end
+
+        it 'increases fail count' do
+          key = "rack::attack:#{Time.now.to_i/@findtime}:fail2ban:count:1.2.3.4"
+          @cache.store.read(key).must_equal 2
+        end
+
+        it 'is banned' do
+          key = "rack::attack:fail2ban:ban:1.2.3.4"
+          @cache.store.read(key).must_equal 1
+        end
+
+      end
+    end
+  end
+
+  describe 'discriminator has been banned' do
+    before do
+      # maxretry is 2 - so hit enough times to get banned
+      get '/?test=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4'
+      get '/?foo=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4'
+    end
+
+    describe 'making request for other discriminator' do
+      it 'succeeds' do
+        get '/', {}, 'REMOTE_ADDR' => '2.2.3.4'
+        last_response.status.must_equal 200
+      end
+    end
+
+    describe 'making ok request' do
+      before do
+        get '/', {}, 'REMOTE_ADDR' => '1.2.3.4'
+      end
+
+      it 'fails' do
+        last_response.status.must_equal 503
+      end
+
+      it 'does not increase fail count' do
+        key = "rack::attack:#{Time.now.to_i/@findtime}:fail2ban:count:1.2.3.4"
+        @cache.store.read(key).must_equal 2
+      end
+
+      it 'is still banned' do
+        key = "rack::attack:fail2ban:ban:1.2.3.4"
+        @cache.store.read(key).must_equal 1
+      end
+    end
+
+    describe 'making failing request' do
+      before do
+        get '/?foo=OMGHAX', {}, 'REMOTE_ADDR' => '1.2.3.4'
+      end
+
+      it 'fails' do
+        last_response.status.must_equal 503
+      end
+
+      it 'does not increase fail count' do
+        key = "rack::attack:#{Time.now.to_i/@findtime}:fail2ban:count:1.2.3.4"
+        @cache.store.read(key).must_equal 2
+      end
+
+      it 'is still banned' do
+        key = "rack::attack:fail2ban:ban:1.2.3.4"
+        @cache.store.read(key).must_equal 1
+      end
+    end
+
+  end
+end

data/spec/rack_attack_cache_spec.rb

@@ -20,6 +20,7 @@ if ENV['TEST_INTEGRATION']
     ]
 
     cache_stores.each do |store|
+      store = Rack::Attack::StoreProxy.build(store)
       describe "with #{store.class}" do
 
         before {
@@ -51,6 +52,28 @@ if ENV['TEST_INTEGRATION']
             @cache.send(:do_count, @key, @expires_in).must_equal 1
           end
         end
+
+        describe "write" do
+          it "should write a value to the store with prefix" do
+            @cache.write("cache-test-key", "foobar", 1)
+            store.read(@key).must_equal "foobar"
+          end
+        end
+
+        describe "write after expiry" do
+          it "must not have a value" do
+            @cache.write("cache-test-key", "foobar", @expires_in)
+            sleep @expires_in # tick... tick... tick...
+            store.read(@key).must_be :nil?
+          end
+        end
+
+        describe "read" do
+          it "must read the value with a prefix" do
+            store.write(@key, "foobar", :expires_in => @expires_in)
+            @cache.read("cache-test-key").must_equal "foobar"
+          end
+        end
       end
 
     end

metadata

@@ -1,83 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: rack-attack
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Aaron Suggs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-16 00:00:00.000000000 Z
+date: 2013-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
 - !ruby/object:Gem::Dependency
@@ -98,28 +98,28 @@ dependencies:
   name: redis-activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: dalli
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: A rack middleware for throttling and blocking abusive requests
@@ -131,6 +131,8 @@ files:
 - lib/rack/attack/blacklist.rb
 - lib/rack/attack/cache.rb
 - lib/rack/attack/check.rb
+- lib/rack/attack/fail2ban.rb
+- lib/rack/attack/store_proxy.rb
 - lib/rack/attack/throttle.rb
 - lib/rack/attack/track.rb
 - lib/rack/attack/version.rb
@@ -138,6 +140,7 @@ files:
 - lib/rack/attack.rb
 - Rakefile
 - README.md
+- spec/fail2ban_spec.rb
 - spec/rack_attack_cache_spec.rb
 - spec/rack_attack_spec.rb
 - spec/rack_attack_throttle_spec.rb
@@ -153,24 +156,24 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.2
 signing_key: 
 specification_version: 4
 summary: Block & throttle abusive requests
 test_files:
+- spec/fail2ban_spec.rb
 - spec/rack_attack_cache_spec.rb
 - spec/rack_attack_spec.rb
 - spec/rack_attack_throttle_spec.rb
 - spec/rack_attack_track_spec.rb
 - spec/spec_helper.rb
-has_rdoc: