rack-attack 5.4.2 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e666812691cc414692f7125979f0b152a9111ccee075e65b811fa4a6d8770daa
-  data.tar.gz: 3e8caba79f7ad09d4999cce6358de9cc29b815dee3c9f9c5adbf12763c764656
+  metadata.gz: f85825803ce676e10466175d4bb99cc151d649130d6f4008bdffdc1381b4650a
+  data.tar.gz: 2bcd9d6a9d75491df5a9ddf2f7a5128eae152245fce8f27a069f36037ebc8ddb
 SHA512:
-  metadata.gz: f630c0cd1a34bd588e616653a2e6795e2ec6baafc0e0df8b489e6aa451cf47fb64065447fb3ceb2b029a51d87a0393d6d44cea02e58423626ea46165531f7da3
-  data.tar.gz: 22efc414db06b0a1bbbf8e6d34a3e0d0ead64f1832f48dc30af7ec0a374ef215d53cacf0a8e95c842bff0af84df0939f27820e4668c739eb8db3c51ebba4088e
+  metadata.gz: 5c9b03bbb0e55105ebe4d2ea9a0f13a025ea7ab4903f86e07956ecbd7f7ddfcacfecbbc8239bc9ac427fcc4bd5445fa85e20732bd4d90b51f6dafeb7194bc063
+  data.tar.gz: a31dad7fb5c9220d4a44b303103ffb12cb23843bc150b14cec38a9d0151bc73791a66a80e8a543fa09f58d36a7b0627f0b5fda4fb93953d525747840d7e1d97f

data/README.md

