rack-attack 5.4.0 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 123608043cbaa1604ab2d7b06c056010decd274dd4a5b1fe8f2175cec766fa4d
-  data.tar.gz: 2bd3ca91293545b76221608f144c1a43a458fbd9e6f2e8ea2647bf561d8ea9a9
+  metadata.gz: ac5af22059fcc24c45b9732a806b13ef8a39b3ab425e713d22b7d0b1c9fbae11
+  data.tar.gz: fdd20e74080d4254d7910be3d1f0343580a2cedd79b18f2448fa753acd9259e2
 SHA512:
-  metadata.gz: '06388ad68edc65019740c9ee77347f817b0769e782d0f8564ac5ac6b9c7fa819fe2157a10d89b570c78c14ef5a86fe080fac30aba8ebdfed281f2073785f5685'
-  data.tar.gz: a15cc2cef9eebda52d662fe3eeee3f187d5b575c089a1fa2cf5e0179012499f6440889349a47108c4017f8b73dd18985655dc933baf8c031e08d73ea23d1dbba
+  metadata.gz: 1f2a7bd75ab8423dde30e482085b19cb5cfbf7347aed13c94da63d31784939075278cc0f891af450bd33e5ef3de4ea092441b26f2519e28ecb5cbe5c6a16d007
+  data.tar.gz: fbe8d0cc86c52be9a028a4fcb2f8f2399af143b6ccd77c7377cbe5f762bb344bdb80833c5e53221ffefad57d04ee132650b38cd5e9d44c5073e475ba894a1a3f

data/README.md

@@ -1,3 +1,6 @@
+__Note__: You are viewing the development version README.
+For the README consistent with the latest released version see https://github.com/kickstarter/rack-attack/blob/6-stable/README.md.
+
 # Rack::Attack
 
 *Rack middleware for blocking & throttling abusive requests*
