rack-attack 0.0.3 → 0.1.0

data/README.md

@@ -1,9 +1,122 @@
-# Rack::Attack - middleware for throttling & blocking abusive clients
+# Rack::Attack
+A DSL for blocking & thottling abusive clients
 
-## Processing order
- * If any whitelist matches, the request is allowed
- * If any blacklist matches, the request is blocked (unless a whitelist matched)
- * If any throttle matches, the request is throttled (unless a whitelist or blacklist matched)
+Rack::Attack is a rack middleware to protect your web app from bad clients.
+It allows *whitelisting*, *blacklisting*, and *thottling* based on arbitrary properties of the request.
 
-[![Travis CI](https://secure.travis-ci.org/ktheory/rack-attack.png)](http://travis-ci.org/ktheory/rack-attack)
+Thottle state is stored in a configurable cache (e.g. `Rails.cache`), presumably backed by memcached.
+
+## Installation
+
+Add the [rack-attack](http://rubygems.org/gems/rack-attack) gem to your Gemfile or run
+
+    gem install rack-attack
+
+Tell your app to use the Rack::Attack middleware.
+For Rails 3 apps:
+
+    # In config/application.rb
+    config.middleware.use Rack::Attack
+
+Or in your `config.ru`:
+
+    use Rack::Attack
+
+Optionally configure the cache store for throttling:
+
+    Rack::Attack.cache.store = my_cache_store # defaults to Rails.cache
+
+Note that `Rack::Attack.cache` is only used for throttling, not blacklisting & whitelisting.
+
+## How it works
+
+The Rack::Attack middleware examines each request against *whitelists*, *blacklists*, and *throttles* that you define. There are none by default.
+
+ * If the request matches any whitelist, the request is allowed. Blacklists and throttles are not checked.
+ * If the request matches any blacklist, the request is blocked. Throttles are not checked.
+ * If the request matches any throttle, a counter is incremented in the Rack::Attack.cache. If the throttle limit is exceeded, the request is blocked and further throttles are not checked.
+
+## Usage
+
+Define blacklists, throttles, and whitelists.
+Note that `req` is a [Rack::Request](http://rack.rubyforge.org/doc/classes/Rack/Request.html) object.
+
+### Blacklists
+
+    # 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
+      '1.2.3.4' == req.ip
+    end
+
+    # Block logins from a bad user agent
+    Rack::Attack.blacklist('block bad UA logins') do |req|
+      req.post? && request.path == '/login' && req.user_agent == 'BadUA'
+    end
+
+### Throttles
+
+    # 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 "rack::attack:req/ip:#{req.ip}" is incremented and checked.
+      # If falsy, the cache key is neither incremented or checked.
+      req.ip
+    end
 
+    # Throttle login attempts for a given email parameter to 6 reqs/minute
+    Rack::Attack.throttle('logins/email', :limit => 6, :period => 60.seconds) do |req|
+      req.post? && request.path == '/login' && req.params['email']
+    end
+
+### Whitelists
+
+    # 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
+
+## Responses
+
+Customize the response of throttled requests using an object that adheres to the [Rack app interface](http://rack.rubyforge.org/doc/SPEC.html).
+
+    Rack:Attack.throttled_response = lambda do |env|
+      env['rack.attack.throttled'] # name and other data about the matched throttle
+      [ 503, {}, ['Throttled']]
+    end
+
+Similarly for blacklisted responses:
+
+    Rack:Attack.blacklisted_response = lambda do |env|
+      env['rack.attack.blacklisted'] # name of the matched blacklist
+      [ 503, {}, ['Blocked']]
+    end
+
+## Logging & Instrumentation
+
+Rack::Attack uses the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API if available.
+
+You can subscribe to 'rack.attack.{blacklist,throttle,whitelist}' events and log it, graph it, etc:
+
+    ActiveSupport::Notifications.subscribe('rack.attack.blacklist') do |name, start, finish, request_id, req|
+      puts req.inspect
+    end
+
+## Motivation
+
+Abusive clients range from malicious login crackers to naively-written scrapers.
+They hinder the security, performance, & availability of web applications.
+
+It is impractical if not impossible to block abusive clients completely.
+
+Rack::Attack aims to let developers quickly mitigate abusive requests and rely
+less on short-term, one-off hacks to block a particular attack.
+
+Rack::Attack complements `iptables` and nginx's [limit_zone module](http://wiki.nginx.org/HttpLimitZoneModule).
+
+## Thanks
+
+Thanks to [Kickstarter](https://github.com/kickstarter) for sponsoring Rack::Attack development
+
+[![Travis CI](https://secure.travis-ci.org/ktheory/rack-attack.png)](http://travis-ci.org/ktheory/rack-attack)

data/lib/rack/attack.rb

@@ -8,17 +8,18 @@ module Rack::Attack
   class << self
 
     attr_reader :cache, :notifier
+    attr_accessor :blacklisted_response, :throttled_response
 
     def whitelist(name, &block)
-      (@whitelists ||= {})[name] = Whitelist.new(name, block)
+      self.whitelists[name] = Whitelist.new(name, block)
     end
 
     def blacklist(name, &block)
-      (@blacklists ||= {})[name] = Blacklist.new(name, block)
+      self.blacklists[name] = Blacklist.new(name, block)
     end
 
     def throttle(name, options, &block)
-      (@throttles ||= {})[name] = Throttle.new(name, options, block)
+      self.throttles[name] = Throttle.new(name, options, block)
     end
 
     def whitelists; @whitelists ||= {}; end
@@ -26,13 +27,20 @@ module Rack::Attack
     def throttles;  @throttles  ||= {}; end
 
     def new(app)
-      @cache ||= Cache.new
-      @notifier = ActiveSupport::Notifications if defined?(ActiveSupport::Notifications)
       @app = app
+
+      # Set defaults
+      @cache ||= Cache.new
+      @notifier ||= ActiveSupport::Notifications if defined?(ActiveSupport::Notifications)
+      @blacklisted_response ||= lambda {|env| [503, {}, ['Blocked']] }
+      @throttled_response   ||= lambda {|env|
+        retry_after = env['rack.attack.matched'][:period] rescue nil
+        [503, {'Retry-After' => retry_after}, ['Retry later']]
+      }
+
       self
     end
 
-
     def call(env)
       req = Rack::Request.new(env)
 
@@ -41,9 +49,9 @@ module Rack::Attack
       end
 
       if blacklisted?(req)
-        blacklisted_response
+        blacklisted_response[env]
       elsif throttled?(req)
-        throttled_response
+        throttled_response[env]
       else
         @app.call(env)
       end
@@ -67,19 +75,11 @@ module Rack::Attack
       end
     end
 
-    def instrument(payload)
-      notifier.instrument('rack.attack', payload) if notifier
-    end
-
-    def blacklisted_response
-      [503, {}, ['Blocked']]
-    end
-
-    def throttled_response
-      [503, {}, ['Throttled']]
+    def instrument(type, payload)
+      notifier.instrument("rack.attack.#{type}", payload) if notifier
     end
 
-    def clear!
+   def clear!
       @whitelists, @blacklists, @throttles = {}, {}, {}
     end
 

data/lib/rack/attack/check.rb

@@ -9,7 +9,10 @@ module Rack
 
       def [](req)
         block[req].tap {|match|
-          Rack::Attack.instrument(:type => type, :name => name, :request => req) if match
+          if match
+            req.env["rack.attack.matched"] = {type => name}
+            Rack::Attack.instrument(type, req)
+          end
         }
       end
 

data/lib/rack/attack/throttle.rb

@@ -21,9 +21,12 @@ module Rack
 
         key = "#{name}:#{discriminator}"
         count = cache.count(key, period)
-        throttled = count > limit
-        Rack::Attack.instrument(:type => :throttle, :name => name, :request => req, :count => count, :throttled => throttled)
-        throttled
+        (count > limit).tap do |throttled|
+          if throttled
+            req.env['rack.attack.matched'] = {:throttle => name, :count => count, :period => period, :limit => limit}
+            Rack::Attack.instrument(:throttle, req)
+          end
+        end
       end
 
     end

data/lib/rack/attack/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module Attack
-    VERSION = '0.0.3'
+    VERSION = '0.1.0'
   end
 end

data/spec/rack_attack_spec.rb

@@ -30,12 +30,18 @@ describe 'Rack::Attack' do
 
     it('has a blacklist') { Rack::Attack.blacklists.key?("ip #{@bad_ip}") }
 
-    it "should blacklist bad requests" do
-      get '/', {}, 'REMOTE_ADDR' => @bad_ip
-      last_response.status.must_equal 503
-    end
+    describe "a bad request" do
+      before { get '/', {}, 'REMOTE_ADDR' => @bad_ip }
+      it "should return a blacklist response" do
+        get '/', {}, 'REMOTE_ADDR' => @bad_ip
+        last_response.status.must_equal 503
+      end
+      it "should tag the env" do
+        last_request.env['rack.attack.matched'].must_equal({:blacklist => "ip #{@bad_ip}"})
+      end
 
-    allow_ok_requests
+      allow_ok_requests
+    end
 
     describe "and with a whitelist" do
       before do
@@ -44,9 +50,15 @@ describe 'Rack::Attack' do
       end
 
       it('has a whitelist'){ Rack::Attack.whitelists.key?("good ua") }
-      it "should allow whitelists before blacklists" do
-        get '/', {}, 'REMOTE_ADDR' => @bad_ip, 'HTTP_USER_AGENT' => @good_ua
-        last_response.status.must_equal 200
+      describe "with a request match both whitelist & blacklist" do
+        before { get '/', {}, 'REMOTE_ADDR' => @bad_ip, 'HTTP_USER_AGENT' => @good_ua }
+        it "should allow whitelists before blacklists" do
+          get '/', {}, 'REMOTE_ADDR' => @bad_ip, 'HTTP_USER_AGENT' => @good_ua
+          last_response.status.must_equal 200
+        end
+        it "should tag the env" do
+          last_request.env['rack.attack.matched'].must_equal({:whitelist => 'good ua'})
+        end
       end
     end
   end
@@ -60,18 +72,26 @@ describe 'Rack::Attack' do
     it('should have a throttle'){ Rack::Attack.throttles.key?('ip/sec') }
     allow_ok_requests
 
-    it 'should set the counter for one request' do
-      get '/', {}, 'REMOTE_ADDR' => '1.2.3.4'
-      Rack::Attack.cache.store.read('rack::attack:ip/sec:1.2.3.4').must_equal 1
+    describe 'a single request' do
+      before { get '/', {}, 'REMOTE_ADDR' => '1.2.3.4' }
+      it 'should set the counter for one request' do
+        Rack::Attack.cache.store.read('rack::attack:ip/sec:1.2.3.4').must_equal 1
+      end
     end
-
-    it 'should block 2 requests' do
-      2.times do
-        get '/', {}, 'REMOTE_ADDR' => '1.2.3.4'
+    describe "with 2 requests" do
+      before do
+        2.times { get '/', {}, 'REMOTE_ADDR' => '1.2.3.4' }
+      end
+      it 'should block the last request' do
+        last_response.status.must_equal 503
+      end
+      it 'should tag the env' do
+        last_request.env['rack.attack.matched'].must_equal({:throttle => 'ip/sec', :count => 2, :limit => 1, :period => 1})
+      end
+      it 'should set a Retry-After header' do
+        last_response.headers['Retry-After'].must_equal 1
       end
-      last_response.status.must_equal 503
     end
-  end
-
 
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-attack
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-27 00:00:00.000000000 Z
+date: 2012-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -107,7 +107,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.1.3
-description: A flexible rack middleware for throttling and blocking requests
+description: A rack middleware for throttling and blocking abusive requests
 email: aaron@ktheory.com
 executables: []
 extensions: []