@@ -10,9 +10,42 @@ See the [Backing & Hacking blog post](https://www.kickstarter.com/backing-and-ha
 [![Build Status](https://travis-ci.org/kickstarter/rack-attack.svg?branch=master)](https://travis-ci.org/kickstarter/rack-attack)
 [![Code Climate](https://codeclimate.com/github/kickstarter/rack-attack.svg)](https://codeclimate.com/github/kickstarter/rack-attack)
 
+## Table of contents
+
+- [Getting started](#getting-started)
+  - [Installing](#installing)
+  - [Plugging into the application](#plugging-into-the-application)
+- [Usage](#usage)
+  - [Safelisting](#safelisting)
+    - [`safelist_ip(ip_address_string)`](#safelist_ipip_address_string)
+    - [`safelist_ip(ip_subnet_string)`](#safelist_ipip_subnet_string)
+    - [`safelist(name, &block)`](#safelistname-block)
+  - [Blocking](#blocking)
+    - [`blocklist_ip(ip_address_string)`](#blocklist_ipip_address_string)
+    - [`blocklist_ip(ip_subnet_string)`](#blocklist_ipip_subnet_string)
+    - [`blocklist(name, &block)`](#blocklistname-block)
+    - [Fail2Ban](#fail2ban)
+    - [Allow2Ban](#allow2ban)
+  - [Throttling](#throttling)
+    - [`throttle(name, options, &block)`](#throttlename-options-block)
+  - [Tracks](#tracks)
+  - [Cache store configuration](#cache-store-configuration)
+- [Customizing responses](#customizing-responses)
+  - [RateLimit headers for well-behaved clients](#ratelimit-headers-for-well-behaved-clients)
+- [Logging & Instrumentation](#logging--instrumentation)
+- [How it works](#how-it-works)
+  - [About Tracks](#about-tracks)
+- [Testing](#testing)
+- [Performance](#performance)
+- [Motivation](#motivation)
+- [Contributing](#contributing)
+- [Code of Conduct](#code-of-conduct)
+- [Development setup](#development-setup)
+- [License](#license)
+
 ## Getting started
 
-### 1. Installing
+### Installing
 
 Add this line to your application's Gemfile:
 
@@ -30,7 +63,7 @@ Or install it yourself as:
 
     $ gem install rack-attack
 
-### 2. Plugging into the application
+### Plugging into the application
 
 Then tell your ruby web application to use rack-attack as a middleware.
 
@@ -55,8 +88,8 @@ __IMPORTANT__: By default, rack-attack won't perform any blocking or throttling,
 
 ## Usage
 
-*Tip:* The example in the wiki is a great way to get started:
-[Example Configuration](https://github.com/kickstarter/rack-attack/wiki/Example-Configuration)
+*Tip:* If you just want to get going asap, then you can take our [example configuration](docs/example_configuration.md)
+and tailor it to your needs, or check out the [advanced configuration](docs/advanced_configuration.md) examples.
 
 Define rules by calling `Rack::Attack` public methods, in any file that runs when your application is being initialized. For rails applications this means creating a new file named `config/initializers/rack_attack.rb` and writing your rules there.
 
@@ -86,7 +119,7 @@ Rack::Attack.safelist_ip("5.6.7.0/24")
 
 #### `safelist(name, &block)`
 
-Name your custom safelist and make your ruby-block argument return a truthy value if you want the request to be blocked, and falsy otherwise.
+Name your custom safelist and make your ruby-block argument return a truthy value if you want the request to be allowed, and falsy otherwise.
 
 The request object is a [Rack::Request](http://www.rubydoc.info/gems/rack/Rack/Request).
 
@@ -252,7 +285,8 @@ Rack::Attack.track("special_agent", limit: 6, period: 60) do |req|
 end
 
 # Track it using ActiveSupport::Notification
-ActiveSupport::Notifications.subscribe("rack.attack") do |name, start, finish, request_id, req|
+ActiveSupport::Notifications.subscribe("rack.attack") do |name, start, finish, request_id, payload|
+  req = payload[:request]
   if req.env['rack.attack.matched'] == "special_agent" && req.env['rack.attack.match_type'] == :track
     Rails.logger.info "special_agent: #{req.path}"
     STATSD.increment("special_agent")
@@ -294,12 +328,12 @@ Rack::Attack.throttled_response = lambda do |env|
 end
 ```
 
-### X-RateLimit headers for well-behaved clients
+### RateLimit headers for well-behaved clients
 
 While Rack::Attack's primary focus is minimizing harm from abusive clients, it
 can also be used to return rate limit data that's helpful for well-behaved clients.
 
-Here's an example response that includes conventional `X-RateLimit-*` headers:
+Here's an example response that includes conventional `RateLimit-*` headers:
 
 ```ruby
 Rack::Attack.throttled_response = lambda do |env|
@@ -307,9 +341,9 @@ Rack::Attack.throttled_response = lambda do |env|
   now = match_data[:epoch_time]
 
   headers = {
-    'X-RateLimit-Limit' => match_data[:limit].to_s,
-    'X-RateLimit-Remaining' => '0',
-    'X-RateLimit-Reset' => (now + (match_data[:period] - now % match_data[:period])).to_s
+    'RateLimit-Limit' => match_data[:limit].to_s,
+    'RateLimit-Remaining' => '0',
+    'RateLimit-Reset' => (now + (match_data[:period] - now % match_data[:period])).to_s
   }
 
   [ 429, headers, ["Throttled\n"]]
@@ -327,11 +361,26 @@ request.env['rack.attack.throttle_data'][name] # => { :count => n, :period => p,
 
 Rack::Attack uses the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API if available.
 
-You can subscribe to 'rack.attack' events and log it, graph it, etc:
+You can subscribe to `rack_attack` events and log it, graph it, etc.
+
+To get notified about specific type of events, subscribe to the event name followed by the `rack_attack` namesapce.
+E.g. for throttles use:
 
 ```ruby
-ActiveSupport::Notifications.subscribe('rack.attack') do |name, start, finish, request_id, req|
-  puts req.inspect
+ActiveSupport::Notifications.subscribe("throttle.rack_attack") do |name, start, finish, request_id, payload|
+  # request object available in payload[:request]
+
+  # Your code here
+end
+```
+
+If you want to subscribe to every `rack_attack` event, use:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/rack_attack/) do |name, start, finish, request_id, payload|
+  # request object available in payload[:request]
+
+  # Your code here
 end
 ```
 
@@ -344,7 +393,7 @@ The Rack::Attack middleware compares each request against *safelists*, *blocklis
  * Otherwise, if the request matches any **throttle**, a counter is incremented in the Rack::Attack.cache. If any throttle's limit is exceeded, the request is blocked.
  * Otherwise, all **tracks** are checked, and the request is allowed.
 
-The algorithm is actually more concise in code: See [Rack::Attack.call](https://github.com/kickstarter/rack-attack/blob/master/lib/rack/attack.rb):
+The algorithm is actually more concise in code: See [Rack::Attack.call](lib/rack/attack.rb):
 
 ```ruby
 def call(env)
@@ -365,7 +414,7 @@ end
 
 Note: `Rack::Attack::Request` is just a subclass of `Rack::Request` so that you
 can cleanly monkey patch helper methods onto the
-[request object](https://github.com/kickstarter/rack-attack/blob/master/lib/rack/attack/request.rb).
+[request object](lib/rack/attack/request.rb).
 
 ### About Tracks
 
@@ -412,13 +461,6 @@ This project is intended to be a safe, welcoming space for collaboration, and co
 
 Check out the [Development guide](docs/development.md).
 
-## Mailing list
-
-New releases of Rack::Attack are announced on
-<rack.attack.announce@librelist.com>. To subscribe, just send an email to
-<rack.attack.announce@librelist.com>. See the
-[archives](http://librelist.com/browser/rack.attack.announce/).
-
 ## License
 
 Copyright Kickstarter, PBC.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rubygems"
 require "bundler/setup"
 require 'bundler/gem_tasks'
@@ -24,4 +26,4 @@ Rake::TestTask.new(:test) do |t|
   t.pattern = "spec/**/*_spec.rb"
 end
 
-task :default => [:rubocop, :test]
+task default: [:rubocop, :test]

data/lib/rack/attack.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rack'
 require 'forwardable'
 require 'rack/attack/path_normalizer'
@@ -16,93 +18,79 @@ class Rack::Attack
   autoload :Track,                'rack/attack/track'
   autoload :StoreProxy,           'rack/attack/store_proxy'
   autoload :DalliProxy,           'rack/attack/store_proxy/dalli_proxy'
-  autoload :MemCacheProxy,        'rack/attack/store_proxy/mem_cache_proxy'
   autoload :MemCacheStoreProxy,   'rack/attack/store_proxy/mem_cache_store_proxy'
   autoload :RedisProxy,           'rack/attack/store_proxy/redis_proxy'
   autoload :RedisStoreProxy,      'rack/attack/store_proxy/redis_store_proxy'
   autoload :RedisCacheStoreProxy, 'rack/attack/store_proxy/redis_cache_store_proxy'
+  autoload :ActiveSupportRedisStoreProxy, 'rack/attack/store_proxy/active_support_redis_store_proxy'
   autoload :Fail2Ban,             'rack/attack/fail2ban'
   autoload :Allow2Ban,            'rack/attack/allow2ban'
 
   class << self
-    attr_accessor :notifier, :blocklisted_response, :throttled_response
+    attr_accessor :notifier, :blocklisted_response, :throttled_response, :anonymous_blocklists, :anonymous_safelists
 
-    def safelist(name, &block)
-      self.safelists[name] = Safelist.new(name, block)
-    end
+    def safelist(name = nil, &block)
+      safelist = Safelist.new(name, &block)
 
-    def whitelist(name, &block)
-      warn "[DEPRECATION] 'Rack::Attack.whitelist' is deprecated.  Please use 'safelist' instead."
-      safelist(name, &block)
+      if name
+        safelists[name] = safelist
+      else
+        anonymous_safelists << safelist
+      end
     end
 
-    def blocklist(name, &block)
-      self.blocklists[name] = Blocklist.new(name, block)
+    def blocklist(name = nil, &block)
+      blocklist = Blocklist.new(name, &block)
+
+      if name
+        blocklists[name] = blocklist
+      else
+        anonymous_blocklists << blocklist
+      end
     end
 
     def blocklist_ip(ip_address)
-      @ip_blocklists ||= []
-      ip_blocklist_proc = lambda { |request| IPAddr.new(ip_address).include?(IPAddr.new(request.ip)) }
-      @ip_blocklists << Blocklist.new(nil, ip_blocklist_proc)
+      anonymous_blocklists << Blocklist.new { |request| IPAddr.new(ip_address).include?(IPAddr.new(request.ip)) }
     end
 
     def safelist_ip(ip_address)
-      @ip_safelists ||= []
-      ip_safelist_proc = lambda { |request| IPAddr.new(ip_address).include?(IPAddr.new(request.ip)) }
-      @ip_safelists << Safelist.new(nil, ip_safelist_proc)
-    end
-
-    def blacklist(name, &block)
-      warn "[DEPRECATION] 'Rack::Attack.blacklist' is deprecated.  Please use 'blocklist' instead."
-      blocklist(name, &block)
+      anonymous_safelists << Safelist.new { |request| IPAddr.new(ip_address).include?(IPAddr.new(request.ip)) }
     end
 
     def throttle(name, options, &block)
-      self.throttles[name] = Throttle.new(name, options, block)
+      throttles[name] = Throttle.new(name, options, &block)
     end
 
     def track(name, options = {}, &block)
-      self.tracks[name] = Track.new(name, options, block)
+      tracks[name] = Track.new(name, options, &block)
     end
 
-    def safelists;  @safelists  ||= {}; end
-
-    def blocklists; @blocklists ||= {}; end
-
-    def throttles;  @throttles  ||= {}; end
+    def safelists
+      @safelists  ||= {}
+    end
 
-    def tracks;     @tracks     ||= {}; end
+    def blocklists
+      @blocklists ||= {}
+    end
 
-    def whitelists
-      warn "[DEPRECATION] 'Rack::Attack.whitelists' is deprecated.  Please use 'safelists' instead."
-      safelists
+    def throttles
+      @throttles  ||= {}
     end
 
-    def blacklists
-      warn "[DEPRECATION] 'Rack::Attack.blacklists' is deprecated.  Please use 'blocklists' instead."
-      blocklists
+    def tracks
+      @tracks     ||= {}
     end
 
     def safelisted?(request)
-      ip_safelists.any? { |safelist| safelist.matched_by?(request) } ||
+      anonymous_safelists.any? { |safelist| safelist.matched_by?(request) } ||
         safelists.any? { |_name, safelist| safelist.matched_by?(request) }
     end
 
-    def whitelisted?(request)
-      warn "[DEPRECATION] 'Rack::Attack.whitelisted?' is deprecated.  Please use 'safelisted?' instead."
-      safelisted?(request)
-    end
-
     def blocklisted?(request)
-      ip_blocklists.any? { |blocklist| blocklist.matched_by?(request) } ||
+      anonymous_blocklists.any? { |blocklist| blocklist.matched_by?(request) } ||
         blocklists.any? { |_name, blocklist| blocklist.matched_by?(request) }
     end
 
-    def blacklisted?(request)
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted?' is deprecated.  Please use 'blocklisted?' instead."
-      blocklisted?(request)
-    end
-
     def throttled?(request)
       throttles.any? do |_name, throttle|
         throttle.matched_by?(request)
@@ -116,7 +104,13 @@ class Rack::Attack
     end
 
     def instrument(request)
-      notifier.instrument('rack.attack', request) if notifier
+      if notifier
+        event_type = request.env["rack.attack.match_type"]
+        notifier.instrument("#{event_type}.rack_attack", request: request)
+
+        # Deprecated: Keeping just for backwards compatibility
+        notifier.instrument("rack.attack", request: request)
+      end
     end
 
     def cache
@@ -125,37 +119,19 @@ class Rack::Attack
 
     def clear_configuration
       @safelists, @blocklists, @throttles, @tracks = {}, {}, {}, {}
-      @ip_blocklists = []
-      @ip_safelists = []
+      self.anonymous_blocklists = []
+      self.anonymous_safelists = []
     end
 
     def clear!
       warn "[DEPRECATION] Rack::Attack.clear! is deprecated. Please use Rack::Attack.clear_configuration instead"
       clear_configuration
     end
-
-    def blacklisted_response=(res)
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted_response=' is deprecated.  Please use 'blocklisted_response=' instead."
-      self.blocklisted_response = res
-    end
-
-    def blacklisted_response
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted_response' is deprecated.  Please use 'blocklisted_response' instead."
-      blocklisted_response
-    end
-
-    private
-
-    def ip_blocklists
-      @ip_blocklists ||= []
-    end
-
-    def ip_safelists
-      @ip_safelists ||= []
-    end
   end
 
   # Set defaults
+  @anonymous_blocklists = []
+  @anonymous_safelists = []
   @notifier             = ActiveSupport::Notifications if defined?(ActiveSupport::Notifications)
   @blocklisted_response = lambda { |_env| [403, { 'Content-Type' => 'text/plain' }, ["Forbidden\n"]] }
   @throttled_response   = lambda { |env|

data/lib/rack/attack/allow2ban.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   class Attack
     class Allow2Ban < Fail2Ban

data/lib/rack/attack/blocklist.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Rack
   class Attack
     class Blocklist < Check
-      def initialize(name, block)
+      def initialize(name = nil, &block)
         super
         @type = :blocklist
       end

data/lib/rack/attack/cache.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   class Attack
     class Cache
@@ -27,7 +29,7 @@ module Rack
       end
 
       def write(unprefixed_key, value, expires_in)
-        store.write("#{prefix}:#{unprefixed_key}", value, :expires_in => expires_in)
+        store.write("#{prefix}:#{unprefixed_key}", value, expires_in: expires_in)
       end
 
       def reset_count(unprefixed_key, period)
@@ -52,13 +54,13 @@ module Rack
         enforce_store_presence!
         enforce_store_method_presence!(:increment)
 
-        result = store.increment(key, 1, :expires_in => expires_in)
+        result = store.increment(key, 1, expires_in: expires_in)
 
         # NB: Some stores return nil when incrementing uninitialized values
         if result.nil?
           enforce_store_method_presence!(:write)
 
-          store.write(key, 1, :expires_in => expires_in)
+          store.write(key, 1, expires_in: expires_in)
         end
         result || 1
       end

data/lib/rack/attack/check.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Rack
   class Attack
     class Check
       attr_reader :name, :block, :type
-      def initialize(name, options = {}, block)
+      def initialize(name, options = {}, &block)
         @name, @block = name, block
         @type = options.fetch(:type, nil)
       end

data/lib/rack/attack/fail2ban.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   class Attack
     class Fail2Ban