@@ -9,10 +12,44 @@ See the [Backing & Hacking blog post](https://www.kickstarter.com/backing-and-ha
 [![Gem Version](https://badge.fury.io/rb/rack-attack.svg)](https://badge.fury.io/rb/rack-attack)
 [![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)
+[![Join the chat at https://gitter.im/rack-attack/rack-attack](https://badges.gitter.im/rack-attack/rack-attack.svg)](https://gitter.im/rack-attack/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,18 +67,23 @@ 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.
 
-a) For __rails__ applications:
-
+a) For __rails__ applications with versions >= 5.1 it is used by default. For older rails versions you should enable it explicitly:
 ```ruby
 # In config/application.rb
 
 config.middleware.use Rack::Attack
 ```
 
+You can disable it permanently (like for specific environment) or temporarily (can be useful for specific test cases) by writing:
+
+```ruby
+Rack::Attack.enabled = false
+```
+
 b) For __rack__ applications:
 
 ```ruby
@@ -55,8 +97,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 +128,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,8 +294,9 @@ 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|
-  if req.env['rack.attack.matched'] == "special_agent" && req.env['rack.attack.match_type'] == :track
+ActiveSupport::Notifications.subscribe("track.rack_attack") do |name, start, finish, request_id, payload|
+  req = payload[:request]
+  if req.env['rack.attack.matched'] == "special_agent"
     Rails.logger.info "special_agent: #{req.path}"
     STATSD.increment("special_agent")
   end
@@ -294,12 +337,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 +350,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"]]
@@ -320,18 +363,33 @@ 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, :epoch_time => t }
+request.env['rack.attack.throttle_data'][name] # => { discriminator: d, count: n, period: p, limit: l, epoch_time: t }
 ```
 
 ## 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' 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("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, req|
-  puts req.inspect
+ActiveSupport::Notifications.subscribe(/rack_attack/) do |name, start, finish, request_id, payload|
+  # request object available in payload[:request]
+
+  # Your code here
 end
 ```
 
@@ -344,7 +402,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 +423,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 +470,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/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rack/attack.rb

@@ -1,187 +1,176 @@
+# frozen_string_literal: true
+
 require 'rack'
 require 'forwardable'
 require 'rack/attack/path_normalizer'
 require 'rack/attack/request'
 require "ipaddr"
 
-class Rack::Attack
-  class MisconfiguredStoreError < StandardError; end
-  class MissingStoreError < StandardError; end
-
-  autoload :Cache,                'rack/attack/cache'
-  autoload :Check,                'rack/attack/check'
-  autoload :Throttle,             'rack/attack/throttle'
-  autoload :Safelist,             'rack/attack/safelist'
-  autoload :Blocklist,            'rack/attack/blocklist'
-  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 :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 :Fail2Ban,             'rack/attack/fail2ban'
-  autoload :Allow2Ban,            'rack/attack/allow2ban'
-
-  class << self
-    attr_accessor :notifier, :blocklisted_response, :throttled_response
-
-    def safelist(name, &block)
-      self.safelists[name] = Safelist.new(name, block)
-    end
-
-    def whitelist(name, &block)
-      warn "[DEPRECATION] 'Rack::Attack.whitelist' is deprecated.  Please use 'safelist' instead."
-      safelist(name, &block)
-    end
-
-    def blocklist(name, &block)
-      self.blocklists[name] = Blocklist.new(name, block)
-    end
+require 'rack/attack/railtie' if defined?(::Rails)
+
+module Rack
+  class Attack
+    class Error < StandardError; end
+    class MisconfiguredStoreError < Error; end
+    class MissingStoreError < Error; end
+
+    autoload :Cache,                'rack/attack/cache'
+    autoload :Check,                'rack/attack/check'
+    autoload :Throttle,             'rack/attack/throttle'
+    autoload :Safelist,             'rack/attack/safelist'
+    autoload :Blocklist,            'rack/attack/blocklist'
+    autoload :Track,                'rack/attack/track'
+    autoload :StoreProxy,           'rack/attack/store_proxy'
+    autoload :DalliProxy,           'rack/attack/store_proxy/dalli_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 :enabled, :notifier, :blocklisted_response, :throttled_response,
+                    :anonymous_blocklists, :anonymous_safelists
+
+      def safelist(name = nil, &block)
+        safelist = Safelist.new(name, &block)
+
+        if name
+          safelists[name] = safelist
+        else
+          anonymous_safelists << safelist
+        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)
-    end
+      def blocklist(name = nil, &block)
+        blocklist = Blocklist.new(name, &block)
 
-    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
+        if name
+          blocklists[name] = blocklist
+        else
+          anonymous_blocklists << blocklist
+        end
+      end
 
-    def blacklist(name, &block)
-      warn "[DEPRECATION] 'Rack::Attack.blacklist' is deprecated.  Please use 'blocklist' instead."
-      blocklist(name, &block)
-    end
+      def blocklist_ip(ip_address)
+        anonymous_blocklists << Blocklist.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)
-    end
+      def safelist_ip(ip_address)
+        anonymous_safelists << Safelist.new { |request| IPAddr.new(ip_address).include?(IPAddr.new(request.ip)) }
+      end
 
-    def track(name, options = {}, &block)
-      self.tracks[name] = Track.new(name, options, block)
-    end
+      def throttle(name, options, &block)
+        throttles[name] = Throttle.new(name, options, &block)
+      end
 
-    def safelists;  @safelists  ||= {}; end
+      def track(name, options = {}, &block)
+        tracks[name] = Track.new(name, options, &block)
+      end
 
-    def blocklists; @blocklists ||= {}; end
+      def safelists
+        @safelists ||= {}
+      end
 
-    def throttles;  @throttles  ||= {}; end
+      def blocklists
+        @blocklists ||= {}
+      end
 
-    def tracks;     @tracks     ||= {}; end
+      def throttles
+        @throttles ||= {}
+      end
 
-    def whitelists
-      warn "[DEPRECATION] 'Rack::Attack.whitelists' is deprecated.  Please use 'safelists' instead."
-      safelists
-    end
+      def tracks
+        @tracks ||= {}
+      end
 
-    def blacklists
-      warn "[DEPRECATION] 'Rack::Attack.blacklists' is deprecated.  Please use 'blocklists' instead."
-      blocklists
-    end
+      def safelisted?(request)
+        anonymous_safelists.any? { |safelist| safelist.matched_by?(request) } ||
+          safelists.any? { |_name, safelist| safelist.matched_by?(request) }
+      end
 
-    def safelisted?(request)
-      ip_safelists.any? { |safelist| safelist.matched_by?(request) } ||
-        safelists.any? { |_name, safelist| safelist.matched_by?(request) }
-    end
+      def blocklisted?(request)
+        anonymous_blocklists.any? { |blocklist| blocklist.matched_by?(request) } ||
+          blocklists.any? { |_name, blocklist| blocklist.matched_by?(request) }
+      end
 
-    def whitelisted?(request)
-      warn "[DEPRECATION] 'Rack::Attack.whitelisted?' is deprecated.  Please use 'safelisted?' instead."
-      safelisted?(request)
-    end
+      def throttled?(request)
+        throttles.any? do |_name, throttle|
+          throttle.matched_by?(request)
+        end
+      end
 
-    def blocklisted?(request)
-      ip_blocklists.any? { |blocklist| blocklist.matched_by?(request) } ||
-        blocklists.any? { |_name, blocklist| blocklist.matched_by?(request) }
-    end
+      def tracked?(request)
+        tracks.each_value do |track|
+          track.matched_by?(request)
+        end
+      end
 
-    def blacklisted?(request)
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted?' is deprecated.  Please use 'blocklisted?' instead."
-      blocklisted?(request)
-    end
+      def instrument(request)
+        if notifier
+          event_type = request.env["rack.attack.match_type"]
+          notifier.instrument("#{event_type}.rack_attack", request: request)
 
-    def throttled?(request)
-      throttles.any? do |_name, throttle|
-        throttle.matched_by?(request)
+          # Deprecated: Keeping just for backwards compatibility
+          notifier.instrument("rack.attack", request: request)
+        end
       end
-    end
 
-    def tracked?(request)
-      tracks.each_value do |track|
-        track.matched_by?(request)
+      def cache
+        @cache ||= Cache.new
       end
-    end
-
-    def instrument(request)
-      notifier.instrument('rack.attack', request) if notifier
-    end
-
-    def cache
-      @cache ||= Cache.new
-    end
 
-    def clear_configuration
-      @safelists, @blocklists, @throttles, @tracks = {}, {}, {}, {}
-      @ip_blocklists = []
-      @ip_safelists = []
-    end
+      def clear_configuration
+        @safelists = {}
+        @blocklists = {}
+        @throttles = {}
+        @tracks = {}
+        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
+      def clear!
+        warn "[DEPRECATION] Rack::Attack.clear! is deprecated. Please use Rack::Attack.clear_configuration instead"
+        clear_configuration
+      end
     end
 
-    def blacklisted_response=(res)
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted_response=' is deprecated.  Please use 'blocklisted_response=' instead."
-      self.blocklisted_response = res
+    # Set defaults
+    @enabled = true
+    @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 do |env|
+      retry_after = (env['rack.attack.match_data'] || {})[:period]
+      [429, { 'Content-Type' => 'text/plain', 'Retry-After' => retry_after.to_s }, ["Retry later\n"]]
     end
 
-    def blacklisted_response
-      warn "[DEPRECATION] 'Rack::Attack.blacklisted_response' is deprecated.  Please use 'blocklisted_response' instead."
-      blocklisted_response
+    def initialize(app)
+      @app = app
     end
 
-    private
+    def call(env)
+      return @app.call(env) unless self.class.enabled
 
-    def ip_blocklists
-      @ip_blocklists ||= []
-    end
+      env['PATH_INFO'] = PathNormalizer.normalize_path(env['PATH_INFO'])
+      request = Rack::Attack::Request.new(env)
 
-    def ip_safelists
-      @ip_safelists ||= []
+      if safelisted?(request)
+        @app.call(env)
+      elsif blocklisted?(request)
+        self.class.blocklisted_response.call(env)
+      elsif throttled?(request)
+        self.class.throttled_response.call(env)
+      else
+        tracked?(request)
+        @app.call(env)
+      end
     end
-  end
-
-  # Set defaults
-  @notifier             = ActiveSupport::Notifications if defined?(ActiveSupport::Notifications)
-  @blocklisted_response = lambda { |_env| [403, { 'Content-Type' => 'text/plain' }, ["Forbidden\n"]] }
-  @throttled_response   = lambda { |env|
-    retry_after = (env['rack.attack.match_data'] || {})[:period]
-    [429, { 'Content-Type' => 'text/plain', 'Retry-After' => retry_after.to_s }, ["Retry later\n"]]
-  }
-
-  def initialize(app)
-    @app = app
-  end
 
-  def call(env)
-    env['PATH_INFO'] = PathNormalizer.normalize_path(env['PATH_INFO'])
-    request = Rack::Attack::Request.new(env)
-
-    if safelisted?(request)
-      @app.call(env)
-    elsif blocklisted?(request)
-      self.class.blocklisted_response.call(env)
-    elsif throttled?(request)
-      self.class.throttled_response.call(env)
-    else
-      tracked?(request)
-      @app.call(env)
-    end
+    extend Forwardable
+    def_delegators self, :safelisted?, :blocklisted?, :throttled?, :tracked?
   end
-
-  extend Forwardable
-  def_delegators self, :safelisted?, :blocklisted?, :throttled?, :tracked?
 end